livery.workshop._seeds¶
livery.workshop._seeds ¶
Write the files a birth starts with, which are the workspace's own afterwards.
A workspace's birth writes the seed tree project. A package's birth
writes the seed tree package-base, then the files of the template
the package is born from. A seed is a file an extension ships under
content/seeds/<tree>/, and every extension of the workspace's stack
adds the seeds it ships for the tree: the base's package-base holds
the docs page and its nav, and a listed extension such as the
changelog's adds its own.
A template is declared under [templates.<name>] by an installed
extension's extension.toml, or by the base's contract.toml: its
doc, the extensions a package born from it lists, and
extends, the template whose files the birth writes first. Its files
live under content/templates/<name>/ beside the file that declares
it.
A template declares creation options under
[templates.<name>.options.<option>]: a doc, either choices or
a type, and a default; one without a default is required. A
template that extends another takes the other's options too, and its
fixes table gives an answer to an option of a template it extends,
which a birth from it then takes no answer for. fm
new.package.<template> <name> --<option>=<answer> answers them
(livery.workshop._templates.generate_template_verbs makes the
verb), and every answer is checked before anything is written
(answered). Each answer renders the
files as a template variable, the option's name with its hyphens as
underscores (--package-type is package_type). Nothing stores the
answers: a later step that needs one reads the file the answer wrote.
A workspace offers the base's templates and those of the extensions
its installed set holds. A birth needs every extension the template's
chain names in the installed set and installed, and it refuses
otherwise, naming what to list or that fm sync installs it: a
creation installs nothing. Each template of the chain lists only
extensions that compose something in a package, as a package's list
does, or the birth refuses naming the entry. A template is read at a
birth alone: nothing records which one a package came from.
create writes a .jinja file rendered with minijinja, its suffix
dropped, and any other file byte for byte; path names render too
(src/{{ source_path }}/...). A .jinja file that renders to
whitespace alone is not written, so a file depends on an answer by
wrapping its whole body in {% if <variable> %} and {% endif %}.
A file that exists is never touched, and nothing is receipted: once
written, a file belongs to the workspace, and no step judges it.
For one path, a template's file wins over the seeds and over the files
of the template it extends. Two extensions seeding one path of a tree
follow the shipped files' rule instead: the one later in composition
order, which requires the other, declares the other's under
[replaces] or [deletes] in its extension.toml, or the birth
refuses naming both. The fragment
engine keeps the composed files current; this module writes these once.
Functions:
| Name | Description |
|---|---|
derived |
The names a package's seeds derive from its name and its namespace. |
template_files |
The directory template's files live in, beside the file declaring it. |
base_templates |
The templates the base declares in its contract file, by name. |
available_templates |
Every template the base or an installed distribution declares, by name. |
installed_templates |
The templates the workspace at or above start offers, by name. |
described |
Each of templates on a line of its own, its name then its doc. |
template_chain |
The templates a birth from name writes, in order: the one extended first. |
chain_needs |
The extensions a birth from chain needs, first met first. |
chain_options |
The options a birth from chain takes, and the answers its templates fix. |
described_options |
Each of options as |
answered |
The template variables a birth from chain renders with, each answer checked. |
verb_options |
The options the verb of the template name offers, read from templates. |
resolved_chain |
The chain of name in the workspace at root, from the installed declarations. |
birth_chain |
The chain a birth from name writes in the workspace at root, once judged. |
plan |
Each file's path, rendered, to the fragment that writes it. |
create |
Write the seeds of tree, then templates' files, into destination. |
create_package |
Write a package born from template into destination; the paths written. |
Attributes:
| Name | Type | Description |
|---|---|---|
SEEDS |
The |
|
TEMPLATES |
The |
|
TEMPLATE |
The suffix of a file rendered with minijinja; any other is copied. |
|
PROJECT |
The tree a workspace's birth writes. |
|
PACKAGE_BASE |
The tree every package's birth writes before its template's files. |
|
PROJECT_SEEDS |
|
TEMPLATES
module-attribute
¶
The content/ subdirectory a template's files live under, by its name.
TEMPLATE
module-attribute
¶
The suffix of a file rendered with minijinja; any other is copied.
PACKAGE_BASE
module-attribute
¶
The tree every package's birth writes before its template's files.
The base's own holds the docs page and its nav, and a listed extension may ship seeds of its own under the same tree.
derived ¶
The names a package's seeds derive from its name and its namespace.
The distribution name decides the import path, as it does in this
repository: each hyphen after the namespace's own prefix is one
namespace level (acme-tools-store in acme imports as
acme.tools.store). The directory decides nothing, so a package
in a group directory (extensions/widgets, named
acme-extensions-widgets) imports as acme.extensions.widgets.
project_slug is the last level, source_path the directory
under src/ and tests/, and import_path the dotted import.
Source code in packages/workshop/src/livery/workshop/_seeds.py
template_files ¶
template_files(template: DeclaredTemplate) -> Path
The directory template's files live in, beside the file declaring it.
base_templates
cached
¶
base_templates() -> dict[str, DeclaredTemplate]
The templates the base declares in its contract file, by name.
Read from the one parse of the file its other readers share.
Raises:
| Type | Description |
|---|---|
Failed
|
for a template off its shape, naming the file and the key. |
Source code in packages/workshop/src/livery/workshop/_seeds.py
available_templates ¶
available_templates() -> dict[str, DeclaredTemplate]
Every template the base or an installed distribution declares, by name.
Read from the declaration files alone, without judging the rest of
an extension's file or importing anything, and whatever the
workspace lists: a birth from a template the workspace does not
offer names the extension that declares it. installed_templates
is the ones a workspace offers.
Raises:
| Type | Description |
|---|---|
Failed
|
for a template two extensions declare, naming both, and for a template off its shape, naming the file and the key. |
Source code in packages/workshop/src/livery/workshop/_seeds.py
installed_templates ¶
installed_templates(start: Path | None = None) -> dict[str, DeclaredTemplate]
The templates the workspace at or above start offers, by name.
The base's, and those of each extension the workspace's installed
set holds that an installed distribution declares. Outside a
workspace, the base's alone. Each has a verb,
fm new.package.<template>, which the mount makes from the
declarations it reads, and a refusal naming the installed templates
names these.
Raises:
| Type | Description |
|---|---|
Failed
|
as |
Source code in packages/workshop/src/livery/workshop/_seeds.py
described ¶
described(templates: Mapping[str, DeclaredTemplate]) -> str
Each of templates on a line of its own, its name then its doc.
Source code in packages/workshop/src/livery/workshop/_seeds.py
template_chain ¶
template_chain(name: str, templates: Mapping[str, DeclaredTemplate] | None = None, *, offered: Mapping[str, DeclaredTemplate] | None = None) -> tuple[DeclaredTemplate, ...]
The templates a birth from name writes, in order: the one extended first.
name is last, after the template it extends and that template's own chain. The chain is read from templates, every available one when None, and a refusal names offered as the installed templates, templates when None.
Raises:
| Type | Description |
|---|---|
Failed
|
for a name no installed extension declares, an
|
Source code in packages/workshop/src/livery/workshop/_seeds.py
chain_needs ¶
chain_needs(chain: Sequence[DeclaredTemplate]) -> tuple[str, ...]
The extensions a birth from chain needs, first met first.
Each template's extensions, then the extension that declares
it, the base aside, from the template extended first to the one
born: a workspace offers a template while its installed set holds
the extension that declares it, and the template it extends with
it.
Source code in packages/workshop/src/livery/workshop/_seeds.py
chain_options ¶
chain_options(chain: Sequence[DeclaredTemplate]) -> tuple[dict[str, TemplateOption], dict[str, Answer]]
The options a birth from chain takes, and the answers its templates fix.
Each template of the chain, the one extended first, adds the options
it declares and fixes the answers its fixes names: a fixed option
is no longer one the birth takes.
Returns:
| Type | Description |
|---|---|
dict[str, TemplateOption]
|
The options by name, in declaration order, and the fixed answers |
dict[str, Answer]
|
by option name. |
Raises:
| Type | Description |
|---|---|
Failed
|
for a template that fixes an option no template it extends declares, a fixed answer that does not answer the option, and an option a template of the chain declares again. |
Source code in packages/workshop/src/livery/workshop/_seeds.py
described_options ¶
described_options(options: Mapping[str, TemplateOption]) -> str
Each of options as --<option>, for a refusal; none for none.
answered ¶
The template variables a birth from chain renders with, each answer checked.
answers holds an answer by each option's variable (package_type
for --package-type), as the template's verb passes them. An option
without an answer takes its default, and a fixed option the answer
its template fixes.
Raises:
| Type | Description |
|---|---|
Failed
|
for an answer to an option the born template does not take, a required option without an answer, and an answer outside an option's choices or of the wrong type; each refusal names the option and what it takes. |
Source code in packages/workshop/src/livery/workshop/_seeds.py
verb_options ¶
verb_options(name: str, templates: Mapping[str, DeclaredTemplate]) -> tuple[TemplateOption, ...]
The options the verb of the template name offers, read from templates.
The options of its chain less the answers the chain fixes, as a
birth takes them (chain_options). A chain that templates do not
resolve, or whose options disagree, offers the options name
declares itself: its verb exists all the same, and running it
refuses as a birth from it refuses.
Source code in packages/workshop/src/livery/workshop/_seeds.py
resolved_chain ¶
resolved_chain(root: Path, name: str) -> tuple[DeclaredTemplate, ...]
The chain of name in the workspace at root, from the installed declarations.
Refuses as birth_chain does for a template no installed extension
declares, and for a chain that does not resolve; the extensions the
chain needs are birth_chain's to judge.
A template that extends one no installed extension declares, while
the part of its chain that resolves needs an extension the
workspace's lists do not hold, refuses naming that extension: listed
and synced, its distribution may declare the template extended, as
python's declares the python-library the base's
workshop-extension extends.
Raises:
| Type | Description |
|---|---|
Failed
|
for a template, or a template it extends, that no
installed extension declares, naming |
Source code in packages/workshop/src/livery/workshop/_seeds.py
birth_chain ¶
birth_chain(root: Path, name: str) -> tuple[DeclaredTemplate, ...]
The chain a birth from name writes in the workspace at root, once judged.
A birth needs every extension the chain names (chain_needs) in
the workspace's installed set, and each of them, with what it
requires, installed: a creation installs nothing, so a refusal
says what to list, and that fm sync installs it. This writes
nothing.
Raises:
| Type | Description |
|---|---|
Failed
|
in this order: for a template, or a template it
extends, that no installed extension declares while the
installed set holds an extension no installed distribution
declares yet, naming each and |
Source code in packages/workshop/src/livery/workshop/_seeds.py
plan ¶
plan(root: Path, tree: str, data: Mapping[str, Any], *, templates: Sequence[DeclaredTemplate] = ()) -> dict[str, Fragment]
Each file's path, rendered, to the fragment that writes it.
The seeds of tree that the stack ships come first, then each of templates in order; a template's file takes a path from the seeds and from the templates before it.
Raises:
| Type | Description |
|---|---|
Failed
|
for two extensions seeding one path with no declaration between them, a declaration naming a seed no listed extension ships, and one naming a seed of an extension the declaring one does not require. |
Source code in packages/workshop/src/livery/workshop/_seeds.py
create ¶
create(root: Path, destination: Path, tree: str, data: Mapping[str, Any], *, templates: Sequence[DeclaredTemplate] = ()) -> list[str]
Write the seeds of tree, then templates' files, into destination.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
root
|
Path
|
The workspace whose stack ships the seeds. |
required |
destination
|
Path
|
Where the files land: the root for a project, the member's directory for a package. |
required |
tree
|
str
|
The seed tree, |
required |
data
|
Mapping[str, Any]
|
What the files read when they render. |
required |
templates
|
Sequence[DeclaredTemplate]
|
The templates whose files come after the seeds, in order: a later one wins for a path. |
()
|
Returns:
| Type | Description |
|---|---|
list[str]
|
The paths written, relative to destination. A path that |
list[str]
|
already exists is left alone and is not listed, and so is a |
list[str]
|
|
Source code in packages/workshop/src/livery/workshop/_seeds.py
create_package ¶
create_package(root: Path, destination: Path, template: str, data: Mapping[str, Any], answers: Mapping[str, object] | None = None) -> list[str]
Write a package born from template into destination; the paths written.
The package-base seeds come first, then the files of each
template of the chain, the one extended first and template last
(template_chain). The files read the born template's
extensions, in their canonical form, as package_extensions,
spelled as a contract spells the list: the contract writes it. They
read the answers to the chain's options as variables, answers
holding each by its variable (answered). Nothing is written until
every template of the chain and every answer is judged, and nothing
is installed: the workspace at root holds and has installed every
extension the chain needs (birth_chain).
Raises:
| Type | Description |
|---|---|
Failed
|
for a template the workspace cannot take
( |