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)

A DNS rdataset.

Create a new rdataset of the specified class and type.

rdclass, a dns.rdataclass.RdataClass, the rdataclass.

rdtype, an dns.rdatatype.RdataType, the rdatatype.

covers, an dns.rdatatype.RdataType, the covered rdatatype.

ttl, an int, the TTL.

add(rd: Rdata, ttl: int | None = None) → None

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.

rd, a dns.rdata.Rdata, the rdata

ttl, an int, the TTL.

Raises dns.rdataset.IncompatibleTypes if the type and class do not match the type and class of the rdataset.

Raises dns.rdataset.DifferingCovers if the type is a signature type and the covered type does not match that of the rdataset.

intersection_update(other)

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

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

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

processing_order() → List[Rdata]

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_text(name: Name | None = None, origin: Name | None = None, relativize: bool = True, override_rdclass: RdataClass | None = None, want_comments: bool = False, **kw: Dict[str, Any]) → str

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.

name, a dns.name.Name. If name is not None, emit RRs with name as the owner name.

origin, a dns.name.Name or None, the origin for relative names.

relativize, a bool. If True, names will be relativized to origin.

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.

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

Convert the rdataset to wire format.

name, a dns.name.Name is the owner name to use.

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

compress, a dict, is the compression table to use. If None (the default), names will not be compressed.

origin is a dns.name.Name or None. If the name is relative and origin is not None, then origin will be appended to it.

override_rdclass, an int, is used as the class instead of the class of the rdataset. This is useful when rendering rdatasets associated with dynamic updates.

want_shuffle, a bool. If True, then the order of the Rdatas within the Rdataset will be shuffled before rendering.

Returns an int, the number of records emitted.

union_update(other)

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

update(other)

Add all rdatas in other to self.

other, a dns.rdataset.Rdataset, the rdataset from which to update.

update_ttl(ttl: int) → None

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.

ttl, an int or str.

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

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

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

match(*args: Any, **kwargs: Any) → bool

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

Convert an RRset into an Rdataset.

Returns a dns.rdataset.Rdataset.

to_text(origin: Name | None = None, relativize: bool = True, **kw: Dict[str, Any]) → str

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.

origin, a dns.name.Name or None, the origin for relative names.

relativize, a bool. If True, names will be relativized to origin.

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

Convert the RRset to wire format.

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

Returns an int, the number of records emitted.

class dns.node.Node

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

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

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

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

rdclass, an int, the class of the rdataset.

rdtype, an int, the type of the rdataset.

covers, an int, the covered type.

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

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

rdclass, a dns.rdataclass.RdataClass, the class of the rdataset.

rdtype, a dns.rdatatype.RdataType, the type of the rdataset.

covers, a dns.rdatatype.RdataType, the covered type. Usually this value is dns.rdatatype.NONE, but if the rdtype is dns.rdatatype.SIG or dns.rdatatype.RRSIG, then the covers value will be the rdata type the SIG/RRSIG covers. The library treats the SIG and RRSIG types as if they were a family of types, e.g. RRSIG(A), RRSIG(NS), RRSIG(SOA). This makes RRSIGs much easier to work with than if RRSIGs covering different rdata types were aggregated into a single RRSIG rdataset.

create, a bool. If True, create the rdataset if it is not found.

Raises KeyError if an rdataset of the desired type and class does not exist and create is not True.

Returns a dns.rdataset.Rdataset.

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

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.

rdclass, an int, the class of the rdataset.

rdtype, an int, the type of the rdataset.

covers, an int, the covered type. Usually this value is dns.rdatatype.NONE, but if the rdtype is dns.rdatatype.SIG or dns.rdatatype.RRSIG, then the covers value will be the rdata type the SIG/RRSIG covers. The library treats the SIG and RRSIG types as if they were a family of types, e.g. RRSIG(A), RRSIG(NS), RRSIG(SOA). This makes RRSIGs much easier to work with than if RRSIGs covering different rdata types were aggregated into a single RRSIG rdataset.

create, a bool. If True, create the rdataset if it is not found.

Returns a dns.rdataset.Rdataset or None.

replace_rdataset(replacement: Rdataset) → None

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.

replacement, a dns.rdataset.Rdataset.

Raises ValueError if replacement is not a dns.rdataset.Rdataset.

to_text(name: Name, **kw: Dict[str, Any]) → str

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.

name, a dns.name.Name, the owner name of the rdatasets.

Returns a str.