Rdataset, RRset and Node Classes

An Rdataset is a set of Rdata objects which all have the same rdatatype, rdataclass, and covered type. Rdatasets also have a ttl (DNS time-to-live) field. Rdatasets support the normal Python set API, but are also ordered.

An RRset is a subclass of Rdataset that also has an owner name, i.e. a dns.name.Name that says where in the DNS tree this set is located.

A Node is a set of Rdataset objects, the Rdatasets being interpreted as at the same place (i.e. same owner name) int the DNS tree. Nodes are primarily used in Zone objects.

class dns.rdataset.Rdataset(rdclass: RdataClass, rdtype: RdataType, covers: RdataType = RdataType.TYPE0, ttl: int = 0)[source]

A DNS rdataset.

Create a new rdataset of the specified class and type.

Parameters:
add(rd: Rdata, ttl: int | None = None) → None[source]

Add the specified rdata to the rdataset.

If the optional ttl parameter is supplied, then self.update_ttl(ttl) will be called prior to adding the rdata.

Parameters:

  • rd (dns.rdata.Rdata) – The rdata to add.

  • ttl (int or None) – The TTL.

Raises:
intersection_update(other)[source]

Update the set, removing any elements from other which are not in both sets.

match(rdclass: RdataClass, rdtype: RdataType, covers: RdataType) → bool[source]

Returns True if this rdataset matches the specified class, type, and covers.

processing_order() → list[Rdata][source]

Return rdatas in a valid processing order according to the type’s specification. For example, MX records are in preference order from lowest to highest preferences, with items of the same preference shuffled.

For types that do not define a processing order, the rdatas are simply shuffled.

to_styled_text(style: RdatasetStyle, name: Name | None = None) → str[source]

Convert the rdataset into styled text format.

See the documentation for dns.rdataset.RdatasetStyle for a description of the style parameters.

to_text(name: Name | None = None, origin: Name | None = None, relativize: bool = True, override_rdclass: RdataClass | None = None, want_comments: bool = False, style: RdatasetStyle | None = None, **kw: Any) → str[source]

Convert the rdataset into DNS zone file format.

See dns.name.Name.choose_relativity for more information on how origin and relativize determine the way names are emitted.

Any additional keyword arguments are passed on to the rdata to_text() method.

Parameters:

  • name (dns.name.Name or None) – If not None, emit RRs with this as the owner name.

  • origin (dns.name.Name or None) – The origin for relative names.

  • relativize (bool) – If True, names will be relativized to origin.

  • override_rdclass (dns.rdataclass.RdataClass or None) – If not None, emit records as if they were of this class.

  • want_comments (bool) – If True, emit comments for rdata which have them. The default is False.

  • style (dns.rdataset.RdatasetStyle or None) – If specified, overrides the other parameters except name.

to_wire(name: Name, file: Any, compress: dict[Name, int] | None = None, origin: Name | None = None, override_rdclass: RdataClass | None = None, want_shuffle: bool = True) → int[source]

Convert the rdataset to wire format.

Parameters:

  • name (dns.name.Name) – The owner name to use.

  • file – The file where the name is emitted (typically a BytesIO file).

  • compress (dict or None) – The compression table to use. If None (the default), names will not be compressed.

  • origin (dns.name.Name or None) – If the name is relative and origin is not None, origin will be appended to it.

  • override_rdclass (int or None) – If not None, used as the class instead of the class of the rdataset. Useful for dynamic update rendering.

  • want_shuffle (bool) – If True, the order of Rdatas within the Rdataset will be shuffled before rendering.

Returns:

The number of records emitted.

Return type:

int

union_update(other)[source]

Update the set, adding any elements from other which are not already in the set.

update(other)[source]

Add all rdatas in other to self.

Parameters:

other (dns.rdataset.Rdataset) – The rdataset from which to update.

update_ttl(ttl: int) → None[source]

Perform TTL minimization.

Set the TTL of the rdataset to be the lesser of the set’s current TTL or the specified TTL. If the set contains no rdatas, set the TTL to the specified TTL.

Parameters:

ttl (int or str) – The candidate TTL value.

class dns.rdataset.RdatasetStyle(omit_final_dot: bool = False, idna_codec: IDNACodec | None = None, origin: Name | None = None, relativize: bool = False, txt_is_utf8: bool = False, base64_chunk_size: int = 32, base64_chunk_separator: str = ' ', hex_chunk_size: int = 128, hex_chunk_separator: str = ' ', truncate_crypto: bool = False, override_rdclass: RdataClass | None = None, want_comments: bool = False, omit_rdclass: bool = False, omit_ttl: bool = False, want_generic: bool = False, deduplicate_names: bool = False, first_name_is_duplicate: bool = False, default_ttl: int | None = None, name_just: int = 0, ttl_just: int = 0, rdclass_just: int = 0, rdtype_just: int = 0)[source]

Rdataset text styles

An RdatasetStyle is also a dns.name.NameStyle and a dns.rdata.RdataStyle. See those classes for a description of their options.

override_rdclass

A dns.rdataclass.RdataClass or None. If not None, use this class instead of the Rdataset’s class.

want_comments

A bool. If True, emit comments for rdata which have them. The default is False.

omit_rdclass

A bool. If True, do not print the RdataClass. The default is False.

omit_ttl

A bool. If True, do not print the TTL. The default is False. Use of this option may lose information.

want_generic

A bool. If True, print RdataClass, RdataType, and Rdatas in the generic format (the “unknown rdata format”). The default is False.

deduplicate_names

A bool. If True, print whitespace instead of the owner name when the owner name of an RR is the same as the prior RR’s owner name. The default is False.

first_name_is_duplicate

A bool. If True, consider the first owner name of the rdataset as a duplicate too, emitting whitespace for it as well. Useful when emitting a Node of multiple rdatasets and the current rdataset is not the first. The default is False.

default_ttl

An int or None. If None (the default), there is no default TTL. If an integer is specified, any TTL matching that value will be omitted. When emitting a zonefile, a value other than None will cause a $TTL directive to be emitted.

name_just

An int. The owner name field justification. Negative values are left-justified, positive values are right-justified. Zero (the default) means no justification.

ttl_just

An int. The TTL field justification. Negative values are left-justified, positive values are right-justified. Zero (the default) means no justification.

rdclass_just

An int. The RdataClass field justification. Negative values are left-justified, positive values are right-justified. Zero (the default) means no justification.

rdtype_just

An int. The RdataType field justification. Negative values are left-justified, positive values are right-justified. Zero (the default) means no justification.

class dns.rrset.RRset(name: Name, rdclass: RdataClass, rdtype: RdataType, covers: RdataType = RdataType.TYPE0, deleting: RdataClass | None = None)[source]

A DNS RRset (named rdataset).

RRset inherits from Rdataset, and RRsets can be treated as Rdatasets in most cases. There are, however, a few notable exceptions. RRsets have different to_wire() and to_text() method arguments, reflecting the fact that RRsets always have an owner name.

Create a new RRset.

full_match(name: Name, rdclass: RdataClass, rdtype: RdataType, covers: RdataType, deleting: RdataClass | None = None) → bool[source]

Returns True if this rrset matches the specified name, class, type, covers, and deletion state.

match(*args: Any, **kwargs: Any) → bool[source]

Does this rrset match the specified attributes?

Behaves as full_match() if the first argument is a dns.name.Name, and as dns.rdataset.Rdataset.match() otherwise.

(This behavior fixes a design mistake where the signature of this method became incompatible with that of its superclass. The fix makes RRsets matchable as Rdatasets while preserving backwards compatibility.)

to_rdataset() → Rdataset[source]

Convert an RRset into an Rdataset.

Return type:

dns.rdataset.Rdataset

to_styled_text(style: RdatasetStyle) → str[source]

Convert the RRset to styled text.

A new style is made from the specified style setting the override_rdclass attribute appropriately for the deleting status of the RRset.

style, a dns.rdataset.RdatasetStyle or None (the default). If specified, the style overrides the other parameters.

Return type:

str

to_text(origin: Name | None = None, relativize: bool = True, want_comments: bool = False, style: RdatasetStyle | None = None, **kw: Any) → str[source]

Convert the RRset into DNS zone file format.

See dns.name.Name.choose_relativity for more information on how origin and relativize determine the way names are emitted.

Any additional keyword arguments are passed on to the rdata to_text() method.

Parameters:

  • origin (dns.name.Name or None) – The origin for relative names.

  • relativize (bool) – If True, names will be relativized to origin.

  • want_comments (bool) – If True, emit comments for rdata which have them. The default is False.

  • style (dns.rdataset.RdatasetStyle or None) – If specified, overrides the other parameters.

to_wire(file: Any, compress: dict[Name, int] | None = None, origin: Name | None = None, **kw: Any) → int[source]

Convert the RRset to wire format.

All keyword arguments are passed to dns.rdataset.to_wire(); see that function for details.

Returns:

The number of records emitted.

Return type:

int

class dns.node.Node[source]

A Node is a set of rdatasets.

A node is either a CNAME node or an “other data” node. A CNAME node contains only CNAME, KEY, NSEC, and NSEC3 rdatasets along with their covering RRSIG rdatasets. An “other data” node contains any rdataset other than a CNAME or RRSIG(CNAME) rdataset. When changes are made to a node, the CNAME or “other data” state is always consistent with the update, i.e. the most recent change wins. For example, if you have a node which contains a CNAME rdataset, and then add an MX rdataset to it, then the CNAME rdataset will be deleted. Likewise if you have a node containing an MX rdataset and add a CNAME rdataset, the MX rdataset will be deleted.

classify() → NodeKind[source]

Classify a node.

A node which contains a CNAME or RRSIG(CNAME) is a NodeKind.CNAME node.

A node which contains only “neutral” types, i.e. types allowed to co-exist with a CNAME, is a NodeKind.NEUTRAL node. The neutral types are NSEC, NSEC3, KEY, and their associated RRSIGS. An empty node is also considered neutral.

A node which contains some rdataset which is not a CNAME, RRSIG(CNAME), or a neutral type is a a NodeKind.REGULAR node. Regular nodes are also commonly referred to as “other data”.

delete_rdataset(rdclass: RdataClass, rdtype: RdataType, covers: RdataType = RdataType.TYPE0) → None[source]

Delete the rdataset matching the specified properties in the current node.

If a matching rdataset does not exist, it is not an error.

Parameters:
find_rdataset(rdclass: RdataClass, rdtype: RdataType, covers: RdataType = RdataType.TYPE0, create: bool = False) → Rdataset[source]

Find an rdataset matching the specified properties in the current node.

Parameters:
Raises:

KeyError – If no matching rdataset exists and create is not True.

Return type:

dns.rdataset.Rdataset

get_rdataset(rdclass: RdataClass, rdtype: RdataType, covers: RdataType = RdataType.TYPE0, create: bool = False) → Rdataset | None[source]

Get an rdataset matching the specified properties in the current node.

None is returned if an rdataset of the specified type and class does not exist and create is not True.

Parameters:
Return type:

dns.rdataset.Rdataset or None

replace_rdataset(replacement: Rdataset) → None[source]

Replace an rdataset.

It is not an error if there is no rdataset matching replacement.

Ownership of the replacement object is transferred to the node; in other words, this method does not store a copy of replacement at the node, it stores replacement itself.

Parameters:

replacement (dns.rdataset.Rdataset) – The replacement rdataset.

Raises:

ValueError – If replacement is not a dns.rdataset.Rdataset.

to_styled_text(style: NodeStyle, name: Name) → str[source]

Convert a node to text format.

Each rdataset at the node is printed.

Parameters:

name (dns.name.Name) – The owner name of the rdatasets.

See the documentation for dns.node.NodeStyle for a description of the style parameters.

Return type:

str

to_text(name: Name, style: NodeStyle | None = None, **kw: Any) → str[source]

Convert a node to text format.

Each rdataset at the node is printed. Any keyword arguments to this method are passed on to the rdataset’s to_text() method.

Parameters:

  • name (dns.name.Name) – The owner name of the rdatasets.

  • style (dns.node.NodeStyle or None) – If specified, overrides the other parameters except name.

Return type:

str

class dns.node.ImmutableNode(*args, **kwargs)[source]
class dns.node.NodeKind(value)[source]

Rdatasets in nodes

CNAME = 2

Has a CNAME or RRSIG(CNAME)

NEUTRAL = 1

Has rdatasets compatible with CNAME, but no CNAME

REGULAR = 0

Has rdatasets not compatible with CNAME

class dns.node.NodeStyle(omit_final_dot: bool = False, idna_codec: IDNACodec | None = None, origin: Name | None = None, relativize: bool = False, txt_is_utf8: bool = False, base64_chunk_size: int = 32, base64_chunk_separator: str = ' ', hex_chunk_size: int = 128, hex_chunk_separator: str = ' ', truncate_crypto: bool = False, override_rdclass: RdataClass | None = None, want_comments: bool = False, omit_rdclass: bool = False, omit_ttl: bool = False, want_generic: bool = False, deduplicate_names: bool = False, first_name_is_duplicate: bool = False, default_ttl: int | None = None, name_just: int = 0, ttl_just: int = 0, rdclass_just: int = 0, rdtype_just: int = 0)[source]

Node text styles.

A NodeStyle is also a dns.name.NameStyle and a dns.rdata.RdataStyle, and a dns.rdataset.RdatasetStyle. See those classes for a description of their options.

There are currently no node-specific style options, but if that changes they will be documented here.