Skip to content

livery.workshop._regions

livery.workshop._regions

The content a repository owns inside its managed files.

A managed file is rendered whole and judged byte for byte, and a repository still needs lines of its own in some of them: its own rules in the root .gitignore, its own tables in pyproject.toml, its own tasks below the mount in tasks.py. A region carries them.

A region is a pair of marker comments the template renders, with the repository's lines between them. The fragment engine reads each region from the committed file and writes it back in place, so a sync preserves it by construction and the drift gate still compares whole bytes: an edit inside a region is the repository's, an edit outside it is drift, and a removed marker is drift too. A file without the region yet gains the markers, empty, on the next apply.

The markers are one shape in every comment style, so a reader who has seen one has seen them all::

# -- workshop: region tables, yours to edit; the render keeps it --
# -- workshop: end tables --

Classes:

Name Description
Region

One region as a committed file carries it.

Functions:

Name Description
regions_in

Every region text carries, in file order.

region_names

The names the markers in text open, whether or not they close.

contents

The committed file's regions, name to content; empty when the file is absent.

unmatched

The names whose markers do not pair up in text.

marker_lines

The opening and closing marker for name under leader.

Attributes:

Name Type Description
OPEN
CLOSE

OPEN module-attribute

OPEN = '{leader} -- workshop: region {name}, yours to edit; the render keeps it --'

CLOSE module-attribute

CLOSE = '{leader} -- workshop: end {name} --'

Region dataclass

Region(name: str, content: str, first: int, last: int)

One region as a committed file carries it.

Attributes:

Name Type Description
name str

The region's name, as its markers spell it.

content str

The lines between the markers, newline-terminated when there are any, empty otherwise.

first int

The line number of the opening marker, one-based.

last int

The line number of the closing marker, one-based.

name instance-attribute

name: str

content instance-attribute

content: str

first instance-attribute

first: int

last instance-attribute

last: int

regions_in

regions_in(text: str) -> tuple[Region, ...]

Every region text carries, in file order.

A marker without its partner is not a region: the drift gate reports the file, since the markers are rendered bytes.

Source code in packages/workshop/src/livery/workshop/_regions.py
def regions_in(text: str) -> tuple[Region, ...]:
    """Every region *text* carries, in file order.

    A marker without its partner is not a region: the drift gate
    reports the file, since the markers are rendered bytes.
    """
    found: list[Region] = []
    lines = text.split("\n")
    open_name = ""
    start = 0
    body: list[str] = []
    for number, line in enumerate(lines, start=1):
        opened = _OPEN.match(line)
        closed = _CLOSE.match(line)
        if opened and not open_name:
            open_name, start, body = opened.group(1), number, []
            continue
        if closed and open_name and closed.group(1) == open_name:
            content = "".join(f"{item}\n" for item in body)
            found.append(Region(open_name, content, start, number))
            open_name = ""
            continue
        if open_name:
            body.append(line)
    return tuple(found)

region_names

region_names(text: str) -> tuple[str, ...]

The names the markers in text open, whether or not they close.

Source code in packages/workshop/src/livery/workshop/_regions.py
def region_names(text: str) -> tuple[str, ...]:
    """The names the markers in *text* open, whether or not they close."""
    return tuple(
        m.group(1) for m in (_OPEN.match(line) for line in text.split("\n")) if m
    )

contents

contents(path: Path) -> dict[str, str]

The committed file's regions, name to content; empty when the file is absent.

Source code in packages/workshop/src/livery/workshop/_regions.py
def contents(path: Path) -> dict[str, str]:
    """The committed file's regions, name to content; empty when the file is absent."""
    if not path.is_file():
        return {}
    text = path.read_text(encoding="utf-8")
    return {region.name: region.content for region in regions_in(text)}

unmatched

unmatched(text: str) -> tuple[str, ...]

The names whose markers do not pair up in text.

Source code in packages/workshop/src/livery/workshop/_regions.py
def unmatched(text: str) -> tuple[str, ...]:
    """The names whose markers do not pair up in *text*."""
    paired = {region.name for region in regions_in(text)}
    opened = set(region_names(text))
    closed = {
        m.group(1) for m in (_CLOSE.match(line) for line in text.split("\n")) if m
    }
    return tuple(sorted((opened | closed) - paired))

marker_lines

marker_lines(leader: str, name: str) -> tuple[str, str]

The opening and closing marker for name under leader.

Source code in packages/workshop/src/livery/workshop/_regions.py
def marker_lines(leader: str, name: str) -> tuple[str, str]:
    """The opening and closing marker for *name* under *leader*."""
    return OPEN.format(leader=leader, name=name), CLOSE.format(leader=leader, name=name)