more doco overhaul

dns/edns.py

@@ -22,10 +22,26 @@
 
 import dns.inet
 
-
+#: NSID
 NSID = 3
+#: DAU
+DAU = 5
+#: DHU
+DHU = 6
+#: N3U
+N3U = 7
+#: ECS (client-subnet)
 ECS = 8
-
+#: EXPIRE
+EXPIRE = 9
+#: COOKIE
+COOKIE = 10
+#: KEEPALIVE
+KEEPALIVE = 11
+#: PADDING
+PADDING = 12
+#: CHAIN
+CHAIN = 13
 
 class Option(object):
 
@@ -220,6 +236,12 @@ def _cmp(self, other):
 }
 
 def get_option_class(otype):
+    """Return the class for the specified option type.
+
+    The GenericOption class is used if a more specific class is not
+    known.
+    """
+
     cls = _type_to_class.get(otype)
     if cls is None:
         cls = GenericOption

dns/flags.py

@@ -91,30 +91,38 @@ def _to_text(flags, table, order):
 def from_text(text):
     """Convert a space-separated list of flag text values into a flags
     value.
-    @rtype: int"""
+
+    Returns an ``int``
+    """
 
     return _from_text(text, _by_text)
 
 
 def to_text(flags):
     """Convert a flags value into a space-separated list of flag text
     values.
-    @rtype: string"""
+
+    Returns a ``text``.
+    """
 
     return _to_text(flags, _by_value, _flags_order)
 
 
 def edns_from_text(text):
     """Convert a space-separated list of EDNS flag text values into a EDNS
     flags value.
-    @rtype: int"""
+
+    Returns an ``int``
+    """
 
     return _from_text(text, _edns_by_text)
 
 
 def edns_to_text(flags):
     """Convert an EDNS flags value into a space-separated list of EDNS flag
     text values.
-    @rtype: string"""
+
+    Returns a ``text``.
+    """
 
     return _to_text(flags, _edns_by_value, _edns_flags_order)

dns/opcode.py

@@ -1,4 +1,4 @@
-# Copyright (C) 2001-2007, 2009-2011 Nominum, Inc.
+# Copyright (C) 2001-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,
@@ -17,10 +17,15 @@
 
 import dns.exception
 
+#: Query
 QUERY = 0
+#: Inverse Query (historical)
 IQUERY = 1
+#: Server Status (unspecified and unimplemented anywhere)
 STATUS = 2
+#: Notify
 NOTIFY = 4
+#: Dynamic Update
 UPDATE = 5
 
 _by_text = {
@@ -39,17 +44,17 @@
 
 
 class UnknownOpcode(dns.exception.DNSException):
-
     """An DNS opcode is unknown."""
 
 
 def from_text(text):
     """Convert text into an opcode.
 
-    @param text: the textual opcode
-    @type text: string
-    @raises UnknownOpcode: the opcode is unknown
-    @rtype: int
+    *text*, a ``text``, the textual opcode
+
+    Raises ``dns.opcode.UnknownOpcode`` if the opcode is unknown.
+
+    Returns an ``int``.
     """
 
     if text.isdigit():
@@ -65,8 +70,9 @@ def from_text(text):
 def from_flags(flags):
     """Extract an opcode from DNS message flags.
 
-    @param flags: int
-    @rtype: int
+    *flags*, an ``int``, the DNS flags.
+
+    Returns an ``int``.
     """
 
     return (flags & 0x7800) >> 11
@@ -75,7 +81,10 @@ def from_flags(flags):
 def to_flags(value):
     """Convert an opcode to a value suitable for ORing into DNS message
     flags.
-    @rtype: int
+
+    *value*, an ``int``, the DNS opcode value.
+
+    Returns an ``int``.
     """
 
     return (value << 11) & 0x7800
@@ -84,10 +93,11 @@ def to_flags(value):
 def to_text(value):
     """Convert an opcode to text.
 
-    @param value: the opcdoe
-    @type value: int
-    @raises UnknownOpcode: the opcode is unknown
-    @rtype: string
+    *value*, an ``int`` the opcode value,
+
+    Raises ``dns.opcode.UnknownOpcode`` if the opcode is unknown.
+
+    Returns a ``text``.
     """
 
     text = _by_value.get(value)
@@ -97,11 +107,11 @@ def to_text(value):
 
 
 def is_update(flags):
-    """True if the opcode in flags is UPDATE.
+    """Is the opcode in flags UPDATE?
+
+    *flags*, an ``int``, the DNS message flags.
 
-    @param flags: DNS flags
-    @type flags: int
-    @rtype: bool
+    Returns a ``bool``.
     """
 
     return from_flags(flags) == UPDATE

doc/exceptions.rst

@@ -34,6 +34,11 @@ dns.name Exceptions
 .. autoexception:: dns.name.NoIDNA2008
 .. autoexception:: dns.name.NoParent
 
+dns.opcode Exceptions
+---------------------
+
+.. autoexception:: dns.opcode.UnknownOpcode
+
 dns.rcode Exceptions
 --------------------
 

doc/message-edns.rst

@@ -0,0 +1,33 @@
+.. _message-edns:
+
+Message EDNS Options
+--------------------
+
+EDNS allows for larger messages and also provides an extension
+mechanism for the protocol.  EDNS *options* are typed data, and are
+treated much like Rdata.  For example, if dnsython encouters the EDNS
+``ECS`` option code when parsing a DNS wire format message, it
+will create a ``dns.edns.ECSOption`` object to represent it.
+
+.. autodata:: dns.edns.NSID
+.. autodata:: dns.edns.DAU
+.. autodata:: dns.edns.DHU
+.. autodata:: dns.edns.N3U
+.. autodata:: dns.edns.ECS
+.. autodata:: dns.edns.EXPIRE
+.. autodata:: dns.edns.COOKIE
+.. autodata:: dns.edns.KEEPALIVE
+.. autodata:: dns.edns.PADDING
+.. autodata:: dns.edns.CHAIN
+
+.. autoclass:: dns.edns.Option
+   :members:
+
+.. autoclass:: dns.edns.GenericOption
+   :members:
+
+.. autoclass:: dns.edns.ECSOption
+   :members:
+
+.. autofunction:: dns.edns.get_option_class
+.. autofunction:: dns.edns.option_from_wire

doc/message-flags.rst

@@ -0,0 +1,33 @@
+.. _message-flags:
+
+Message Flags
+=============
+
+DNS message flags are used for signalling of various kinds
+in the DNS protocol.  For example, the ``QR`` flag indicates
+that a message is a response to a prior query.
+
+Messages flags are encoded in two locations: the DNS header
+and the EDNS flags field.
+
+Header Flags
+------------
+
+.. autodata:: dns.flags.QR
+.. autodata:: dns.flags.AA
+.. autodata:: dns.flags.TC
+.. autodata:: dns.flags.RD
+.. autodata:: dns.flags.RA
+.. autodata:: dns.flags.AD
+.. autodata:: dns.flags.CD
+
+.. autofunction:: dns.flags.from_text
+.. autofunction:: dns.flags.to_text
+
+EDNS Flags
+----------
+
+.. autodata:: dns.flags.DO
+
+.. autofunction:: dns.flags.edns_from_text
+.. autofunction:: dns.flags.edns_to_text

doc/message-opcode.rst

@@ -0,0 +1,20 @@
+.. _message-opcode:
+
+Message Opcodes
+---------------
+
+DNS Opcodes describe what kind of operation a DNS message is requesting
+or replying to.  Opcodes are embedded in the flags field in the DNS
+header.
+
+.. autodata:: dns.opcode.QUERY
+.. autodata:: dns.opcode.IQUERY
+.. autodata:: dns.opcode.STATUS
+.. autodata:: dns.opcode.NOTIFY
+.. autodata:: dns.opcode.UPDATE
+
+.. autofunction:: dns.opcode.from_text
+.. autofunction:: dns.opcode.to_text
+.. autofunction:: dns.opcode.from_flags
+.. autofunction:: dns.opcode.to_flags
+.. autofunction:: dns.opcode.is_update

doc/message-rcode.rst

@@ -0,0 +1,27 @@
+.. _message-rcode:
+
+Message Rcodes
+--------------
+
+A DNS Rcode describes the result of a DNS request.  If EDNS is not in
+use, then the rcode is encoded solely in the DNS header.   If EDNS is
+in use, then the rcode is encoded using bits form both the header and
+the EDNS OPT RR.
+
+.. autodata:: dns.rcode.NOERROR
+.. autodata:: dns.rcode.FORMERR
+.. autodata:: dns.rcode.SERVFAIL
+.. autodata:: dns.rcode.NXDOMAIN
+.. autodata:: dns.rcode.NOTIMP
+.. autodata:: dns.rcode.REFUSED
+.. autodata:: dns.rcode.YXDOMAIN
+.. autodata:: dns.rcode.YXRRSET
+.. autodata:: dns.rcode.NXRRSET
+.. autodata:: dns.rcode.NOTAUTH
+.. autodata:: dns.rcode.NOTZONE
+.. autodata:: dns.rcode.BADVERS
+
+.. autofunction:: dns.rcode.from_text
+.. autofunction:: dns.rcode.to_text
+.. autofunction:: dns.rcode.from_flags
+.. autofunction:: dns.rcode.to_flags

doc/message.rst

@@ -14,3 +14,7 @@ a textual form, and also read from that form.
 
    message-class
    message-make
+   message-flags
+   message-opcode
+   message-rcode
+   message-edns