octodns.processor.templating

Classes

Templating(id, *args[, trailing_dots, context])

Record templating using python format.

Exceptions

TemplatingError(record, msg)

exception octodns.processor.templating.TemplatingError(record, msg)

Bases: Exception

__init__(record, msg)

class octodns.processor.templating.Templating(id, *args, trailing_dots=True, context={}, **kwargs)

Bases: BaseProcessor

Record templating using python format. For simple records like TXT and CAA that is the value itself. For multi-field records like MX or SRV it’s the text portions, exchange and target respectively.

Example Processor Config:

templating:
  class: octodns.processor.templating.Templating
  # When `trailing_dots` is disabled, trailing dots are removed from all
  # built-in variables values who represent a FQDN, like `{zone_name}`
  # or `{record_fqdn}`. Optional. Default to `True`.
  trailing_dots: False
  # Any k/v present in context will be passed into the .format method and
  # thus be available as additional variables in the template. This is all
  # optional.
  context:
    key: value
    another: 42

Example Records:

foo:
  type: TXT
  value: The zone this record lives in is {zone_name}. There are {zone_num_records} record(s).

bar:
  type: MX
  values:
    - preference: 1
      exchange: mx1.{zone_name}.mail.mx.
    - preference: 1
      exchange: mx2.{zone_name}.mail.mx.

Note that validations for some types reject values with {}. When encountered the best option is to use record level lenient: true https://github.com/octodns/octodns/blob/main/docs/records.md#lenience

Note that if you need to add dynamic context you can create a custom processor that inherits from Templating and passes them into the call to super, e.g.:

class MyTemplating(Templating):
    def __init__(self, *args, context={}, **kwargs):
        context['year'] = lambda desired, sources: datetime.now().strftime('%Y')
        super().__init__(*args, context, **kwargs)

See https://docs.python.org/3/library/string.html#custom-string-formatting for details on formatting options. Anything possible in an f-string or .format should work here.

__init__(id, *args, trailing_dots=True, context={}, **kwargs)

Initialize the processor.

Parameters:

• name (str) – Unique identifier for this processor instance. Used in logging and configuration references.

• lenient (bool) – When True, the processor will operate in lenient mode. This value is combined with the per-call lenient parameter in process_* methods.

Note

The name parameter is deprecated and will be removed in version 2.0. Use id instead.

process_source_and_target_zones(desired, existing, provider, lenient=False)

Process both desired and existing zones before computing changes.

Called just prior to computing changes for the target provider between desired and existing. Provides an opportunity for the processor to modify either or both zones that will be used to compute the changes and create the initial plan.

Parameters:

• desired (octodns.zone.Zone) – The desired zone state after all source processing.

• existing (octodns.zone.Zone) – The existing zone state after all target processing.

• target (octodns.provider.base.BaseProvider) – The target provider for which changes will be computed.

• lenient (bool) – When True, relaxed validation rules should be applied when modifying zone records.

Returns:

A tuple of (desired, existing) zones, typically the same objects passed in.

Return type:

tuple[octodns.zone.Zone, octodns.zone.Zone]

Important

• Will see desired after any modifications done by Provider._process_desired_zone and all processors via Processor.process_source_zone.

• Will see existing after any modifications done by all processors via Processor.process_target_zone.

• Will see both desired and existing after any modifications done by any processors configured to run before this one via Processor.process_source_and_target_zones.

• May modify desired directly.

• Must return desired which will normally be the desired param.

• May modify existing directly.

• Must return existing which will normally be the existing param.

• Must not modify records directly; record.copy should be called, the results of which can be modified, and then Zone.add_record may be used with replace=True.

• May call Zone.remove_record to remove records from desired.

• May call Zone.remove_record to remove records from existing.

• Implementations should combine self.lenient or lenient and pass the result to any record and zone calls that accept lenient as a parameter, e.g. zone.add_record(..., lenient=lenient).