basic documentation updates for revised message hierarchy

diff --git a/dns/message.py b/dns/message.py
index 710cc98325d3f758d1856ce75507cbe769013329..a08b0517aefa2f8a9f999c8106d43a60632806d8 100644 (file)
--- 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 d57d0cd4e511427c1f78a7a8c01f8e99184f1465..9615a73274815c91769be2c605a3128c7d3709bf 100644 (file)
--- 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 a4ed049d3b8186620252765855cc803d9d2097ba..b235d900d1f4078edb9edc8c2910ebc0a4384664 100644 (file)
--- 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 dddb6d050456445136960dd50cf81eab00229681..87e217183b67d23dd30d7266d077e0f1e637266d 100644 (file)
--- 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 c953f61e8b65bc496101082c4206f080958b28d8..08381f9c30c4a524f94c7ea3b8eca5632b926b83 100644 (file)
--- 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 <https://tools.ietf.org/html/rfc1035>`_ 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
+<https://tools.ietf.org/html/rfc1035>`_ 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