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'), {'help': 'Kind of runnable', 'required': True, 'type': <class 'str'>}), (('-u', '--uri'), {'default': None, 'help': 'URI of runnable', 'type': <class 'str'>}), (('-c', '--config'), {'default': '{}', 'help': 'A config JSON data', 'type': <class 'str'>}), (('-a', '--arg'), {'action': 'append', 'default': [], 'help': 'Simple arguments to runnable'}), (('kwargs',), {'default': [], 'help': 'Keyword (key=val) arguments to runnable', 'metavar': 'KEY_VAL', 'nargs': '*', 'type': <function _parse_key_val>}))
The command line arguments to the “runnable-run” command
- CMD_RUNNABLE_RUN_RECIPE_ARGS = ((('recipe',), {'help': 'Path to the runnable recipe file', 'type': <class 'str'>}),)
- CMD_STATUS_SERVER_ARGS = ((('uri',), {'help': 'URI to bind a status server to', 'type': <class 'str'>}),)
- CMD_TASK_RUN_ARGS = ((('-i', '--identifier'), {'help': 'Task unique identifier', 'required': True, 'type': <class 'str'>}), (('-t', '--category'), {'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', 'required': False, 'type': <class 'str'>}), (('-s', '--status-uri'), {'action': 'append', 'default': None, 'help': 'URIs of status services to report to'}), (('-j', '--job-id'), {'help': 'Identifier of Job this task belongs to', 'metavar': 'JOB_ID', 'required': False, 'type': <class 'str'>}), (('-k', '--kind'), {'help': 'Kind of runnable', 'required': True, 'type': <class 'str'>}), (('-u', '--uri'), {'default': None, 'help': 'URI of runnable', 'type': <class 'str'>}), (('-c', '--config'), {'default': '{}', 'help': 'A config JSON data', 'type': <class 'str'>}), (('-a', '--arg'), {'action': 'append', 'default': [], 'help': 'Simple arguments to runnable'}), (('kwargs',), {'default': [], 'help': 'Keyword (key=val) arguments to runnable', 'metavar': 'KEY_VAL', 'nargs': '*', 'type': <function _parse_key_val>}))
- CMD_TASK_RUN_RECIPE_ARGS = ((('recipe',), {'help': 'Path to the task recipe file', 'type': <class 'str'>}),)
- 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:
- 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:
- 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:
- 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 givendict
. 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 ofobject_pairs_hook
will be used instead of thedict
. This feature can be used to implement custom decoders. Ifobject_hook
is also defined, theobject_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
(astr
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 aTypeError
).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 super().default(o)
avocado.core.nrunner.runnable module
- avocado.core.nrunner.runnable.CONFIGURATION_USED = ['runner.identifier_format']
Configuration used by all runnables, no matter what its kind. The configuration that a kind uses in addition to this is set in their own class attribute “CONFIGURATION_USED”
- 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, identifier=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
This attributes holds configuration from Avocado proper that is passed to runners, as long as a runner declares its interest in using them with attr:avocado.core.nrunner.runner.BaseRunner.CONFIGURATION_USED
- property default_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:
- Returns:
Config dict, which has only values essential for runner based on STANDALONE_EXECUTABLE_CONFIG_USED
- Return type:
- classmethod from_args(args)
Returns a runnable from arguments
- classmethod from_avocado_config(kind, uri, *args, config=None, identifier=None, **kwargs)
Creates runnable with only essential config for runner of specific kind.
- classmethod from_dict(recipe_dict)
Returns a runnable from a runnable dictionary
- Parameters:
recipe_dict – a dictionary with runnable keys and values
- Return type:
instance of
Runnable
- 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:
- classmethod get_configuration_used_by_kind(kind)
Returns the configuration used by a runner of a given kind
- 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:
- 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
- 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
- read_dependencies(dependencies_dict)
Converts dependencies from json to avocado.core.dependencies.dependency.Dependency
- Parameters:
dependencies (list of dict, or list of Dependency) – Runnable dependencies
- Returns:
Runnable dependencies in avocado.core.dependencies.dependency.Dependency format.
- Return type:
list of Dependency
- 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
- 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)
- exception avocado.core.nrunner.runnable.RunnableRecipeInvalidError
Bases:
Exception
Signals that a runnable recipe is not well formed, contains missing or bad data
- avocado.core.nrunner.runnable.STANDALONE_EXECUTABLE_CONFIG_USED = {}
The configuration that is known to be used by standalone runners
- avocado.core.nrunner.runnable.SYSTEM_WIDE_SCHEMA_PATH = '/usr/share/avocado/schemas'
Location used for schemas when packaged (as in RPMs)
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.
- 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:
- 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 checkedrunners_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:
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)
Bases:
JSONEncoder
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 aTypeError
).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 super().default(o)
- avocado.core.nrunner.task.TASK_DEFAULT_CATEGORY = 'test'
The default category for tasks, and the value that will cause the task results to be included in the job results
- class avocado.core.nrunner.task.Task(runnable, identifier=None, status_uris=None, category='test', job_id=None)
Bases:
object
Wraps the execution of a runnable
While a runnable describes what to be run, and gets run by a runner, a task should be a unique entity to track its state, that is, whether it is pending, is running or has finished.
Instantiates a new Task.
- Parameters:
runnable (
avocado.core.nrunner.Runnable
) – the “description” of what the task should run.identifier – any identifier that is guaranteed to be unique within the context of a Job. A recommended value is a
avocado.core.test_id.TestID
instance when a task represents a test, because besides the uniqueness aspect, it’s also descriptive. If an identifier is not given, an automatically generated one will be set.status_uris (list) – the URIs for the status servers that this task should send updates to.
category (str) – category of this task. Defaults to
TASK_DEFAULT_CATEGORY
.job_id (str) – the ID of the job, for authenticating messages that get sent to the destination job’s status server and will make into the job’s results.
- are_dependencies_available(runners_registry=None)
Verifies if dependencies needed to run this task are available.
This currently checks the runner command only, but can be expanded once the handling of other types of dependencies are implemented. See BP002.
- category
Category of the task. If the category is not “test”, it will not be accounted for on a Job’s test results.
- classmethod from_recipe(task_path)
Creates a task (which contains a runnable) from a task recipe file
- Parameters:
task_path – Path to a recipe file
- Return type:
instance of
Task
- get_command_args()
Returns the command arguments that adhere to the runner interface
This is useful for building ‘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:
- run()
- setup_output_dir(output_dir=None)
- class avocado.core.nrunner.task.TaskStatusService(uri)
Bases:
object
Implementation of interface that a task can use to post status updates
TODO: make the interface generic and this just one of the implementations
- close()
- property connection
- post(status)
- avocado.core.nrunner.task.json_dumps(data)