From b73865954f74362fee356d7eb8b777678f7f2598 Mon Sep 17 00:00:00 2001 From: Bob Halley Date: Sat, 14 Jan 2017 07:26:49 -0800 Subject: [PATCH] checkpoint message doc --- dns/message.py | 80 +----------------------- doc/manual.rst | 1 + doc/message-class.rst | 139 ++++++++++++++++++++++++++++++++++++++++++ doc/message-make.rst | 10 +++ doc/message.rst | 10 +++ 5 files changed, 161 insertions(+), 79 deletions(-) create mode 100644 doc/message-class.rst create mode 100644 doc/message-make.rst create mode 100644 doc/message.rst diff --git a/dns/message.py b/dns/message.py index faa29682..acb89f83 100644 --- a/dns/message.py +++ b/dns/message.py @@ -40,113 +40,35 @@ from ._compat import long, xrange, string_types class ShortHeader(dns.exception.FormError): - """The DNS packet passed to from_wire() is too short.""" class TrailingJunk(dns.exception.FormError): - """The DNS packet passed to from_wire() has extra junk at the end of it.""" class UnknownHeaderField(dns.exception.DNSException): - """The header field name was not recognized when converting from text into a message.""" class BadEDNS(dns.exception.FormError): - - """OPT record occurred somewhere other than the start of + """An OPT record occurred somewhere other than the start of the additional data section.""" class BadTSIG(dns.exception.FormError): - """A TSIG record occurred somewhere other than the end of the additional data section.""" class UnknownTSIGKey(dns.exception.DNSException): - """A TSIG with an unknown key was received.""" class Message(object): - """A DNS message. - @ivar id: The query id; the default is a randomly chosen id. - @type id: int - @ivar flags: The DNS flags of the message. @see: RFC 1035 for an - explanation of these flags. - @type flags: int - @ivar question: The question section. - @type question: list of dns.rrset.RRset objects - @ivar answer: The answer section. - @type answer: list of dns.rrset.RRset objects - @ivar authority: The authority section. - @type authority: list of dns.rrset.RRset objects - @ivar additional: The additional data section. - @type additional: list of dns.rrset.RRset objects - @ivar edns: The EDNS level to use. The default is -1, no Edns. - @type edns: int - @ivar ednsflags: The EDNS flags - @type ednsflags: long - @ivar payload: The EDNS payload size. The default is 0. - @type payload: int - @ivar options: The EDNS options - @type options: list of dns.edns.Option objects - @ivar request_payload: The associated request's EDNS payload size. - @type request_payload: int - @ivar keyring: The TSIG keyring to use. The default is None. - @type keyring: dict - @ivar keyname: The TSIG keyname to use. The default is None. - @type keyname: dns.name.Name object - @ivar keyalgorithm: The TSIG algorithm to use; defaults to - dns.tsig.default_algorithm. Constants for TSIG algorithms are defined - in dns.tsig, and the currently implemented algorithms are - HMAC_MD5, HMAC_SHA1, HMAC_SHA224, HMAC_SHA256, HMAC_SHA384, and - HMAC_SHA512. - @type keyalgorithm: string - @ivar request_mac: The TSIG MAC of the request message associated with - this message; used when validating TSIG signatures. @see: RFC 2845 for - more information on TSIG fields. - @type request_mac: string - @ivar fudge: TSIG time fudge; default is 300 seconds. - @type fudge: int - @ivar original_id: TSIG original id; defaults to the message's id - @type original_id: int - @ivar tsig_error: TSIG error code; default is 0. - @type tsig_error: int - @ivar other_data: TSIG other data. - @type other_data: string - @ivar mac: The TSIG MAC for this message. - @type mac: string - @ivar xfr: Is the message being used to contain the results of a DNS - zone transfer? The default is False. - @type xfr: bool - @ivar origin: The origin of the zone in messages which are used for - zone transfers or for DNS dynamic updates. The default is None. - @type origin: dns.name.Name object - @ivar tsig_ctx: The TSIG signature context associated with this - message. The default is None. - @type tsig_ctx: hmac.HMAC object - @ivar had_tsig: Did the message decoded from wire format have a TSIG - signature? - @type had_tsig: bool - @ivar multi: Is this message part of a multi-message sequence? The - default is false. This variable is used when validating TSIG signatures - on messages which are part of a zone transfer. - @type multi: bool - @ivar first: Is this message standalone, or the first of a multi - message sequence? This variable is used when validating TSIG signatures - on messages which are part of a zone transfer. - @type first: bool - @ivar index: An index of rrsets in the message. The index key is - (section, name, rdclass, rdtype, covers, deleting). Indexing can be - disabled by setting the index to None. - @type index: dict """ def __init__(self, id=None): diff --git a/doc/manual.rst b/doc/manual.rst index f44b39bb..c88f8e00 100644 --- a/doc/manual.rst +++ b/doc/manual.rst @@ -8,5 +8,6 @@ Dnspython Manual py2vs3 name rdata + message exceptions utilities diff --git a/doc/message-class.rst b/doc/message-class.rst new file mode 100644 index 00000000..6f6a98e0 --- /dev/null +++ b/doc/message-class.rst @@ -0,0 +1,139 @@ +.. _message-class: + +The dns.message.Message Class +----------------------------- + +.. autoclass:: dns.message.Message + :members: + + .. attribute:: id + + An ``int``, the query id; the default is a randomly chosen id. + + .. attribute:: flags + + An ``int``, the DNS flags of the message. + + .. attribute:: question + + The question section, a list of ``dns.rrset.RRset`` objects. + + .. attribute:: answer + + The answer section, a list of ``dns.rrset.RRset`` objects. + + .. attribute:: authority + + The authority section, a list of ``dns.rrset.RRset`` objects. + + .. attribute:: additional + + The additional section, a list of ``dns.rrset.RRset`` objects. + + .. attribute:: edns + + An ``int``, the EDNS level to use. The default is -1, no EDNS. + + .. attribute:: ednsflags + + An ``int``, the EDNS flags. + + .. attribute:: payload + + An ``int``, the EDNS payload size. The default is 0. + + .. attribute:: options + + The EDNS options, a list of ``dns.edns.Option`` objects. The default + is the empty list. + + .. attribute:: request_payload + + The associated request's EDNS payload size. This field is meaningful + in response messages, and if set to a non-zero value, will limit + the size of the response to the specified size. The default is 0, + which means "use the default limit" which is currently 65535. + + .. attribute:: keyring + + The TSIG keyring to use. The default is `None`. A TSIG keyring + is a dictionary mapping from TSIG key name, a ``dns.name.Name``, to + a TSIG secret, a ``binary``. + + .. attribute:: keyname + + The TSIG keyname to use, a ``dns.name.Name``. The default is ``None``. + + .. attribute:: keyalgorithm + + A ``text``, the TSIG algorithm to use. Defaults to + ``dns.tsig.default_algorithm``. Constants for TSIG algorithms are + defined the in ``dns.tsig`` module. + + .. attribute:: request_mac + + A ``binary``, the TSIG MAC of the request message associated with + this message; used when validating TSIG signatures. + + .. attribute:: fudge + + An ``int``, the TSIG time fudge. The default is 300 seconds. + + .. attribute:: original_id + + An ``int``, the TSIG original id; defaults to the message's id. + + .. attribute:: tsig_error + + An ``int``, the TSIG error code. The default is 0. + + .. attribute:: other_data + + A ``binary``, the TSIG "other data". The default is the empty + ``binary``. + + .. attribute:: mac + + A ``binary``, the TSIG MAC for this message. + + .. attribute:: xfr + + A ``bool``. This attribute is true when the message being used + for the results of a DNS zone transfer. The default is ``False``. + + .. attribute:: origin + + A ``dns.name.Name``. The origin of the zone in messages which are + used for zone transfers or for DNS dynamic updates. The default + is ``None``. + + .. attribute:: tsig_ctx + + An ``hmac.HMAC``, the TSIG signature context associated with this + message. The default is ``None``. + + .. attribute:: had_tsig + + A ``bool``, which is ``True`` if the message had a TSIG signature + when it was decoded from wire format. + + .. attribute:: multi + + A ``bool``, which is ``True`` if this message is part of a + multi-message sequence. The default is ``False``. + This attribute is used when validating TSIG signatures + on messages which are part of a zone transfer. + + .. attribute:: first + + A ``bool``, which is ``True`` if this message is stand-alone, + or the first of a multi-message sequence. The default is ``True``. + This variable is used when validating TSIG signatures + on messages which are part of a zone transfer. + + .. attribute:: index + + A ``dict``, an index of RRsets in the message. The index key is + ``(section, name, rdclass, rdtype, covers, deleting)``. The default + is ``{}``. Indexing improves the performance of finding RRsets. + Indexing can be disabled by setting the index to ``None``. diff --git a/doc/message-make.rst b/doc/message-make.rst new file mode 100644 index 00000000..3c580a94 --- /dev/null +++ b/doc/message-make.rst @@ -0,0 +1,10 @@ +.. _message-make: + +Making DNS Messages +------------------- + +.. autofunction:: dns.message.from_file +.. autofunction:: dns.message.from_text +.. autofunction:: dns.message.from_wire +.. autofunction:: dns.message.make_query +.. autofunction:: dns.message.make_response diff --git a/doc/message.rst b/doc/message.rst new file mode 100644 index 00000000..ee34b474 --- /dev/null +++ b/doc/message.rst @@ -0,0 +1,10 @@ +.. module:: dns.messages +.. _message: + +DNS Messages +============ + +.. toctree:: + + message-class + message-make -- 2.47.3