From: Bob Halley <halley@dnspython.org>
Date: Wed, 12 Aug 2020 01:07:02 +0000 (-0700)
Subject: doco update
X-Git-Tag: v2.1.0rc1~87
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6cf5fa8b4c271515caca9318ac471197b28fc619;p=thirdparty%2Fdnspython.git

doco update
---

diff --git a/doc/whatsnew.rst b/doc/whatsnew.rst
index 8ff267c2..b6090b9b 100644
--- a/doc/whatsnew.rst
+++ b/doc/whatsnew.rst
@@ -25,7 +25,7 @@ What's New in dnspython
 * The SVCB and HTTPS RR types are now supported.
 
 * TSIG has been enhanced with TKEY and GSS-TSIG support.  Thanks to
-Nick Hall for writing this.
+  Nick Hall for writing this.
 
 2.0.0
 -----
diff --git a/doc/zone-class.rst b/doc/zone-class.rst
index b4d98698..bdaf884d 100644
--- a/doc/zone-class.rst
+++ b/doc/zone-class.rst
@@ -3,6 +3,11 @@
 The dns.zone.Zone Class
 -----------------------
 
+The ``Zone`` class provides a non-thread-safe implementation of a DNS zone,
+as well as a lightweight transation mechanism that allows it to be atomically
+updated.  For more complicated transactional needs, or for concurrency, please
+use the ``dns.versioned.Zone`` class (described below).
+
 .. autoclass:: dns.zone.Zone
    :members:
       
@@ -28,3 +33,67 @@ create new nodes and defaults to ``dns.node.Node``.  ``Zone`` may be
 subclassed if a different node factory is desired.
 The node factory is a class or callable that returns a subclass of
 ``dns.node.Node``.
+
+
+The dns.versioned.Zone Class
+----------------------------
+
+A versioned Zone is a subclass of ``Zone`` that provides a thread-safe
+multiversioned transactional API.  There can be many concurrent
+readers, of possibly different versions, and at most one active
+writer.  Others cannot see the changes being made by the writer until
+it commits.  Versions are immutable once committed.
+
+The read-only parts of the standard zone API continue to be available, and
+are equivalent to doing a single-query read-only transaction.  Note that
+unless reading is done through a transaction, version stability is not
+guaranteed between successive calls.  Attempts to use zone API methods
+that directly manipulate the zone, e.g. ``replace_rdataset`` will result
+in a ``UseTransaction`` exception.
+
+Transactions are context managers, and are created with ``reader()`` or
+``writer()``.  For example:
+
+::
+
+   # Print the SOA serial number of the most recent version
+   with zone.reader() as txn:
+       rdataset = txn.get('@', 'in', 'soa')
+       print('The most recent serial number is', rdataset[0].serial)
+
+   # Write an A RR and increment the SOA serial number to the next value.
+   with zone.writer() as txn:
+       txn.replace('node1', dns.rdataset.from_text('in', 'a', 300,
+                   '10.0.0.1'))
+       txn.set_serial()
+
+See below for more information on the ``Transaction`` API.
+       
+.. autoclass:: dns.versioned.Zone
+   :exclude-members: delete_node, delete_rdataset, replace_rdataset
+   :members:
+      
+   .. attribute:: rdclass
+
+      The zone's rdata class, an ``int``; the default is class IN.
+
+   .. attribute:: origin
+
+      The origin of the zone, a ``dns.name.Name``.
+
+   .. attribute:: nodes
+                   
+   A dictionary mapping the names of nodes in the zone to the nodes
+   themselves.
+   
+   .. attribute:: relativize
+
+   A ``bool``, which is ``True`` if names in the zone should be relativized.
+
+
+The Transaction Class
+---------------------
+
+.. autoclass:: dns.transaction.Transaction
+   :members:
+