avocado.core.nrunner package¶

Submodules¶

avocado.core.nrunner.app module¶

class avocado.core.nrunner.app.BaseRunnerApp(echo=<built-in function print>, prog=None, description=None)¶

Bases: object

Helper base class for common runner application behavior

CMD_RUNNABLE_RUN_ARGS = ((('-k', '--kind'), {'type': <class 'str'>, 'help': 'Kind of runnable', 'required': True}), (('-u', '--uri'), {'type': <class 'str'>, 'default': None, 'help': 'URI of runnable'}), (('-c', '--config'), {'type': <class 'str'>, 'default': '{}', 'help': 'A config JSON data'}), (('-a', '--arg'), {'action': 'append', 'default': [], 'help': 'Simple arguments to runnable'}), (('kwargs',), {'default': [], 'type': <function _parse_key_val>, 'nargs': '*', 'metavar': 'KEY_VAL', 'help': 'Keyword (key=val) arguments to runnable'}))¶: The command line arguments to the “runnable-run” command

CMD_RUNNABLE_RUN_RECIPE_ARGS = ((('recipe',), {'type': <class 'str'>, 'help': 'Path to the runnable recipe file'}),)¶

CMD_STATUS_SERVER_ARGS = ((('uri',), {'type': <class 'str'>, 'help': 'URI to bind a status server to'}),)¶

CMD_TASK_RUN_ARGS = ((('-i', '--identifier'), {'type': <class 'str'>, 'required': True, 'help': 'Task unique identifier'}), (('-t', '--category'), {'type': <class 'str'>, 'required': False, 'default': 'test', 'help': 'The category for tasks. Only tasks with category set to "test" (the default) will be included in the test results of its parent job. Other categories may be used for purposes that do include test results such as requirements resolution tasks'}), (('-s', '--status-uri'), {'action': 'append', 'default': None, 'help': 'URIs of status services to report to'}), (('-j', '--job-id'), {'type': <class 'str'>, 'required': False, 'metavar': 'JOB_ID', 'help': 'Identifier of Job this task belongs to'}), (('-k', '--kind'), {'type': <class 'str'>, 'help': 'Kind of runnable', 'required': True}), (('-u', '--uri'), {'type': <class 'str'>, 'default': None, 'help': 'URI of runnable'}), (('-c', '--config'), {'type': <class 'str'>, 'default': '{}', 'help': 'A config JSON data'}), (('-a', '--arg'), {'action': 'append', 'default': [], 'help': 'Simple arguments to runnable'}), (('kwargs',), {'default': [], 'type': <function _parse_key_val>, 'nargs': '*', 'metavar': 'KEY_VAL', 'help': 'Keyword (key=val) arguments to runnable'}))¶

CMD_TASK_RUN_RECIPE_ARGS = ((('recipe',), {'type': <class 'str'>, 'help': 'Path to the task recipe file'}),)¶

PROG_DESCRIPTION = ''¶: The description of the command line application given to the command line parser

PROG_NAME = ''¶: The name of the command line application given to the command line parser

RUNNABLE_KINDS_CAPABLE = []¶: The names of types of runnables that this runner can handle.

command_capabilities(_)¶

Outputs capabilities, including runnables and commands

The output is intended to be consumed by upper layers of Avocado, such as the Job layer selecting the right runner script to handle a runnable of a given kind, or identifying if a runner script has a given feature (as implemented by a command).

command_runnable_run(args)¶

Runs a runnable definition from arguments

This defines a Runnable instance purely from the command line arguments, then selects a suitable Runner, and runs it.

Parameters: args (dict) – parsed command line arguments turned into a dictionary

command_runnable_run_recipe(args)¶

Runs a runnable definition from a recipe

Parameters: args (dict) – parsed command line arguments turned into a dictionary

command_task_run(args)¶

Runs a task from arguments

Parameters: args (dict) – parsed command line arguments turned into a dictionary

command_task_run_recipe(args)¶

Runs a task from a recipe

Parameters: args (dict) – parsed command line arguments turned into a dictionary

get_capabilities()¶

Returns the runner capabilities, including runnables and commands

This can be used by higher level tools, such as the entity spawning runners, to know which runner can be used to handle each runnable type.

Return type: dict

get_commands()¶

Return the command names, as seen on the command line application

For every method whose name starts with “command”, and the name of the command follows, with underscores replaced by dashes. So, a method named “command_foo_bar”, will be a command available on the command line as “foo-bar”.

Return type: list

get_configuration_used_by_runners()¶

Returns the configuration keys used by capable runners.

Returns: the configuration keys (aka namespaces) used by known runners
Return type: list

get_output_produced_by_runners()¶

Returns the output produced by runners.

Returns: the configuration keys (aka namespaces) used by known runners
Return type: list

get_runner_from_runnable(runnable)¶

Returns a runner that is suitable to run the given runnable

Return type: instance of class inheriting from BaseRunner
Raises: ValueError if runnable is now supported

run()¶: Runs the application by finding a suitable command method to call

avocado.core.nrunner.config module¶

class avocado.core.nrunner.config.ConfigDecoder(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)¶

Bases: JSONDecoder

JSON Decoder for config options.

object_hook, if specified, will be called with the result of every JSON object decoded and its return value will be used in place of the given dict. This can be used to provide custom deserializations (e.g. to support JSON-RPC class hinting).

object_pairs_hook, if specified will be called with the result of every JSON object decoded with an ordered list of pairs. The return value of object_pairs_hook will be used instead of the dict. This feature can be used to implement custom decoders. If object_hook is also defined, the object_pairs_hook takes priority.

parse_float, if specified, will be called with the string of every JSON float to be decoded. By default this is equivalent to float(num_str). This can be used to use another datatype or parser for JSON floats (e.g. decimal.Decimal).

parse_int, if specified, will be called with the string of every JSON int to be decoded. By default this is equivalent to int(num_str). This can be used to use another datatype or parser for JSON integers (e.g. float).

parse_constant, if specified, will be called with one of the following strings: -Infinity, Infinity, NaN. This can be used to raise an exception if invalid JSON numbers are encountered.

If strict is false (true is the default), then control characters will be allowed inside strings. Control characters in this context are those with character codes in the 0-31 range, including '\t' (tab), '\n', '\r' and '\0'.

decode(config_str)¶: Return the Python representation of s (a str instance containing a JSON document).

static decode_set(config_dict)¶

class avocado.core.nrunner.config.ConfigEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)¶

Bases: JSONEncoder

JSON Encoder for config options.

Constructor for JSONEncoder, with sensible defaults.

If skipkeys is false, then it is a TypeError to attempt encoding of keys that are not str, int, float or None. If skipkeys is True, such items are simply skipped.

If ensure_ascii is true, the output is guaranteed to be str objects with all incoming non-ASCII characters escaped. If ensure_ascii is false, the output can contain non-ASCII characters.

If check_circular is true, then lists, dicts, and custom encoded objects will be checked for circular references during encoding to prevent an infinite recursion (which would cause an RecursionError). Otherwise, no such check takes place.

If allow_nan is true, then NaN, Infinity, and -Infinity will be encoded as such. This behavior is not JSON specification compliant, but is consistent with most JavaScript based encoders and decoders. Otherwise, it will be a ValueError to encode such floats.

If sort_keys is true, then the output of dictionaries will be sorted by key; this is useful for regression tests to ensure that JSON serializations can be compared on a day-to-day basis.

If indent is a non-negative integer, then JSON array elements and object members will be pretty-printed with that indent level. An indent level of 0 will only insert newlines. None is the most compact representation.

If specified, separators should be an (item_separator, key_separator) tuple. The default is (’, ‘, ‘: ‘) if indent is None and (‘,’, ‘: ‘) otherwise. To get the most compact JSON representation, you should specify (‘,’, ‘:’) to eliminate whitespace.

If specified, default is a function that gets called for objects that can’t otherwise be serialized. It should return a JSON encodable version of the object or raise a TypeError.

default(o)¶

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)

avocado.core.nrunner.runnable module¶

avocado.core.nrunner.runnable.RUNNERS_REGISTRY_STANDALONE_EXECUTABLE = {}¶: All known runner commands, capable of being used by a SpawnMethod.STANDALONE_EXECUTABLE compatible spawners

class avocado.core.nrunner.runnable.Runnable(kind, uri, *args, config=None, **kwargs)¶

Bases: object

Describes an entity that be executed in the context of a task

A instance of BaseRunner is the entity that will actually execute a runnable.

assets¶: list of (ReferenceResolutionAssetType, str) tuples expressing assets that the test will require in order to run.

property config¶

classmethod filter_runnable_config(kind, config)¶

Returns only essential values for specific runner.

It will use configuration from argument completed by values from config file and avocado default configuration.

Parameters

kind (str) – Kind of runner which should use the configuration.
config (dict) – Configuration values for runner. If some values will be missing the default ones and from config file will be used.

Returns

Config dict, which has only values essential for runner based on STANDALONE_EXECUTABLE_CONFIG_USED

Return type

dict

classmethod from_args(args)¶: Returns a runnable from arguments

classmethod from_avocado_config(kind, uri, *args, config=None, **kwargs)¶: Creates runnable with only essential config for runner of specific kind.

classmethod from_recipe(recipe_path)¶

Returns a runnable from a runnable recipe file

Parameters: recipe_path – Path to a recipe file
Return type: instance of Runnable

static get_capabilities_from_runner_command(runner_command, env=None)¶

Returns the capabilities of a given runner from a command.

In case of failures, an empty capabilities dictionary is returned.

When the capabilities are obtained, it also updates the STANDALONE_EXECUTABLE_CONFIG_USED info.

get_command_args()¶

Returns the command arguments that adhere to the runner interface

This is useful for building ‘runnable-run’ and ‘task-run’ commands that can be executed on a command line interface.

Returns: the arguments that can be used on an avocado-runner command
Return type: list

classmethod get_configuration_used_by_kind(kind)¶

Returns the configuration used by a runner of a given kind

Parameters: kind (str) – Kind of runner which should use the configuration.
Returns: the configuration used by a runner of a given kind
Return type: list

get_dict()¶

Returns a dictionary representation for the current runnable

This is usually the format that will be converted to a format that can be serialized to disk, such as JSON.

Return type: collections.OrderedDict

get_json()¶

Returns a JSON representation

Return type: str

get_serializable_tags()¶

property identifier¶

Runnable identifier respecting user’s format string.

This is still experimental and we have room for improvements.

This property it will return an unique identifier for this runnable. Please use this property in order to respect user’s customization.

By default runnables has its ‘{uri}’ as identifier.

Custom formatter can be configured and currently we accept the following values as normal f-strings replacements: {uri}, {args}, and {kwargs}. “args” and “kwargs” are special cases.

For args, since it is a list, you can use in two different ways: “{args}” for the entire list, or “{args[n]}” for a specific element inside this list. The same is valid when using “{kwargs}”. With kwargs, since it is a dictionary, you have to specify a key as index and then the values are used. For instance if you have a kwargs value named ‘DEBUG’, a valid usage could be: “{kwargs[DEBUG]}” and this will print the current value to this variable (i.e: True or False).

Since this is formatter, combined values can be used. Example: “{uri}-{args}”.

static is_kind_supported_by_runner_command(kind, runner_cmd, capabilities=None, env=None)¶: Checks if a runner command that seems a good fit declares support.

pick_runner_class()¶

Selects a runner class from the registry based on kind.

This is related to the SpawnMethod.PYTHON_CLASS

Returns: a class that inherits from BaseRunner
Raises: ValueError if kind there’s no runner from kind of runnable

pick_runner_class_from_entry_point()¶

Selects a runner class from entry points based on kind.

This is related to the SpawnMethod.PYTHON_CLASS.

Returns: a class that inherits from BaseRunner or None

static pick_runner_class_from_entry_point_kind(kind)¶

Selects a runner class from entry points based on kind.

This is related to the SpawnMethod.PYTHON_CLASS.

Parameters: kind (str) – Kind of runner
Returns: a class that inherits from BaseRunner or None

static pick_runner_command(kind, runners_registry=None)¶

Selects a runner command based on the runner kind.

And when finding a suitable runner, keeps found runners in registry.

This utility function will look at the given kind and try to find a matching runner. The matching runner probe results are kept in a registry (that is modified by this function) so that further executions take advantage of previous probes.

This is related to the SpawnMethod.STANDALONE_EXECUTABLE

Parameters

kind (str) – runners’ kind
runners_registry (dict) – a registry with previously found (and not found) runners keyed by runnable kind

Returns

command line arguments to execute the runner

Return type

list of str or None

static pick_runner_module_from_entry_point_kind(kind)¶

Selects a runner module from entry points based on kind.

This is related to the SpawnMethod.STANDALONE_EXECUTABLE. The module found (if any) will be one that can be used with the Python interpreter using the “python -m $module” command.

Parameters: kind (str) – Kind of runner
Returns: a module that can be run with “python -m” or None

runner_command(runners_registry=None)¶

Selects a runner command based on the runner.

And when finding a suitable runner, keeps found runners in registry.

This utility function will look at the given task and try to find a matching runner. The matching runner probe results are kept in a registry (that is modified by this function) so that further executions take advantage of previous probes.

This is related to the SpawnMethod.STANDALONE_EXECUTABLE

Parameters: runners_registry (dict) – a registry with previously found (and not found) runners keyed by runnable kind
Returns: command line arguments to execute the runner
Return type: list of str or None

uri¶: The main reference to what needs to be run. This is free form, but commonly set to the path to a file containing the test or being the test, or an actual URI with multiple parts

write_json(recipe_path)¶: Writes a file with a JSON representation (also known as a recipe)

avocado.core.nrunner.runnable.STANDALONE_EXECUTABLE_CONFIG_USED = {}¶: The configuration that is known to be used by standalone runners

avocado.core.nrunner.runner module¶

class avocado.core.nrunner.runner.BaseRunner¶

Bases: RunnableRunner

CONFIGURATION_USED = []¶: The “main Avocado” configuration keys (AKA namespaces) that this runners makes use of.

OUTPUT_PRODUCED = []¶: The output produced by the runners.

static prepare_status(status_type, additional_info=None)¶

Prepare a status dict with some basic information.

This will add the keyword ‘status’ and ‘time’ to all status.

Param: status_type: The type of event (‘started’, ‘running’, ‘finished’)
Param: addional_info: Any additional information that you would like to add to the dict. This must be a dict.
Return type: dict

running_loop(condition)¶

Produces timely running messages until end condition is found.

Parameters: condition – a callable that will be evaluated as a condition for continuing the loop

avocado.core.nrunner.runner.RUNNER_RUN_CHECK_INTERVAL = 0.01¶: The amount of time (in seconds) between each internal status check

avocado.core.nrunner.runner.RUNNER_RUN_STATUS_INTERVAL = 0.5¶: The amount of time (in seconds) between a status report from a runner that performs its work asynchronously

avocado.core.nrunner.runner.check_runnables_runner_requirements(runnables, runners_registry=None)¶

Checks if runnables have runner requirements fulfilled

Parameters

runnables (list of Runnable) – the tasks whose runner requirements will be checked
runners_registry (dict) – a registry with previously found (and not found) runners keyed by a task’s runnable kind. Defaults to RUNNERS_REGISTRY_STANDALONE_EXECUTABLE

Returns

two list of tasks in a tuple, with the first being the tasks that pass the requirements check and the second the tasks that fail the requirements check

Return type

tuple of (list, list)

avocado.core.nrunner.task module¶

class avocado.core.nrunner.task.StatusEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)¶