Job Tree Builder.
plainbox.impl.job
– job definition¶
Warning
THIS MODULE DOES NOT HAVE STABLE PUBLIC API
-
class
plainbox.impl.job.
JobDefinition
(data, origin=None, provider=None, controller=None, raw_data=None, parameters=None, field_offset_map=None)[source]¶ Bases:
plainbox.impl.unit.unit_with_id.UnitWithId
,plainbox.impl.unit._legacy.JobDefinitionLegacyAPI
,plainbox.abc.IJobDefinition
Job definition class.
Thin wrapper around the RFC822 record that defines a checkbox job definition
-
class
Meta
[source]¶ Bases:
plainbox.impl.unit.unit_with_id.Meta
,plainbox.impl.unit._legacy.Meta
Collection of meta-data about
JobDefinition
This class is partially automatically generated. It always inherits the Meta class of the base unit type.
This class has (at most) three attributes:
- field_validators:
- A dictionary mapping from each field to a list of
IFieldvalidator:
that check that particular field for correctness. - fields:
- A :class`SymbolDef` with a symbol for each field that this unit defines. This does not include dynamically created fields that are not a part of the unit itself.
- validator_cls:
- A
UnitValidator
subclass that can be used to check this unit for correctness
-
field_validators
= {Symbol('unit'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <plainbox.impl.unit.validators.PresentFieldValidator object at 0x7faeb6793470>], Symbol('estimated_duration'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <plainbox.impl.unit.validators.PresentFieldValidator object at 0x7faeb683bbe0>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7faeb683bba8>], Symbol('verification'): [<class 'plainbox.impl.unit.validators.TranslatableFieldValidator'>, <plainbox.impl.unit.validators.PresentFieldValidator object at 0x7faeb683b940>], Symbol('environ'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <plainbox.impl.unit.validators.UselessFieldValidator object at 0x7faeb683bc18>], Symbol('certification_status'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7faeb683be80>], Symbol('shell'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7faeb683bda0>], Symbol('command'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <plainbox.impl.unit.validators.PresentFieldValidator object at 0x7faeb683b898>, <plainbox.impl.unit.validators.UselessFieldValidator object at 0x7faeb683ba58>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7faeb683ba20>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7faeb683b828>, <class 'plainbox.impl.unit.validators.ShellProgramValidator'>], Symbol('id'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.PresentFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateVariantFieldValidator'>, <class 'plainbox.impl.unit.validators.UniqueValueValidator'>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7faeb65239b0>], Symbol('after'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7faeb683b5f8>, <plainbox.impl.unit.validators.UnitReferenceValidator object at 0x7faeb683b748>], Symbol('name'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateVariantFieldValidator'>, <plainbox.impl.unit.validators.DeprecatedFieldValidator object at 0x7faeb67de5c0>], Symbol('imports'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7faeb683bd68>, <plainbox.impl.unit.validators.UnitReferenceValidator object at 0x7faeb683b710>], Symbol('purpose'): [<class 'plainbox.impl.unit.validators.TranslatableFieldValidator'>, <plainbox.impl.unit.validators.PresentFieldValidator object at 0x7faeb683b9b0>], Symbol('category_id'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <plainbox.impl.unit.validators.UnitReferenceValidator object at 0x7faeb683bcf8>], Symbol('qml_file'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <plainbox.impl.unit.validators.PresentFieldValidator object at 0x7faeb683bb70>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7faeb683b278>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7faeb683b198>], Symbol('steps'): [<class 'plainbox.impl.unit.validators.TranslatableFieldValidator'>, <plainbox.impl.unit.validators.PresentFieldValidator object at 0x7faeb683b908>], Symbol('plugin'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <class 'plainbox.impl.unit.validators.PresentFieldValidator'>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7faeb683b860>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7faeb683b8d0>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7faeb683b9e8>], Symbol('depends'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7faeb683be10>, <plainbox.impl.unit.validators.UnitReferenceValidator object at 0x7faeb683b6a0>], Symbol('flags'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7faeb683b550>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7faeb683b4a8>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7faeb683bb00>], Symbol('requires'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7faeb683b780>, <plainbox.impl.unit.validators.UnitReferenceValidator object at 0x7faeb683bcc0>], Symbol('description'): [<class 'plainbox.impl.unit.validators.TranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateVariantFieldValidator'>, <plainbox.impl.unit.validators.PresentFieldValidator object at 0x7faeb683b7f0>, <plainbox.impl.unit.validators.PresentFieldValidator object at 0x7faeb683b978>], Symbol('summary'): [<class 'plainbox.impl.unit.validators.TranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateVariantFieldValidator'>, <plainbox.impl.unit.validators.PresentFieldValidator object at 0x7faeb67de898>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7faeb67de828>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7faeb67de860>], Symbol('user'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7faeb683ba90>, <plainbox.impl.unit.validators.UselessFieldValidator object at 0x7faeb683b5c0>]}¶
-
class
fields
¶ Bases:
plainbox.impl.symbol.fields
A symbol definition containing all fields used by
JobDefinition
This class is partially automatically generated. It always inherits from the Meta.fields class of the base unit class.
-
after
= Symbol('after')¶
-
category_id
= Symbol('category_id')¶
-
certification_status
= Symbol('certification_status')¶
-
command
= Symbol('command')¶
-
depends
= Symbol('depends')¶
-
description
= Symbol('description')¶
-
environ
= Symbol('environ')¶
-
estimated_duration
= Symbol('estimated_duration')¶
-
flags
= Symbol('flags')¶
-
classmethod
get_all_symbols
()¶ Get all symbols defined by this symbol definition block
-
id
= Symbol('id')¶
-
imports
= Symbol('imports')¶
-
name
= Symbol('name')¶
-
plugin
= Symbol('plugin')¶
-
purpose
= Symbol('purpose')¶
-
qml_file
= Symbol('qml_file')¶
-
requires
= Symbol('requires')¶
-
shell
= Symbol('shell')¶
-
steps
= Symbol('steps')¶
-
summary
= Symbol('summary')¶
-
unit
= Symbol('unit')¶
-
user
= Symbol('user')¶
-
verification
= Symbol('verification')¶
-
-
JobDefinition.Meta.
name
= 'job'¶
-
JobDefinition.Meta.
template_constraints
= {'name': 'vary', 'environ': 'const', 'shell': 'const', 'imports': 'const', 'unit': 'const', 'id': 'vary', 'description': 'vary', 'summary': 'vary', 'category_id': 'const', 'user': 'const', 'plugin': 'const'}¶
-
JobDefinition.Meta.
validator_cls
¶ alias of
UnitWithIdValidator
-
JobDefinition.
after
¶
-
JobDefinition.
automated
¶ Whether the job is fully automated and runs without any intervention from the user
-
JobDefinition.
category_id
¶ fully qualified identifier of the category unit this job belongs to
Note
Jobs that don’t have an explicit category association, also known as the natural category, automatically get assigned to the special, built-in 2013.com.canonical.plainbox::uncategorised category.
Note that to get the definition of that special category unit applications need to include one of the special providers exposed as
plainbox.impl.providers.special:get_categories()
.
-
JobDefinition.
certification_status
[source]¶ Get the natural certification status of this job.
The default certification status of all jobs is
CertificationStatus.unspecified
Note
Remember that the certification status can be overridden by a test plan. You should, instead, consider the effective certification status that can be obtained from
JobState
.
-
JobDefinition.
check
(*, context=None, live=False)¶ Check this unit for correctness
Parameters: - context – A keyword-only argument, if specified it should be a
UnitValidationContext
instance used to validate a number of units together. - live – A keyword-only argument, if True the return value is a generator that yields subsequent issues. Otherwise (default) the return value is buffered and returned as a list. Checking everything takes considerable time, for responsiveness, consider using live=True.
Returns: A list of issues or a generator yielding subsequent issues. Each issue is a
plainbox.impl.validation.Issue
.- context – A keyword-only argument, if specified it should be a
-
JobDefinition.
checksum
¶ Checksum of the unit definition.
This property can be used to compute the checksum of the canonical form of the unit definition. The canonical form is the UTF-8 encoded JSON serialization of the data that makes up the full definition of the unit (all keys and values). The JSON serialization uses no indent and minimal separators.
The checksum is defined as the SHA256 hash of the canonical form.
-
JobDefinition.
command
¶
-
JobDefinition.
controller
¶ The controller object associated with this JobDefinition
-
JobDefinition.
create_child_job_from_record
(record)[source]¶ Create a new JobDefinition from RFC822 record.
This method should only be used to create additional jobs from local jobs (plugin local). This ensures that the child job shares the embedded provider reference.
-
JobDefinition.
depends
¶
-
JobDefinition.
description
¶
-
JobDefinition.
environ
¶
-
JobDefinition.
estimated_duration
¶ estimated duration of this job in seconds.
The value may be None, which indicates that the duration is basically unknown. Fractional numbers are allowed and indicate fractions of a second.
-
JobDefinition.
field_offset_map
¶ The field-to-line-number-offset mapping.
A dictionary mapping field name to offset (in lines) relative to the origin where that field definition commences.
Note: the return value may be None
-
class
JobDefinition.
fields
¶ Bases:
plainbox.impl.symbol.fields
A symbol definition containing all fields used by
JobDefinition
This class is partially automatically generated. It always inherits from the Meta.fields class of the base unit class.
-
after
= Symbol('after')¶
-
category_id
= Symbol('category_id')¶
-
certification_status
= Symbol('certification_status')¶
-
command
= Symbol('command')¶
-
depends
= Symbol('depends')¶
-
description
= Symbol('description')¶
-
environ
= Symbol('environ')¶
-
estimated_duration
= Symbol('estimated_duration')¶
-
flags
= Symbol('flags')¶
-
classmethod
get_all_symbols
()¶ Get all symbols defined by this symbol definition block
-
id
= Symbol('id')¶
-
imports
= Symbol('imports')¶
-
name
= Symbol('name')¶
-
plugin
= Symbol('plugin')¶
-
purpose
= Symbol('purpose')¶
-
qml_file
= Symbol('qml_file')¶
-
requires
= Symbol('requires')¶
-
shell
= Symbol('shell')¶
-
steps
= Symbol('steps')¶
-
summary
= Symbol('summary')¶
-
unit
= Symbol('unit')¶
-
user
= Symbol('user')¶
-
verification
= Symbol('verification')¶
-
-
JobDefinition.
flags
¶
-
classmethod
JobDefinition.
from_rfc822_record
(record, provider=None)[source]¶ Create a JobDefinition instance from rfc822 record. The resulting instance may not be valid but will always be created. Only valid jobs should be executed.
The record must be a RFC822Record instance.
-
JobDefinition.
get_accessed_parameters
(*, force=False)¶ Get a set of attributes accessed from each template attribute
Parameters: (keyword-only) (force) – If specified then it will operate despite being invoked on a non-parametric unit. This is only intended to be called by TemplateUnit to inspect what the generated unit looks like in the early validation code. Returns: A dictionary of sets with names of attributes accessed by each template field. Note that for non-parametric Units the return value is always a dictionary of empty sets, regardless of how they actual parameter values look like. This function computes a dictionary of sets mapping from each template field (except from fields starting with the string ‘template-‘) to a set of all the resource object attributes accessed by that element.
-
JobDefinition.
get_after_dependencies
()[source]¶ Compute and return a set of after dependencies.
After dependencies express the desire that given job A runs after a given job B. This is spelled out as:
id: A after: B id: B
To combat a simple mistake where the jobs are space-delimited any mixture of white-space (including newlines) and commas are allowed.
-
JobDefinition.
get_category_id
()[source]¶ Get the fully-qualified category id that this job belongs to
-
JobDefinition.
get_direct_dependencies
()[source]¶ Compute and return a set of direct dependencies
To combat a simple mistake where the jobs are space-delimited any mixture of white-space (including newlines) and commas are allowed.
-
JobDefinition.
get_imported_jobs
()[source]¶ Parse the ‘imports’ line and compute the imported symbols.
Return generator for a sequence of pairs (job_id, identifier) that describe the imported job identifiers from arbitrary namespace.
The syntax of each imports line is:
- IMPORT_STMT :: “from” <NAMESPACE> “import” <PARTIAL_ID>
- “from” <NAMESPACE> “import” <PARTIAL_ID> AS <IDENTIFIER>
-
JobDefinition.
get_normalized_translated_data
(msgid)¶ Get a localized piece of data and filter it with RFC822 parser normalization
Parameters: msgid – data to translate Returns: translated and normalized data obtained from the provider if this unit has one, msgid itself otherwise.
-
JobDefinition.
get_raw_record_value
(name, default=None)¶ Obtain the raw value of the specified record attribute
Parameters: - name – Name of the field to access
- default – Default value, used if the field is not defined in the unit
Returns: The raw value of the field, possibly with parameters inserted, or the default value
Raises: KeyError if the field is parametrized but parameters are incorrect
The raw value may have additional whitespace or indentation around the text. It will also not have the magic RFC822 dots removed. In general the text will be just as it was parsed from the unit file.
-
JobDefinition.
get_record_value
(name, default=None)¶ Obtain the normalized value of the specified record attribute
Parameters: - name – Name of the field to access
- default – Default value, used if the field is not defined in the unit
Returns: The value of the field, possibly with parameters inserted, or the default value
Raises: KeyError if the field is parametrized but parameters are incorrect
-
JobDefinition.
get_resource_dependencies
()[source]¶ Compute and return a set of resource dependencies
-
JobDefinition.
get_resource_program
()[source]¶ Return a ResourceProgram based on the ‘requires’ expression.
The program instance is cached in the JobDefinition and is not compiled or validated on subsequent calls.
Returns: ResourceProgram if one is available or None Raises ResourceProgramError: If the program definition is incorrect
-
JobDefinition.
get_translated_data
(msgid)¶ Get a localized piece of data
Parameters: msgid – data to translate Returns: translated data obtained from the provider if this unit has one, msgid itself otherwise.
-
JobDefinition.
get_translated_record_value
(name, default=None)¶ Obtain the translated value of the specified record attribute
Parameters: - name – Name of the field/attribute to access
- default – Default value, used if the field is not defined in the unit
Returns: The (perhaps) translated value of the field with (perhaps) parameters inserted, or the default value. The idea is to return the best value we can but there are no guarantees on returning a translated value.
Raises: KeyError if the field is parametrized but parameters are incorrect This may imply that the unit is invalid but it may also imply that translations are broken. A malicious translation can break formatting and prevent an otherwise valid unit from working.
-
JobDefinition.
get_unit_type
()¶ Deprecated since version 0.7: call unit.tr_unit() instead
-
JobDefinition.
id
¶ Identifier of this unit, with the provider namespace.
Note
In rare (unit tests only?) edge case a Unit can be separated from the parent provider. In that case the value of
id
is always equal topartial_id
.
-
JobDefinition.
imports
¶
-
classmethod
JobDefinition.
instantiate_template
(data, raw_data, origin, provider, parameters, field_offset_map)[source]¶ Instantiate this unit from a template.
The point of this method is to have a fixed API, regardless of what the API of a particular unit class
__init__
method actually looks like.It is easier to standardize on a new method that to patch all of the initializers, code using them and tests to have an uniform initializer.
-
JobDefinition.
is_parametric
¶ If true, then this unit is parametric
Parametric units are instances of a template. To know which fields are constant and which are parametrized call the support method
get_accessed_parametes()
-
JobDefinition.
is_translatable_field
(name)¶ Check if a field is marked as translatable
Parameters: name – Name of the field to check Returns: True if the field is marked as translatable, False otherwise
-
JobDefinition.
name
¶ Deprecated since version 0.11: use .partial_id or .summary instead
-
JobDefinition.
origin
¶ The Origin object associated with this Unit
-
JobDefinition.
parameters
¶ The mapping of parameters supplied to this Unit
This may be either a dictionary or None.
See also
-
JobDefinition.
partial_id
¶ Identifier of this job, without the provider name
This field should not be used anymore, except for display
-
JobDefinition.
provider
¶ The provider object associated with this Unit
-
JobDefinition.
purpose
¶
-
JobDefinition.
qml_file
¶ path to a QML file that implements tests UI for this job
This property exposes a path to QML file that follows the Plainbox QML Test Specification. The file will be loaded either in the native test shell of the application using plainbox or with a helper, generic loader for all command-line applications.
To use this property, the plugin type should be set to ‘qml’.
-
JobDefinition.
qualify_id
(some_id)¶ Transform some unit identifier to be fully qualified
Parameters: some_id – A potentially unqualified unit identifier Returns: A fully qualified unit identifier This method uses the namespace of the associated provider to transform unqualified unit identifiers to qualified identifiers. Qualified identifiers are left alone.
-
JobDefinition.
requires
¶
-
JobDefinition.
shell
¶ Shell that is used to interpret the command
Defaults to ‘bash’ for checkbox compatibility.
-
JobDefinition.
startup_user_interaction_required
¶ The job needs to be started explicitly by the test operator. This is intended for things that may be timing-sensitive or may require the tester to understand the necessary manipulations that he or she may have to perform ahead of time.
The test operator may select to skip certain tests, in that case the outcome is skip.
-
JobDefinition.
steps
¶
-
JobDefinition.
summary
¶
-
JobDefinition.
tr_description
()[source]¶ Get the translated version of
description()
-
JobDefinition.
tr_unit
()¶ Translated (optionally) value of the unit field (overridden)
The return value is always ‘self.Meta.name’ (translated)
-
JobDefinition.
tr_verification
()[source]¶ Get the translated version of
verification()
-
JobDefinition.
unit
¶ the value of the unit field (overridden)
The return value is always ‘job’
-
JobDefinition.
user
¶
-
JobDefinition.
validate
(**validation_kwargs)¶ Validate this job definition
Parameters: validation_kwargs – Keyword arguments to pass to the JobDefinitionValidator.validate()
Raises ValidationError: If the job has any problems that make it unsuitable for execution.
-
JobDefinition.
verification
¶
-
JobDefinition.
virtual
¶ Flag indicating if this unit is a virtual unit
Virtual units are created (synthetised) by PlainBox and don’t exist in any one specific file as normal units do.
-
class