Skip to content

livery.workshop._new_project

livery.workshop._new_project

fm new.project: birth, end to end, one idempotent verb.

Seed the contract, write the project's seeds, lock and sync, deliver the extension content, generate the CI files, initialise git, then the forge half: create the repository, assert its configuration, push, and open the unarmed setup pull request. Every step detects done and walks past it, so re-running is the recovery procedure and a kill between any two steps costs nothing. --local is everything that stays on the machine and nothing that leaves it.

The task lives above any repository, so the workspace it makes never needed one. The workspace's extensions are the stock list (birth_extensions) unless --extensions names them, and the birth writes them as their canonical list.

Functions:

Name Description
birth_extensions

The extensions a birth lists, from the running App's builtin providers.

canonical_extensions

names as the canonical list a birth writes.

new_project

Create a workspace in an empty or new folder, end to end, as one verb.

Attributes:

Name Type Description
PUBLISHED_INDEX
STOCK

PUBLISHED_INDEX module-attribute

PUBLISHED_INDEX = 'https://docs.willem.net/livery/tools/'

STOCK module-attribute

STOCK = ('basedpyright', 'changelog', 'coverage', 'mkdocstrings', 'pytest', 'python', 'ruff')

birth_extensions

birth_extensions(builtin: list[str] | tuple[str, ...]) -> list[str]

The extensions a birth lists, from the running App's builtin providers.

Footman's own providers and the base are never listed. A stock App (the base among its builtins) lists the stock list (STOCK), and a branded App its own extensions beside them, all as their canonical list (canonical_extensions). A brand's extension takes another's file or step by requiring it and declaring the replacement, never by where it is listed.

Source code in packages/workshop/src/livery/workshop/_new_project.py
def birth_extensions(builtin: list[str] | tuple[str, ...]) -> list[str]:
    """The extensions a birth lists, from the running App's builtin providers.

    Footman's own providers and the base are never listed. A stock App
    (the base among its builtins) lists the stock list (``STOCK``), and
    a branded App its own extensions beside them, all as their
    canonical list (``canonical_extensions``). A brand's extension
    takes another's file or step by requiring it and declaring the
    replacement, never by where it is listed.
    """
    kept = [entry for entry in builtin if not entry.startswith("footman.")]
    kept = kept or ["livery.workshop"]
    listed = [entry for entry in kept if entry != "livery.workshop"]
    if "livery.workshop" in kept:
        listed[:0] = STOCK
    return canonical_extensions(listed)

canonical_extensions

canonical_extensions(names: list[str] | tuple[str, ...]) -> list[str]

names as the canonical list a birth writes.

The minimal list of their set in composition order, as the installed declarations compose it: an extension another one requires is left out, and a name no installed distribution declares requires nothing.

Raises:

Type Description
Failed

when the set's declared order has no start, naming the cycle.

Source code in packages/workshop/src/livery/workshop/_new_project.py
def canonical_extensions(names: list[str] | tuple[str, ...]) -> list[str]:
    """*names* as the canonical list a birth writes.

    The minimal list of their set in composition order, as the installed
    declarations compose it: an extension another one requires is left
    out, and a name no installed distribution declares requires
    nothing.

    Raises:
        Failed: when the set's declared order has no start, naming the
            cycle.
    """
    from livery.workshop._composition import OrderCycle, canonical
    from livery.workshop._extensions import installed_declaration

    try:
        return list(canonical(names, installed_declaration))
    except OrderCycle as error:
        fail(f"the extensions cannot be listed: {error}")

new_project

new_project(folder: Annotated[Arg[str], doc('where the project is born, an empty or new folder; this one by default')] = '', name: Annotated[str, doc("the workspace's name, also the repository's; the folder's by default")] = '', forge: Annotated[str, doc('github, gitea, or gitlab; github by default')] = '', owner: Annotated[str, doc('the owner or organisation the repository lives under')] = '', url: Annotated[str, doc('the forge server (empty for github.com and gitlab.com)')] = '', description: Annotated[str, doc('one sentence for the virtual root')] = '', author: Annotated[str, doc("the authors entry's name (default: git config)")] = '', email: Annotated[str, doc("the authors entry's email (default: git config)")] = '', namespace: Annotated[str, doc('dotted namespace packages live in')] = '', extension: Annotated[str, doc("also scaffold this named extension package, with its branded App, and self-host it: the workspace becomes the extension's home")] = '', local: Annotated[bool, doc('everything that stays on the machine, nothing that leaves it')] = False, extensions: Annotated[str, doc("the extensions the workspace lists, comma-separated, each by name, written as their canonical list; the stock list by default, which names python for the workspace's own tests")] = '', resume: Annotated[bool, hidden] = False) -> None

Create a workspace in an empty or new folder, end to end, as one verb.

The birth seeds the contract, whose [workspace] extensions is the stock list or the one --extensions names, written as its canonical list: no extension another one requires, in composition order. The stock list names python: the workspace's own tests hold the root's set, and run while it holds python. It writes the project's files, locks and syncs its environment, then hands the rest to the runner that environment holds, run as new.project --resume inside the project. There the project's own extensions are mounted, so its tools, its composed and generated files and its forge half come from them at the versions it locked. A folder that holds a project refuses, naming --resume, which finishes that project's birth: every step of it detects done and walks past it, so it is also the recovery after a birth that stopped part way. Headless runs never hang; a missing required answer is a refusal listing what to pass.

Source code in packages/workshop/src/livery/workshop/_new_project.py
@new_group.task(name="project", expose="always", interactive=True, cwd="asinvoked")
def new_project(
    folder: Annotated[
        Arg[str],
        doc("where the project is born, an empty or new folder; this one by default"),
    ] = "",
    name: Annotated[
        str, doc("the workspace's name, also the repository's; the folder's by default")
    ] = "",
    forge: Annotated[str, doc("github, gitea, or gitlab; github by default")] = "",
    owner: Annotated[
        str, doc("the owner or organisation the repository lives under")
    ] = "",
    url: Annotated[
        str, doc("the forge server (empty for github.com and gitlab.com)")
    ] = "",
    description: Annotated[str, doc("one sentence for the virtual root")] = "",
    author: Annotated[str, doc("the authors entry's name (default: git config)")] = "",
    email: Annotated[str, doc("the authors entry's email (default: git config)")] = "",
    namespace: Annotated[str, doc("dotted namespace packages live in")] = "",
    extension: Annotated[
        str,
        doc(
            "also scaffold this named extension package, with its branded App,"
            " and self-host it: the workspace becomes the extension's home"
        ),
    ] = "",
    local: Annotated[
        bool, doc("everything that stays on the machine, nothing that leaves it")
    ] = False,
    extensions: Annotated[
        str,
        doc(
            "the extensions the workspace lists, comma-separated, each by name,"
            " written as their canonical list; the stock list by default, which"
            " names python for the workspace's own tests"
        ),
    ] = "",
    resume: Annotated[bool, hidden] = False,
) -> None:
    """Create a workspace in an empty or new folder, end to end, as one verb.

    The birth seeds the contract, whose ``[workspace] extensions`` is
    the stock list or the one ``--extensions`` names, written as its
    canonical list: no extension another one requires, in composition
    order. The stock list names python: the workspace's own tests hold
    the root's set, and run while it holds python. It writes the
    project's files, locks and syncs its environment, then hands the
    rest to the runner that environment holds, run as
    ``new.project --resume`` inside the project. There the project's
    own extensions are mounted, so its
    tools, its composed and generated files and its forge half come
    from them at the versions it locked. A folder that holds a project
    refuses, naming ``--resume``, which finishes that project's birth:
    every step of it detects done and walks past it, so it is also
    the recovery after a birth that stopped part way. Headless runs
    never hang; a missing required answer is a refusal listing what to
    pass.
    """
    # The task's directory is the launch directory (`asinvoked`), not
    # the directory of whichever tasks file mounted the verb: the folder
    # means where the caller stands.
    here = footman.cwd()
    root = (here / folder).resolve() if folder else here
    prog = footman.prog()
    held = (root / "workshop.toml").is_file()
    if resume:
        if not held:
            fail(
                f"{root} holds no project to resume: `{prog} new.project`"
                " births one into an empty or new folder"
            )
        from livery.workshop._extensions import workspace_root

        # Inside the project this process is its own runner; elsewhere
        # the project's runner finishes it.
        finish = _finish if workspace_root() == root else _hand_off
        finish(
            root, forge=forge, owner=owner, url=url, local=local, extension=extension
        )
        return
    if held:
        fail(
            f"{root} holds a project already; `{prog} new.project --resume`"
            " finishes its birth"
        )
    if root.exists() and any(root.iterdir()):
        fail(f"{root} is not empty: a project is born into an empty or new folder")
    name = name or root.name
    forge = forge or "github"
    _check_answers(name, forge=forge, owner=owner, url=url, local=local)
    # The contract: a birth-time seed the render never touches. The
    # list is the running App's own builtin providers, minus footman's
    # and the base, which is never listed (contract 19): a branded App's
    # children carry its extensions. Stock fm's carry the stock list,
    # whose distributions the newborn's sync installs.
    # footman.BUILTIN is an import-time snapshot of the stock brand;
    # the running App's own list lives in _paths.builtin() (a public
    # runtime accessor is footman#536's family). It is composed before
    # the folder is made, so a list that cannot be written leaves none.
    from livery.footman import builtins

    named = [e.strip() for e in extensions.split(",") if e.strip()]
    listed = canonical_extensions(named) if named else birth_extensions(builtins())
    root.mkdir(parents=True, exist_ok=True)
    contract = root / "workshop.toml"
    spelled = ", ".join(f'"{entry}"' for entry in listed)
    year = str(datetime.datetime.now(tz=datetime.UTC).year)
    author_name = author or _git_config("user.name") or f"{name} authors"
    author_email = email or _git_config("user.email")
    person = f"{{ name = {toml_string(author_name)}"
    if author_email:
        person += f", email = {toml_string(author_email)}"
    person += " }"
    lines = [
        "[workspace]",
        f"name = {toml_string(name)}",
        "description = "
        + toml_string(description or f"The {name} monorepo (virtual root)."),
        f"namespace = {toml_string(namespace or name.replace('-', '_'))}",
        f"authors = [{person}]",
        f'copyright-year = "{year}"',
        f"extensions = [{spelled}]",
    ]
    lines += ["", "[forge]", f'kind = "{forge}"']
    if owner:
        lines.append(f'owner = "{owner}"')
    if url:
        lines.append(f'url = "{url}"')
    lines += [
        "",
        "[toolroom]",
        f'index = "{PUBLISHED_INDEX}"',
        "",
        "[ci]",
        'runners = ["ubuntu-latest"]',
        'required-context = "gate"',
    ]
    contract.write_text("\n".join(lines) + "\n", encoding="utf-8")
    print("  workshop.toml: seeded")

    _prepare(root)
    _hand_off(root, local=local, extension=extension)