name.rst 1.7 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243
  1. .. module:: dns.name
  2. .. _name:
  3. DNS Names
  4. =========
  5. Objects of the dns.name.Name class represent an immutable domain name.
  6. The representation is a tuple of labels, with each lable being a ``binary``
  7. object in the DNS wire format. Typically names are not created by
  8. supplying the labels tuple directly, but rather by converting from DNS
  9. text format or the DNS wire format.
  10. Labels are in the same order as in the DNS textual form, e.g. the labels
  11. value for ``www.dnspython.org.`` is ``(b'www', b'dnspython', b'org', b'')`` on
  12. Python 3, and ``('www', 'dnspython', 'org', '')`` on Python 2.
  13. Names may be *absolute* or *relative*. Absolute names end in the root label,
  14. which is an empty ``binary``. Relative names do not end in the root label. To
  15. convert a relative name to an absolute name requires specifying an *origin*.
  16. Typically the origin is known by context. Dnspython provides tools to
  17. relativize and derelativize names. It's a good idea not to mix relative
  18. and absolute names, other than in the context of a zone. Names encoded
  19. in the DNS wire protocol are always absolute. Dnspython's functions to
  20. make names from text also default to an origin of the root name, and thus
  21. to make a relative name using them you must specify an origin of None or
  22. ``dns.name.empty``.
  23. Names are compared and ordered according to the rules of the DNS. The
  24. order is the DNSSEC canonical ordering. Relative names always sort before
  25. absolute names.
  26. Names may also be compared according to the DNS tree hierarchy with
  27. the ``fullcompare()`` method. For example ```www.dnspython.org.`` is
  28. a subdomain of ``dnspython.org.``. See the method description for
  29. full details.
  30. .. toctree::
  31. name-class
  32. name-make
  33. name-dict
  34. name-helpers
  35. name-codecs