Skip to content

livery.workshop._prose

livery.workshop._prose

Prose fragments: what the extensions say to the agent and to a reader, in sections.

An extension's prose, its voice, its standards, its rules, is a set of fragments, and one set writes the agent's entry file and the site's development pages. A fragment is a markdown file in the extension's content/fragments/ named <section>.<topic>[.<audience>].md, or one the base renders from its registries, a render that takes the audience. The base defines the sections and their order, and an extension adds fragments to them, never a section. The audience is agent or human, and a name without one serves both; a render answers each audience itself, and an empty answer leaves the fragment out for that reader. A topic is never named agent or human: the last part of a name spells the audience.

fm sync delivers the agent's set flat under .workshop/fragments/ with the audience dropped from the name: a shipped fragment byte for byte its source, a rendered one under a header naming its origin, each through the fragment engine so an edited copy is kept and named. The repository's own fragments live in fragments/ at the root under the same names, are never copied, and come last. Reach for livery.workshop._prose.fragments for the set a reader gets and livery.workshop._shipped_files for the delivery.

Classes:

Name Description
ProseError

A fragment name the guidance refuses; the message names the files.

Prose

One prose fragment: a file an extension ships, or a render from the registries.

Functions:

Name Description
parse_name

Split a fragment file name into section, topic and audience.

shipped

The fragments extension ships under content/fragments/, in name order.

repository_fragments

The repository's own fragments under fragments/ at root, in name order.

in_play

Every shipped fragment in play: each extension's set in order, then the own.

guidance

The guidance one reader gets in the workspace at root, in reading order.

present_extensions

The extensions the sets of the packages present in root hold.

fragments

The fragments audience reads: by section, then extension, then name.

render_gate

The gate's steps for the extensions the members hold.

forget_trees

Drop every tree this process listed, so the next read lists again.

composed_tree

The workspace's composed task tree, as --json --list reports it.

render_verbs

The verbs by provider, then what each extension of the installed set provides.

render_compositions

The sets of extensions the present packages hold, each with its packages.

render_tools

The tools the lock pins, each with its version and the sites requiring it.

Attributes:

Name Type Description
BASE_EXTENSION
AGENT
HUMAN
AUDIENCES
BASE_SECTIONS
OWN
REPOSITORY
Render

BASE_EXTENSION module-attribute

BASE_EXTENSION = 'livery.workshop'

AGENT module-attribute

AGENT = 'agent'

HUMAN module-attribute

HUMAN = 'human'

AUDIENCES module-attribute

AUDIENCES = (AGENT, HUMAN)

BASE_SECTIONS module-attribute

BASE_SECTIONS = ('identity', 'voice', 'standards', 'rules', 'workflow', 'gate', 'verbs', 'compositions', 'tools')

OWN module-attribute

OWN = 'fragments'

REPOSITORY module-attribute

REPOSITORY = ''

Render module-attribute

Render = Callable[[Path, 'str | None'], str]

ProseError

Bases: ValueError

A fragment name the guidance refuses; the message names the files.

Prose dataclass

Prose(section: str, topic: str, audience: str = '', extension: str = BASE_EXTENSION, source: Path | None = None, render: Render | None = None)

One prose fragment: a file an extension ships, or a render from the registries.

Attributes:

Name Type Description
section str

The section it belongs to, one of the base's.

topic str

What it is about; with the section, its name.

audience str

agent or human for a file that serves one reader, empty for both; a rendered fragment is empty here and answers per audience.

extension str

The extension that ships or renders it; empty for the repository's own.

source Path | None

The shipped file, or None for a rendered fragment.

render Render | None

The render, or None for a shipped fragment.

Methods:

Name Description
text

The markdown for audience: the shipped text, or the render's answer.

section instance-attribute

section: str

topic instance-attribute

topic: str

audience class-attribute instance-attribute

audience: str = ''

extension class-attribute instance-attribute

extension: str = BASE_EXTENSION

source class-attribute instance-attribute

source: Path | None = None

render class-attribute instance-attribute

render: Render | None = None

name property

name: str

The delivered file name, <section>.<topic>.md.

origin property

origin: str

Where it comes from, for a refusal: the posix file, or the extension.

text

text(root: Path, audience: str | None) -> str

The markdown for audience: the shipped text, or the render's answer.

Source code in packages/workshop/src/livery/workshop/_prose.py
def text(self, root: Path, audience: str | None) -> str:
    """The markdown for *audience*: the shipped text, or the render's answer."""
    if self.render is not None:
        return self.render(root, audience)
    if self.source is not None:
        return self.source.read_text(encoding="utf-8")
    return ""

parse_name

parse_name(filename: str, *, where: str = '') -> tuple[str, str, str]

Split a fragment file name into section, topic and audience.

rules.tests.agent.md is the rules section, the topic tests, for the agent. A third part spells the audience, so a topic is never named agent or human. Refuses a name outside the convention and an unknown section, naming where, the file by default.

Source code in packages/workshop/src/livery/workshop/_prose.py
def parse_name(filename: str, *, where: str = "") -> tuple[str, str, str]:
    """Split a fragment file name into section, topic and audience.

    ``rules.tests.agent.md`` is the rules section, the topic tests, for
    the agent. A third part spells the audience, so a topic is never
    named ``agent`` or ``human``. Refuses a name outside the convention
    and an unknown section, naming *where*, the file by default.
    """
    where = where or filename
    stem, dot, suffix = filename.rpartition(".")
    parts = stem.split(".") if dot and suffix == "md" else []
    audience = ""
    if len(parts) > 2 and parts[-1] in AUDIENCES:
        audience = parts.pop()
    if len(parts) != 2 or not all(parts):
        raise ProseError(
            f"{where}: a fragment is named <section>.<topic>[.<audience>].md"
        )
    section, topic = parts
    _check_section(where, section)
    return section, topic, audience

shipped

shipped(extension: str, content: Path) -> list[Prose]

The fragments extension ships under content/fragments/, in name order.

Every file there is a fragment, so a name outside the convention refuses naming the file. The repository's own come from its root with the empty extension name.

Source code in packages/workshop/src/livery/workshop/_prose.py
def shipped(extension: str, content: Path) -> list[Prose]:
    """The fragments *extension* ships under ``content/fragments/``, in name order.

    Every file there is a fragment, so a name outside the convention
    refuses naming the file. The repository's own come from its root
    with the empty extension name.
    """
    directory = content / OWN
    if not directory.is_dir():
        return []
    found: list[Prose] = []
    for path in sorted(directory.iterdir()):
        if not path.is_file():
            continue
        section, topic, audience = parse_name(path.name, where=path.as_posix())
        found.append(Prose(section, topic, audience, extension, source=path))
    return found

repository_fragments

repository_fragments(root: Path) -> list[Prose]

The repository's own fragments under fragments/ at root, in name order.

Source code in packages/workshop/src/livery/workshop/_prose.py
def repository_fragments(root: Path) -> list[Prose]:
    """The repository's own fragments under ``fragments/`` at *root*, in name order."""
    return shipped(REPOSITORY, root)

in_play

in_play(root: Path, order: Iterable[str] | None = None) -> list[Prose]

Every shipped fragment in play: each extension's set in order, then the own.

order is the mounted extensions' order, the workspace's stack when absent. An extension that ships no content adds nothing.

Source code in packages/workshop/src/livery/workshop/_prose.py
def in_play(root: Path, order: Iterable[str] | None = None) -> list[Prose]:
    """Every shipped fragment in play: each extension's set in *order*, then the own.

    *order* is the mounted extensions' order, the workspace's stack when
    absent. An extension that ships no content adds nothing.
    """
    from livery.workshop._extensions import extension_content, stack_names

    listed: list[Prose] = []
    for extension in stack_names(root) if order is None else order:
        content = extension_content(extension)
        if content is not None:
            listed += shipped(extension, content)
    return [*listed, *repository_fragments(root)]

guidance

guidance(root: Path, audience: str) -> list[Prose]

The guidance one reader gets in the workspace at root, in reading order.

audience is livery.workshop.AGENT or livery.workshop.HUMAN. The set is every fragment the mounted extensions ship, every fragment the base renders, and the repository's own under fragments/: by section, then by extension in mount order, the repository's own last, then by name. A fragment written for the other reader is left out.

Raises:

Type Description
ValueError

when two fragments in the set deliver under one name, naming both.

Source code in packages/workshop/src/livery/workshop/_prose.py
def guidance(root: Path, audience: str) -> list[Prose]:
    """The guidance one reader gets in the workspace at *root*, in reading order.

    *audience* is [livery.workshop.AGENT][] or [livery.workshop.HUMAN][].
    The set is every fragment the mounted extensions ship, every
    fragment the base renders, and the repository's own under
    ``fragments/``: by section, then by extension in mount order, the
    repository's own last, then by name. A fragment written for the
    other reader is left out.

    Raises:
        ValueError: when two fragments in the set deliver under one name,
            naming both.
    """
    return fragments(root, in_play(root), audience)

present_extensions

present_extensions(root: Path) -> frozenset[str]

The extensions the sets of the packages present in root hold.

Source code in packages/workshop/src/livery/workshop/_prose.py
def present_extensions(root: Path) -> frozenset[str]:
    """The extensions the sets of the packages present in *root* hold."""
    from livery.workshop._composition import extension_set
    from livery.workshop._packages import discover_packages

    return frozenset(
        name for package in discover_packages(root) for name in extension_set(package)
    )

fragments

fragments(root: Path, shipped: Iterable[Prose], audience: str | None) -> list[Prose]

The fragments audience reads: by section, then extension, then name.

A shipped fragment for the other reader is left out; a rendered fragment is always in and answers for itself when rendered. The mounted extensions come in mount order, an extension outside the mount after them, and the repository's own last. Two fragments of one name in the set refuse naming both.

Source code in packages/workshop/src/livery/workshop/_prose.py
def fragments(
    root: Path, shipped: Iterable[Prose], audience: str | None
) -> list[Prose]:
    """The fragments *audience* reads: by section, then extension, then name.

    A shipped fragment for the other reader is left out; a rendered
    fragment is always in and answers for itself when rendered. The
    mounted extensions come in mount order, an extension outside the mount
    after them, and the repository's own last. Two fragments of one
    name in the set refuse naming both.
    """
    from livery.workshop._extensions import stack_names

    chosen: list[Prose] = []
    for prose in [*shipped, *_RENDERED.values()]:
        if prose.audience and prose.audience != audience:
            continue
        chosen.append(prose)
    mounted = list(stack_names(root))

    def rank(prose: Prose) -> tuple[int, int, int, str, str]:
        if prose.extension == REPOSITORY:
            tier, index, name = 2, 0, ""
        elif prose.extension in mounted:
            tier, index, name = 0, mounted.index(prose.extension), ""
        else:
            tier, index, name = 1, 0, prose.extension
        return (BASE_SECTIONS.index(prose.section), tier, index, name, prose.name)

    chosen.sort(key=rank)
    seen: dict[str, Prose] = {}
    for prose in chosen:
        other = seen.setdefault(prose.name, prose)
        if other is not prose:
            raise ProseError(
                f"two fragments deliver as {prose.name}: {other.origin} and"
                f" {prose.origin}; a topic is unique across everything delivered"
            )
    return chosen

render_gate

render_gate(root: Path, audience: str | None) -> str

The gate's steps for the extensions the members hold.

A list for the agent, a table for a reader. A step of a phase the gate does not run, one declared gated = false, is left out.

Source code in packages/workshop/src/livery/workshop/_prose.py
def render_gate(root: Path, audience: str | None) -> str:
    """The gate's steps for the extensions the members hold.

    A list for the agent, a table for a reader. A step of a phase the
    gate does not run, one declared ``gated = false``, is left out.
    """
    from livery.workshop._steps import _gated, steps_by_name

    present = present_extensions(root)
    records = [
        record
        for record in steps_by_name().values()
        if _gated(record)
        and (not record.extensions or present & set(record.extensions))
    ]
    if not records:
        return ""
    held = ", ".join(sorted(present)) or "none"
    prog = footman.prog()
    lines = ["# The gate's steps", ""]
    if audience == HUMAN:
        lines += [
            f"`{prog} check` runs every step below, each registered by an"
            f" extension; the members hold the extensions {held}.",
            "",
            "| step | tools | packages | rewrites under `--fix` |",
            "| --- | --- | --- | --- |",
        ]
        for record in records:
            tools = ", ".join(record.tools) or "none"
            scope = " or ".join(record.extensions) or "every"
            fix = "yes" if record.fix is not None else "no"
            lines.append(f"| {record.name} | {tools} | {scope} | {fix} |")
    else:
        lines += [
            f"`{prog} check` runs these steps in parallel, the rewriters first"
            f" and one at a time under `--fix`; the members hold the"
            f" extensions {held}.",
            "",
        ]
        for record in records:
            # The name carries the tool; the store's tools are named
            # only where they are more than it.
            tools = (
                f" ({', '.join(record.tools)})"
                if record.tools and record.tools != (record.step,)
                else ""
            )
            where = "the workspace"
            if record.extensions:
                where = f"{' or '.join(record.extensions)} packages"
            fix = "; rewrites under --fix" if record.fix is not None else ""
            lines.append(f"- {record.name}{tools}: judges {where}{fix}")
    return "\n".join(lines) + "\n"

forget_trees

forget_trees() -> None

Drop every tree this process listed, so the next read lists again.

Source code in packages/workshop/src/livery/workshop/_prose.py
def forget_trees() -> None:
    """Drop every tree this process listed, so the next read lists again."""
    _TREES.clear()

composed_tree

composed_tree(root: Path) -> dict[str, Any] | None

The workspace's composed task tree, as --json --list reports it.

This process's own workspace answers from the tree it discovered (livery.footman.task_tree). Another root, a newborn a birth syncs from its parent's task, is listed by running the runner there: its tree lives in its own venv's entry points, which only a process in that venv can list. None without a tasks file at the root, without the runner on PATH, and when the listing fails: the fragment is then left out rather than guessed. Listed once per process; a later read answers from the first until the tasks file or the contract changes.

Source code in packages/workshop/src/livery/workshop/_prose.py
def composed_tree(root: Path) -> dict[str, Any] | None:
    """The workspace's composed task tree, as ``--json --list`` reports it.

    This process's own workspace answers from the tree it discovered
    ([livery.footman.task_tree][]). Another root, a newborn a birth syncs
    from its parent's task, is listed by running the runner there: its
    tree lives in its own venv's entry points, which only a process in
    that venv can list. None without a tasks file at the root, without
    the runner on PATH, and when the listing fails: the fragment is then
    left out rather than guessed. Listed once per process; a later read
    answers from the first until the tasks file or the contract changes.
    """
    if not (root / "tasks.py").is_file():
        return None
    key = _tree_key(root)
    if key in _TREES:
        return _TREES[key]
    own = _own_root()
    if own is not None and own.resolve() == root.resolve():
        tree = footman.task_tree()
        _TREES[key] = tree
        return tree
    runner = shutil.which(footman.prog())
    if runner is None:
        return None
    result = footman.run(
        [runner, "--json", "--list"], cwd=root, nofail=True, recorded=False
    )
    if int(result) != 0:
        return None
    tree = cast("dict[str, Any]", json.loads(result.stdout)["tree"])
    _TREES[key] = tree
    return tree

render_verbs

render_verbs(root: Path, audience: str | None) -> str

The verbs by provider, then what each extension of the installed set provides.

The composed tree's verbs open it: the base's, those of each plugin no extension of the set carries, and the repository's own last. Then each extension of the installed set, in composition order, has a block, read from its declaration: what it does, its verbs, its templates, its contract keys and step options, the steps it declares off, and the extensions it cooperates with. Without a tree, as a workspace without a tasks file has, the blocks stand alone; with neither a verb nor an extension, the fragment is left out.

Source code in packages/workshop/src/livery/workshop/_prose.py
def render_verbs(root: Path, audience: str | None) -> str:
    """The verbs by provider, then what each extension of the installed set provides.

    The composed tree's verbs open it: the base's, those of each plugin
    no extension of the set carries, and the repository's own last.
    Then each extension of the installed set, in composition order, has
    a block, read from its declaration: what it does, its verbs, its
    templates, its contract keys and step options, the steps it
    declares off, and the extensions it cooperates with. Without a
    tree, as a workspace without a tasks file has, the blocks stand
    alone; with neither a verb nor an extension, the fragment is left
    out.
    """
    from livery.workshop._capabilities import blocks, render_block, verbs_by_provider
    from livery.workshop._extensions import stack_names

    tree = composed_tree(root)
    found, by_extension = blocks(root, verbs_by_provider(tree) if tree else {})
    if not found and not by_extension:
        return ""
    mounted = [
        extension for extension in stack_names(root) if extension in by_extension
    ]
    others = sorted(
        extension
        for extension in by_extension
        if extension not in mounted and extension != REPOSITORY
    )
    ordered = [*mounted, *others, *([REPOSITORY] if REPOSITORY in by_extension else [])]
    prog = footman.prog()
    lines = ["# The verbs by extension", ""]
    if ordered:
        if audience == HUMAN:
            lines.append(
                f"`{prog}` composes these verbs from the base, the plugins the"
                " project mounts and the repository's own tasks file, and an"
                f" extension's verbs are in its section below; `{prog} <verb>"
                " --help` describes one."
            )
        else:
            lines.append(
                f"Every job goes through `{prog}`; these are its verbs, by what"
                " provides them: the base, each plugin the project mounts, and"
                " the repository's own tasks file. An extension's verbs are in"
                " its block below. Verbs hidden from `--help`, which CI and other"
                f" verbs call, are not listed; `{prog} --all --help` shows them:"
            )
        lines.append("")
        for extension in ordered:
            verbs = sorted(verb.address for verb in by_extension[extension])
            lines.append(f"- {extension or 'this repository'}: {', '.join(verbs)}")
        lines.append("")
    if found:
        lines += [
            "Each extension the workspace installs, listed or required by one"
            " listed, has a block below: what it does, its verbs, its templates,"
            " the contract keys and step options it reads, and the installed"
            " extensions it contributes to. A package turns any step off with"
            " `enabled = false` in its `[phases.<phase>.<step>]` table.",
            "",
        ]
        for block in found:
            lines += render_block(block, audience)
    return "\n".join(lines).rstrip("\n") + "\n"

render_compositions

render_compositions(root: Path, audience: str | None) -> str

The sets of extensions the present packages hold, each with its packages.

A set is named by the shortest list that composes it, the extensions joined with +, and is listed with every extension it holds and the gate phases that judge a package holding it. A package holding no extension is listed under none.

Source code in packages/workshop/src/livery/workshop/_prose.py
def render_compositions(root: Path, audience: str | None) -> str:
    """The sets of extensions the present packages hold, each with its packages.

    A set is named by the shortest list that composes it, the extensions
    joined with ``+``, and is listed with every extension it holds and
    the gate phases that judge a package holding it. A package holding
    no extension is listed under ``none``.
    """
    from livery.workshop._composition import extension_set, implied
    from livery.workshop._extensions import installed_declaration
    from livery.workshop._packages import discover_packages
    from livery.workshop._phases import declared_phases
    from livery.workshop._steps import judges_extensions, steps_by_name

    gated = {name for name, spec in declared_phases().items() if spec.gated}
    members: dict[tuple[str, ...], list[str]] = {}
    for package in discover_packages(root):
        held = extension_set(package)
        members.setdefault(held, []).append(package.path)
    if not members:
        return ""
    lines = ["# The compositions present", ""]
    if audience == HUMAN:
        lines += [
            "| composition | extensions | packages | gate phases |",
            "| --- | --- | --- | --- |",
        ]
    else:
        lines += [
            "The sets of extensions the packages hold, each named by the shortest"
            " list that composes it, with its packages and the gate phases that"
            " judge them:",
            "",
        ]
    named: dict[tuple[str, ...], str] = {}
    for held in members:
        required = implied(held, installed_declaration)
        # The shortest list leaves out what another member requires; a
        # cycle among the requires leaves nothing out of the whole set.
        shortest = [name for name in held if name not in required] or held
        named[held] = "+".join(shortest) or "none"
    for held in sorted(members, key=named.__getitem__):
        extensions = ", ".join(held) or "none"
        paths = ", ".join(sorted(members[held]))
        # A set's phases are those of the gate's steps that judge a
        # package holding it; a step naming no extensions judges the
        # workspace, never one set, and a step of a phase the gate never
        # runs, the docs phase's, is no gate's.
        phases = (
            ", ".join(
                sorted(
                    {
                        r.phase
                        for r in steps_by_name().values()
                        if r.phase in gated
                        and r.extensions
                        and judges_extensions(r, held)
                    }
                )
            )
            or "none"
        )
        if audience == HUMAN:
            lines.append(f"| {named[held]} | {extensions} | {paths} | {phases} |")
        else:
            lines.append(
                f"- {named[held]} ({paths}): holds {extensions}; gate phases {phases}"
            )
    return "\n".join(lines) + "\n"

render_tools

render_tools(root: Path, audience: str | None) -> str

The tools the lock pins, each with its version and the sites requiring it.

Source code in packages/workshop/src/livery/workshop/_prose.py
def render_tools(root: Path, audience: str | None) -> str:
    """The tools the lock pins, each with its version and the sites requiring it."""
    from livery.workshop._tools import current_lock, requirements

    lock = current_lock(root)
    if lock is None or not lock.tools:
        return ""
    sites: dict[str, set[str]] = {}
    for requirement in requirements(root):
        sites.setdefault(requirement.name, set()).add(requirement.site)
    prog = footman.prog()
    hosts = ", ".join(lock.hosts)
    lines = ["# The locked tools", ""]
    if audience == HUMAN:
        lines.append(
            f"`toolroom.lock` pins these for {hosts}; `{prog} toolroom.sync` installs"
            f" them into the tool store, and `{prog} sync` runs it."
        )
    else:
        lines.append(
            f"The tool store holds these versions, pinned by `toolroom.lock` for"
            f" {hosts}; `{prog} sync` installs them, never a hand install:"
        )
    lines.append("")
    for name in sorted(lock.tools):
        where = ", ".join(sorted(sites.get(name, ())))
        scope = ", ".join(lock.tools[name].on)
        lines.append(
            f"- {name} {lock.tools[name].version}"
            + (f": {where}" if where else "")
            + (f" ({scope} only)" if scope else "")
        )
    return "\n".join(lines) + "\n"