Job State.

plainbox.impl.session.jobs – jobs state handling

This module contains a helper class for associating job state within a particular session. The JobState class holds references to a JobDefinition and JobResult as well as a list of inhibitors that prevent the job from being runnable in a particular session.

class plainbox.impl.session.jobs.InhibitionCause[source]

Bases: plainbox.vendor.enum.IntEnum

There are four possible not-ready causes.

UNDESIRED:
This job was not selected to run in this session
PENDING_DEP:
This job depends on another job which was not started yet
FAILED_DEP:
This job depends on another job which was started and failed
PENDING_RESOURCE:
This job has a resource requirement expression that uses a resource produced by another job which was not started yet
FAILED_RESOURCE:
This job has a resource requirement that evaluated to a false value
FAILED_DEP = <InhibitionCause.FAILED_DEP: 2>
FAILED_RESOURCE = <InhibitionCause.FAILED_RESOURCE: 4>
PENDING_DEP = <InhibitionCause.PENDING_DEP: 1>
PENDING_RESOURCE = <InhibitionCause.PENDING_RESOURCE: 3>
UNDESIRED = <InhibitionCause.UNDESIRED: 0>
class plainbox.impl.session.jobs.JobReadinessInhibitor(cause, related_job=None, related_expression=None)[source]

Bases: plainbox.impl.pod.POD

Class representing the cause of a job not being ready to execute.

It is intended to be consumed by UI layers and to provide them with enough information to render informative error messages or other visual feedback that will aid the user in understanding why a job cannot be started.

There are four possible not ready causes:

UNDESIRED:
This job was not selected to run in this session
PENDING_DEP:
This job depends on another job which was not started yet
FAILED_DEP:
This job depends on another job which was started and failed
PENDING_RESOURCE:
This job has a resource requirement expression that uses a resource produced by another job which was not started yet
FAILED_RESOURCE:
This job has a resource requirement that evaluated to a false value

All causes apart from UNDESIRED use the related_job property to encode a job that is related to the problem. The PENDING_RESOURCE and FAILED_RESOURCE causes also store related_expression that describes the relevant requirement expression.

There are three attributes that can be accessed:

cause:
Encodes the reason why a job is not ready, see InhibitionCause.
related_job:
Provides additional context for the problem. This is not the job that is affected, rather, the job that is causing the problem.
related_expression:
Provides additional context for the problem caused by a failing resource expression.
as_dict() → dict

Return the data in this POD as a dictionary.

Note

UNSET values are not added to the dictionary.

as_tuple() → tuple

Return the data in this POD as a tuple.

Order of elements in the tuple corresponds to the order of field declarations.

cause

cause (constant) of the inhibitor

Side effects of assign filters:
  • constant (read-only after initialization)
field_list = [<Field name:'cause'>, <Field name:'related_job'>, <Field name:'related_expression'>]
namedtuple_cls

alias of JobReadinessInhibitor

related_expression

an (optional) resource expression reference

Side effects of assign filters:
  • constant (read-only after initialization)
related_job

an (optional) job reference

Side effects of assign filters:
  • constant (read-only after initialization)
class plainbox.impl.session.jobs.JobState(*args, **kwargs)[source]

Bases: plainbox.impl.pod.POD

Class representing the state of a job in a session.

Contains the following basic properties of each job:

  • the readiness_inhibitor_list that prevent the job form starting
  • the result (outcome) of the run (IJobResult)
  • the effective category identifier
  • the effective certification status
  • the job that was used to create it (via_job)

For convenience (to SessionState implementation) it also has a reference to the job itself. This class is a pure state holder an will typically collaborate with the SessionState class and the UI layer.

apply_overrides()[source]

Apply overrides to effective jop values.

This method is automatically called by SessionDeviceContext to implement effective overrides originating from test plan data.

Parameters:

override_list – A list, as exposed by values of TestPlanUnitSupport.override_list, composed of a sequence of pairs (field, value), where field is the name of the field to override (without the prefix effective_) and value is any valid value of that field.

Raises:
  • AttributeError – If any of the ``field``s refer to an unknown field.
  • ValueError – If any of the ``field``s refer to fields that are not designated as overridable.
  • ValueError – If the value supplied is incorrect for the given field.
  • TypeError – If the type of the value supplied is incorrect for the given field.

Note

Consult field specification for details on what types and values are valid for that field.

Example:

>>> from plainbox.vendor.mock import Mock
>>> job = Mock(spec=JobDefinition)
>>> job_state = JobState(job)
>>> job_state.apply_overrides([
...     ('category_id', 'new-category-id'),
...     ('certification_status', 'blocker')])
>>> job_state.effective_category_id
'new-category-id'
>>> job_state.effective_certification_status
'blocker'
as_dict() → dict

Return the data in this POD as a dictionary.

Note

UNSET values are not added to the dictionary.

as_tuple() → tuple

Return the data in this POD as a tuple.

Order of elements in the tuple corresponds to the order of field declarations.

attempts

number of attempts remaining (in auto-retry mode)

can_start()[source]

Quickly check if the associated job can run right now.

effective_auto_retry

the ability to automatically retry this job if it fails

effective_category_id

the effective categorization of this test in a session

effective_certification_status

the effective certification status of this job

field_list = [<Field name:'job'>, <Field name:'readiness_inhibitor_list'>, <Field name:'result'>, <Field name:'result_history'>, <Field name:'via_job'>, <OverridableJobField name:'effective_category_id'>, <Field name:'attempts'>, <OverridableJobField name:'effective_certification_status'>, <OverridableJobField name:'effective_auto_retry'>]
get_readiness_description()[source]

Get a human readable description of the current readiness state.

job

the job associated with this state

namedtuple_cls

alias of JobState

on_result_changed

Basic signal that supports arbitrary listeners.

While this class can be used directly it is best used with the helper decorator Signal.define on a function or method. See the documentation for the plainbox.vendor.morris module for details.

Attr _name:Name of the signal, typically accessed via name().
Attr _listeners:
 List of signal listeners. Each item is a tuple (listener, pass_signal) that encodes how to call the listener.
on_result_history_changed

Basic signal that supports arbitrary listeners.

While this class can be used directly it is best used with the helper decorator Signal.define on a function or method. See the documentation for the plainbox.vendor.morris module for details.

Attr _name:Name of the signal, typically accessed via name().
Attr _listeners:
 List of signal listeners. Each item is a tuple (listener, pass_signal) that encodes how to call the listener.
readiness_inhibitor_list

the list of readiness inhibitors of the associated job

result

the result of running the associated job

result_history

a tuple of result_history of the associated job

Side effects of assign filters:
  • type-checked (value must be of type tuple)
  • type-checked sequence (items must be of type IJobResult)
via_job

the parent job definition

class plainbox.impl.session.jobs.OverridableJobField(job_field, doc=None, type=None, notify=False, assign_filter_list=None)[source]

Bases: plainbox.impl.pod.Field

A custom Field for modeling job values that can be overridden.

A readable-writable field that has a special initial value JOB_VALUE which is interpreted as “load this value from the corresponding job definition”.

This field class facilitates implementation of fields that have some per-job value but can be also overridden in a session state context.

alter_cls(cls: type) → None

Modify class definition this field belongs to.

This method is called during class construction. It allows the field to alter the class and add the on_{field.name}_changed signal. The signal is only added if notification is enabled and if there is no such signal in the first place (this allows inheritance not to create separate but identically-named signals and allows signal handlers connected via the base class to work on child classes.

change_notifier

Decorator for changing the change notification function.

This decorator can be used to define all the fields in one block and all the notification function in another block. It helps to make the code easier to read.

Example:

>>> class Person(POD):
...     name = Field()
...
...     @name.change_notifier
...     def _name_changed(self, old, new):
...         print("changed from {!r} to {!r}".format(old, new))
>>> person = Person()
changed from UNSET to None
>>> person.name = "bob"
changed from None to 'bob'

Note

Keep in mind that the decorated function is converted to a signal automatically. The name of the function is also irrelevant, the POD core automatically creates signals that have consistent names of on_{field}_changed().

gain_name(name: str) → None

Set field name.

Parameters:name – Name of the field as it appears in a class definition

Method called at most once on each Field instance embedded in a POD subclass. This method informs the field of the name it was assigned to in the class.

is_mandatory

Flag indicating if the field needs a mandatory initializer.

on_changed()

The first responder of the per-field modification signal.

Parameters:
  • pod – The object that contains the modified values
  • old – The old value of the field
  • new – The new value of the field
plainbox.impl.session.jobs.cause_convert_assign_filter()[source]

Assign filter for for JobReadinessInhibitor.cause.

Custom assign filter for the JobReadinessInhibitor.cause field that produces a very specific error message.

plainbox.impl.session.jobs.job_assign_filter(instance, field, old_value, new_value)[source]

A custom setter for the JobState.job.

Warning

This setter should not exist. job attribute should be read-only. This is a temporary kludge to get session restoring over DBus working. Once a solution that doesn’t involve setting a JobState’s job attribute is implemented, please remove this awful method.

plainbox.impl.session.jobs.job_via_assign_filter(instance, field, old_value, new_value)[source]

A custom setter for JobState.via_job.

comments powered by Disqus