livery.workshop._queries¶
livery.workshop._queries ¶
Ask a typed question that extensions answer, combined by the query's declared rule.
A query is declared, by the base in the [queries] section of its
contract.toml and by an extension under [queries.<name>] in its
extension.toml, in one grammar (livery.workshop._queries.QuerySpec):
combine, how the answers make one, union, nearest, agreed
or a function module:name; level, package for a question
about one package and workspace for one about the workspace;
default, the answer while no extension answers; and values, the
only answers it takes. livery.workshop._queries.declared_queries is
every declared query by name, the base's and then each installed
extension's; two extensions declaring one query refuse naming both.
An extension answers a query under [queries] in its declaration
file: <name> = "module:function", a function called with the
package or the workspace root, or a literal, [queries.<name>] value.
It answers under [for.<target>.queries] the same way, and that
answer is asked only while the target is listed and the extension's
listing contributes to it, the rule
livery.workshop.contributions_for reads a target's tables by.
livery.workshop.answer asks a package's set, or the installed set,
in composition order, and combines the answers by the query's rule. A
handle, livery.workshop.Query, names a query and types its answer;
the base's handles are the constants here, and an extension names its
own with Query("docs.members").
Classes:
| Name | Description |
|---|---|
QueryError |
A query asked or answered in a way its declaration cannot take. |
Query |
A handle naming a declared query, typed by its answer. |
QuerySpec |
A query as its declarer declares it: one |
RequirementWriter |
Write a package's requirement on a sibling into one ecosystem's manifest. |
Folder |
Fold one file a check leg's shards each left into the platform leg's one file. |
Functions:
| Name | Description |
|---|---|
merged |
Every name any answer holds, to its one value; a name valued twice refuses. |
owned |
Every item any answer holds; an item two extensions answer refuses. |
base_queries |
The base's queries, read from the |
declared_queries |
Every declared query by name: the base's, then each installed extension's. |
query_spec |
The declared query name; refuses naming the declared ones. |
answered_at |
Where extension answers query about subject now, each place and answer. |
answers |
Each extension that answers query about subject, to its answer. |
answer |
The answer to query about subject: the extensions' answers, combined. |
workspace_answers |
Every workspace-level query's answer about root, by name. |
Attributes:
| Name | Type | Description |
|---|---|---|
T |
|
|
T_co |
|
|
PACKAGE_LEVEL |
|
|
WORKSPACE_LEVEL |
|
|
LEVELS |
|
|
UNION |
|
|
NEAREST |
|
|
AGREED |
|
|
BASE |
|
|
Combine |
|
|
RULES |
Mapping[str, Combine]
|
|
PUBLIC_MODULES |
Query[tuple[str, ...]]
|
|
COMPILE_COMMANDS |
Query[Path | None]
|
|
MODULE_ROOTS |
Query[tuple[str, ...]]
|
|
REFERENCES |
Query[tuple[SourceReferences, ...]]
|
|
CURRENT_VERSION |
Query[str]
|
|
VERSION_FILES |
Query[tuple[Path, ...]]
|
|
REQUIREMENTS |
Query[Mapping[str, str]]
|
|
REQUIREMENT_WRITERS |
Query[tuple[RequirementWriter, ...]]
|
|
TEST_REQUIREMENTS |
Query[Mapping[str, str]]
|
|
TEST_REQUIREMENT_WRITERS |
Query[tuple[RequirementWriter, ...]]
|
|
DISTRIBUTIONS |
Query[tuple[tuple[str, str], ...]]
|
|
REGISTRY |
Query[Registry | None]
|
|
EXECUTABLES |
Query[tuple[str, ...]]
|
|
HOST_TOOLS |
Query[tuple[str, ...]]
|
|
EDITOR_EXTENSIONS |
Query[tuple[str, ...]]
|
|
STORE_SERIES |
Query[tuple[Series | Keyed, ...]]
|
|
JOB_BUILT_MEMBERS |
Query[Mapping[str, str]]
|
|
CHECKOUT_INPUTS |
Query[Mapping[str, str]]
|
|
FOLDERS |
Query[Mapping[str, Folder]]
|
|
Reached |
|
|
REACHES |
Query[tuple[Callable[[Changes], Reached], ...]]
|
|
RULES
module-attribute
¶
COMPILE_COMMANDS
module-attribute
¶
REQUIREMENT_WRITERS
module-attribute
¶
REQUIREMENT_WRITERS: Query[tuple[RequirementWriter, ...]] = Query('requirement-writers')
TEST_REQUIREMENTS
module-attribute
¶
TEST_REQUIREMENT_WRITERS
module-attribute
¶
TEST_REQUIREMENT_WRITERS: Query[tuple[RequirementWriter, ...]] = Query('test-requirement-writers')
DISTRIBUTIONS
module-attribute
¶
EDITOR_EXTENSIONS
module-attribute
¶
STORE_SERIES
module-attribute
¶
JOB_BUILT_MEMBERS
module-attribute
¶
CHECKOUT_INPUTS
module-attribute
¶
REACHES
module-attribute
¶
QueryError ¶
Bases: RuntimeError
A query asked or answered in a way its declaration cannot take.
A name no extension declares, a question asked at the other level, an answer off the query's values, or answers its rule cannot combine; the message names the query and the extensions.
Query
dataclass
¶
Query(name: str)
QuerySpec
dataclass
¶
QuerySpec(name: str, combine: str | Reference = UNION, level: str = PACKAGE_LEVEL, default: object = None, values: tuple[object, ...] | None = None, extension: str = BASE)
A query as its declarer declares it: one [queries.<name>] table.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The key an extension answers it under: |
combine |
str | Reference
|
How the answers make one. |
level |
str
|
|
default |
object
|
The answer while no extension answers; None takes the rule's answer over no answers, an empty union, no nearest, no agreement, a function's answer over nothing. |
values |
tuple[object, ...] | None
|
The only answers the query takes; None takes any. |
extension |
str
|
The extension that declares it; the base for its own. |
RequirementWriter ¶
Bases: Protocol
Write a package's requirement on a sibling into one ecosystem's manifest.
An extension answers the requirement-writers query with its
writers, and the test-requirement-writers query with the writers
of a requirement the package's tests alone have. Every writer of a
package's set is called for each requirement. A writer takes a
sibling of its own ecosystem alone: for any other sibling it writes
nothing and returns None, so the requirement lands in the manifest
of the sibling's ecosystem. A requirement no writer of the set
takes refuses, naming the sibling's set.
Methods:
| Name | Description |
|---|---|
__call__ |
Write dependency at floor into package's manifest. |
__call__ ¶
Write dependency at floor into package's manifest.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
package
|
Package
|
The package whose manifest gains the requirement. |
required |
dependency
|
Package
|
The sibling it requires. |
required |
floor
|
str
|
The lowest version of dependency the requirement takes. |
required |
Returns:
| Type | Description |
|---|---|
list[str] | None
|
The files changed, relative to the package; empty when the |
list[str] | None
|
manifest names dependency already. None for a sibling |
list[str] | None
|
outside the writer's ecosystem, which it leaves alone. |
Source code in packages/workshop/src/livery/workshop/_queries.py
Folder ¶
Bases: Protocol
Fold one file a check leg's shards each left into the platform leg's one file.
An extension answers the ci.fold query with one folder per file
its leg entry leaves in the leg's spool, by the file's name. The
gate job calls it with the shards' files, in shard order, each as
the per-run ref holds it, and puts what it returns on the platform
leg's ref under the same name, where the judges read it as one
leg's file.
Methods:
| Name | Description |
|---|---|
__call__ |
The one file of the platform leg, from shards' files. |
__call__ ¶
The one file of the platform leg, from shards' files.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
shards
|
Sequence[Mapping[str, Any]]
|
The file as each shard left it, in shard order. |
required |
Returns:
| Type | Description |
|---|---|
Mapping[str, Any]
|
The folded file. |
Raises:
| Type | Description |
|---|---|
ValueError
|
When the shards' files cannot be one leg's, naming what differs; the fold is red with it. |
Source code in packages/workshop/src/livery/workshop/_queries.py
merged ¶
Every name any answer holds, to its one value; a name valued twice refuses.
The rule of the requirements, test-requirements and
job-built-members queries, which the base's contract file names.
Source code in packages/workshop/src/livery/workshop/_queries.py
owned ¶
Every item any answer holds; an item two extensions answer refuses.
The executables query's rule, which the base's contract file
names.
Source code in packages/workshop/src/livery/workshop/_queries.py
base_queries
cached
¶
The base's queries, read from the [queries] section of its contract file.
In the file's order, each spec naming the base as its declarer.
Raises:
| Type | Description |
|---|---|
DeclarationError
|
when a section is off the shape a query's declaration has. |
Source code in packages/workshop/src/livery/workshop/_queries.py
declared_queries
cached
¶
Every declared query by name: the base's, then each installed extension's.
An installed extension's declaration is read whether the workspace lists it or not, so an answer to its query reads the same anywhere; a query nobody listed declares is asked by nobody.
Raises:
| Type | Description |
|---|---|
DeclarationError
|
when two extensions declare one query. |
Source code in packages/workshop/src/livery/workshop/_queries.py
query_spec ¶
The declared query name; refuses naming the declared ones.
Raises:
| Type | Description |
|---|---|
QueryError
|
when no extension declares name. |
Source code in packages/workshop/src/livery/workshop/_queries.py
answered_at ¶
answered_at(subject: Package | Path, extension: str, declared: Declaration, query: str) -> list[tuple[tuple[str, ...], Reference | DeclaredValue]]
Where extension answers query about subject now, each place and answer.
A place is a key path in declared's file: the top level,
queries.<query>, always, and a [for.<target>] table's,
for.<target>.queries.<query>, while target is listed and the
extension's listing contributes to it. Decided from the
declarations and the contracts' lists alone, asking nothing; empty
when no place answers now. livery.workshop._queries.answers
asks the places it names.
Source code in packages/workshop/src/livery/workshop/_queries.py
answers ¶
Each extension that answers query about subject, to its answer.
subject is the package for a package-level query, and the
workspace root, or a directory in the workspace, for a
workspace-level one. Each declaration is read through lookup,
the installed ones when absent. An extension answers at the top
level of its declaration file, and in a [for.<target>] table
while target is listed and the extension's listing contributes to
it (livery.workshop._queries.answered_at); answering in two of
those places, it answers a union query with every item of both.
Raises:
| Type | Description |
|---|---|
QueryError
|
when no extension declares the query, when subject is at the other level, when an answer is off the query's values, naming the extension, or when an extension answers a query of another rule in two places, naming both. |
Source code in packages/workshop/src/livery/workshop/_queries.py
answer ¶
The answer to query about subject: the extensions' answers, combined.
subject is the package for a package-level query, answered by its set in composition order, and the workspace root, or a directory in the workspace, for a workspace-level one, answered by the installed set in composition order. With no extension answering, the query's declared default, or its rule's answer over nothing.
Raises:
| Type | Description |
|---|---|
QueryError
|
when no extension declares the query, when subject is at the other level, when an answer is off the query's values, or when the answers break the query's rule; the message names the query and the extensions, and a package's path for a package-level query. |
Source code in packages/workshop/src/livery/workshop/_queries.py
workspace_answers ¶
Every workspace-level query's answer about root, by name.
A rendered template reads queries["python.dev-group"] through
it; a name no extension declares at the workspace level is absent.