Updated documentation for v0.5.0 release

MelindaShore · MelindaShore · commit 3cb9de2108d8 · 2015-12-04T17:43:55.000-08:00
diff --git a/doc/conf.py b/doc/conf.py
@@ -48,9 +48,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = 'v0.4.1'
+version = 'v0.5.0'
 # The full version, including alpha/beta/rc tags.
-release = 'v0.4.1'
+release = 'v0.5.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/doc/functions.rst b/doc/functions.rst
@@ -29,63 +29,16 @@ as its methods and attributes.
 
   The :class:`Context` class has the following public read/write attributes:
 
-  .. py:attribute:: resolution_type
-
-   Specifies whether DNS queries are performed with
-   nonrecursive lookups or as a stub resolver. The value is
-   either ``getdns.RESOLUTION_RECURSING`` or
-   ``getdns.RESOLUTION_STUB``.
-
-   If an implementation of this API is only able to act as a
-   recursive resolver, setting `resolution_type`
-   to ``getdns.RESOLUTION_STUB`` will throw an exception.
-
-  .. py:attribute:: namespaces
-
-   The `namespaces` attribute takes an ordered list of
-   namespaces that will be queried. (*Important: this context
-   setting is ignored for the getdns.general() function;
-   it is used for the other
-   functions.*) The allowed values are
-   ``getdns.NAMESPACE_DNS``, ``getdns.NAMESPACE_LOCALNAMES``, 
-   ``getdns.NAMESPACE_NETBIOS``,
-   ``getdns.NAMESPACE_MDNS``, and ``getdns.NAMESPACE_NIS``. When a
-   normal lookup is done, the API does the lookups in the
-   order given and stops when it gets the first result; a
-   different method with the same result would be to run the
-   queries in parallel and return when it gets the first
-   result. Because lookups might be done over different
-   mechanisms because of the different namespaces, there can
-   be information leakage that is similar to that seen with
-   POSIX *getaddrinfo()*. The default is determined by the OS.
-
-   .. py:attribute:: dns_transport_list
-
-   An ordered list of transport options to be used for DNS
-   lookups, ordered by preference (first choice as list
-   element 0, second as list element 1, and so on).  The
-   possible values are ``getdns.TRANSPORT_UDP``,
-   ``getdns.TRANSPORT_TCP``, ``getdns.TRANSPORT_TLS``,
-   and ``getdns.TRANSPORT_STARTTLS``.  [n.b.: *the
-   ``dns_transport`` attribute is still supported but will
-   be deprecated in a future release*]
-
-  .. py:attribute:: limit_outstanding_queries
-
-   Specifies `limit` (an integer value) on the number of outstanding DNS
-   queries. The API will block itself from sending more
-   queries if it is about to exceed this value, and instead
-   keep those queries in an internal queue. The a value of 0
-   indicates that the number of outstanding DNS queries is unlimited.
-
-  .. py:attribute:: follow_redirects
+  .. py:attribute:: append_name
 
-   Specifies whether or not DNS queries follow
-   redirects.  The value must be one of ``getdns.REDIRECTS_FOLLOW`` for
-   normal following of redirects though CNAME and DNAME; or
-   ``getdns.REDIRECTS_DO_NOT_FOLLOW`` to cause any lookups that
-   would have gone through CNAME and DNAME to return the
-   CNAME or DNAME, not the eventual target.
+   Specifies whether to append a suffix to the query string
+   before the API starts resolving a name. Its value must be
+   one of
+   ``getdns.APPEND_NAME_ALWAYS``,
+   ``getdns.APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE``,
+   ``getdns.APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE``,
+   or ``getdns.APPEND_NAME_NEVER``. This controls whether or not
+   to append the suffix given by :attr:`suffix`.
 
   .. py:attribute:: dns_root_servers
 
@@ -104,58 +57,130 @@ as its methods and attributes.
    ...         { 'address_data': '65.22.9.1', 'address_type': 'IPv4' } ]
    >>> mycontext.dns_root_servers = addrs
 
-  .. py:attribute:: append_name
+  .. py:attribute:: dns_transport_list
 
-   Specifies whether to append a suffix to the query string
-   before the API starts resolving a name. Its value must be
-   one of
-   ``getdns.APPEND_NAME_ALWAYS``,
-   ``getdns.APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE``,
-   ``getdns.APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE``,
-   or ``getdns.APPEND_NAME_NEVER``. This controls whether or not
-   to append the suffix given by :attr:`suffix`.
+   An ordered list of transport options to be used for DNS
+   lookups, ordered by preference (first choice as list
+   element 0, second as list element 1, and so on).  The
+   possible values are ``getdns.TRANSPORT_UDP``,
+   ``getdns.TRANSPORT_TCP``, ``getdns.TRANSPORT_TLS``,
+   and ``getdns.TRANSPORT_STARTTLS``. 
 
-  .. py:attribute:: suffix
+  .. py:attribute:: dnssec_allowed_skew
 
-   Its value is a list of strings to be appended based on
-   :attr:`append_name`.  The list elements must
-   follow the rules in :rfc:`4343#section-2.1`
+   Its value is the number of seconds of skew that is
+   allowed in either direction when checking an RRSIG's
+   Expiration and Inception fields. The default is 0.
 
   .. py:attribute:: dnssec_trust_anchors
 
    Its value is a list of DNSSEC trust anchors, expressed as
    RDATAs from DNSKEY resource records.
 
-  .. py:attribute:: dnssec_allowed_skew
+  .. py:attribute:: edns_client_subnet_private
 
-   Its value is the number of seconds of skew that is
-   allowed in either direction when checking an RRSIG's
-   Expiration and Inception fields. The default is 0.
+   May be set to 0 or 1.  When 1, requests upstreams not to
+   reveal query's originating network.
 
-  .. py:attribute:: edns_maximum_udp_payload_size
+  .. py:attribute:: edns_do_bit
 
-   Its value must be an integer between 512 and 65535,
-   inclusive.  The default is 512.
+   Its value must be an integer valued either 0 or 1.  The default is 0.
 
   .. py:attribute:: edns_extended_rcode
 
    Its value must be an integer between 0 and 255, inclusive.
    The default is 0.
 
+  .. py:attribute:: edns_maximum_udp_payload_size
+
+   Its value must be an integer between 512 and 65535,
+   inclusive.  The default is 512.
+
   .. py:attribute:: edns_version
 
    Its value must be an integer between 0 and 255, inclusive.
    The default is 0.
 
-  .. py:attribute:: edns_do_bit
+  .. py:attribute:: follow_redirects
 
-   Its value must be an integer valued either 0 or 1.  The default is 0.
+   Specifies whether or not DNS queries follow
+   redirects.  The value must be one of ``getdns.REDIRECTS_FOLLOW`` for
+   normal following of redirects though CNAME and DNAME; or
+   ``getdns.REDIRECTS_DO_NOT_FOLLOW`` to cause any lookups that
+   would have gone through CNAME and DNAME to return the
+   CNAME or DNAME, not the eventual target.
+
+  .. py:attribute:: idle_timeout
+
+   The idle timeout for TCP connections.
+
+  .. py:attribute:: implementation_string
+
+   A string describing the implementation of the underlying
+   getdns library, retrieved from
+   libgetdns.  Currently "https://getdnsapi.net"
+
+  .. py:attribute:: limit_outstanding_queries
+
+   Specifies `limit` (an integer value) on the number of outstanding DNS
+   queries. The API will block itself from sending more
+   queries if it is about to exceed this value, and instead
+   keep those queries in an internal queue. The a value of 0
+   indicates that the number of outstanding DNS queries is unlimited.
+
+  .. py:attribute:: namespaces
+
+   The `namespaces` attribute takes an ordered list of
+   namespaces that will be queried. (*Important: this context
+   setting is ignored for the getdns.general() function;
+   it is used for the other
+   functions.*) The allowed values are
+   ``getdns.NAMESPACE_DNS``, ``getdns.NAMESPACE_LOCALNAMES``, 
+   ``getdns.NAMESPACE_NETBIOS``,
+   ``getdns.NAMESPACE_MDNS``, and ``getdns.NAMESPACE_NIS``. When a
+   normal lookup is done, the API does the lookups in the
+   order given and stops when it gets the first result; a
+   different method with the same result would be to run the
+   queries in parallel and return when it gets the first
+   result. Because lookups might be done over different
+   mechanisms because of the different namespaces, there can
+   be information leakage that is similar to that seen with
+   POSIX *getaddrinfo()*. The default is determined by the OS.
+
+  .. py:attribute:: resolution_type
+
+   Specifies whether DNS queries are performed with
+   nonrecursive lookups or as a stub resolver. The value is
+   either ``getdns.RESOLUTION_RECURSING`` or
+   ``getdns.RESOLUTION_STUB``.
+
+   If an implementation of this API is only able to act as a
+   recursive resolver, setting `resolution_type`
+   to ``getdns.RESOLUTION_STUB`` will throw an exception.
+
+  .. py:attribute:: suffix
+
+   Its value is a list of strings to be appended based on
+   :attr:`append_name`.  The list elements must
+   follow the rules in :rfc:`4343#section-2.1`
 
   .. py:attribute:: timeout
    
    Its value must be an integer specifying a timeout for a query, expressed 
    in milliseconds.
 
+  .. py:attribute:: tls_authentication
+
+   The mechanism to be used for authenticating the TLS
+   server when using a TLS transport.  May be ``getdns.AUTHENTICATION_HOSTNAME`` or
+   ``getdns.AUTHENTICATION_NONE``.
+
+  .. py:attribute:: tls_query_padding_blocksize
+
+   Optional padding blocksize for queries when using TLS.  Used to
+   increase the difficulty for observers to guess traffic
+   content.
+
   .. py:attribute:: upstream_recursive_servers
 
    A list of dicts defining where a stub resolver will send queries.
@@ -168,6 +193,10 @@ as its methods and attributes.
    tsig_algorithm (a bindata) that is the name of the TSIG hash
    algorithm, and tsig_secret (a bindata) that is the TSIG key.
 
+  .. py:attribute:: version_string
+
+    The libgetdns version, retrieved from the underlying
+    getdns library.
                     
   The :class:`Context` class includes public methods to execute a DNS query, as well as a
   method to return the entire set of context attributes as a Python dictionary.  :class:`Context`
@@ -243,6 +272,10 @@ as its methods and attributes.
    * ``timeout``
    * ``upstream_recursive_servers``
 
+  .. py:method:: get_supported_attributes()
+
+   Returns a list of the attributes supported by this
+   Context object.
 
 The ``getdns`` module has the following read-only attribute:
 
diff --git a/doc/index.rst b/doc/index.rst
@@ -29,13 +29,12 @@ This version of getdns has been built and tested against Python
 2.7.  We also expect these other prerequisites to be
 installed:
 
-* `libgetdns <http://getdnsapi.net/>`_, version 0.1.7 or later
+* `libgetdns <http://getdnsapi.net/>`_, version 0.5.0 or later
 * `libldns <https://www.nlnetlabs.nl/projects/ldns/>`_,
   version 1.6.11 or later
 * `libunbound
   <http://www.nlnetlabs.nl/projects/unbound/>`_, version
   1.4.16 or later
-* `libexpat <http://expat.sourceforge.net/>`_ (needed for unbound)
 * `libidn <http://www.gnu.org/software/libidn/>`_ version 1
 * `libevent <http://libevent.org/>`_ version 2.0.21 stable
 
@@ -50,7 +49,7 @@ you must compile support for them into libgetdns, by
 including the --enable-draft-edns-cookies argument to
 configure.
 
-This release has been tested against libgetdns 0.3.1.
+This release has been tested against libgetdns 0.5.0.
 
 Building
 ========
@@ -199,6 +198,32 @@ In this example, we do a DNSSEC query and check the response:
         main()
         
 
+Module-level attributes and methods
+===================================
+
+.. py:attribute:: __version__
+
+   The ``getdns.__version__`` attribute contains the version
+   string for the Python getdns module.  Please note that
+   this is independent of the version of the underlying
+   getdns library, which may be retrieved through attributes
+   associated with a Context.
+
+.. py:method:: get_errorstr_by_id()
+
+   Returns a human-friendly string representation of an
+   error ID.
+
+.. py:method:: ulabel_to_alabel()
+
+   Converts a ulabel to an alabel.  Takes one argument (the ulabel)
+
+.. py:method:: alabel_to_ulabel()
+
+   Converts an alabel to a ulabel.  Takes one argument (the
+   alabel)
+
+
 Known issues
 ============
 
diff --git a/doc/response.rst b/doc/response.rst
@@ -154,6 +154,11 @@ Response data from queries
    RRSIGs) that are needed to perform the validation from
    the root up.                    
 
+  .. py:attribute:: call_debugging
+
+    A list of dictionaries containing call_debugging
+    information, if requested in the query.
+
   .. py:attribute:: replies_tree
 
    The names in each entry in the the ``replies_tree`` list for DNS
