plainbox.impl.unit.job
– job unit¶
-
class
plainbox.impl.unit.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('shell'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0xffec85d198>], Symbol('certification_status'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0xffeca66c18>], Symbol('estimated_duration'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <plainbox.impl.unit.validators.PresentFieldValidator object at 0xffec866eb8>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0xffec866ef0>], Symbol('description'): [<class 'plainbox.impl.unit.validators.TranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateVariantFieldValidator'>, <plainbox.impl.unit.validators.PresentFieldValidator object at 0xffec866cf8>, <plainbox.impl.unit.validators.PresentFieldValidator object at 0xffec866d30>], 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 0xffecbf2b38>], Symbol('unit'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <plainbox.impl.unit.validators.PresentFieldValidator object at 0xffecb764e0>], Symbol('category_id'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <plainbox.impl.unit.validators.UnitReferenceValidator object at 0xffec85d2b0>], Symbol('command'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <plainbox.impl.unit.validators.PresentFieldValidator object at 0xffec866c18>, <plainbox.impl.unit.validators.UselessFieldValidator object at 0xffec866c50>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0xffec866c88>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0xffec866cc0>, <class 'plainbox.impl.unit.validators.ShellProgramValidator'>], Symbol('after'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0xffec866fd0>, <plainbox.impl.unit.validators.UnitReferenceValidator object at 0xffec85d080>], Symbol('user'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0xffec866e10>, <plainbox.impl.unit.validators.UselessFieldValidator object at 0xffec866e48>], Symbol('requires'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0xffec85d0b8>, <plainbox.impl.unit.validators.UnitReferenceValidator object at 0xffec85d160>], Symbol('verification'): [<class 'plainbox.impl.unit.validators.TranslatableFieldValidator'>, <plainbox.impl.unit.validators.PresentFieldValidator object at 0xffec866dd8>], Symbol('flags'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0xffec85d2e8>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0xffec85d320>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0xffec85d358>], 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 0xffec866b70>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0xffec866ba8>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0xffec866be0>], Symbol('environ'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <plainbox.impl.unit.validators.UselessFieldValidator object at 0xffec866e80>], Symbol('steps'): [<class 'plainbox.impl.unit.validators.TranslatableFieldValidator'>, <plainbox.impl.unit.validators.PresentFieldValidator object at 0xffec866da0>], Symbol('depends'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0xffec866f28>, <plainbox.impl.unit.validators.UnitReferenceValidator object at 0xffec866f98>], Symbol('name'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateVariantFieldValidator'>, <plainbox.impl.unit.validators.DeprecatedFieldValidator object at 0xffec889f98>], Symbol('summary'): [<class 'plainbox.impl.unit.validators.TranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateVariantFieldValidator'>, <plainbox.impl.unit.validators.PresentFieldValidator object at 0xffeca75208>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0xffec8666a0>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0xffec866b38>], Symbol('purpose'): [<class 'plainbox.impl.unit.validators.TranslatableFieldValidator'>, <plainbox.impl.unit.validators.PresentFieldValidator object at 0xffec866d68>], Symbol('imports'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0xffec85d1d0>, <plainbox.impl.unit.validators.UnitReferenceValidator object at 0xffec85d240>], Symbol('qml_file'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <plainbox.impl.unit.validators.PresentFieldValidator object at 0xffec85d390>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0xffec85d3c8>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0xffec85d400>]}¶
-
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
= {'shell': 'const', 'user': 'const', 'imports': 'const', 'plugin': 'const', 'description': 'vary', 'environ': 'const', 'id': 'vary', 'unit': 'const', 'category_id': 'const', 'name': 'vary', 'summary': 'vary'}¶
-
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
-
class
plainbox.impl.unit.job.
propertywithsymbols
(fget=None, fset=None, fdel=None, doc=None, symbols=None)[source]¶ Bases:
property
A property that also keeps a group of symbols around
-
deleter
()¶ Descriptor to change the deleter on a property.
-
fdel
¶
-
fget
¶
-
fset
¶
-
getter
()¶ Descriptor to change the getter on a property.
-
setter
()¶ Descriptor to change the setter on a property.
-