From 9c55663682055c786176f18dec48aedc56ebbd56 Mon Sep 17 00:00:00 2001 From: Bob Halley Date: Fri, 26 Jun 2020 07:57:06 -0700 Subject: [PATCH] basic documentation updates for revised message hierarchy --- dns/message.py | 15 +++++++++++---- dns/update.py | 3 +++ doc/message-class.rst | 19 +++++-------------- doc/message-update.rst | 21 +++++++++++++++------ doc/message.rst | 8 +++++--- 5 files changed, 39 insertions(+), 27 deletions(-) diff --git a/dns/message.py b/dns/message.py index 710cc983..a08b0517 100644 --- a/dns/message.py +++ b/dns/message.py @@ -129,6 +129,7 @@ class Message: @property def question(self): + """ The question section.""" return self.sections[0] @question.setter @@ -137,6 +138,7 @@ class Message: @property def answer(self): + """ The answer section.""" return self.sections[1] @answer.setter @@ -145,6 +147,7 @@ class Message: @property def authority(self): + """ The authority section.""" return self.sections[2] @authority.setter @@ -153,6 +156,7 @@ class Message: @property def additional(self): + """ The additional data section.""" return self.sections[3] @additional.setter @@ -1226,14 +1230,14 @@ def make_query(qname, rdtype, rdclass=dns.rdataclass.IN, use_edns=None, encoder/decoder. If ``None``, the default IDNA 2003 encoder/decoder is used. - Returns a ``dns.message.Message`` + Returns a ``dns.message.QueryMessage`` """ if isinstance(qname, str): qname = dns.name.from_text(qname, idna_codec=idna_codec) rdtype = dns.rdatatype.RdataType.make(rdtype) rdclass = dns.rdataclass.RdataClass.make(rdclass) - m = Message() + m = QueryMessage() m.flags |= dns.flags.RD m.find_rrset(m.question, qname, rdclass, rdtype, create=True, force_unique=True) @@ -1283,12 +1287,15 @@ def make_response(query, recursion_available=False, our_payload=8192, *fudge*, an ``int``, the TSIG time fudge. - Returns a ``dns.message.Message`` object. + Returns a ``dns.message.Message`` object whose specific class is + appropriate for the query. For example, if query is a + ``dns.update.UpdateMessage``, response will be too. """ if query.flags & dns.flags.QR: raise dns.exception.FormError('specified query message is not a query') - response = dns.message.Message(query.id) + factory = _message_factory_from_opcode(query.opcode) + response = factory(id=query.id) response.flags = dns.flags.QR | (query.flags & dns.flags.RD) if recursion_available: response.flags |= dns.flags.RA diff --git a/dns/update.py b/dns/update.py index d57d0cd4..9615a732 100644 --- a/dns/update.py +++ b/dns/update.py @@ -88,6 +88,7 @@ class UpdateMessage(dns.message.Message): @property def zone(self): + """The zone section.""" return self.sections[0] @zone.setter @@ -96,6 +97,7 @@ class UpdateMessage(dns.message.Message): @property def prerequisite(self): + """The prerequisite section.""" return self.sections[1] @prerequisite.setter @@ -104,6 +106,7 @@ class UpdateMessage(dns.message.Message): @property def update(self): + """The update section.""" return self.sections[2] @update.setter diff --git a/doc/message-class.rst b/doc/message-class.rst index a4ed049d..b235d900 100644 --- a/doc/message-class.rst +++ b/doc/message-class.rst @@ -3,6 +3,9 @@ The dns.message.Message Class ----------------------------- +This is the base class for all messages, and the class used for any +DNS opcodes that do not have a more specific class. + .. autoclass:: dns.message.Message :members: @@ -14,21 +17,9 @@ The dns.message.Message Class 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 + .. attribute:: sections - The additional section, a list of ``dns.rrset.RRset`` objects. + A list of lists of ``dns.rrset.RRset`` objects. .. attribute:: edns diff --git a/doc/message-update.rst b/doc/message-update.rst index dddb6d05..87e21718 100644 --- a/doc/message-update.rst +++ b/doc/message-update.rst @@ -1,11 +1,20 @@ .. _message-update: -The dns.update.Update Class ---------------------------- +The dns.update.UpdateMessage Class +---------------------------------- -DNS Dynamic Update message have a complex encoding, so -dnspython provides a subclass of ``dns.message.Message`` -specialized for creating them. +The ``dns.update.UpdateMessage`` class is used for DNS Dynamic Update +messages. It provides section access using the DNS Dynamic Update +section names, and a variety of convenience methods for constructing +dynamic updates. -.. autoclass:: dns.update.Update +.. autoclass:: dns.update.UpdateMessage :members: + +The following constants may be used to specify sections in the +``find_rrset()`` and ``get_rrset()`` methods: + +.. autodata:: dns.update.ZONE +.. autodata:: dns.update.PREREQ +.. autodata:: dns.update.UPDATE +.. autodata:: dns.update.ADDITIONAL diff --git a/doc/message.rst b/doc/message.rst index c953f61e..08381f9c 100644 --- a/doc/message.rst +++ b/doc/message.rst @@ -4,9 +4,10 @@ DNS Messages ============ -Objects of the dns.message.Message class represent a single DNS message, -as defined by `RFC 1035 `_ and its -many updates and extensions. +Objects of the dns.message.Message class and its subclasses represent +a single DNS message, as defined by `RFC 1035 +`_ and its many updates and +extensions. The module provides tools for constructing and manipulating messages. TSIG signatures and EDNS are also supported. Messages can be dumped to @@ -20,4 +21,5 @@ a textual form, and also read from that form. message-opcode message-rcode message-edns + message-query message-update -- 2.47.3