when#

class WhenResult(value: bool, reason: str | None)#

Bases: object

Simple class holding the value of the result of a When evaluation

Instances of this class contain two members: value and reason. value is True if the underlying When expression evaluated to True else False. If value=False, reason will contain the reason.

value#

reason#

Bases: object

Implements the when= logic that controls the conditions under which a directive is run

canary directives can be run depending on the options passed to canary on the command line. E.g., a test may be parameterized on a only if run linux: canary.directives.parameterize('a', (1, 2, 3), when='platforms=linux'). This parameterize instance will only be active on linux platforms.

Parameters:

options – expression defining options under which the directive will be activated, e.g., options=’opt and baz’. Options are typically passed on the command line.
parameters – expression defining parameterizations under which the directive will be activated, e.g., parameters='cpus>1'.
testname – expression defining the testname under which the directive will be activated, e.g. testname=’baz’.
platforms – expression defining the platforms under which the directive will be activated, e.g. platform='linux'.

Notes:

The environment variable CANARY_PLATFORMS can be set to alternative platform names to activate directives requiring a specific platform

Examples:

>>> import canary
>>> canary.directives.parameterize('gpus', (1, 4), when='platform=linux')

static factory(input: str | dict[str, str] | None) → When#

classmethod from_string(input: str | None) → When#

Parse expression, such as

when="options='not dbg' keywords='fast and regression'"

and return {“options”: “not dbg”, “keywords”: “fast and regression”}

evaluate_platform_expression(**kwds: str) → str | None#

evaluate_testname_expression(testname_arg: str | None, **kwds: str) → str | None#

evaluate_option_expression(options_arg: list[str] | None, **kwds: str) → str | None#

evaluate_keyword_expression(keywords_arg: list[str] | None, **kwds: str) → str | None#

evaluate_parameter_expression(parameters_arg: dict[str, Any] | None, **kwds: str) → str | None#

evaluate(*, testname: str | None = None, keywords: list[str] | None = None, on_options: list[str] | None = None, parameters: dict[str, Any] | None = None) → WhenResult#

class NameMatcher(own_names: AbstractSet[str])#

Bases: object

A matcher for names. The match expression can contain wildcards.

Tries to match on any name, attached to the given items.

own_names: AbstractSet[str]#

class OptionMatcher(own_opt_names: AbstractSet[str])#

Bases: object

A matcher for options which are present.

Tries to match on any options, attached to the given items

own_opt_names: AbstractSet[str]#

class AnyMatcher(own_names: AbstractSet[str], case_sensitive: bool)#

Bases: object

Tries to match on any options, attached to the given items

own_names: AbstractSet[str]#

case_sensitive: bool#

class PlatformMatcher#

Bases: object

A matcher for platform.

match_any(code: str, items: list[str], ignore_case: bool = False) → bool#

safe_substitute(arg: str, **kwds) → str#

get_tokens(code) → Iterator[TokenInfo]#

anymatch(items: AbstractSet[str], pattern: str, case_sensitive: bool = True) → bool#

remove_surrounding_quotes(arg: str) → str#

when(input: str | bool | dict, keywords: list[str] | None = None, parameters: dict[str, Any] | None = None, testname: str | None = None, on_options: list[str] | None = None) → bool#

exception InvalidSyntax(token, msg=None)#: Bases: SyntaxError

exception InvalidExpression#: Bases: Exception

exception UsageError#: Bases: Exception