Skip to content

livery.toolroom.store._requirement

livery.toolroom.store._requirement

The one requirement grammar: name[option,...]?>=floor@scope, parsed once.

Every site that names a tool or an extension spells it the same way, and livery.toolroom.store.Spec is the one parser:

  • [...] names options: a tool's profile, or an extension's switches;
  • ? marks the requirement optional;
  • >=floor is the lowest version that satisfies;
  • @scope limits it to some hosts: comma-separated platforms (windows) or host keys (windows-x64), each excluded with a leading !.

The parser enforces the grammar alone. What a site allows of it (a floor, options, ?) is the site's own rule, so a refusal there names the site. livery.toolroom.store.Scope resolves a scope against the hosts a workspace supports.

Classes:

Name Description
SpecError

A spelling the requirement grammar does not read; the message names why.

Scope

The hosts a requirement is limited to, as written after @.

Spec

One requirement as the grammar spells it: name[options]?>=floor@scope.

SpecError

Bases: ValueError

A spelling the requirement grammar does not read; the message names why.

Scope dataclass

Scope(include: tuple[str, ...] = (), exclude: tuple[str, ...] = ())

The hosts a requirement is limited to, as written after @.

Attributes:

Name Type Description
include tuple[str, ...]

The platforms and host keys named without !; empty for every supported host.

exclude tuple[str, ...]

The platforms and host keys named with !.

Methods:

Name Description
parse

The scope comma-separated text spells, every token checked.

hosts

The hosts of supported this scope reaches, in their order.

__bool__

Whether the scope limits anything: false for every host.

__str__

The scope as written after @.

include class-attribute instance-attribute

include: tuple[str, ...] = ()

exclude class-attribute instance-attribute

exclude: tuple[str, ...] = ()

parse classmethod

parse(text: str, *, where: str = 'a requirement', spelled: str = '') -> Scope

The scope comma-separated text spells, every token checked.

Parameters:

Name Type Description Default
text str

The tokens after @, linux,!linux-arm say.

required
where str

The site a refusal names.

'a requirement'
spelled str

The whole spelling the scope came from, for a refusal; text itself when empty.

''

Raises:

Type Description
SpecError

for a scope naming no token, or a token that is neither a platform nor a host key.

Source code in packages/toolroom-store/src/livery/toolroom/store/_requirement.py
@classmethod
def parse(
    cls, text: str, *, where: str = "a requirement", spelled: str = ""
) -> Scope:
    """The scope comma-separated *text* spells, every token checked.

    Args:
        text: The tokens after ``@``, ``linux,!linux-arm`` say.
        where: The site a refusal names.
        spelled: The whole spelling the scope came from, for a
            refusal; *text* itself when empty.

    Raises:
        SpecError: for a scope naming no token, or a token that is
            neither a platform nor a host key.
    """
    whole = spelled or text
    tokens = tuple(token.strip() for token in text.split(",") if token.strip())
    if not tokens:
        raise SpecError(
            f"{where}: {whole!r} names no host after @; a scope names a"
            f" platform ({', '.join(PLATFORMS)}) or a host key"
            f" ({', '.join(HOSTS)})"
        )
    include: list[str] = []
    exclude: list[str] = []
    for token in tokens:
        name = token.removeprefix("!")
        if name not in PLATFORMS and name not in HOSTS:
            raise SpecError(
                f"{where}: {name!r} in {whole!r} is neither a platform"
                f" ({', '.join(PLATFORMS)}) nor a host key ({', '.join(HOSTS)})"
            )
        (exclude if token.startswith("!") else include).append(name)
    return cls(tuple(include), tuple(exclude))

hosts

hosts(supported: Iterable[str]) -> tuple[str, ...]

The hosts of supported this scope reaches, in their order.

No inclusion reaches every supported host; an exclusion then removes its hosts, so a scope of exclusions alone starts from every supported host.

Source code in packages/toolroom-store/src/livery/toolroom/store/_requirement.py
def hosts(self, supported: Iterable[str]) -> tuple[str, ...]:
    """The hosts of *supported* this scope reaches, in their order.

    No inclusion reaches every supported host; an exclusion then
    removes its hosts, so a scope of exclusions alone starts from
    every supported host.
    """
    return tuple(
        host
        for host in supported
        if (not self.include or _matches(host, self.include))
        and not _matches(host, self.exclude)
    )

__bool__

__bool__() -> bool

Whether the scope limits anything: false for every host.

Source code in packages/toolroom-store/src/livery/toolroom/store/_requirement.py
def __bool__(self) -> bool:
    """Whether the scope limits anything: false for every host."""
    return bool(self.include or self.exclude)

__str__

__str__() -> str

The scope as written after @.

Source code in packages/toolroom-store/src/livery/toolroom/store/_requirement.py
def __str__(self) -> str:
    """The scope as written after ``@``."""
    return ",".join([*self.include, *(f"!{name}" for name in self.exclude)])

Spec dataclass

Spec(name: str, options: tuple[str, ...] = (), optional: bool = False, floor: str = '', scope: Scope = Scope())

One requirement as the grammar spells it: name[options]?>=floor@scope.

Attributes:

Name Type Description
name str

The tool's or the extension's name.

options tuple[str, ...]

The names inside [...], in their order.

optional bool

Whether ? marks it optional.

floor str

The lowest version that satisfies; empty for any.

scope Scope

The hosts it is limited to; empty for every host.

Methods:

Name Description
parse

The requirement text spells.

__str__

The requirement as the grammar spells it.

name instance-attribute

name: str

options class-attribute instance-attribute

options: tuple[str, ...] = ()

optional class-attribute instance-attribute

optional: bool = False

floor class-attribute instance-attribute

floor: str = ''

scope class-attribute instance-attribute

scope: Scope = field(default_factory=Scope)

parse classmethod

parse(text: str, *, where: str = 'a requirement') -> Spec

The requirement text spells.

Parameters:

Name Type Description Default
text str

ruff, llvm[slim]>=20, docker?@!windows.

required
where str

The site a refusal names: the one that declared it.

'a requirement'

Raises:

Type Description
SpecError

for a spelling the grammar does not read, an empty or malformed option, or a scope livery.toolroom.store.Scope.parse refuses.

Source code in packages/toolroom-store/src/livery/toolroom/store/_requirement.py
@classmethod
def parse(cls, text: str, *, where: str = "a requirement") -> Spec:
    """The requirement *text* spells.

    Args:
        text: ``ruff``, ``llvm[slim]>=20``, ``docker?@!windows``.
        where: The site a refusal names: the one that declared it.

    Raises:
        SpecError: for a spelling the grammar does not read, an
            empty or malformed option, or a scope
            [livery.toolroom.store.Scope.parse][] refuses.
    """
    found = _SPEC.match(text)
    if found is None:
        raise SpecError(
            f"{where}: {text!r} is not a requirement; spell it"
            " `name[options]?>=floor@scope`, every part after the name"
            " optional"
        )
    options: tuple[str, ...] = ()
    if found["options"] is not None:
        options = tuple(part.strip() for part in found["options"].split(","))
        bad = [option for option in options if not _OPTION.match(option)]
        if bad:
            raise SpecError(
                f"{where}: {text!r} names an option that is not a name:"
                f" {', '.join(repr(option) for option in bad)}"
            )
    scope = Scope()
    if found["scope"] is not None:
        scope = Scope.parse(found["scope"], where=where, spelled=text)
    return cls(
        found["name"],
        options,
        found["optional"] is not None,
        found["floor"] or "",
        scope,
    )

__str__

__str__() -> str

The requirement as the grammar spells it.

Source code in packages/toolroom-store/src/livery/toolroom/store/_requirement.py
def __str__(self) -> str:
    """The requirement as the grammar spells it."""
    spelled = self.name
    if self.options:
        spelled += f"[{','.join(self.options)}]"
    if self.optional:
        spelled += "?"
    if self.floor:
        spelled += f">={self.floor}"
    if self.scope:
        spelled += f"@{self.scope}"
    return spelled