From: Bob Halley Date: Thu, 5 Jan 2017 14:45:13 +0000 (-0800) Subject: rdata doco X-Git-Tag: v1.16.0~85 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=862d8d7c4d87726c305766d627de1951c78d847c;p=thirdparty%2Fdnspython.git rdata doco --- diff --git a/dns/rdata.py b/dns/rdata.py index 3ad0e186..5c6c34de 100644 --- a/dns/rdata.py +++ b/dns/rdata.py @@ -1,4 +1,4 @@ -# Copyright (C) 2001-2007, 2009-2011 Nominum, Inc. +# Copyright (C) 2001-2017 Nominum, Inc. # # Permission to use, copy, modify, and distribute this software and its # documentation for any purpose with or without fee is hereby granted, @@ -13,17 +13,7 @@ # ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT # OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -"""DNS rdata. - -@var _rdata_modules: A dictionary mapping a (rdclass, rdtype) tuple to -the module which implements that type. -@type _rdata_modules: dict -@var _module_prefix: The prefix to use when forming modules names. The -default is 'dns.rdtypes'. Changing this value will break the library. -@type _module_prefix: string -@var _hex_chunk: At most this many octets that will be represented in each -chunk of hexstring that _hexify() produces before whitespace occurs. -@type _hex_chunk: int""" +"""DNS rdata.""" from io import BytesIO import base64 @@ -42,12 +32,7 @@ _hex_chunksize = 32 def _hexify(data, chunksize=_hex_chunksize): """Convert a binary string into its hex encoding, broken up into chunks - of I{chunksize} characters separated by a space. - - @param data: the binary string - @type data: string - @param chunksize: the chunk size. Default is L{dns.rdata._hex_chunksize} - @rtype: string + of chunksize characters separated by a space. """ line = binascii.hexlify(data) @@ -60,13 +45,7 @@ _base64_chunksize = 32 def _base64ify(data, chunksize=_base64_chunksize): """Convert a binary string into its base64 encoding, broken up into chunks - of I{chunksize} characters separated by a space. - - @param data: the binary string - @type data: string - @param chunksize: the chunk size. Default is - L{dns.rdata._base64_chunksize} - @rtype: string + of chunksize characters separated by a space. """ line = base64.b64encode(data) @@ -77,13 +56,7 @@ def _base64ify(data, chunksize=_base64_chunksize): __escaped = bytearray(b'"\\') def _escapify(qstring): - """Escape the characters in a quoted string which need it. - - @param qstring: the string - @type qstring: string - @returns: the escaped string - @rtype: string - """ + """Escape the characters in a quoted string which need it.""" if isinstance(qstring, text_type): qstring = qstring.encode() @@ -104,10 +77,6 @@ def _escapify(qstring): def _truncate_bitmap(what): """Determine the index of greatest byte that isn't all zeros, and return the bitmap that contains all the bytes less than that index. - - @param what: a string of octets representing a bitmap. - @type what: string - @rtype: string """ for i in xrange(len(what) - 1, -1, -1): @@ -117,30 +86,30 @@ def _truncate_bitmap(what): class Rdata(object): - - """Base class for all DNS rdata types. - """ + """Base class for all DNS rdata types.""" __slots__ = ['rdclass', 'rdtype'] def __init__(self, rdclass, rdtype): """Initialize an rdata. - @param rdclass: The rdata class - @type rdclass: int - @param rdtype: The rdata type - @type rdtype: int + + *rdclass*, an ``int`` is the rdataclass of the Rdata. + *rdtype*, an ``int`` is the rdatatype of the Rdata. """ self.rdclass = rdclass self.rdtype = rdtype def covers(self): - """DNS SIG/RRSIG rdatas apply to a specific type; this type is + """Return the type a Rdata covers. + + DNS SIG/RRSIG rdatas apply to a specific type; this type is returned by the covers() function. If the rdata type is not SIG or RRSIG, dns.rdatatype.NONE is returned. This is useful when creating rdatasets, allowing the rdataset to contain only RRSIGs of a particular type, e.g. RRSIG(NS). - @rtype: int + + Returns an ``int``. """ return dns.rdatatype.NONE @@ -149,37 +118,52 @@ class Rdata(object): """Return a 32-bit type value, the least significant 16 bits of which are the ordinary DNS type, and the upper 16 bits of which are the "covered" type, if any. - @rtype: int + + Returns an ``int``. """ return self.covers() << 16 | self.rdtype def to_text(self, origin=None, relativize=True, **kw): """Convert an rdata to text format. - @rtype: string + + Returns a ``text``. """ + raise NotImplementedError def to_wire(self, file, compress=None, origin=None): """Convert an rdata to wire format. - @rtype: string + + Returns a ``binary``. """ raise NotImplementedError def to_digestable(self, origin=None): """Convert rdata to a format suitable for digesting in hashes. This - is also the DNSSEC canonical form.""" + is also the DNSSEC canonical form. + + Returns a ``binary``. + """ + f = BytesIO() self.to_wire(f, None, origin) return f.getvalue() def validate(self): """Check that the current contents of the rdata's fields are - valid. If you change an rdata by assigning to its fields, + valid. + + If you change an rdata by assigning to its fields, it is a good idea to call validate() when you are done making changes. + + Raises various exceptions if there are problems. + + Returns ``None``. """ + dns.rdata.from_text(self.rdclass, self.rdtype, self.to_text()) def __repr__(self): @@ -197,17 +181,20 @@ class Rdata(object): def _cmp(self, other): """Compare an rdata with another rdata of the same rdtype and - rdclass. Return < 0 if self < other in the DNSSEC ordering, - 0 if self == other, and > 0 if self > other. + rdclass. + + Return < 0 if self < other in the DNSSEC ordering, 0 if self + == other, and > 0 if self > other. + """ our = self.to_digestable(dns.name.root) their = other.to_digestable(dns.name.root) if our == their: return 0 - if our > their: + elif our > their: return 1 - - return -1 + else: + return -1 def __eq__(self, other): if not isinstance(other, Rdata): @@ -253,42 +240,10 @@ class Rdata(object): @classmethod def from_text(cls, rdclass, rdtype, tok, origin=None, relativize=True): - """Build an rdata object from text format. - - @param rdclass: The rdata class - @type rdclass: int - @param rdtype: The rdata type - @type rdtype: int - @param tok: The tokenizer - @type tok: dns.tokenizer.Tokenizer - @param origin: The origin to use for relative names - @type origin: dns.name.Name - @param relativize: should names be relativized? - @type relativize: bool - @rtype: dns.rdata.Rdata instance - """ - raise NotImplementedError @classmethod def from_wire(cls, rdclass, rdtype, wire, current, rdlen, origin=None): - """Build an rdata object from wire format - - @param rdclass: The rdata class - @type rdclass: int - @param rdtype: The rdata type - @type rdtype: int - @param wire: The wire-format message - @type wire: string - @param current: The offset in wire of the beginning of the rdata. - @type current: int - @param rdlen: The length of the wire-format rdata - @type rdlen: int - @param origin: The origin to use for relative names - @type origin: dns.name.Name - @rtype: dns.rdata.Rdata instance - """ - raise NotImplementedError def choose_relativity(self, origin=None, relativize=True): @@ -392,20 +347,23 @@ def from_text(rdclass, rdtype, tok, origin=None, relativize=True): Once a class is chosen, its from_text() class method is called with the parameters to this function. - If I{tok} is a string, then a tokenizer is created and the string + If *tok* is a ``text``, then a tokenizer is created and the string is used as its input. - @param rdclass: The rdata class - @type rdclass: int - @param rdtype: The rdata type - @type rdtype: int - @param tok: The tokenizer or input text - @type tok: dns.tokenizer.Tokenizer or string - @param origin: The origin to use for relative names - @type origin: dns.name.Name - @param relativize: Should names be relativized? - @type relativize: bool - @rtype: dns.rdata.Rdata instance""" + *rdclass*, an ``int``, the rdataclass. + + *rdtype*, an ``int``, the rdatatype. + + *tok*, a ``dns.tokenizer.Tokenizer`` or a ``text``. + + *origin*, a ``dns.name.Name`` (or ``None``), the + origin to use for relative names. + + *relativize*, a ``bool``. If true, name will be relativized to + the specified origin. + + Returns an instance of the chosen Rdata subclass. + """ if isinstance(tok, string_types): tok = dns.tokenizer.Tokenizer(tok) @@ -439,19 +397,22 @@ def from_wire(rdclass, rdtype, wire, current, rdlen, origin=None): Once a class is chosen, its from_wire() class method is called with the parameters to this function. - @param rdclass: The rdata class - @type rdclass: int - @param rdtype: The rdata type - @type rdtype: int - @param wire: The wire-format message - @type wire: string - @param current: The offset in wire of the beginning of the rdata. - @type current: int - @param rdlen: The length of the wire-format rdata - @type rdlen: int - @param origin: The origin to use for relative names - @type origin: dns.name.Name - @rtype: dns.rdata.Rdata instance""" + *rdclass*, an ``int``, the rdataclass. + + *rdtype*, an ``int``, the rdatatype. + + *wire*, a ``binary``, the wire-format message. + + *current*, an ``int``, the offset in wire of the beginning of + the rdata. + + *rdlen*, an ``int``, the length of the wire-format rdata + + *origin*, a ``dns.name.Name`` (or ``None``). If not ``None``, + then names will be relativized to this origin. + + Returns an instance of the chosen Rdata subclass. + """ wire = dns.wiredata.maybe_wrap(wire) cls = get_rdata_class(rdclass, rdtype) diff --git a/doc/rdata-class.rst b/doc/rdata-class.rst new file mode 100644 index 00000000..fbe0004b --- /dev/null +++ b/doc/rdata-class.rst @@ -0,0 +1,14 @@ +.. _rdata-class: + +DNS Rdata Base Class +==================== + +All Rdata objects are instances of some subclass of ``dns.rdata.Rdata``. +The Rdata factory functions described in :ref:`rdata-make` will create +objects which are instances of the most appropriate subclass. For example, +a AAAA record will be an instance of the ``dns.rdtypes.IN.AAAA`` class, +but a record of TYPE12345, which we don't know anything specific about, +will be an instance of ``dns.rdata.GenericRdata``. + +.. autoclass:: dns.rdata.Rdata + :members: diff --git a/doc/rdata-make.rst b/doc/rdata-make.rst new file mode 100644 index 00000000..eb31db08 --- /dev/null +++ b/doc/rdata-make.rst @@ -0,0 +1,7 @@ +.. _rdata-make: + +Making DNS Rdata +---------------- + +.. autofunction:: dns.rdata.from_text +.. autofunction:: dns.rdata.from_wire diff --git a/doc/rdata-subclasses.rst b/doc/rdata-subclasses.rst new file mode 100644 index 00000000..aa9470b7 --- /dev/null +++ b/doc/rdata-subclasses.rst @@ -0,0 +1,174 @@ +.. _rdata-subclasses: + +Rdata Subclass Reference +======================== + +XXXRTH This is just a placeholder for proper documentation of all +the subclasses, which will basically just be documenting the attributes +of the subclass, as well as any method specific to the subclass. + +.. autoclass:: dns.rdata.GenericRdata + :members: + +.. automodule:: dns.rdtypes.dnskeybase + :members: + +.. automodule:: dns.rdtypes.dsbase + :members: + +.. automodule:: dns.rdtypes.euibase + :members: + +.. automodule:: dns.rdtypes.mxbase + :members: + +.. automodule:: dns.rdtypes.nsbase + :members: + +.. automodule:: dns.rdtypes.txtbase + :members: + +.. automodule:: dns.rdtypes.ANY.AFSDB + :members: + +.. automodule:: dns.rdtypes.ANY.AVC + :members: + +.. automodule:: dns.rdtypes.ANY.CAA + :members: + +.. automodule:: dns.rdtypes.ANY.CDNSKEY + :members: + +.. automodule:: dns.rdtypes.ANY.CDS + :members: + +.. automodule:: dns.rdtypes.ANY.CERT + :members: + +.. automodule:: dns.rdtypes.ANY.CNAME + :members: + +.. automodule:: dns.rdtypes.ANY.CSYNC + :members: + +.. automodule:: dns.rdtypes.ANY.DLV + :members: + +.. automodule:: dns.rdtypes.ANY.DNAME + :members: + +.. automodule:: dns.rdtypes.ANY.DNSKEY + :members: + +.. automodule:: dns.rdtypes.ANY.DS + :members: + +.. automodule:: dns.rdtypes.ANY.EUI48 + :members: + +.. automodule:: dns.rdtypes.ANY.EUI64 + :members: + +.. automodule:: dns.rdtypes.ANY.GPOS + :members: + +.. automodule:: dns.rdtypes.ANY.HINFO + :members: + +.. automodule:: dns.rdtypes.ANY.HIP + :members: + +.. automodule:: dns.rdtypes.ANY.ISDN + :members: + +.. automodule:: dns.rdtypes.ANY.LOC + :members: + +.. automodule:: dns.rdtypes.ANY.MX + :members: + +.. automodule:: dns.rdtypes.ANY.NS + :members: + +.. automodule:: dns.rdtypes.ANY.NSEC + :members: + +.. automodule:: dns.rdtypes.ANY.NSEC3 + :members: + +.. automodule:: dns.rdtypes.ANY.NSEC3PARAM + :members: + +.. automodule:: dns.rdtypes.ANY.OPENPGPKEY + :members: + +.. automodule:: dns.rdtypes.ANY.PTR + :members: + +.. automodule:: dns.rdtypes.ANY.RP + :members: + +.. automodule:: dns.rdtypes.ANY.RRSIG + :members: + +.. automodule:: dns.rdtypes.ANY.RT + :members: + +.. automodule:: dns.rdtypes.ANY.SOA + :members: + +.. automodule:: dns.rdtypes.ANY.SPF + :members: + +.. automodule:: dns.rdtypes.ANY.SSHFP + :members: + +.. automodule:: dns.rdtypes.ANY.TLSA + :members: + +.. automodule:: dns.rdtypes.ANY.TXT + :members: + +.. automodule:: dns.rdtypes.ANY.URI + :members: + +.. automodule:: dns.rdtypes.ANY.X25 + :members: + +.. automodule:: dns.rdtypes.IN.A + :members: + +.. automodule:: dns.rdtypes.IN.AAAA + :members: + +.. automodule:: dns.rdtypes.IN.APL + :members: + +.. automodule:: dns.rdtypes.IN.DHCID + :members: + +.. automodule:: dns.rdtypes.IN.IPSECKEY + :members: + +.. automodule:: dns.rdtypes.IN.KX + :members: + +.. automodule:: dns.rdtypes.IN.NAPTR + :members: + +.. automodule:: dns.rdtypes.IN.NSAP + :members: + +.. automodule:: dns.rdtypes.IN.NSAP_PTR + :members: + +.. automodule:: dns.rdtypes.IN.PX + :members: + +.. automodule:: dns.rdtypes.IN.SRV + :members: + +.. automodule:: dns.rdtypes.IN.WKS + :members: + diff --git a/doc/rdata.rst b/doc/rdata.rst index 367e9e60..c304e052 100644 --- a/doc/rdata.rst +++ b/doc/rdata.rst @@ -6,3 +6,6 @@ DNS Rdata .. toctree:: rdata-types + rdata-class + rdata-make + rdata-subclasses