Browse Source

Fix all sphinx docstring errors and warnings, not links

pull/1288/head
Ross McFarland 4 months ago
parent
commit
245e764dbe
No known key found for this signature in database GPG Key ID: 943B179E15D3B22A
11 changed files with 446 additions and 425 deletions
  1. +4
    -0
      .changelog/0a8ba4255d9a4ba29ac6f55fb83cd624.md
  2. +8
    -3
      docs/index.md
  3. +9
    -6
      octodns/manager.py
  4. +11
    -9
      octodns/processor/acme.py
  5. +22
    -21
      octodns/processor/base.py
  6. +244
    -244
      octodns/processor/filter.py
  7. +21
    -21
      octodns/processor/restrict.py
  8. +20
    -20
      octodns/processor/spf.py
  9. +33
    -34
      octodns/processor/templating.py
  10. +70
    -64
      octodns/provider/yaml.py
  11. +4
    -3
      octodns/record/geo.py

+ 4
- 0
.changelog/0a8ba4255d9a4ba29ac6f55fb83cd624.md View File

@ -0,0 +1,4 @@
---
type: none
---
Fix all sphinx docstring errors and warnings, not links

+ 8
- 3
docs/index.md View File

@ -81,7 +81,12 @@ ______________________________________________________________________
- {ref}`genindex`
- {ref}`modindex`
### Project info
- [License](info/license.md)
- [Changelog](info/changelog.md)
```{toctree}
:caption: Project info:
:titlesonly:
info/changelog.md
info/license.md
```

+ 9
- 6
octodns/manager.py View File

@ -442,13 +442,16 @@ class Manager(object):
'''
Accepts either UTF-8 or IDNA encoded zone name and returns the list of
any configured sub-zones in IDNA form. E.g. for the following
configured zones:
some.com.
other.some.com.
deep.thing.some.com.
Configured zones:
- some.com.
- other.some.com.
- deep.thing.some.com.
It would return
other
deep.thing
- other
- deep.thing
'''
if self._configured_sub_zones is None:
# First time through we compute all the sub-zones


+ 11
- 9
octodns/processor/acme.py View File

@ -12,18 +12,20 @@ class AcmeManagingProcessor(BaseProcessor):
def __init__(self, name):
'''
processors:
acme:
class: octodns.processor.acme.AcmeManagingProcessor
Example configuration::
...
zones:
something.com.:
...
processors:
- acme
acme:
class: octodns.processor.acme.AcmeManagingProcessor
...
zones:
something.com.:
...
processors:
- acme
...
'''
super().__init__(name)


+ 22
- 21
octodns/processor/base.py View File

@ -50,28 +50,29 @@ class BaseProcessor(object):
def process_source_and_target_zones(self, desired, existing, target):
'''
Called just prior to computing changes for `target` between `desired`
and `existing`. Provides an opportunity for the processor to modify
either the desired or existing `Zone`s that will be used to compute the
changes and create the initial plan.
Called just prior to computing changes for ``target`` between
``desired`` and `existing`. Provides an opportunity for the processor
to modify either the desired or existing ``Zone`` that will be used to
compute the changes and create the initial plan.
- 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`.
- 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``.
'''
return desired, existing


+ 244
- 244
octodns/processor/filter.py View File

@ -59,27 +59,27 @@ class _TypeBaseFilter(_FilterProcessor):
class TypeAllowlistFilter(_TypeBaseFilter, AllowsMixin):
'''Only manage records of the specified type(s).
Example usage:
processors:
only-a-and-aaaa:
class: octodns.processor.filter.TypeAllowlistFilter
allowlist:
- A
- AAAA
# Optional param that can be set to False to leave the target zone
# alone, thus allowing deletion of existing records
# (default: true)
# include_target: True
zones:
exxampled.com.:
sources:
- config
processors:
- only-a-and-aaaa
targets:
- ns1
Example usage::
processors:
only-a-and-aaaa:
class: octodns.processor.filter.TypeAllowlistFilter
allowlist:
- A
- AAAA
# Optional param that can be set to False to leave the target zone
# alone, thus allowing deletion of existing records
# (default: true)
# include_target: True
zones:
exxampled.com.:
sources:
- config
processors:
- only-a-and-aaaa
targets:
- ns1
'''
def __init__(self, name, allowlist, **kwargs):
@ -89,26 +89,26 @@ class TypeAllowlistFilter(_TypeBaseFilter, AllowsMixin):
class TypeRejectlistFilter(_TypeBaseFilter, RejectsMixin):
'''Ignore records of the specified type(s).
Example usage:
processors:
ignore-cnames:
class: octodns.processor.filter.TypeRejectlistFilter
rejectlist:
- CNAME
# Optional param that can be set to False to leave the target zone
# alone, thus allowing deletion of existing records
# (default: true)
# include_target: True
zones:
exxampled.com.:
sources:
- config
processors:
- ignore-cnames
targets:
- route53
Example usage::
processors:
ignore-cnames:
class: octodns.processor.filter.TypeRejectlistFilter
rejectlist:
- CNAME
# Optional param that can be set to False to leave the target zone
# alone, thus allowing deletion of existing records
# (default: true)
# include_target: True
zones:
exxampled.com.:
sources:
- config
processors:
- ignore-cnames
targets:
- route53
'''
def __init__(self, name, rejectlist, **kwargs):
@ -146,33 +146,33 @@ class _NameBaseFilter(_FilterProcessor):
class NameAllowlistFilter(_NameBaseFilter, AllowsMixin):
'''Only manage records with names that match the provider patterns
Example usage:
processors:
only-these:
class: octodns.processor.filter.NameAllowlistFilter
allowlist:
# exact string match
- www
# contains/substring match
- /substring/
# regex pattern match
- /some-pattern-\\d\\+/
# regex - anchored so has to match start to end
- /^start-.+-end$/
# Optional param that can be set to False to leave the target zone
# alone, thus allowing deletion of existing records
# (default: true)
# include_target: True
zones:
exxampled.com.:
sources:
- config
processors:
- only-these
targets:
- route53
Example usage::
processors:
only-these:
class: octodns.processor.filter.NameAllowlistFilter
allowlist:
# exact string match
- www
# contains/substring match
- /substring/
# regex pattern match
- /some-pattern-\\d\\+/
# regex - anchored so has to match start to end
- /^start-.+-end$/
# Optional param that can be set to False to leave the target zone
# alone, thus allowing deletion of existing records
# (default: true)
# include_target: True
zones:
exxampled.com.:
sources:
- config
processors:
- only-these
targets:
- route53
'''
def __init__(self, name, allowlist, **kwargs):
@ -182,33 +182,33 @@ class NameAllowlistFilter(_NameBaseFilter, AllowsMixin):
class NameRejectlistFilter(_NameBaseFilter, RejectsMixin):
'''Reject managing records with names that match the provider patterns
Example usage:
processors:
not-these:
class: octodns.processor.filter.NameRejectlistFilter
rejectlist:
# exact string match
- www
# contains/substring match
- /substring/
# regex pattern match
- /some-pattern-\\d\\+/
# regex - anchored so has to match start to end
- /^start-.+-end$/
# Optional param that can be set to False to leave the target zone
# alone, thus allowing deletion of existing records
# (default: true)
# include_target: True
zones:
exxampled.com.:
sources:
- config
processors:
- not-these
targets:
- route53
Example usage::
processors:
not-these:
class: octodns.processor.filter.NameRejectlistFilter
rejectlist:
# exact string match
- www
# contains/substring match
- /substring/
# regex pattern match
- /some-pattern-\\d\\+/
# regex - anchored so has to match start to end
- /^start-.+-end$/
# Optional param that can be set to False to leave the target zone
# alone, thus allowing deletion of existing records
# (default: true)
# include_target: True
zones:
exxampled.com.:
sources:
- config
processors:
- not-these
targets:
- route53
'''
def __init__(self, name, rejectlist, **kwargs):
@ -255,33 +255,33 @@ class _ValueBaseFilter(_FilterProcessor):
class ValueAllowlistFilter(_ValueBaseFilter, AllowsMixin):
'''Only manage records with values that match the provider patterns
Example usage:
processors:
only-these:
class: octodns.processor.filter.ValueAllowlistFilter
allowlist:
# exact string match
- www
# contains/substring match
- /substring/
# regex pattern match
- /some-pattern-\\d\\+/
# regex - anchored so has to match start to end
- /^start-.+-end$/
# Optional param that can be set to False to leave the target zone
# alone, thus allowing deletion of existing records
# (default: true)
# include_target: True
zones:
exxampled.com.:
sources:
- config
processors:
- only-these
targets:
- route53
Example usage::
processors:
only-these:
class: octodns.processor.filter.ValueAllowlistFilter
allowlist:
# exact string match
- www
# contains/substring match
- /substring/
# regex pattern match
- /some-pattern-\\d\\+/
# regex - anchored so has to match start to end
- /^start-.+-end$/
# Optional param that can be set to False to leave the target zone
# alone, thus allowing deletion of existing records
# (default: true)
# include_target: True
zones:
exxampled.com.:
sources:
- config
processors:
- only-these
targets:
- route53
'''
def __init__(self, name, allowlist, **kwargs):
@ -292,33 +292,33 @@ class ValueAllowlistFilter(_ValueBaseFilter, AllowsMixin):
class ValueRejectlistFilter(_ValueBaseFilter, RejectsMixin):
'''Reject managing records with names that match the provider patterns
Example usage:
processors:
not-these:
class: octodns.processor.filter.ValueRejectlistFilter
rejectlist:
# exact string match
- www
# contains/substring match
- /substring/
# regex pattern match
- /some-pattern-\\d\\+/
# regex - anchored so has to match start to end
- /^start-.+-end$/
# Optional param that can be set to False to leave the target zone
# alone, thus allowing deletion of existing records
# (default: true)
# include_target: True
zones:
exxampled.com.:
sources:
- config
processors:
- not-these
targets:
- route53
Example usage::
processors:
not-these:
class: octodns.processor.filter.ValueRejectlistFilter
rejectlist:
# exact string match
- www
# contains/substring match
- /substring/
# regex pattern match
- /some-pattern-\\d\\+/
# regex - anchored so has to match start to end
- /^start-.+-end$/
# Optional param that can be set to False to leave the target zone
# alone, thus allowing deletion of existing records
# (default: true)
# include_target: True
zones:
exxampled.com.:
sources:
- config
processors:
- not-these
targets:
- route53
'''
def __init__(self, name, rejectlist, **kwargs):
@ -356,27 +356,27 @@ class _NetworkValueBaseFilter(BaseProcessor):
class NetworkValueAllowlistFilter(_NetworkValueBaseFilter, AllowsMixin):
'''Only manage A and AAAA records with values that match the provider patterns
All other types will be left as-is.
Example usage:
processors:
only-these:
class: octodns.processor.filter.NetworkValueAllowlistFilter
allowlist:
- 127.0.0.1/32
- 192.168.0.0/16
- fd00::/8
zones:
exxampled.com.:
sources:
- config
processors:
- only-these
targets:
- route53
'''Only manage A and AAAA records with values that match the provider
patterns All other types will be left as-is.
Example usage::
processors:
only-these:
class: octodns.processor.filter.NetworkValueAllowlistFilter
allowlist:
- 127.0.0.1/32
- 192.168.0.0/16
- fd00::/8
zones:
exxampled.com.:
sources:
- config
processors:
- only-these
targets:
- route53
'''
def __init__(self, name, allowlist):
@ -384,27 +384,27 @@ class NetworkValueAllowlistFilter(_NetworkValueBaseFilter, AllowsMixin):
class NetworkValueRejectlistFilter(_NetworkValueBaseFilter, RejectsMixin):
'''Reject managing A and AAAA records with value matching a that match the provider patterns
All other types will be left as-is.
Example usage:
processors:
not-these:
class: octodns.processor.filter.NetworkValueRejectlistFilter
rejectlist:
- 127.0.0.1/32
- 192.168.0.0/16
- fd00::/8
zones:
exxampled.com.:
sources:
- config
processors:
- not-these
targets:
- route53
'''Reject managing A and AAAA records with value matching a that match the
provider patterns All other types will be left as-is.
Example usage::
processors:
not-these:
class: octodns.processor.filter.NetworkValueRejectlistFilter
rejectlist:
- 127.0.0.1/32
- 192.168.0.0/16
- fd00::/8
zones:
exxampled.com.:
sources:
- config
processors:
- not-these
targets:
- route53
'''
def __init__(self, name, rejectlist):
@ -414,20 +414,20 @@ class NetworkValueRejectlistFilter(_NetworkValueBaseFilter, RejectsMixin):
class IgnoreRootNsFilter(BaseProcessor):
'''Do not manage Root NS Records.
Example usage:
Example usage::
processors:
no-root-ns:
class: octodns.processor.filter.IgnoreRootNsFilter
processors:
no-root-ns:
class: octodns.processor.filter.IgnoreRootNsFilter
zones:
exxampled.com.:
sources:
- config
processors:
- no-root-ns
targets:
- ns1
zones:
exxampled.com.:
sources:
- config
processors:
- no-root-ns
targets:
- ns1
'''
def _process(self, zone, *args, **kwargs):
@ -444,25 +444,25 @@ class IgnoreRootNsFilter(BaseProcessor):
class ExcludeRootNsChanges(BaseProcessor):
'''Do not allow root NS record changes
Example usage:
processors:
exclude-root-ns-changes:
class: octodns.processor.filter.ExcludeRootNsChanges
# If true an a change for a root NS is seen an error will be thrown. If
# false a warning will be printed and the change will be removed from
# the plan.
# (default: true)
error: true
zones:
exxampled.com.:
sources:
- config
processors:
- exclude-root-ns-changes
targets:
- ns1
Example usage::
processors:
exclude-root-ns-changes:
class: octodns.processor.filter.ExcludeRootNsChanges
# If true an a change for a root NS is seen an error will be thrown.
# If false a warning will be printed and the change will be removed
# from the plan.
# (default: true)
error: true
zones:
exxampled.com.:
sources:
- config
processors:
- exclude-root-ns-changes
targets:
- ns1
'''
def __init__(self, name, error=True):
@ -492,28 +492,28 @@ class ExcludeRootNsChanges(BaseProcessor):
class ZoneNameFilter(_FilterProcessor):
'''Filter or error on record names that contain the zone name
Example usage:
processors:
zone-name:
class: octodns.processor.filter.ZoneNameFilter
# If true a ValidationError will be throw when such records are
# encouterd, if false the records will just be ignored/omitted.
# (default: true)
# error: True
# Optional param that can be set to False to leave the target zone
# alone, thus allowing deletion of existing records
# (default: true)
# include_target: True
zones:
exxampled.com.:
sources:
- config
processors:
- zone-name
targets:
- azure
Example usage::
processors:
zone-name:
class: octodns.processor.filter.ZoneNameFilter
# If true a ValidationError will be throw when such records are
# encouterd, if false the records will just be ignored/omitted.
# (default: true)
# error: True
# Optional param that can be set to False to leave the target zone
# alone, thus allowing deletion of existing records
# (default: true)
# include_target: True
zones:
exxampled.com.:
sources:
- config
processors:
- zone-name
targets:
- azure
'''
def __init__(self, name, error=True, **kwargs):


+ 21
- 21
octodns/processor/restrict.py View File

@ -18,32 +18,32 @@ class TtlRestrictionFilter(BaseProcessor):
default maximum is 604800 (seven days.) allowed_ttls is only used when
explicitly configured and min and max are ignored in that case.
Example usage:
Example usage::
processors:
min-max-ttl:
class: octodns.processor.restrict.TtlRestrictionFilter
min_ttl: 60
max_ttl: 3600
# allowed_ttls: [300, 900, 3600]
processors:
min-max-ttl:
class: octodns.processor.restrict.TtlRestrictionFilter
min_ttl: 60
max_ttl: 3600
# allowed_ttls: [300, 900, 3600]
zones:
exxampled.com.:
sources:
- config
processors:
- min-max-ttl
targets:
- azure
zones:
exxampled.com.:
sources:
- config
processors:
- min-max-ttl
targets:
- azure
The restriction can be skipped for specific records by setting the lenient
flag, e.g.
flag, e.g.::
a:
octodns:
lenient: true
ttl: 0
value: 1.2.3.4
a:
octodns:
lenient: true
ttl: 0
value: 1.2.3.4
The higher level lenient flags are not checked as it would make more sense
to just avoid enabling the processor in those cases.


+ 20
- 20
octodns/processor/spf.py View File

@ -25,30 +25,30 @@ class SpfDnsLookupProcessor(BaseProcessor):
'''
Validate that SPF values in TXT records are valid.
Example usage:
Example usage::
processors:
spf:
class: octodns.processor.spf.SpfDnsLookupProcessor
processors:
spf:
class: octodns.processor.spf.SpfDnsLookupProcessor
zones:
example.com.:
sources:
- config
processors:
- spf
targets:
- route53
zones:
example.com.:
sources:
- config
processors:
- spf
targets:
- route53
The validation can be skipped for specific records by setting the lenient
flag, e.g.
_spf:
octodns:
lenient: true
ttl: 86400
type: TXT
value: v=spf1 ptr ~all
flag, e.g.::
_spf:
octodns:
lenient: true
ttl: 86400
type: TXT
value: v=spf1 ptr ~all
'''
log = getLogger('SpfDnsLookupProcessor')


+ 33
- 34
octodns/processor/templating.py View File

@ -19,34 +19,34 @@ class Templating(BaseProcessor):
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.
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`
@ -54,17 +54,16 @@ class Templating(BaseProcessor):
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.
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)
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.
'''
def __init__(self, id, *args, trailing_dots=True, context={}, **kwargs):


+ 70
- 64
octodns/provider/yaml.py View File

@ -16,9 +16,12 @@ from .base import BaseProvider
class YamlProvider(BaseProvider):
'''
Core provider for records configured in yaml files on disk.
Example Configuration
---------------------
config:
Core provider for records configured in yaml files on disk.::
config:
class: octodns.provider.yaml.YamlProvider
# The location of yaml config files. By default records are defined in a
@ -77,11 +80,10 @@ class YamlProvider(BaseProvider):
# (optional, default True)
escaped_semicolons: True
Note
----
.. Note::
When using this provider as a target any existing comments or formatting
in the zone files will be lost when changes are applyed.
When using this provider as a target any existing comments or formatting in
the zone files will be lost when changes are applyed.
Split Details
-------------
@ -93,13 +95,13 @@ class YamlProvider(BaseProvider):
organize them.
With `split_extension: .` the directory structure for the zone github.com.
managed under directory "zones/" would look like:
managed under directory "zones/" would look like::
zones/
github.com./
$github.com.yaml
www.yaml
...
zones/
github.com./
$github.com.yaml
www.yaml
...
Overriding Values
-----------------
@ -110,63 +112,67 @@ class YamlProvider(BaseProvider):
to external DNS providers and internally, but you want to modify some of
the records in the internal version.
config/octodns.com.yaml
---
other:
type: A
values:
- 192.30.252.115
- 192.30.252.116
www:
type: A
values:
- 192.30.252.113
- 192.30.252.114
internal/octodns.com.yaml
---
'www':
type: A
values:
- 10.0.0.12
- 10.0.0.13
external.yaml
---
providers:
config:
class: octodns.provider.yaml.YamlProvider
directory: ./config
config/octodns.com.yaml::
zones:
---
other:
type: A
values:
- 192.30.252.115
- 192.30.252.116
www:
type: A
values:
- 192.30.252.113
- 192.30.252.114
octodns.com.:
sources:
- config
targets:
- route53
internal.yaml
---
providers:
config:
class: octodns.provider.yaml.YamlProvider
directory: ./config
internal/octodns.com.yaml::
internal:
class: octodns.provider.yaml.YamlProvider
directory: ./internal
populate_should_replace: true
---
'www':
type: A
values:
- 10.0.0.12
- 10.0.0.13
external.yaml::
---
providers:
config:
class: octodns.provider.yaml.YamlProvider
directory: ./config
zones:
octodns.com.:
sources:
- config
targets:
- route53
internal.yaml::
---
providers:
config:
class: octodns.provider.yaml.YamlProvider
directory: ./config
internal:
class: octodns.provider.yaml.YamlProvider
directory: ./internal
populate_should_replace: true
zones:
zones:
octodns.com.:
sources:
- config
- internal
targets:
- pdns
octodns.com.:
sources:
- config
- internal
targets:
- pdns
You can then sync our records eternally with `--config-file=external.yaml`
and internally (with the custom overrides) with
@ -487,7 +493,7 @@ class SplitYamlProvider(YamlProvider):
DEPRECATED: Use YamlProvider with the split_extension parameter instead.
When migrating the following configuration options would result in the same
behavior as SplitYamlProvider
behavior as SplitYamlProvider::
config:
class: octodns.provider.yaml.YamlProvider


+ 4
- 3
octodns/record/geo.py View File

@ -20,9 +20,10 @@ class GeoCodes(object):
'''
Validates an octoDNS geo code making sure that it is a valid and
corresponding:
* continent
* continent & country
* continent, country, & province
* continent
* continent & country
* continent, country, & province
'''
reasons = []


Loading…
Cancel
Save