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

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('plugin'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.TemplateInvariantFieldValidator object>, <plainbox.impl.unit.validators.PresentFieldValidator object>, <plainbox.impl.unit.validators.MemberOfFieldValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>], Symbol('depends'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>, <plainbox.impl.unit.validators.UnitReferenceValidator object>], Symbol('estimated_duration'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.TemplateInvariantFieldValidator object>, <plainbox.impl.unit.validators.PresentFieldValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>], Symbol('flags'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.TemplateInvariantFieldValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>], Symbol('shell'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.TemplateInvariantFieldValidator object>, <plainbox.impl.unit.validators.MemberOfFieldValidator object>], Symbol('after'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>, <plainbox.impl.unit.validators.UnitReferenceValidator object>], Symbol('description'): [<plainbox.impl.unit.validators.TranslatableFieldValidator object>, <plainbox.impl.unit.validators.TemplateVariantFieldValidator object>, <plainbox.impl.unit.validators.PresentFieldValidator object>, <plainbox.impl.unit.validators.PresentFieldValidator object>], Symbol('steps'): [<plainbox.impl.unit.validators.TranslatableFieldValidator object>, <plainbox.impl.unit.validators.PresentFieldValidator object>], Symbol('command'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.PresentFieldValidator object>, <plainbox.impl.unit.validators.UselessFieldValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>, <plainbox.impl.unit.validators.ShellProgramValidator object>], Symbol('unit'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.TemplateInvariantFieldValidator object>, <plainbox.impl.unit.validators.PresentFieldValidator object>], Symbol('name'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.TemplateVariantFieldValidator object>, <plainbox.impl.unit.validators.DeprecatedFieldValidator object>], Symbol('environ'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.TemplateInvariantFieldValidator object>, <plainbox.impl.unit.validators.UselessFieldValidator object>], Symbol('id'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.PresentFieldValidator object>, <plainbox.impl.unit.validators.TemplateVariantFieldValidator object>, <plainbox.impl.unit.validators.UniqueValueValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>], Symbol('verification'): [<plainbox.impl.unit.validators.TranslatableFieldValidator object>, <plainbox.impl.unit.validators.PresentFieldValidator object>], Symbol('purpose'): [<plainbox.impl.unit.validators.TranslatableFieldValidator object>, <plainbox.impl.unit.validators.PresentFieldValidator object>], Symbol('imports'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.TemplateInvariantFieldValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>, <plainbox.impl.unit.validators.UnitReferenceValidator object>], Symbol('siblings'): [<plainbox.impl.unit.validators.TranslatableFieldValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>], Symbol('qml_file'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.TemplateInvariantFieldValidator object>, <plainbox.impl.unit.validators.PresentFieldValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>], Symbol('certification_status'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.TemplateInvariantFieldValidator object>, <plainbox.impl.unit.validators.MemberOfFieldValidator object>], Symbol('category_id'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.TemplateInvariantFieldValidator object>, <plainbox.impl.unit.validators.UnitReferenceValidator object>], Symbol('requires'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>, <plainbox.impl.unit.validators.UnitReferenceValidator object>], Symbol('user'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.TemplateInvariantFieldValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>, <plainbox.impl.unit.validators.UselessFieldValidator object>], Symbol('summary'): [<plainbox.impl.unit.validators.TranslatableFieldValidator object>, <plainbox.impl.unit.validators.TemplateVariantFieldValidator object>, <plainbox.impl.unit.validators.PresentFieldValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>], Symbol('auto_retry'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.TemplateInvariantFieldValidator object>, <plainbox.impl.unit.validators.MemberOfFieldValidator object>]}
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')
auto_retry = Symbol('auto_retry')
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')
siblings = Symbol('siblings')
steps = Symbol('steps')
summary = Symbol('summary')
unit = Symbol('unit')
user = Symbol('user')
verification = Symbol('verification')
JobDefinition.Meta.name = 'job'
JobDefinition.Meta.validator_cls

alias of UnitWithIdValidator

JobDefinition.after
JobDefinition.auto_retry[source]

Check if this job should be automatically retried if it fails.

The default certification status of all jobs is AutoRetry.unspecified

Note

Remember that the auto-retry value can be overridden by a test plan. You should, instead, consider the effective auto-retry value that can be obtained from JobState.

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')
auto_retry = Symbol('auto_retry')
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')
siblings = Symbol('siblings')
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, template_engine='default')

Get a set of attributes accessed from each template attribute

Parameters:
  • (keyword-only) (template_engine) – 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.
  • (keyword-only) – If different from default python string templating, the name of the template engine to use to parse the data. Currently only Jinja2 is supported.
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

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

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

value of the ‘template-engine’ field.

This attribute stores the template engine to use, default is python string formatting (See PEP 3101).

JobDefinition.tr_description()[source]

Get the translated version of description()

JobDefinition.tr_purpose()[source]

Get the translated version of purpose()

JobDefinition.tr_siblings()[source]

Get the translated version of siblings()

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

comments powered by Disqus