commit e3b66e4bcb343017fae1dd18a35def44d581e13e
Author: Shikhar Bhushan <shikhar@schmizz.net>
Date:   Fri Nov 6 16:07:19 2009 +0100

    documentation

diff --git a/docs/source/index.rst b/docs/source/index.rst
index 2c6e3b5..ef5267f 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,7 +1,9 @@
 Welcome
 =======
 
-``ncclient`` is a Python library for NETCONF clients. It aims to offer an intuitive API that sensibly maps the XML-encoded nature of NETCONF to Python constructs and idioms, and make writing network-management scripts easier. Other key features are:
+``ncclient`` is a Python library for NETCONF clients. It aims to offer an intuitive API that
+sensibly maps the XML-encoded nature of NETCONF to Python constructs and idioms, and make writing
+network-management scripts easier. Other key features are:
 
 * Supports all operations and capabilities defined in :rfc:`4741`.
 * Request pipelining.
@@ -9,7 +11,8 @@ Welcome
 * Keeping XML out of the way unless really needed.
 * Extensible. New transport mappings and capabilities/operations can be easily added.
 
-It is suitable for Python 2.6+ (not Python 3 yet, though), and depends on `paramiko <http://www.lag.net/paramiko/>`_, an SSH library.
+It is suitable for Python 2.6+ (not Python 3 yet, though), and depends on `paramiko
+<http://www.lag.net/paramiko/>`_, an SSH library.
 
 The best way to introduce is of course, through a simple code example::
 
diff --git a/docs/source/manager.rst b/docs/source/manager.rst
index 0d01d24..a387cdf 100644
--- a/docs/source/manager.rst
+++ b/docs/source/manager.rst
@@ -10,10 +10,10 @@ Module data
 These attributes control what capabilties are exchanged with the NETCONF server and what operations
 are available through the `Manager` API.
 
-.. autodata:: CAPABILITIES
-
 .. autodata:: OPERATIONS
 
+.. autodata:: CAPABILITIES
+
 Factory functions
 -----------------
 
diff --git a/docs/source/operations.rst b/docs/source/operations.rst
index 3a904dc..6cafa2a 100644
--- a/docs/source/operations.rst
+++ b/docs/source/operations.rst
@@ -20,9 +20,11 @@ Base classes
 Operations
 ----------
 
-*TODO* The operation classes are currently undocumented. See documentation of
-`~ncclient.manager.Manager` for methods that utilize the operation classes. The parameters accepted
-by :meth:`~RPC.request` for these classes are the same.
+*TODO*
+
+The operation classes are currently undocumented. See documentation of `~ncclient.manager.Manager`
+for methods that utilize the operation classes. The parameters accepted by :meth:`~RPC.request` for
+these classes are the same.
 
 Replies with data
 -----------------
diff --git a/docs/source/xml_.rst b/docs/source/xml_.rst
index 423d7fa..a74bde9 100644
--- a/docs/source/xml_.rst
+++ b/docs/source/xml_.rst
@@ -1,4 +1,41 @@
-:mod:`~ncclient.xml_` -- XML Handling
+:mod:`~ncclient.xml_` -- XML handling
 =====================================
 
-*TODO*
\ No newline at end of file
+.. module:: ncclient.xml_
+    :synopsis: XML handling
+
+.. autoexception:: XMLError
+    :show-inheritance:
+
+Namespaces
+-----------
+
+.. autodata:: BASE_NS_1_0
+
+.. autodata:: TAILF_AAA_1_1
+
+.. autodata:: TAILF_EXECD_1_1
+
+.. autodata:: CISCO_CPI_1_0
+
+.. autodata:: FLOWMON_1_0
+
+.. function:: register_namespace(prefix, uri)
+    
+    ElementTree's namespace map determines the prefixes for namespace URI's when serializing to XML.
+    This method allows modifying this map to specify a prefix for a namespace URI.
+
+.. autofunction:: qualify
+
+Conversion
+-----------
+
+.. autofunction:: to_xml
+
+.. autofunction:: to_ele
+
+.. autofunction:: parse_root
+
+.. autofunction:: validated_element
+
+.. 
\ No newline at end of file
diff --git a/ncclient/manager.py b/ncclient/manager.py
index d305c02..a508eff 100644
--- a/ncclient/manager.py
+++ b/ncclient/manager.py
@@ -21,8 +21,7 @@ import transport
 import logging
 logger = logging.getLogger('ncclient.manager')
 
-
-CAPABILITIES = capabilities.Capabilities([
+CAPABILITIES = [
     "urn:ietf:params:netconf:base:1.0",
     "urn:ietf:params:netconf:capability:writable-running:1.0",
     "urn:ietf:params:netconf:capability:candidate:1.0",
@@ -35,10 +34,9 @@ CAPABILITIES = capabilities.Capabilities([
     "urn:liberouter:params:netconf:capability:power-control:1.0"
     "urn:ietf:params:netconf:capability:interleave:1.0"
     #'urn:ietf:params:netconf:capability:notification:1.0', # TODO    
-])
-"""`~ncclient.capabilities.Capabilities` object representing the client's capabilities. This is used
-during the initial capability exchange. Modify this if you need to announce some capability not
-already included.
+]
+"""A list of URI's representing the client's capabilities. This is used during the initial
+capability exchange. Modify this if you need to announce some capability not already included.
 """
 
 OPERATIONS = {
@@ -57,10 +55,9 @@ OPERATIONS = {
     "poweroff_machine": operations.PoweroffMachine,
     "reboot_machine": operations.RebootMachine
 }
-"""Dictionary of method names and corresponding `~ncclient.operations.RPC` subclasses. `Manager`
-uses this to lookup operations, e.g. "get_config" is mapped to `~ncclient.operations.GetConfig`. It
-is thus possible to add additional operations to the `Manager` API.
-"""
+"""Dictionary of method names and corresponding `~ncclient.operations.RPC` subclasses. It is used to
+lookup operations, e.g. "get_config" is mapped to `~ncclient.operations.GetConfig`. It is thus
+possible to add additional operations to the `Manager` API."""
 
 def connect_ssh(*args, **kwds):
     """Initializes a NETCONF session over SSH, and creates a connected `Manager` instance. *host*
@@ -114,7 +111,7 @@ def connect_ssh(*args, **kwds):
     
     :rtype: `Manager`
     """    
-    session = transport.SSHSession(CAPABILITIES)
+    session = transport.SSHSession(capabilities.Capabilities(CAPABILITIES))
     session.load_known_hosts()
     session.connect(*args, **kwds)
     return Manager(session)
diff --git a/ncclient/xml_.py b/ncclient/xml_.py
index 08bd02b..0ea2bb3 100644
--- a/ncclient/xml_.py
+++ b/ncclient/xml_.py
@@ -12,7 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-
 "Methods for creating, parsing, and dealing with XML and ElementTree objects."
 
 from cStringIO import StringIO
@@ -25,15 +24,15 @@ class XMLError(NCClientError): pass
 ### Namespace-related
 
 #: Base NETCONF namespace
-BASE_NS_1_0 = 'urn:ietf:params:xml:ns:netconf:base:1.0'
+BASE_NS_1_0 = "urn:ietf:params:xml:ns:netconf:base:1.0"
 #: Namespace for Tail-f core data model
-TAILF_AAA_1_1 = 'http://tail-f.com/ns/aaa/1.1'
+TAILF_AAA_1_1 = "http://tail-f.com/ns/aaa/1.1"
 #: Namespace for Tail-f execd data model
-TAILF_EXECD_1_1 = 'http://tail-f.com/ns/execd/1.1'
+TAILF_EXECD_1_1 = "http://tail-f.com/ns/execd/1.1"
 #: Namespace for Cisco data model
-CISCO_CPI_1_0 = 'http://www.cisco.com/cpi_10/schema'
+CISCO_CPI_1_0 = "http://www.cisco.com/cpi_10/schema"
 #: Namespace for Flowmon data model
-FLOWMON_1_0 = 'http://www.liberouter.org/ns/netopeer/flowmon/1.0'
+FLOWMON_1_0 = "http://www.liberouter.org/ns/netopeer/flowmon/1.0"
 
 try:
     register_namespace = ET.register_namespace
@@ -43,47 +42,49 @@ except AttributeError:
         # cElementTree uses ElementTree's _namespace_map, so that's ok
         ElementTree._namespace_map[uri] = prefix
 
-prefix_map = {
+for (ns, pre) in {
     BASE_NS_1_0: 'nc',
     TAILF_AAA_1_1: 'aaa',
     TAILF_EXECD_1_1: 'execd',
     CISCO_CPI_1_0: 'cpi',
     FLOWMON_1_0: 'fm',
-}
+}.items(): register_namespace(pre, ns)
 
-for (ns, pre) in prefix_map.items():
-    register_namespace(pre, ns)
+qualify = lambda tag, ns=BASE_NS_1_0: tag if ns is None else "{%s}%s" % (ns, tag)
+"""Qualify a tag name with a namespace, in :mod:`~xml.etree.ElementTree` fashion i.e. *{namespace}tagname*.
 
-qualify = lambda tag, ns=BASE_NS_1_0: tag if ns is None else '{%s}%s' % (ns, tag)
+:arg tag: name of the tag
+:type arg: `string`
 
-#unqualify = lambda tag: tag[tag.rfind('}')+1:]
+:arg ns: namespace to qualify with
+:type ns: `string`
+"""
 
 def to_xml(ele, encoding="UTF-8"):
-    """Convert an :class:`~xml.etree.ElementTree.Element` to XML.
+    """Convert an `~xml.etree.ElementTree.Element` to XML.
     
-    :arg ele: the :class:`~xml.etree.ElementTree.Element`
+    :arg ele: the `~xml.etree.ElementTree.Element`
     :arg encoding: character encoding
-    :rtype: :obj:`string`
+    :rtype: `string`
     """
     xml = ET.tostring(ele, encoding)
     return xml if xml.startswith('<?xml') else '<?xml version="1.0" encoding="%s"?>%s' % (encoding, xml)
 
 def to_ele(x):
-    """Convert XML to :class:`~xml.etree.ElementTree.Element`.
+    """Convert XML to `~xml.etree.ElementTree.Element`. If passed an
+    `~xml.etree.ElementTree.Element` simply returns that.
     
-    :type xml: :obj:`string`
-    :rtype: :class:`~xml.etree.ElementTree.Element`
+    :arg x: the XML document or element
+    :type x: `string` or `~xml.etree.ElementTree.Element`
+    :rtype: `~xml.etree.ElementTree.Element`
     """
-    return x if iselement(x) else ET.fromstring(x)
-
-iselement = ET.iselement
+    return x if ET.iselement(x) else ET.fromstring(x)
 
 def parse_root(raw):
     """Efficiently parses the root element of an XML document.
 
     :arg raw: XML document
-    :returns: a tuple of `(tag, attrib)`, where *tag* is the (qualified)
-    name of the element and *attrib* is a dictionary of its attributes.
+    :returns: a tuple of ``(tag, attrib)``, where *tag* is the (qualified) name of the element and *attrib* is a dictionary of its attributes.
     :rtype: `tuple`
     """
     fp = StringIO(raw)
@@ -91,7 +92,16 @@ def parse_root(raw):
         return (element.tag, element.attrib)
 
 def validated_element(x, tags=None, attrs=None):
-    "Checks if the root element of an XML document or Element meets the supplied criteria."
+    """Checks if the root element of an XML document or Element meets the supplied criteria.
+    
+    :arg tags: allowable tag name or sequence of allowable alternatives
+    :type tags: `string` or sequence of strings
+    
+    :arg attrs: list of required attributes, each of which may be a sequence of several allowable alternatives
+    :type attrs: sequence of strings or sequence of sequences of strings
+    
+    :raises: `XMLError` if the requirements are not met
+    """
     ele = to_ele(x)
     if tags:
         if isinstance(tags, basestring):
@@ -108,7 +118,6 @@ def validated_element(x, tags=None, attrs=None):
                 raise XMLError("Element [%s] does not have required attributes" % ele.tag)
     return ele
 
-
 new_ele = lambda tag, attrs={}, **extra: ET.Element(tag, attrs, **extra)
 
 sub_ele = lambda parent, tag, attrs={}, **extra: ET.SubElement(parent, tag, attrs, **extra)
\ No newline at end of file
