From: Bob Halley <halley@dnspython.org>
Date: Mon, 2 Jan 2017 15:47:20 +0000 (-0800)
Subject: Exception doc
X-Git-Tag: v1.16.0~91
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f9686b2abe9c523cda63bac24e08b1678bafa040;p=thirdparty%2Fdnspython.git

Exception doc
---

diff --git a/dns/exception.py b/dns/exception.py
index 0e468c75..89aee9c7 100644
--- a/dns/exception.py
+++ b/dns/exception.py
@@ -1,4 +1,4 @@
-# Copyright (C) 2003-2007, 2009-2011 Nominum, Inc.
+# Copyright (C) 2003-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,32 +13,35 @@
 # ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
 # OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
-"""Common DNS Exceptions."""
+"""Common DNS Exceptions.
 
+Dnspython modules may also define their own exceptions, which will
+always be subclasses of ``DNSException``.
+"""
 
 class DNSException(Exception):
-
     """Abstract base class shared by all dnspython exceptions.
 
     It supports two basic modes of operation:
 
-    a) Old/compatible mode is used if __init__ was called with
-    empty \**kwargs.
-    In compatible mode all \*args are passed to standard Python Exception class
-    as before and all \*args are printed by standard __str__ implementation.
-    Class variable msg (or doc string if msg is None) is returned from str()
-    if \*args is empty.
-
-    b) New/parametrized mode is used if __init__ was called with
-    non-empty \**kwargs.
-    In the new mode \*args has to be empty and all kwargs has to exactly match
-    set in class variable self.supp_kwargs. All kwargs are stored inside
-    self.kwargs and used in new __str__ implementation to construct
-    formatted message based on self.fmt string.
-
-    In the simplest case it is enough to override supp_kwargs and fmt
-    class variables to get nice parametrized messages.
+    a) Old/compatible mode is used if ``__init__`` was called with
+    empty *kwargs*.  In compatible mode all *args* are passed
+    to the standard Python Exception class as before and all *args* are
+    printed by the standard ``__str__`` implementation.  Class variable
+    ``msg`` (or doc string if ``msg`` is ``None``) is returned from ``str()``
+    if *args* is empty.
+
+    b) New/parametrized mode is used if ``__init__`` was called with
+    non-empty *kwargs*.
+    In the new mode *args* must be empty and all kwargs must match
+    those set in class variable ``supp_kwargs``. All kwargs are stored inside
+    ``self.kwargs`` and used in a new ``__str__`` implementation to construct
+    a formatted message based on the ``fmt`` class variable, a ``string``.
+
+    In the simplest case it is enough to override the ``supp_kwargs``
+    and ``fmt`` class variables to get nice parametrized messages.
     """
+
     msg = None  # non-parametrized message
     supp_kwargs = set()  # accepted parameters for _fmt_kwargs (sanity check)
     fmt = None  # message parametrized with results from _fmt_kwargs
@@ -102,27 +105,22 @@ class DNSException(Exception):
 
 
 class FormError(DNSException):
-
     """DNS message is malformed."""
 
 
 class SyntaxError(DNSException):
-
     """Text input is malformed."""
 
 
 class UnexpectedEnd(SyntaxError):
-
     """Text input ended unexpectedly."""
 
 
 class TooBig(DNSException):
-
     """The DNS message is too big."""
 
 
 class Timeout(DNSException):
-
     """The DNS operation timed out."""
     supp_kwargs = set(['timeout'])
     fmt = "The DNS operation timed out after {timeout} seconds"
diff --git a/doc/exceptions.rst b/doc/exceptions.rst
new file mode 100644
index 00000000..0fc9e86a
--- /dev/null
+++ b/doc/exceptions.rst
@@ -0,0 +1,7 @@
+.. _exceptions:
+
+Common Exceptions
+=================
+
+.. automodule:: dns.exception
+   :members:
diff --git a/doc/manual.rst b/doc/manual.rst
index 50b1afb3..b3e18b07 100644
--- a/doc/manual.rst
+++ b/doc/manual.rst
@@ -8,3 +8,4 @@ Dnspython Manual
    py2vs3
    name
    rdata
+   exceptions