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.
- __init__(labels)
Initialize a name using labels, an iterable of
bytes
orstr
.
- canonicalize() Name [source]
Return a name which is equal to the current name, but is in DNSSEC canonical form.
- 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 isTrue
the name is relativized, and if relativize isFalse
the name is derelativized.Returns a
dns.name.Name
.
- concatenate(other: Name) Name [source]
Return a new name which is the concatenation of self and other.
Raises
dns.name.AbsoluteConcatenation
if the name is absolute and other is not the empty name.Returns a
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 origindnspython.org.
returns the namewww.dnspython.org.
. Derelativizingexample.
to origindnspython.org.
returnsexample.
.Returns a
dns.name.Name
.
- fullcompare(other: Name) Tuple[NameRelation, int, int] [source]
Compare two names, returning a 3-tuple
(relation, order, nlabels)
.relation describes the relation ship between the names, and is one of:
dns.name.NameRelation.NONE
,dns.name.NameRelation.SUPERDOMAIN
,dns.name.NameRelation.SUBDOMAIN
,dns.name.NameRelation.EQUAL
, ordns.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
- is_absolute() bool [source]
Is the most significant label of this name the root label?
Returns a
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.
Returns a
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.
Returns a
bool
.
- is_wild() bool [source]
Is this name wild? (I.e. Is the least significant label ‘*’?)
Returns a
bool
.
- parent() Name [source]
Return the parent of the name.
For example, the parent of
www.dnspython.org.
isdnspython.org
.Raises
dns.name.NoParent
if the name is either the root name or the empty name, and thus has no parent.Returns a
dns.name.Name
.
- predecessor(origin: Name, prefix_ok: bool = True) Name [source]
Return the maximal predecessor of name in the DNSSEC ordering in the zone whose origin is origin, or return the longest name under origin if the name is origin (i.e. wrap 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.
prefix_ok indicates if prefixing labels is allowed, and defaults to
True
. Normally it is good to allow this, but if computing a maximal predecessor at a zone cut point thenFalse
must be specified.
- 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 origindnspython.org.
returns the namewww
. Relativizingexample.
to origindnspython.org.
returnsexample.
.Returns a
dns.name.Name
.
- split(depth: int) Tuple[Name, Name] [source]
Split a name into a prefix and suffix names at the specified depth.
depth is an
int
specifying the number of labels in the suffixRaises
ValueError
if depth was not >= 0 and <= the length of the name.Returns the tuple
(prefix, suffix)
.
- successor(origin: Name, prefix_ok: bool = True) Name [source]
Return the minimal successor of name in the DNSSEC ordering in the zone whose origin is origin, or return 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.
prefix_ok indicates if prefixing a new minimal label is allowed, and defaults to
True
. Normally it is good to allow this, but if computing a minimal successor at a zone cut point thenFalse
must be specified.
- 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.
origin is a
dns.name.Name
orNone
. If the name is relative and origin is notNone
, then origin will be appended to the name.Raises
dns.name.NeedAbsoluteNameOrOrigin
if the name is relative and no origin was provided.Returns a
bytes
.
- to_text(omit_final_dot: bool = False) str [source]
Convert name to DNS text format.
omit_final_dot is a
bool
. If True, don’t emit the final dot (denoting the root label) for absolute names. The default is False.Returns a
str
.
- to_unicode(omit_final_dot: bool = False, idna_codec: IDNACodec | None = None) str [source]
Convert name to Unicode text format.
IDN ACE labels are converted to Unicode.
omit_final_dot is a
bool
. If True, don’t emit the final dot (denoting the root label) for absolute names. The default is False. idna_codec specifies the IDNA encoder/decoder. If None, the dns.name.IDNA_2003_Practical encoder/decoder is used. The IDNA_2003_Practical decoder does not impose any policy, it just decodes punycode, so if you don’t want checking for compliance, you can use this decoder for IDNA2008 as well.Returns a
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.
file is the file where the name is emitted (typically an io.BytesIO file). If
None
(the default), abytes
containing the wire name will be returned.compress, a
dict
, is the compression table to use. IfNone
(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 is a
dns.name.Name
orNone
. If the name is relative and origin is notNone
, then origin will be appended to it.canonicalize, a
bool
, indicates 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 a
bytes
orNone
.
- 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, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[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.