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)

Bases: plainbox.impl.unit.unit.Unit

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

Bases: plainbox.impl.unit.unit.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-imports'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>], Symbol('template-resource'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.PresentFieldValidator object>, <plainbox.impl.unit.validators.UnitReferenceValidator object>], Symbol('template-unit'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>], Symbol('unit'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.TemplateInvariantFieldValidator object>, <plainbox.impl.unit.validators.PresentFieldValidator object>], Symbol('template-filter'): [<plainbox.impl.unit.validators.UntranslatableFieldValidator object>, <plainbox.impl.unit.validators.CorrectFieldValueValidator object>]}

class fields

Bases: plainbox.impl.unit.unit.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')

name = 'template'

validator_cls

alias of TemplateUnitValidator

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.

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.

field_offset_map

Decorator that converts a method with a single self argument into a property cached on the instance. See https://goo.gl/QgJYks (django cached_property)

class fields

Bases: plainbox.impl.unit.unit.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')

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

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.

get_filter_program()

Get filter program compiled from the template-filter field.

Returns:ResourceProgram created out of the text of the template-filter field.

get_imported_jobs()

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>

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.

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.

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

get_target_unit_cls()

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

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.

id

Identifier of this template unit.

instantiate_all(resource_list)

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_one(resource, unit_cls_hint=None, index=0)

Instantiate a single job out of a resource and this template.

Parameters:

• resource – A Resource object to provide template data
• unit_cls_hint – A unit class to instantiate
• index – An integer parameter representing the current loop index

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 instantiate_template(data, raw_data, origin, provider, parameters, field_offset_map)

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.

is_parametric

Decorator that converts a method with a single self argument into a property cached on the instance. See https://goo.gl/QgJYks (django cached_property)

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

origin

Decorator that converts a method with a single self argument into a property cached on the instance. See https://goo.gl/QgJYks (django cached_property)

parameters

Decorator that converts a method with a single self argument into a property cached on the instance. See https://goo.gl/QgJYks (django cached_property)

partial_id

Identifier of this job, without the provider name.

This field should not be used anymore, except for display

provider

Decorator that converts a method with a single self argument into a property cached on the instance. See https://goo.gl/QgJYks (django cached_property)

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.

resource_id

fully qualified identifier of the resource object.

resource_namespace

namespace of the referenced resource object.

resource_partial_id

name of the referenced resource object.

should_instantiate(resource)

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.

template_engine

Decorator that converts a method with a single self argument into a property cached on the instance. See https://goo.gl/QgJYks (django cached_property)

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.

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.

template_resource

value of the ‘template-resource’ field.

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.

tr_unit()

Translated (optionally) value of the unit field (overridden)

The return value is always ‘self.Meta.name’ (translated)

unit

Decorator that converts a method with a single self argument into a property cached on the instance. See https://goo.gl/QgJYks (django cached_property)

virtual

Decorator that converts a method with a single self argument into a property cached on the instance. See https://goo.gl/QgJYks (django cached_property)

comments powered by Disqus