livery.workshop._categories¶
livery.workshop._categories ¶
The two questions the workshop asks about a path, on two axes.
A path's category says what it is to its package: source, test,
test support, configuration, and whatever a table adds, prose,
example, asset, nav. Its channel says who wrote it and where to
edit it: rendered, generated, materialised, seed, contract, yours.
Neither answer can be read off the other, so the vocabularies stay
apart: category_of answers the first, and channel_of the second
from the rules register_channels adds.
A category rule is a pattern in a table, since nothing a category
needs reads state: an extension declares its own table under
[categories] in its extension.toml, and the base's two tables
are data here, BASE_RULES beneath every package's extensions and
WORKSPACE_RULES for the workspace's own unit. A channel rule is a
callable with a rank, since it reads the delivery manifest, the
emitted set and the template source.
The most specific category rule wins. Between rules of one
specificity from two tables, the nearer table wins: of the extensions
a package holds, the one later in composition order, where an
extension comes after the extensions it requires and the others go
alphabetically, and the base's table last. Two rules of one table and
one specificity that claim one path for different categories, or from
different extensions, refuse naming both, so two checkouts of one
commit answer alike and the order a table lists its rules in settles
nothing in silence. A package's contract may reassign its own paths
among the categories,
[categories] vendored = ["docs/assets/vendor/**"], and that table
wins over every rule of its extensions and the base.
Classes:
| Name | Description |
|---|---|
CategoryError |
Two rules claim one path at one level; the message names both. |
CategoryRule |
One pattern's claim on a category. |
Category |
A path's category, and who supplied the rule that answered. |
Provenance |
One file's channel answer: the channel, the source, the edit path. |
ChannelRule |
One callable's claim on the channel axis. |
Channel |
A path's channel answer and who supplied it. |
Functions:
| Name | Description |
|---|---|
specificity |
pattern's specificity: the literal characters it names, then its segments. |
matches |
Whether pattern claims path, a relative posix path. |
category_rules |
The rules that answer for a package holding extensions, the nearest first. |
workspace_rules |
The rules that answer for the workspace's own unit: its table alone. |
extension_rules |
The category rules extension declares, in a table named after it. |
category_of |
Say what path, relative to package's directory, is to the package. |
register_channels |
Register channel rules; a rule of the same name is replaced. |
channel_rules |
Every channel rule, highest rank first, registration order within a rank. |
channel_of |
Who wrote relative inside root, or None when no rule claims it. |
known_categories |
The four builtin categories, and every category the base's two tables name. |
Attributes:
| Name | Type | Description |
|---|---|---|
SOURCE |
|
|
TEST |
|
|
TEST_SUPPORT |
|
|
CONFIGURATION |
|
|
EXAMPLE |
|
|
WORKSPACE |
|
|
BASE_TABLE |
|
|
ChannelJudge |
|
|
BASE_RULES |
tuple[CategoryRule, ...]
|
|
WORKSPACE_RULES |
tuple[CategoryRule, ...]
|
|
ChannelJudge
module-attribute
¶
BASE_RULES
module-attribute
¶
BASE_RULES: tuple[CategoryRule, ...] = tuple(CategoryRule(BASE_TABLE, pattern, category, _BASE) for pattern, category in (('docs/**/*.md', 'prose'), ('docs/nav.toml', 'nav'), ('docs/assets/**', 'asset'), ('docs/examples/**/*.py', EXAMPLE), ('docs/_generated/**', 'generated'), ('**', CONFIGURATION)))
WORKSPACE_RULES
module-attribute
¶
WORKSPACE_RULES: tuple[CategoryRule, ...] = tuple(CategoryRule(WORKSPACE, pattern, category, _BASE) for pattern, category in (('tests/**/test_*.py', TEST), ('tests/**/*_test.py', TEST), ('tests/**', TEST_SUPPORT), ('notes/**', 'notes'), ('docs/**', 'site'), ('zensical.toml', 'site'), ('README.md', 'readme'), ('**', CONFIGURATION)))
CategoryError ¶
Bases: ValueError
Two rules claim one path at one level; the message names both.
Two category rules of one table and one specificity, or two channel rules of one rank.
CategoryRule
dataclass
¶
One pattern's claim on a category.
Attributes:
| Name | Type | Description |
|---|---|---|
table |
str
|
The table the rule belongs to: the extension that
declares it, or |
pattern |
str
|
A path pattern relative to the package, |
category |
str
|
The label the pattern claims. |
extension |
str
|
The extension that supplied the rule; the base's own is
|
Category
dataclass
¶
Provenance
dataclass
¶
ChannelRule
dataclass
¶
ChannelRule(name: str, judge: ChannelJudge, rank: int, extension: str)
One callable's claim on the channel axis.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The rule's name, for a refusal. |
judge |
ChannelJudge
|
Answers for a path, or None when the rule does not claim it; called with the root, the relative path, and the emitted set when the caller computed one. |
rank |
int
|
Higher ranks answer first; two rules of one rank both answering refuse naming both. |
extension |
str
|
The extension that registered the rule. |
Channel
dataclass
¶
Channel(provenance: Provenance, supplier: str)
A path's channel answer and who supplied it.
Attributes:
| Name | Type | Description |
|---|---|---|
provenance |
Provenance
|
The answer. |
supplier |
str
|
The extension whose rule answered. |
specificity ¶
pattern's specificity: the literal characters it names, then its segments.
tests/**/test_*.py names 13 characters and beats tests/**
with 5, which beats ** with none; a longer path prefix beats
a shorter one the same way.
Source code in packages/workshop/src/livery/workshop/_categories.py
matches ¶
category_rules ¶
category_rules(extensions: Iterable[str]) -> tuple[CategoryRule, ...]
The rules that answer for a package holding extensions, the nearest first.
Each extension's declared table, the one later in composition order first, then the base's table. While the extensions' declared order has no start, they come in alphabetical order. An extension nothing installed declares adds no rule.
Source code in packages/workshop/src/livery/workshop/_categories.py
workspace_rules ¶
workspace_rules() -> tuple[CategoryRule, ...]
extension_rules ¶
extension_rules(extension: str) -> tuple[CategoryRule, ...]
The category rules extension declares, in a table named after it.
Empty for an extension nothing installed declares.
Source code in packages/workshop/src/livery/workshop/_categories.py
category_of ¶
Say what path, relative to package's directory, is to the package.
The package's own [categories] exception answers first. Then
the most specific rule of the tables that answer for the package
wins, and between rules of one specificity the nearer table's: the
extension later in composition order, the base's table last.
Nothing matching is configuration, which the base's table also says
last. The base's table names the documentation's paths (prose,
nav, asset, example, generated) and everything else
configuration; the extensions a package holds name the rest,
such as source and test. The workspace's own tests
(livery.workshop.WORKSPACE_TESTS) are answered by one table of
the base's alone, in which a file under tests/ is test or
test-support.
Returns:
| Type | Description |
|---|---|
Category
|
The category's name, who supplied the rule that answered, and |
Category
|
the pattern that matched. |
Raises:
| Type | Description |
|---|---|
CategoryError
|
a ValueError, when two rules of one specificity and one table claim path for different categories or from different extensions. |
Source code in packages/workshop/src/livery/workshop/_categories.py
register_channels ¶
register_channels(rules: Iterable[ChannelRule]) -> None
Register channel rules; a rule of the same name is replaced.
Source code in packages/workshop/src/livery/workshop/_categories.py
channel_rules ¶
channel_rules() -> tuple[ChannelRule, ...]
Every channel rule, highest rank first, registration order within a rank.
channel_of ¶
Who wrote relative inside root, or None when no rule claims it.
Raises:
| Type | Description |
|---|---|
CategoryError
|
when two rules of one rank both claim the path. |
Source code in packages/workshop/src/livery/workshop/_categories.py
known_categories ¶
The four builtin categories, and every category the base's two tables name.