rules#

Rules for selecting and filtering ResolvedSpec objects.

This module defines a set of Rule classes used to determine whether a ResolvedSpec should be included in test execution. Each rule evaluates specific attributes—such as keywords, parameters, owners, IDs, file prefixes, regular expressions, or resource requirements—and returns a RuleOutcome object indicating whether the spec passed or failed the rule.

Rules support serialization to and from dictionaries and JSON strings to allow persistence and reconstruction across sessions.

class RuleOutcome(ok: bool = True, reason: str | None = None)#

Bases: object

Represents the result of evaluating a rule.

ok#

reason#

classmethod failed(reason: str) → RuleOutcome#

class Rule(priority: int = 0)#

Bases: object

Base class for all selection rules.

Subclasses should override __call__ to evaluate whether a ResolvedSpec satisfies the rule. Rules may also define a default_reason explaining why a spec is rejected when the rule fails.

asdict() → dict[str, Any]#

Return a dictionary representation of the rule.

Returns:: A mapping containing the parameters required to reconstruct the rule.
Return type:: dict

classmethod from_dict(params: dict[str, Any]) → Rule#

Create a rule instance from serialized parameters.

Parameters:: params – A mapping of constructor parameters.
Returns:: A new rule instance with the given parameters.
Return type:: Rule

property default_reason: str#

Return the generic failure reason for the rule.

Returns:: A human-readable description of why the rule would fail if no more specific reason is provided.
Return type:: str

serialize() → str#

Return a compact JSON string representing the rule.

Returns:: Serialized representation of the rule.
Return type:: str

static validate(data) → Any#

static reconstruct(serialized: str) → Rule#

Reconstruct a rule from a serialized JSON string.

Parameters:: serialized – JSON string previously produced by serialize().
Returns:: The reconstructed rule instance.
Return type:: Rule

class KeywordRule(keyword_exprs: list[str], priority: int = 0)#

Bases: Rule

Selects specs based on keyword expressions.

A spec passes if all keyword expressions match its explicit or implicit keywords, unless the expression list contains ‘__all__’ or ‘:all:’, in which case all specs pass.

property default_reason: str#

Return the generic failure reason for the rule.

Returns:: A human-readable description of why the rule would fail if no more specific reason is provided.
Return type:: str

class ParameterRule(parameter_expr: str, priority: int = 0)#

Bases: Rule

Selects specs based on parameter expressions.

The spec passes if the parameter expression matches any of the spec’s explicit or implicit parameters.

property default_reason: str#

Return the generic failure reason for the rule.

Returns:: A human-readable description of why the rule would fail if no more specific reason is provided.
Return type:: str

class IDsRule(ids: Iterable[str] = (), priority: int = 0)#

Bases: Rule

Selects specs based on test ID prefixes.

A spec passes if its ID begins with any of the configured prefixes.

property default_reason: str#

Return the generic failure reason for the rule.

Returns:: A human-readable description of why the rule would fail if no more specific reason is provided.
Return type:: str

class OwnersRule(owners: Iterable[str] = (), priority: int = 0)#

Bases: Rule

Selects specs based on declared owners.

A spec passes if at least one of its owners appears in the rule’s configured owner set.

property default_reason: str#

Return the generic failure reason for the rule.

Returns:: A human-readable description of why the rule would fail if no more specific reason is provided.
Return type:: str

class PrefixRule(prefixes: Iterable[str] = (), priority: int = 0)#

Bases: Rule

Selects specs based on file path prefixes.

A spec passes if its underlying file path begins with any of the configured prefixes.

property default_reason: str#

Return the generic failure reason for the rule.

Returns:: A human-readable description of why the rule would fail if no more specific reason is provided.
Return type:: str

class RegexRule(regex: str, priority: int = 0)#

Bases: Rule

Selects specs by searching for a regular expression in test files.

A spec passes if the configured regular expression occurs in the spec’s primary file or in any referenced asset file.

string: str#

rx: Pattern#

property default_reason: str#

Return the generic failure reason for the rule.

Returns:: A human-readable description of why the rule would fail if no more specific reason is provided.
Return type:: str

asdict() → dict[str, Any]#

Return a dictionary representation of the rule.

Returns:: A mapping containing the parameters required to reconstruct the rule.
Return type:: dict

class RuntimeRule(priority: int = 0)#

Bases: object

Base class for all runtime selection rules.

Subclasses should override __call__ to evaluate whether a TestCase satisfies the rule. Rules may also define a default_reason explaining why a spec is rejected when the rule fails.

property default_reason: str#

Return the generic failure reason for the rule.

Returns:: A human-readable description of why the rule would fail if no more specific reason is provided.
Return type:: str

class ResourceCapacityRule(priority: int = 0)#

Bases: RuntimeRule

Selects cases based on system resource capacity.

This rule queries plugin hooks to determine whether the available resource pool can accommodate the spec’s declared resource needs. Evaluation results are cached based on the resource set’s hashable representation.

cache: dict[tuple[tuple[str, Any], ...], RuleOutcome]#

property default_reason: str#

Return the generic failure reason for the rule.

Returns:: A human-readable description of why the rule would fail if no more specific reason is provided.
Return type:: str

freeze_resource_set(resource_set: list[dict[str, Any]]) → tuple[tuple[str, Hashable], ...]#

class RerunRule(strategy: str = 'not_pass', priority: int = 0)#

Bases: RuntimeRule

STRATEGIES = ('all', 'failed', 'not_pass', 'not_run', 'changed', 'ids:...')#

strategy: str#

property default_reason: str#

Return the generic failure reason for the rule.

Returns:: A human-readable description of why the rule would fail if no more specific reason is provided.
Return type:: str

contains_any(elements: tuple[str, ...], test_elements: list[str]) → bool#