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() |
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
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.
Get all symbols defined by this symbol definition block
alias of TemplateUnitValidator
Check this unit for correctness
Parameters: |
|
---|---|
Returns: | A list of issues or a generator yielding subsequent issues. Each issue is a plainbox.impl.validation.Issue. |
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.
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
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.
Get all symbols defined by this symbol definition block
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 |
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.
Get filter program compiled from the template-filter field
Returns: | ResourceProgram created out of the text of the template-filter field. |
---|
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:
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. |
Obtain the raw value of the specified record attribute
Parameters: |
|
---|---|
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.
Obtain the normalized value of the specified record attribute
Parameters: |
|
---|---|
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 |
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 a job 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.
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. |
Obtain the translated value of the specified record attribute
Parameters: |
|
---|---|
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. |
Deprecated since version 0.7: call unit.tr_unit() instead
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. |
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.
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.
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()
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 |
The Origin object associated with this Unit
The mapping of parameters supplied to this Unit
This may be either a dictionary or None.
See also
Identifier of this job, without the provider name
This field should not be used anymore, except for display
The provider object associated with this Unit
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.
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.
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.
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.
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.
Translated (optionally) value of the unit field (overridden)
The return value is always ‘self.Meta.name’ (translated)
the value of the unit field
This property _may_ be overridden by certain subclasses but this behavior is not generally recommended.
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
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.