Skip to content

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 [queries.<name>] table.

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 [queries] section of its contract file.

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], ...]]

T module-attribute

T = TypeVar('T')

T_co module-attribute

T_co = TypeVar('T_co', covariant=True)

PACKAGE_LEVEL module-attribute

PACKAGE_LEVEL = 'package'

WORKSPACE_LEVEL module-attribute

WORKSPACE_LEVEL = 'workspace'

LEVELS module-attribute

UNION module-attribute

UNION = 'union'

NEAREST module-attribute

NEAREST = 'nearest'

AGREED module-attribute

AGREED = 'agreed'

BASE module-attribute

BASE = 'livery.workshop'

Combine module-attribute

Combine = Callable[[Mapping[str, Any], 'Lookup'], Any]

RULES module-attribute

RULES: Mapping[str, Combine] = {UNION: _union, NEAREST: _nearest, AGREED: _agreed}

PUBLIC_MODULES module-attribute

PUBLIC_MODULES: Query[tuple[str, ...]] = Query('public-modules')

COMPILE_COMMANDS module-attribute

COMPILE_COMMANDS: Query[Path | None] = Query('compile-commands')

MODULE_ROOTS module-attribute

MODULE_ROOTS: Query[tuple[str, ...]] = Query('module-roots')

REFERENCES module-attribute

REFERENCES: Query[tuple[SourceReferences, ...]] = Query('references')

CURRENT_VERSION module-attribute

CURRENT_VERSION: Query[str] = Query('current-version')

VERSION_FILES module-attribute

VERSION_FILES: Query[tuple[Path, ...]] = Query('version-files')

REQUIREMENTS module-attribute

REQUIREMENTS: Query[Mapping[str, str]] = Query('requirements')

REQUIREMENT_WRITERS module-attribute

REQUIREMENT_WRITERS: Query[tuple[RequirementWriter, ...]] = Query('requirement-writers')

TEST_REQUIREMENTS module-attribute

TEST_REQUIREMENTS: Query[Mapping[str, str]] = Query('test-requirements')

TEST_REQUIREMENT_WRITERS module-attribute

TEST_REQUIREMENT_WRITERS: Query[tuple[RequirementWriter, ...]] = Query('test-requirement-writers')

DISTRIBUTIONS module-attribute

DISTRIBUTIONS: Query[tuple[tuple[str, str], ...]] = Query('distributions')

REGISTRY module-attribute

REGISTRY: Query[Registry | None] = Query('registry')

EXECUTABLES module-attribute

EXECUTABLES: Query[tuple[str, ...]] = Query('executables')

HOST_TOOLS module-attribute

HOST_TOOLS: Query[tuple[str, ...]] = Query('host-tools')

EDITOR_EXTENSIONS module-attribute

EDITOR_EXTENSIONS: Query[tuple[str, ...]] = Query('editor-extensions')

STORE_SERIES module-attribute

STORE_SERIES: Query[tuple[Series | Keyed, ...]] = Query('store.series')

JOB_BUILT_MEMBERS module-attribute

JOB_BUILT_MEMBERS: Query[Mapping[str, str]] = Query('job-built-members')

CHECKOUT_INPUTS module-attribute

CHECKOUT_INPUTS: Query[Mapping[str, str]] = Query('checkout-inputs')

FOLDERS module-attribute

FOLDERS: Query[Mapping[str, Folder]] = Query('ci.fold')

Reached module-attribute

Reached = Mapping[str, tuple[str, tuple[str, ...]]]

REACHES module-attribute

REACHES: Query[tuple[Callable[[Changes], Reached], ...]] = Query('reaches')

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)

Bases: Generic[T_co]

A handle naming a declared query, typed by its answer.

The handle is covariant in its answer: one typed by a tuple serves a reader that takes any iterable.

Attributes:

Name Type Description
name str

The key an extension answers it under: public-modules.

name instance-attribute

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: public-modules.

combine str | Reference

How the answers make one. union: every item any answer holds, once each, in the order first met, each answer a list. nearest: the answer of the one extension no other answering one requires. agreed: the one value every answer that is not empty holds. Or a function, called with the answers by extension and the declarations' lookup, which raises livery.workshop._queries.QueryError or ValueError naming the extensions when the answers break its rule.

level str

package for a question about one package, asked with the package and answered by its set in composition order; workspace for one about the workspace, asked with its root and answered by the installed set in composition order.

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.

name instance-attribute

name: str

combine class-attribute instance-attribute

combine: str | Reference = UNION

level class-attribute instance-attribute

level: str = PACKAGE_LEVEL

default class-attribute instance-attribute

default: object = None

values class-attribute instance-attribute

values: tuple[object, ...] | None = None

extension class-attribute instance-attribute

extension: str = BASE

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__

__call__(package: Package, dependency: Package, floor: str) -> list[str] | None

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
def __call__(
    self, package: Package, dependency: Package, floor: str
) -> list[str] | None:
    """Write *dependency* at *floor* into *package*'s manifest.

    Args:
        package: The package whose manifest gains the requirement.
        dependency: The sibling it requires.
        floor: The lowest version of *dependency* the requirement
            takes.

    Returns:
        The files changed, relative to the package; empty when the
        manifest names *dependency* already. None for a sibling
        outside the writer's ecosystem, which it leaves alone.
    """
    ...

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__

__call__(shards: Sequence[Mapping[str, Any]]) -> Mapping[str, Any]

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
def __call__(self, shards: Sequence[Mapping[str, Any]]) -> Mapping[str, Any]:
    """The one file of the platform leg, from *shards*' files.

    Args:
        shards: The file as each shard left it, in shard order.

    Returns:
        The folded file.

    Raises:
        ValueError: When the shards' files cannot be one leg's,
            naming what differs; the fold is red with it.
    """
    ...

merged

merged(answers: Mapping[str, Any], lookup: Lookup) -> Mapping[str, str]

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
def merged(answers: Mapping[str, Any], lookup: Lookup) -> Mapping[str, str]:
    """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.
    """
    del lookup
    found: dict[str, str] = {}
    by: dict[str, str] = {}
    for name, value in answers.items():
        for key, held in cast("Mapping[str, str]", value).items():
            if key in found and found[key] != held:
                raise QueryError(
                    f"{by[key]} answers {key} {found[key]!r} and {name} answers"
                    f" {held!r}; the answers name each entry once, or alike"
                )
            found[key] = held
            by.setdefault(key, name)
    return found

owned

owned(answers: Mapping[str, Any], lookup: Lookup) -> tuple[str, ...]

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
def owned(answers: Mapping[str, Any], lookup: Lookup) -> tuple[str, ...]:
    """Every item any answer holds; an item two extensions answer refuses.

    The ``executables`` query's rule, which the base's contract file
    names.
    """
    del lookup
    owners: dict[str, str] = {}
    for name, value in answers.items():
        for item in cast("Iterable[str]", value):
            if item in owners and owners[item] != name:
                raise QueryError(
                    f"{owners[item]} and {name} both answer {item}; one extension"
                    " of a package answers each"
                )
            owners[item] = name
    return tuple(owners)

base_queries cached

base_queries() -> dict[str, QuerySpec]

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
@functools.cache
def base_queries() -> dict[str, QuerySpec]:
    """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:
        DeclarationError: when a section is off the shape a query's
            declaration has.
    """
    from livery.workshop._contract_keys import BASE_FILE, base_contract
    from livery.workshop._declaration import query_specs_of

    return query_specs_of(base_contract(), BASE_FILE, extension=BASE, package=BASE)

declared_queries cached

declared_queries() -> dict[str, QuerySpec]

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
@functools.cache
def declared_queries() -> dict[str, QuerySpec]:
    """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:
        DeclarationError: when two extensions declare one query.
    """
    from livery.footman import installed_entry_points
    from livery.workshop._declaration import DeclarationError, query_declarations

    found = dict(base_queries())
    for entry in installed_entry_points("workshop.extensions"):
        for spec in query_declarations(entry.name, entry.value.partition(":")[0]):
            held = found.get(spec.name)
            if held is not None and held.extension != spec.extension:
                both = " and ".join(sorted((held.extension, spec.extension)))
                raise DeclarationError(
                    f"the {spec.name} query is declared by both {both}; one"
                    " extension declares a query"
                )
            found[spec.name] = spec
    return found

query_spec

query_spec(name: str) -> QuerySpec

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
def query_spec(name: str) -> QuerySpec:
    """The declared query *name*; refuses naming the declared ones.

    Raises:
        QueryError: when no extension declares *name*.
    """
    specs = declared_queries()
    found = specs.get(name)
    if found is None:
        raise QueryError(
            f"{name} is not a declared query; the queries are {', '.join(specs)}"
        )
    return found

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
def 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.
    """
    held: list[tuple[tuple[str, ...], Reference | DeclaredValue]] = []
    if query in declared.queries:
        held.append((("queries", query), declared.queries[query]))
    targets = [
        target
        for target, answered in declared.target_queries.items()
        if query in answered
    ]
    if targets:
        # The lists are read only when a [for] table answers the query.
        contributed = _contributed(subject, extension)
        held += [
            (("for", target, "queries", query), declared.target_queries[target][query])
            for target in targets
            if target in contributed
        ]
    return held

answers

answers(subject: Package | Path, query: Query[T], *, lookup: Lookup | None = None) -> dict[str, T]

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
def answers(
    subject: Package | Path, query: Query[T], *, lookup: Lookup | None = None
) -> dict[str, T]:
    """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:
        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.
    """
    if lookup is None:
        from livery.workshop._extensions import installed_declaration

        lookup = installed_declaration
    spec = query_spec(query.name)
    found: dict[str, T] = {}
    for name in _walk(subject, spec, lookup):
        declared = lookup(name)
        if declared is None:
            continue
        held = answered_at(subject, name, declared, query.name)
        if held:
            found[name] = cast("T", _one_answer(name, held, subject, spec))
    return found

answer

answer(subject: Package | Path, query: Query[T], *, lookup: Lookup | None = None) -> T

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
def answer(
    subject: Package | Path, query: Query[T], *, lookup: Lookup | None = None
) -> T:
    """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:
        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.
    """
    if lookup is None:
        from livery.workshop._extensions import installed_declaration

        lookup = installed_declaration
    spec = query_spec(query.name)
    found = answers(subject, query, lookup=lookup)
    if not found and spec.default is not None:
        return cast("T", spec.default)
    combine: Combine = (
        RULES[spec.combine] if isinstance(spec.combine, str) else spec.combine
    )
    where = "" if isinstance(subject, Path) else f"{subject.path}: "
    try:
        return cast("T", combine(found, lookup))
    except (QueryError, ValueError) as error:
        raise QueryError(f"{where}{query.name}: {error}") from None

workspace_answers

workspace_answers(root: Path, *, lookup: Lookup | None = None) -> dict[str, object]

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.

Source code in packages/workshop/src/livery/workshop/_queries.py
def workspace_answers(root: Path, *, lookup: Lookup | None = None) -> dict[str, object]:
    """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.
    """
    return {
        name: answer(root, Query(name), lookup=lookup)
        for name, spec in declared_queries().items()
        if spec.level == WORKSPACE_LEVEL
    }