plainbox.impl.template
– template unit¶
-
class
plainbox.impl.unit.template.
TemplateUnit
(data, origin=None, provider=None, raw_data=None, parameters=None, field_offset_map=None)[source]¶ Bases:
plainbox.impl.unit.unit.Unit
,plainbox.impl.unit._legacy.TemplateUnitLegacyAPI
Template that can instantiate zero or more additional units.
Templates are a generalized replacement to the
local job
system from Checkbox. Instead of running a job definition that prints additional job definitions, a static template is provided. PlainBox has all the visibility of each of the fields in the template and can perform validation and other analysis without having to run any external commands.To instantiate a template a resource object must be provided. This adds a natural dependency from each template unit to a resource job definition unit. Actual instantiation allows PlainBox to create additional unit instance for each resource eligible record. Eligible records are either all records or a subset of records that cause the filter program to evaluate to True. The filter program uses the familiar resource program syntax available to normal job definitions.
Attr _filter_program: Cached ResourceProgram computed (once) and returned by get_filter_program()
-
class
Meta
[source]¶ Bases:
plainbox.impl.unit.unit.Meta
,plainbox.impl.unit._legacy.Meta
Collection of meta-data about
TemplateUnit
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('template-unit'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7f45706dbe10>], Symbol('unit'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.TemplateInvariantFieldValidator'>, <plainbox.impl.unit.validators.PresentFieldValidator object at 0x7f4570a69668>], Symbol('template-resource'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <class 'plainbox.impl.unit.validators.PresentFieldValidator'>, <plainbox.impl.unit.validators.UnitReferenceValidator object at 0x7f45706f3dd8>], Symbol('template-filter'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7f45706f3e10>], Symbol('template-imports'): [<class 'plainbox.impl.unit.validators.UntranslatableFieldValidator'>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7f45706f3e48>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object at 0x7f45706f3e80>]}¶
-
class
fields
¶ Bases:
plainbox.impl.symbol.fields
A symbol definition containing all fields used by
TemplateUnit
This class is partially automatically generated. It always inherits from the Meta.fields class of the base unit class.
-
classmethod
get_all_symbols
()¶ Get all symbols defined by this symbol definition block
-
template_filter
= Symbol('template-filter')¶
-
template_imports
= Symbol('template-imports')¶
-
template_resource
= Symbol('template-resource')¶
-
template_unit
= Symbol('template-unit')¶
-
unit
= Symbol('unit')¶
-
classmethod
-
TemplateUnit.Meta.
name
= 'template'¶
-
TemplateUnit.Meta.
template_constraints
= {'unit': 'const'}¶
-
TemplateUnit.Meta.
validator_cls
¶ alias of
TemplateUnitValidator
-
TemplateUnit.
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
-
TemplateUnit.
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.
-
TemplateUnit.
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
TemplateUnit.
fields
¶ Bases:
plainbox.impl.symbol.fields
A symbol definition containing all fields used by
TemplateUnit
This class is partially automatically generated. It always inherits from the Meta.fields class of the base unit class.
-
classmethod
get_all_symbols
()¶ Get all symbols defined by this symbol definition block
-
template_filter
= Symbol('template-filter')¶
-
template_imports
= Symbol('template-imports')¶
-
template_resource
= Symbol('template-resource')¶
-
template_unit
= Symbol('template-unit')¶
-
unit
= Symbol('unit')¶
-
classmethod
-
TemplateUnit.
from_rfc822_record
(record, provider=None)¶ Create a new Unit from RFC822 record. The resulting instance may not be valid but will always be created.
Parameters: record – A RFC822Record object Returns: A new Unit
-
TemplateUnit.
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.
-
TemplateUnit.
get_filter_program
()[source]¶ Get filter program compiled from the template-filter field
Returns: ResourceProgram created out of the text of the template-filter field.
-
TemplateUnit.
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>
-
TemplateUnit.
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.
-
TemplateUnit.
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.
-
TemplateUnit.
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
-
TemplateUnit.
get_target_unit_cls
()[source]¶ Get the Unit subclass that implements the instantiated unit
Returns: A subclass of Unit the template will try to instantiate. If there is no template-unit
field in the template then ajob
template is assumed.Raises KeyError: if the field ‘template-unit’ refers to unknown unit or is undefined Note
Typically this will return a JobDefinition class but it’s not the only possible value.
-
TemplateUnit.
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.
-
TemplateUnit.
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.
-
TemplateUnit.
get_unit_type
()¶ Deprecated since version 0.7: call unit.tr_unit() instead
-
TemplateUnit.
id
¶
-
TemplateUnit.
instantiate_all
(resource_list)[source]¶ Instantiate a list of job definitions by creating one from each non-filtered out resource records.
Parameters: resource_list – A list of resource objects with the correct name ( template_resource()
)Returns: A list of new Unit (or subclass) objects.
-
TemplateUnit.
instantiate_one
(resource, unit_cls_hint=None)[source]¶ Instantiate a single job out of a resource and this template.
Parameters: resource – A Resource object to provide template data Returns: A new JobDefinition created out of the template and resource data. Raises AttributeError: If the template referenced a value not defined by the resource object. Fields starting with the string ‘template-‘ are discarded. All other fields are interpolated by attributes from the resource object. References to missing resource attributes cause the process to fail.
-
classmethod
TemplateUnit.
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.
-
TemplateUnit.
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()
-
TemplateUnit.
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
-
TemplateUnit.
origin
¶ The Origin object associated with this Unit
-
TemplateUnit.
parameters
¶ The mapping of parameters supplied to this Unit
This may be either a dictionary or None.
See also
-
TemplateUnit.
partial_id
¶ Identifier of this job, without the provider name
This field should not be used anymore, except for display
-
TemplateUnit.
provider
¶ The provider object associated with this Unit
-
TemplateUnit.
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.
-
TemplateUnit.
resource_id
¶ fully qualified identifier of the resource object
-
TemplateUnit.
resource_namespace
¶ namespace of the referenced resource object
-
TemplateUnit.
resource_partial_id
¶ name of the referenced resource object
-
TemplateUnit.
should_instantiate
(resource)[source]¶ Check if a job should be instantiated for a specific resource.
Parameters: resource – A Resource object to check Returns: True if a job should be instantiated for the resource object Determine if a job instance should be created using the specific resource object. This is the case if there is no filter or if the specified resource object would make the filter program evaluate to True.
-
TemplateUnit.
template_filter
¶ value of the ‘template-filter’ field
This attribute stores the text of a resource program (optional) that select a subset of available resource objects. If you wish to access the actual resource program call
get_filter_program()
. In both cases the value can be None.
-
TemplateUnit.
template_imports
¶ value of the ‘template-imports’ field
This attribute stores the text of a resource import that is specific to the template itself. In other words, it allows the template to access resources from any namespace.
-
TemplateUnit.
template_resource
¶ value of the ‘template-resource’ field
-
TemplateUnit.
template_unit
¶ value of the ‘template-unit’ field
This attribute stores the type of the unit that this template intends to instantiate. It defaults to ‘job’ for backwards compatibility and simplicity.
-
TemplateUnit.
tr_unit
()¶ Translated (optionally) value of the unit field (overridden)
The return value is always ‘self.Meta.name’ (translated)
-
TemplateUnit.
unit
¶ the value of the unit field
This property _may_ be overridden by certain subclasses but this behavior is not generally recommended.
-
TemplateUnit.
validate
(**validation_kwargs)¶ Validate this job definition template
Parameters: validation_kwargs – Keyword arguments to pass to the TemplateUnitValidator.validate()
Raises ValidationError: If the template has any problems that make it unsuitable for execution. Deprecated since version 0.11: use .check() instead
-
TemplateUnit.
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