The dns.name.Name Class and Predefined Names

class dns.name.Name(*args, **kwargs)[source]

labels

A tuple of bytes in DNS wire format specifying the DNS labels in the name, in order from least-significant label (i.e. farthest from the origin) to most-significant label.

Type:: tuple[bytes, …]

__init__(*args, **kwargs)

canonicalize() → Name[source]

Return a name which is equal to the current name, but is in DNSSEC canonical form.

Return type:: dns.name.Name

choose_relativity(origin: Name | None = None, relativize: bool = True) → Name[source]

Return a name with the relativity desired by the caller.

If origin is None, then the name is returned. Otherwise, if relativize is True the name is relativized, and if relativize is False the name is derelativized.

Parameters:

origin (dns.name.Name or None) – If not None, controls relativization.
relativize (bool) – If True, relativize; if False, derelativize.

Return type:

dns.name.Name

concatenate(other: Name) → Name[source]

Return a new name which is the concatenation of self and other.

Parameters:: other (dns.name.Name) – The name to concatenate.
Raises:: dns.name.AbsoluteConcatenation – if the name is absolute and other is not the empty name.
Return type:: dns.name.Name

derelativize(origin: Name) → Name[source]

If the name is a relative name, return a new name which is the concatenation of the name and origin. Otherwise return the name.

For example, derelativizing www to origin dnspython.org. returns the name www.dnspython.org.. Derelativizing example. to origin dnspython.org. returns example..

Parameters:: origin (dns.name.Name) – The origin to append.
Return type:: dns.name.Name

fullcompare(other: Name) → tuple[NameRelation, int, int][source]

Compare two names, returning a 3-tuple (relation, order, nlabels).

relation describes the relationship between the names, and is one of: dns.name.NameRelation.NONE, dns.name.NameRelation.SUPERDOMAIN, dns.name.NameRelation.SUBDOMAIN, dns.name.NameRelation.EQUAL, or dns.name.NameRelation.COMMONANCESTOR.

order is < 0 if self < other, > 0 if self > other, and == 0 if self == other. A relative name is always less than an absolute name. If both names have the same relativity, then the DNSSEC order relation is used to order them.

nlabels is the number of significant labels that the two names have in common.

Here are some examples. Names ending in “.” are absolute names, those not ending in “.” are relative names.

self	other	relation	order	nlabels
www.example.	www.example.	equal	0	3
www.example.	example.	subdomain	> 0	2
example.	www.example.	superdomain	< 0	2
example1.com.	example2.com.	common anc.	< 0	2
example1	example2.	none	< 0	0
example1.	example2	none	> 0	0

Parameters:: other (dns.name.Name) – The name to compare with.
Returns:: A 3-tuple (relation, order, nlabels).
Return type:: tuple[dns.name.NameRelation, int, int]

is_absolute() → bool[source]

Is the most significant label of this name the root label?

Return type:: bool

is_subdomain(other: Name) → bool[source]

Is self a subdomain of other?

Note that the notion of subdomain includes equality, e.g. dnspython.org is a subdomain of itself.

Return type:: bool

is_superdomain(other: Name) → bool[source]

Is self a superdomain of other?

Note that the notion of superdomain includes equality, e.g. dnspython.org is a superdomain of itself.

Return type:: bool

is_wild() → bool[source]

Is this name wild? (I.e. Is the least significant label '*'?)

Return type:: bool

parent() → Name[source]

Return the parent of the name.

For example, the parent of www.dnspython.org. is dnspython.org..

Raises:: dns.name.NoParent – if the name is either the root name or the empty name, and thus has no parent.
Return type:: dns.name.Name

predecessor(origin: Name, prefix_ok: bool = True) → Name[source]

Return the maximal predecessor of the name in the DNSSEC ordering.

Returns the maximal predecessor in the zone whose origin is origin, or returns the longest name under origin if the name is origin (i.e. wraps around to the longest name, which may still be origin due to length considerations).

The relativity of the name is preserved, so if this name is relative then the method will return a relative name, and likewise if this name is absolute then the predecessor will be absolute.

Parameters:

origin (dns.name.Name) – The zone origin.
prefix_ok (bool) – If True (the default), prefixing labels is allowed. Specify False when computing a maximal predecessor at a zone cut point.

Return type:

dns.name.Name

relativize(origin: Name) → Name[source]

If the name is a subdomain of origin, return a new name which is the name relative to origin. Otherwise return the name.

For example, relativizing www.dnspython.org. to origin dnspython.org. returns the name www. Relativizing example. to origin dnspython.org. returns example..

Parameters:: origin (dns.name.Name) – The origin to relativize against.
Return type:: dns.name.Name

split(depth: int) → tuple[Name, Name][source]

Split a name into a prefix and suffix names at the specified depth.

Parameters:: depth (int) – The number of labels in the suffix.
Raises:: ValueError – if depth is not >= 0 and <= the length of the name.
Returns:: A (prefix, suffix) tuple.
Return type:: tuple[dns.name.Name, dns.name.Name]

successor(origin: Name, prefix_ok: bool = True) → Name[source]

Return the minimal successor of the name in the DNSSEC ordering.

Returns the minimal successor in the zone whose origin is origin, or returns origin if the successor cannot be computed due to name length limitations.

Note that origin is returned in the “too long” cases because wrapping around to the origin is how NSEC records express “end of the zone”.

The relativity of the name is preserved, so if this name is relative then the method will return a relative name, and likewise if this name is absolute then the successor will be absolute.

Parameters:

origin (dns.name.Name) – The zone origin.
prefix_ok (bool) – If True (the default), prefixing a new minimal label is allowed. Specify False when computing a minimal successor at a zone cut point.

Return type:

dns.name.Name

to_digestable(origin: Name | None = None) → bytes[source]

Convert name to a format suitable for digesting in hashes.

The name is canonicalized and converted to uncompressed wire format. All names in wire format are absolute. If the name is a relative name, then an origin must be supplied.

Parameters:: origin (dns.name.Name or None) – If the name is relative and origin is not None, then origin will be appended to the name.
Raises:: dns.name.NeedAbsoluteNameOrOrigin – if the name is relative and no origin was provided.
Return type:: bytes

to_styled_text(style: NameStyle) → str[source]

Convert name to text format, applying the style.

See the documentation for dns.name.NameStyle for a description of the style parameters.

Parameters:: style (dns.name.NameStyle) – The style to apply.
Return type:: str

to_text(omit_final_dot: bool = False, style: NameStyle | None = None) → str[source]

Convert name to DNS text format.

Parameters:

omit_final_dot (bool) – If True, don’t emit the final dot (denoting the root label) for absolute names. The default is False.
style (dns.name.NameStyle or None) – If specified, the style overrides the other parameters.

Return type:

str

to_unicode(omit_final_dot: bool = False, idna_codec: IDNACodec | None = None, style: NameStyle | None = None) → str[source]

Convert name to DNS text format.

IDN ACE labels are converted to Unicode using the specified codec.

Parameters:

omit_final_dot (bool) – If True, don’t emit the final dot (denoting the root label) for absolute names. The default is False.
idna_codec (dns.name.IDNACodec or None) – The IDNA codec to use for decoding ACE labels. If None, the default IDNA codec is used.
style (dns.name.NameStyle or None) – If specified, the style overrides the other parameters.

Return type:

str

to_wire(file: Any | None = None, compress: dict[Name, int] | None = None, origin: Name | None = None, canonicalize: bool = False) → bytes | None[source]

Convert name to wire format, possibly compressing it.

Parameters:

file – The file where the name is emitted (typically an io.BytesIO file). If None (the default), a bytes containing the wire name will be returned.
compress (dict or None) – The compression table to use. If None (the default), names will not be compressed. Note that the compression code assumes that compression offset 0 is the start of file, and thus compression will not be correct if this is not the case.
origin (dns.name.Name or None) – If the name is relative and origin is not None, then origin will be appended to it.
canonicalize (bool) – Whether the name should be canonicalized; that is, converted to a format suitable for digesting in hashes.

Raises:

dns.name.NeedAbsoluteNameOrOrigin – if the name is relative and no origin was provided.

Returns:

None if file is provided, otherwise the wire format as bytes.

Return type:

bytes or None

dns.name.root: The root name, i.e. dns.name.Name([b'']).

dns.name.empty: The empty name, i.e. dns.name.Name([]).

class dns.name.NameRelation(value)[source]

Name relation result from fullcompare().

COMMONANCESTOR = 4: The compared names have a common ancestor.

EQUAL = 3: The compared names are equal.

NONE = 0: The compared names have no relationship to each other.

SUBDOMAIN = 2: The first name is a subdomain of the second.

SUPERDOMAIN = 1: the first name is a superdomain of the second.

class dns.name.NameStyle(omit_final_dot: bool = False, idna_codec: IDNACodec | None = None, origin: Name | None = None, relativize: bool = False)[source]

Name text styles.

Parameters:

omit_final_dot (bool) – If True, don’t emit the final dot (denoting the root label) for absolute names. The default is False.
idna_codec (dns.name.IDNACodec or None) – The IDNA decoder to use. The default is None, which means all text is in the standard DNS zonefile format, i.e. punycode will not be decoded.
origin (dns.name.Name or None) – If None (the default), the name’s relativity is not altered before conversion to text. Otherwise, if relativize is True the name is relativized, and if relativize is False the name is derelativized.
relativize (bool) – Controls the direction of relativization when origin is set.