dns :: name :: Name :: Class Name
[hide private]
[frames] | no frames]

Class Name

source code

object --+
         |
        Name

A DNS name.

The dns.name.Name class represents a DNS name as a tuple of labels. Each label is a `binary` in DNS wire format. Instances of the class are immutable.

Instance Methods [hide private]
 
__init__(self, labels)
*labels* is any iterable whose values are ``text`` or ``binary``.
source code
 
__setattr__(self, name, value)
x.__setattr__('name', value) <==> x.name = value
source code
 
__copy__(self) source code
 
__deepcopy__(self, memo) source code
 
__getstate__(self) source code
 
__setstate__(self, state) source code
 
is_absolute(self)
Is the most significant label of this name the root label?
source code
 
is_wild(self)
Is this name wild? (I.e.
source code
 
__hash__(self)
Return a case-insensitive hash of the name.
source code
 
fullcompare(self, other)
Compare two names, returning a 3-tuple ``(relation, order, nlabels)``.
source code
 
is_subdomain(self, other)
Is self a subdomain of other?
source code
 
is_superdomain(self, other)
Is self a superdomain of other?
source code
 
canonicalize(self)
Return a name which is equal to the current name, but is in DNSSEC canonical form.
source code
 
__eq__(self, other) source code
 
__ne__(self, other) source code
 
__lt__(self, other) source code
 
__le__(self, other) source code
 
__ge__(self, other) source code
 
__gt__(self, other) source code
 
__repr__(self)
repr(x)
source code
 
__str__(self)
str(x)
source code
 
to_text(self, omit_final_dot=False)
Convert name to DNS text format.
source code
 
to_unicode(self, omit_final_dot=False, idna_codec=None)
Convert name to Unicode text format.
source code
 
to_digestable(self, origin=None)
Convert name to a format suitable for digesting in hashes.
source code
 
to_wire(self, file=None, compress=None, origin=None)
Convert name to wire format, possibly compressing it.
source code
 
__len__(self)
The length of the name (in labels).
source code
 
__getitem__(self, index) source code
 
__add__(self, other) source code
 
__sub__(self, other) source code
 
split(self, depth)
Split a name into a prefix and suffix names at the specified depth.
source code
 
concatenate(self, other)
Return a new name which is the concatenation of self and other.
source code
 
relativize(self, origin)
If the name is a subdomain of *origin*, return a new name which is the name relative to origin.
source code
 
derelativize(self, origin)
If the name is a relative name, return a new name which is the concatenation of the name and origin.
source code
 
choose_relativity(self, origin=None, relativize=True)
Return a name with the relativity desired by the caller.
source code
 
parent(self)
Return the parent of the name.
source code

Inherited from object: __delattr__, __format__, __getattribute__, __new__, __reduce__, __reduce_ex__, __sizeof__, __subclasshook__

Properties [hide private]
  labels

Inherited from object: __class__

Method Details [hide private]

__init__(self, labels)
(Constructor)

source code 

*labels* is any iterable whose values are ``text`` or ``binary``.

Overrides: object.__init__

__setattr__(self, name, value)

source code 

x.__setattr__('name', value) <==> x.name = value

Overrides: object.__setattr__
(inherited documentation)

is_absolute(self)

source code 

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

Returns a ``bool``.

is_wild(self)

source code 

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

Returns a ``bool``.

__hash__(self)
(Hashing function)

source code 

Return a case-insensitive hash of the name.

Returns an ``int``.

Overrides: object.__hash__

fullcompare(self, other)

source code 

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

*relation* describes the relation ship between the names, and is one of: ``dns.name.NAMERELN_NONE``, ``dns.name.NAMERELN_SUPERDOMAIN``, ``dns.name.NAMERELN_SUBDOMAIN``, ``dns.name.NAMERELN_EQUAL``, or ``dns.name.NAMERELN_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_subdomain(self, other)

source code 

Is self a subdomain of other?

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

Returns a ``bool``.

is_superdomain(self, other)

source code 

Is self a superdomain of other?

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

Returns a ``bool``.

__repr__(self)
(Representation operator)

source code 

repr(x)

Overrides: object.__repr__
(inherited documentation)

__str__(self)
(Informal representation operator)

source code 

str(x)

Overrides: object.__str__
(inherited documentation)

to_text(self, omit_final_dot=False)

source code 

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 ``text``.

to_unicode(self, omit_final_dot=False, idna_codec=None)

source code 

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 ``text``.

to_digestable(self, origin=None)

source code 

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`` 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.

Returns a ``binary``.

to_wire(self, file=None, compress=None, origin=None)

source code 

Convert name to wire format, possibly compressing it.

*file* is the file where the name is emitted (typically a BytesIO file). If ``None`` (the default), a ``binary`` containing the wire name will be returned.

*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.

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

Returns a ``binary`` or ``None``.

__len__(self)
(Length operator)

source code 

The length of the name (in labels).

Returns an ``int``.

split(self, depth)

source code 

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

*depth* is an ``int`` specifying the number of labels in the suffix

Raises ``ValueError`` if *depth* was not >= 0 and <= the length of the name.

Returns the tuple ``(prefix, suffix)``.

concatenate(self, other)

source code 

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``.

relativize(self, origin)

source code 

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.``.

Returns a ``dns.name.Name``.

derelativize(self, origin)

source code 

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.``.

Returns a ``dns.name.Name``.

choose_relativity(self, origin=None, relativize=True)

source code 

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.

Returns a ``dns.name.Name``.

parent(self)

source code 

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.

Returns a ``dns.name.Name``.