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.

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_environ_settings()[source]

Return a set of requested environment variables

JobDefinition.get_flag_set()[source]

Return a set of flags associated with this job

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 to partial_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

is_parametric()

JobDefinition.partial_id

Identifier of this job, without the provider name

This field should not be used anymore, except for display

JobDefinition.plugin[source]
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_purpose()[source]

Get the translated version of purpose()

JobDefinition.tr_steps()[source]

Get the translated version of steps()

JobDefinition.tr_summary()[source]

Get the translated version of summary()

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 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.