Skip to content

livery.workshop._fragments

livery.workshop._fragments

The configuration a step owns, composed into the files the render writes.

A step record carries one fragment per rendered file it has something to say in: its tables in pyproject.toml, its lines in .vscode/settings.json, its .clang-tidy in each C or C++ package. The render composes the base template with the registered fragments in step-name order, so two machines write the same bytes, and the drift gate judges the result. A fragment is jinja text rendered with the same data the template reads. A project file's fragment applies once per workspace, with per-package variation spelled inside it the tool's own way; a package file's fragment applies in each package whose set holds one of the extensions it names, the first step by name winning when two have one. A fragment leaves the render with its record: unregistering the step removes the section from the next render, and a per-package file it wrote alone goes when its bytes are the bytes the render last wrote.

Classes:

Name Description
Fragment

One step's configuration for one rendered file.

Functions:

Name Description
verify

Refuse a fragment naming a file the render does not write.

compose_project

Each project file's composed fragments, by file, in step-name order.

package_files

The per-package files the registered steps' fragments render, sorted.

package_fragment

The fragment text a package holding extensions renders as file, and its step.

compose_package

file rendered for a package holding extensions; None when no step owns it.

Attributes:

Name Type Description
PROJECT_FILES

PROJECT_FILES module-attribute

PROJECT_FILES = ('pyproject.toml', '.vscode/settings.json', '.vscode/extensions.json')

Fragment dataclass

Fragment(file: str, text: str, extensions: tuple[str, ...] = ())

One step's configuration for one rendered file.

Attributes:

Name Type Description
file str

The rendered file, a project file relative to the root or a per-package file name.

text str

The fragment's jinja text, rendered with the file's own render data.

extensions tuple[str, ...]

For a per-package file, the extensions whose packages render it; empty for a project file.

file instance-attribute

file: str

text instance-attribute

text: str

extensions class-attribute instance-attribute

extensions: tuple[str, ...] = ()

verify

verify(fragments: tuple[Fragment, ...], step: str) -> None

Refuse a fragment naming a file the render does not write.

Raises:

Type Description
ValueError

naming the step, the file, and the files a fragment may address.

Source code in packages/workshop/src/livery/workshop/_fragments.py
def verify(fragments: tuple[Fragment, ...], step: str) -> None:
    """Refuse a fragment naming a file the render does not write.

    Raises:
        ValueError: naming the step, the file, and the files a
            fragment may address.
    """
    for fragment in fragments:
        if fragment.file in PROJECT_FILES:
            if fragment.extensions:
                raise ValueError(
                    f"step {step!r}: a fragment for {fragment.file} applies to"
                    " the whole workspace and names no extension"
                )
            continue
        if fragment.extensions:
            continue
        raise ValueError(
            f"step {step!r}: a fragment for {fragment.file!r} names a file the"
            f" render does not write; the project files are"
            f" {', '.join(PROJECT_FILES)}, and a fragment that names extensions is"
            " rendered in each package whose set holds one"
        )

compose_project

compose_project(data: dict[str, Any]) -> dict[str, str]

Each project file's composed fragments, by file, in step-name order.

A file no step has a fragment for maps to the empty string, so a template's {{ fragments['...'] }} always resolves.

Source code in packages/workshop/src/livery/workshop/_fragments.py
def compose_project(data: dict[str, Any]) -> dict[str, str]:
    """Each project file's composed fragments, by file, in step-name order.

    A file no step has a fragment for maps to the empty string, so a
    template's ``{{ fragments['...'] }}`` always resolves.
    """
    from livery.workshop._steps import steps_by_name

    found: dict[str, str] = {}
    for file in PROJECT_FILES:
        found[file] = ""
    for name in sorted(steps_by_name()):
        record = steps_by_name()[name]
        for fragment in record.fragments:
            if fragment.file in PROJECT_FILES:
                rendered = _render(fragment.text, data)
                if found[fragment.file] and not found[fragment.file].endswith("\n\n"):
                    found[fragment.file] += "\n"
                found[fragment.file] += rendered
    return found

package_files

package_files() -> tuple[str, ...]

The per-package files the registered steps' fragments render, sorted.

A fragment that names extensions is rendered in each package whose set holds one, so the files a C or C++ package carries are the registered steps' to say, and leave with them.

Source code in packages/workshop/src/livery/workshop/_fragments.py
def package_files() -> tuple[str, ...]:
    """The per-package files the registered steps' fragments render, sorted.

    A fragment that names extensions is rendered in each package whose
    set holds one, so the files a C or C++ package carries are the
    registered steps' to say, and leave with them.
    """
    from livery.workshop._steps import steps_by_name

    return tuple(
        sorted(
            {
                fragment.file
                for record in steps_by_name().values()
                for fragment in record.fragments
                if fragment.extensions
            }
        )
    )

package_fragment

package_fragment(extensions: tuple[str, ...], file: str) -> tuple[str, str] | None

The fragment text a package holding extensions renders as file, and its step.

The first step by name whose fragment names one of extensions wins; None when no step has one, which is what a withdrawn step looks like to the apply.

Source code in packages/workshop/src/livery/workshop/_fragments.py
def package_fragment(extensions: tuple[str, ...], file: str) -> tuple[str, str] | None:
    """The fragment text a package holding *extensions* renders as *file*, and its step.

    The first step by name whose fragment names one of *extensions*
    wins; None when no step has one, which is what a withdrawn step
    looks like to the apply.
    """
    from livery.workshop._steps import steps_by_name

    held = set(extensions)
    for name in sorted(steps_by_name()):
        for fragment in steps_by_name()[name].fragments:
            if fragment.file == file and held & set(fragment.extensions):
                return fragment.text, name
    return None

compose_package

compose_package(extensions: tuple[str, ...], file: str, data: dict[str, Any]) -> str | None

file rendered for a package holding extensions; None when no step owns it.

Source code in packages/workshop/src/livery/workshop/_fragments.py
def compose_package(
    extensions: tuple[str, ...], file: str, data: dict[str, Any]
) -> str | None:
    """*file* rendered for a package holding *extensions*; None when no step owns it."""
    found = package_fragment(extensions, file)
    if found is None:
        return None
    text, _step = found
    return _render(text, data)