Skip to content

API Reference

The tagged object classes

parse_stages.Tagged dataclass

A base class for representing an object that has some tags.

Source code in src/parse_stages/defs.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
@dataclasses.dataclass
class Tagged:
    """A base class for representing an object that has some tags."""

    name: str
    """The name of the object, e.g. the name of the Tox test environment."""

    tags: list[str]
    """The tags specified for this object."""

    def get_keyword_haystacks(self) -> list[str]:
        """Get the strings to look for keywords in.

        Default: the object's `name` attribute.
        """
        return [self.name]

name: str instance-attribute

The name of the object, e.g. the name of the Tox test environment.

tags: list[str] instance-attribute

The tags specified for this object.

get_keyword_haystacks()

Get the strings to look for keywords in.

Default: the object's name attribute.

Source code in src/parse_stages/defs.py 
38
39
40
41
42
43
def get_keyword_haystacks(self) -> list[str]:
    """Get the strings to look for keywords in.

    Default: the object's `name` attribute.
    """
    return [self.name]

parse_stages.TaggedFrozen dataclass

A base class for representing a constant object that has some tags.

Source code in src/parse_stages/defs.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
@dataclasses.dataclass(frozen=True)
class TaggedFrozen:
    """A base class for representing a constant object that has some tags."""

    name: str
    """The name of the object, e.g. the name of the Tox test environment."""

    tags: list[str]
    """The tags specified for this object."""

    def get_keyword_haystacks(self) -> list[str]:
        """Get the strings to look for keywords in.

        Default: the object's `name` attribute.
        """
        return [self.name]

name: str instance-attribute

The name of the object, e.g. the name of the Tox test environment.

tags: list[str] instance-attribute

The tags specified for this object.

get_keyword_haystacks()

Get the strings to look for keywords in.

Default: the object's name attribute.

Source code in src/parse_stages/defs.py 
20
21
22
23
24
25
def get_keyword_haystacks(self) -> list[str]:
    """Get the strings to look for keywords in.

    Default: the object's `name` attribute.
    """
    return [self.name]

The evaluated boolean expression

parse_stages.BoolExpr dataclass

Bases: ABC

A boolean expression parsed out of a specification string.

Source code in src/parse_stages/expr.py 
16
17
18
19
20
21
22
23
@dataclasses.dataclass(frozen=True)
class BoolExpr(abc.ABC):
    """A boolean expression parsed out of a specification string."""

    @abc.abstractmethod
    def evaluate(self, obj: defs.TaggedFrozen | defs.Tagged) -> bool:
        """Evaluate the expression for the specified object."""
        raise NotImplementedError

evaluate(obj) abstractmethod

Evaluate the expression for the specified object.

Source code in src/parse_stages/expr.py 
20
21
22
23
@abc.abstractmethod
def evaluate(self, obj: defs.TaggedFrozen | defs.Tagged) -> bool:
    """Evaluate the expression for the specified object."""
    raise NotImplementedError

parse_stages.OrExpr dataclass

Bases: BoolExpr

An "subexpr or subexpr [or subexpr...]" subexpression.

Source code in src/parse_stages/expr.py 
74
75
76
77
78
79
80
81
82
83
@dataclasses.dataclass(frozen=True)
class OrExpr(BoolExpr):
    """An "subexpr or subexpr [or subexpr...]" subexpression."""

    children: list[BoolExpr]
    """The subexpressions to be combined."""

    def evaluate(self, obj: defs.TaggedFrozen | defs.Tagged) -> bool:
        """Check whether any of the specified expressions hold(s) true."""
        return any(child.evaluate(obj) for child in self.children)

children: list[BoolExpr] instance-attribute

The subexpressions to be combined.

evaluate(obj)

Check whether any of the specified expressions hold(s) true.

Source code in src/parse_stages/expr.py 
81
82
83
def evaluate(self, obj: defs.TaggedFrozen | defs.Tagged) -> bool:
    """Check whether any of the specified expressions hold(s) true."""
    return any(child.evaluate(obj) for child in self.children)

parse_stages.AndExpr dataclass

Bases: BoolExpr

An "atom and atom [and atom...]" subexpression.

Source code in src/parse_stages/expr.py 
62
63
64
65
66
67
68
69
70
71
@dataclasses.dataclass(frozen=True)
class AndExpr(BoolExpr):
    """An "atom and atom [and atom...]" subexpression."""

    children: list[BoolExpr]
    """The subexpressions to be combined."""

    def evaluate(self, obj: defs.TaggedFrozen | defs.Tagged) -> bool:
        """Check whether all the specified expressions hold true."""
        return all(child.evaluate(obj) for child in self.children)

children: list[BoolExpr] instance-attribute

The subexpressions to be combined.

evaluate(obj)

Check whether all the specified expressions hold true.

Source code in src/parse_stages/expr.py 
69
70
71
def evaluate(self, obj: defs.TaggedFrozen | defs.Tagged) -> bool:
    """Check whether all the specified expressions hold true."""
    return all(child.evaluate(obj) for child in self.children)

parse_stages.NotExpr dataclass

Bases: BoolExpr

A negated boolean expression.

Source code in src/parse_stages/expr.py 
50
51
52
53
54
55
56
57
58
59
@dataclasses.dataclass(frozen=True)
class NotExpr(BoolExpr):
    """A negated boolean expression."""

    child: BoolExpr
    """The expression to be negated."""

    def evaluate(self, obj: defs.TaggedFrozen | defs.Tagged) -> bool:
        """Check whether the specified expression does not hold true."""
        return not self.child.evaluate(obj)

child: BoolExpr instance-attribute

The expression to be negated.

evaluate(obj)

Check whether the specified expression does not hold true.

Source code in src/parse_stages/expr.py 
57
58
59
def evaluate(self, obj: defs.TaggedFrozen | defs.Tagged) -> bool:
    """Check whether the specified expression does not hold true."""
    return not self.child.evaluate(obj)

The object's tags and keywords

parse_stages.TagExpr dataclass

Bases: BoolExpr

A tag to be checked against obj.tags.

Source code in src/parse_stages/expr.py 
26
27
28
29
30
31
32
33
34
35
@dataclasses.dataclass(frozen=True)
class TagExpr(BoolExpr):
    """A tag to be checked against obj.tags."""

    tag: str
    """The tag to be matched exactly against the object's list of tags."""

    def evaluate(self, obj: defs.TaggedFrozen | defs.Tagged) -> bool:
        """Check whether the tag is present in the object's list of tags."""
        return self.tag in obj.tags

tag: str instance-attribute

The tag to be matched exactly against the object's list of tags.

evaluate(obj)

Check whether the tag is present in the object's list of tags.

Source code in src/parse_stages/expr.py 
33
34
35
def evaluate(self, obj: defs.TaggedFrozen | defs.Tagged) -> bool:
    """Check whether the tag is present in the object's list of tags."""
    return self.tag in obj.tags

parse_stages.KeywordExpr dataclass

Bases: BoolExpr

A tag to be checked against an object's name or list of tags.

Source code in src/parse_stages/expr.py 
38
39
40
41
42
43
44
45
46
47
@dataclasses.dataclass(frozen=True)
class KeywordExpr(BoolExpr):
    """A tag to be checked against an object's name or list of tags."""

    keyword: str
    """The keyword to be matched as a substring of the object's keywords."""

    def evaluate(self, obj: defs.TaggedFrozen | defs.Tagged) -> bool:
        """Check whether the tag is present in the object's list of tags."""
        return any(self.keyword in item for item in obj.get_keyword_haystacks())

keyword: str instance-attribute

The keyword to be matched as a substring of the object's keywords.

evaluate(obj)

Check whether the tag is present in the object's list of tags.

Source code in src/parse_stages/expr.py 
45
46
47
def evaluate(self, obj: defs.TaggedFrozen | defs.Tagged) -> bool:
    """Check whether the tag is present in the object's list of tags."""
    return any(self.keyword in item for item in obj.get_keyword_haystacks())

The helper functions

parse_stages.EMPTY_SET_SPECS = ['', '0', 'none'] module-attribute

The list of exact strings that parse_stage_ids() will return an empty list for.

parse_stages.parse_spec(spec)

Parse an expression using the pyparsing library.

Source code in src/parse_stages/p_pyp.py 
161
162
163
164
165
166
167
168
169
def parse_spec(spec: str) -> expr.BoolExpr:
    """Parse an expression using the `pyparsing` library."""
    res = _p_complete.parse_string(spec, parse_all=True).as_list()
    match res:
        case [expr.BoolExpr() as spec]:
            return spec

        case _:
            raise ParseError(res)

parse_stages.parse_stage_ids(spec, *, empty_set_specs=None)

Parse a list of stage ranges, return them as zero-based indices.

As a special case, the exact strings "" (an empty string), "0", and "none" will produce an empty list. Note that none of these strings are considered valid stage ranges, so they cannot be combined with any others (e.g. "0,3" is invalid).

The default list of strings that signify an empty set ("", "0", "none") may be overridden by the empty_set_specs parameter.

Source code in src/parse_stages/p_pyp.py 
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
def parse_stage_ids(spec: str, *, empty_set_specs: list[str] | None = None) -> list[int]:
    """Parse a list of stage ranges, return them as zero-based indices.

    As a special case, the exact strings "" (an empty string), "0", and "none" will
    produce an empty list. Note that none of these strings are considered valid
    stage ranges, so they cannot be combined with any others (e.g. "0,3" is invalid).

    The default list of strings that signify an empty set ("", "0", "none") may be
    overridden by the `empty_set_specs` parameter.
    """
    if empty_set_specs is None:
        empty_set_specs = EMPTY_SET_SPECS
    if spec in empty_set_specs:
        return []

    res: list[int] = _p_stage_ids_complete.parse_string(spec, parse_all=True).as_list()
    if any(not isinstance(item, int) or item < 0 for item in res):
        raise ParseError(res)
    return res