Documentation of the XML-RPC class

Improved documentation of the XML-RPC glue class and a few smaller
fixes.

Author: garberg

.gitignore

@@ -2,4 +2,6 @@
 *.sw[po]
 *.pyc
 *.class
+*.tar.gz
+*.deb
 docs/sphinx/_build/

docs/sphinx/authlib.rst

@@ -0,0 +1,2 @@
+.. automodule:: nipap.authlib
+   :members:

docs/sphinx/conf.py

@@ -12,8 +12,8 @@
 # serve to show the default.
 
 import sys, os
-sys.path.append('../../nipap')
-sys.path.append('../../nipap-www/nipapwww')
+sys.path.insert(0, '../../nipap')
+#sys.path.append('../../nipap-www/nipapwww')
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the

docs/sphinx/index.rst

@@ -27,6 +27,7 @@ Contents:
    design
    nipap
    xmlrpc
+   authlib
 
 
 Indices and tables

nipap/nipap/authlib.py

@@ -1,4 +1,7 @@
-""" A base authentication & authorization module.
+""" Authentication library
+    ======================
+
+    A base authentication & authorization module.
 
     Includes the base class BaseAuth.
 """

nipap/nipap/nipap.py

@@ -32,6 +32,8 @@
     * :func:`~Nipap.add_schema` - Create a new schema.
     * :func:`~Nipap.edit_schema` - Edit a schema.
     * :func:`~Nipap.remove_schema` - Remove a schema.
+    * :func:`~Nipap.search_schema` - Search schemas from a specifically formatted dict.
+    * :func:`~Nipap.smart_search_schema` - Search schemas from arbitarly formatted string.
 
 
     Prefix
@@ -57,7 +59,8 @@
     * :attr:`indent` - Depth in prefix tree. Set by NIPAP.
     * :attr:`country` - Country where the prefix resides (two-letter country code).
     * :attr:`order_id` - Order identifier.
-    * :attr:`authoritative_source` - String identifying which system added the prefix.
+    * :attr:`authoritative_source` - String identifying which system last
+        modified the prefix.
     * :attr:`alarm_priority` - String 'low', 'medium' or 'high'. Used by netwatch.
     * :attr:`monitor` - A boolean specifying whether the prefix should be
         monitored or not.
@@ -126,6 +129,17 @@
 
     If multiple keys are given, they will be ANDed together.
 
+    Authorization & accounting
+    --------------------------
+    With each query an object extending the BaseAuth class should be passed.
+    This object is used in the Nipap class to perform authorization (not yet
+    implemented) and accounting. Authentication should be performed at an
+    earlier stage and is NOT done in the Nipap class.
+
+    Each command which alters data stored in NIPAP is logged. There are
+    currently no API functions for extracting this data, but this will change
+    in the future.
+
     Classes
     -------
 """
@@ -567,6 +581,8 @@ def _expand_schema_query(self, query, table_name = None):
     def add_schema(self, auth, attr):
         """ Add a new network schema.
 
+            * `auth` [BaseAuth]
+                AAA options.
             * `attr` [schema_attr]
                 The news schema's attributes.
 
@@ -608,6 +624,8 @@ def add_schema(self, auth, attr):
     def remove_schema(self, auth, spec):
         """ Remove a schema.
 
+            * `auth` [BaseAuth]
+                AAA options.
             * `spec` [schema_spec]
                 A schema specification.
 
@@ -640,6 +658,8 @@ def remove_schema(self, auth, spec):
     def list_schema(self, auth, spec=None):
         """ Return a list of schemas matching `spec`.
 
+            * `auth` [BaseAuth]
+                AAA options.
             * `spec` [schema_spec]
                 A schema specification. If omitted, all schemas are returned.
 
@@ -688,6 +708,8 @@ def _get_schema(self, auth, spec):
     def edit_schema(self, auth, spec, attr):
         """ Updata schema matching `spec` with attributes `attr`.
 
+            * `auth` [BaseAuth]
+                AAA options.
             * `spec` [schema_spec]
                 Schema specification.
             * `attr` [schema_attr]
@@ -732,6 +754,8 @@ def edit_schema(self, auth, spec, attr):
     def search_schema(self, auth, query, search_options = {}):
         """ Search schema list for schemas matching `query`.
 
+            * `auth` [BaseAuth]
+                AAA options.
             * `query` [dict_to_sql]
                 How the search should be performed.
             * `search_options` [options_dict]
@@ -852,6 +876,8 @@ def search_schema(self, auth, query, search_options = {}):
     def smart_search_schema(self, auth, query_str, search_options = {}):
         """ Perform a smart search on schema list.
 
+            * `auth` [BaseAuth]
+                AAA options.
             * `query_str` [string]
                 Search string
             * `search_options` [options_dict]
@@ -1043,9 +1069,10 @@ def _expand_pool_query(self, query, table_name = None):
     def add_pool(self, auth, schema_spec, attr):
         """ Create a pool according to `attr`.
 
+            * `auth` [BaseAuth]
+                AAA options.
             * `schema_spec` [schema_spec]
                 Specifies what schema we are working within.
-
             * `attr` [pool_attr]
                 A dict containing the attributes the new pool should have.
 
@@ -1090,6 +1117,8 @@ def add_pool(self, auth, schema_spec, attr):
     def remove_pool(self, auth, schema_spec, spec):
         """ Remove a pool.
 
+            * `auth` [BaseAuth]
+                AAA options.
             * `schema_spec` [schema_spec]
                 Specifies what schema we are working within.
             * `spec` [pool_spec]
@@ -1129,6 +1158,8 @@ def remove_pool(self, auth, schema_spec, spec):
     def list_pool(self, auth, schema_spec, spec = {}):
         """ Return a list of pools.
 
+            * `auth` [BaseAuth]
+                AAA options.
             * `schema_spec` [schema_spec]
                 Specifies what schema we are working within.
             * `spec` [pool_spec]
@@ -1196,6 +1227,8 @@ def _get_pool(self, auth, schema_spec, spec):
     def edit_pool(self, auth, schema_spec, spec, attr):
         """ Update pool given by `spec` with attributes `attr`.
 
+            * `auth` [BaseAuth]
+                AAA options.
             * `schema_spec` [schema_spec]
                 Specifies what schema we are working within.
             * `spec` [pool_spec]
@@ -1255,6 +1288,8 @@ def edit_pool(self, auth, schema_spec, spec, attr):
     def search_pool(self, auth, schema_spec, query, search_options = {}):
         """ Search pool list for pools matching `query`.
 
+            * `auth` [BaseAuth]
+                AAA options.
             * `schema_spec` [schema_spec]
                 Specifies what schema we are working within.
             * `query` [dict_to_sql]
@@ -1400,6 +1435,8 @@ def search_pool(self, auth, schema_spec, query, search_options = {}):
     def smart_search_pool(self, auth, schema_spec, query_str, search_options = {}):
         """ Perform a smart search on pool list.
 
+            * `auth` [BaseAuth]
+                AAA options.
             * `schema_spec` [schema_spec]
                 Specifies what schema we are working within.
             * `query_str` [string]
@@ -1605,6 +1642,8 @@ def _expand_prefix_query(self, query, table_name = None):
     def add_prefix(self, auth, schema_spec, attr, args = {}):
         """ Add a prefix and return its ID.
 
+            * `auth` [BaseAuth]
+                AAA options.
             * `schema_spec` [schema_spec]
                 Specifies what schema we are working within.
             * `attr` [prefix_attr]
@@ -1722,6 +1761,8 @@ def add_prefix(self, auth, schema_spec, attr, args = {}):
     def edit_prefix(self, auth, schema_spec, spec, attr):
         """ Update prefix matching `spec` with attributes `attr`.
 
+            * `auth` [BaseAuth]
+                AAA options.
             * `schema_spec` [schema_spec]
                 Specifies what schema we are working within.
             * `spec` [prefix_spec]
@@ -1810,6 +1851,8 @@ def edit_prefix(self, auth, schema_spec, spec, attr):
     def find_free_prefix(self, auth, schema_spec, args):
         """ Finds free prefixes in the sources given in `args`.
 
+            * `auth` [BaseAuth]
+                AAA options.
             `schema_spec` [schema_spec]
                 Specifies what schema we are working within.
             `args` [find_free_prefix_args]
@@ -1829,7 +1872,7 @@ def find_free_prefix(self, auth, schema_spec, args):
 
             Example::
 
-                attr = {
+                args = {
                     'from-pool': { 'name': 'CUSTOMER-' },
                     'family': 6,
                     'prefix_length': 64
@@ -1844,7 +1887,7 @@ def find_free_prefix(self, auth, schema_spec, args):
 
             Example::
 
-                attr = {
+                args = {
                     'from-prefix': '192.0.2.0/24'
                     'prefix_length': 27
                 }
@@ -1964,6 +2007,8 @@ def find_free_prefix(self, auth, schema_spec, args):
     def list_prefix(self, auth, schema_spec, spec = None):
         """ List prefixes matching the `spec`.
 
+            * `auth` [BaseAuth]
+                AAA options.
             * `schema_spec` [schema_spec]
                 Specifies what schema we are working within.
             * `spec` [prefix_spec]
@@ -2002,6 +2047,8 @@ def list_prefix(self, auth, schema_spec, spec = None):
     def remove_prefix(self, auth, schema_spec, spec):
         """ Remove prefix matching `spec`.
 
+            * `auth` [BaseAuth]
+                AAA options.
             * `schema_spec` [schema_spec]
                 Specifies what schema we are working within.
             * `spec` [prefix_spec]
@@ -2055,6 +2102,8 @@ def remove_prefix(self, auth, schema_spec, spec):
     def search_prefix(self, auth, schema_spec, query, search_options = {}):
         """ Search prefix list for prefixes matching `query`.
 
+            * `auth` [BaseAuth]
+                AAA options.
             * `schema_spec` [schema_spec]
                 Specifies what schema we are working within.
             * `query` [dict_to_sql]
@@ -2344,6 +2393,8 @@ def search_prefix(self, auth, schema_spec, query, search_options = {}):
     def smart_search_prefix(self, auth, schema_spec, query_str, search_options = {}):
         """ Perform a smart search on prefix list.
 
+            * `auth` [BaseAuth]
+                AAA options.
             * `schema_spec` [schema_spec]
                 Specifies what schema we are working within.
             * `query_str` [string]