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
an (optional) resource expression reference
- Side effects of assign filters:
- constant (read-only after initialization)
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
(override_list: 'List[Tuple[str, Any]]')¶ 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)
, wherefield
is the name of the field to override (without the prefixeffective_
) 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.
-
can_start
()¶ Quickly check if the associated job can run right now.
-
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'>, <OverridableJobField name:'effective_certification_status'>]¶
-
get_readiness_description
()¶ Get a human readable description of the current readiness state.
-
job
¶ the job associated with this state
-
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
(pod: 'POD', old: 'Any', new: 'Any') → None¶ 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
(instance: plainbox.impl.pod.POD, field: plainbox.impl.pod.Field, old: 'Any', new: 'Any') → 'Any'[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.