Recent changes to Python API

Python API modified by Mark R. Bannister

Mark R. Bannister — Wed, 11 Nov 2015 12:04:32 -0000

--- v14
+++ v15
@@ -7,6 +7,16 @@

 * `dbis-cachemgr` must be running.
 * Python program must have permission to connect to DBIS client socket (default is `/var/run/dbis/client`).
+
+Online documentation is available through pydoc, e.g.
+
+~~~~
+$ python
+>>> import dbis.client, dbis.client.api
+>>> help(dbis.client)
+>>> help(dbis.client.opts)
+>>> help(dbis.client.api)
+~~~~

 By default the data is returned by the API as a list of strings in short format.  Here is a simple example that looks up a single host entry:

Python API modified by Mark R. Bannister

Mark R. Bannister — Thu, 16 Apr 2015 06:15:25 -0000

--- v13
+++ v14
@@ -148,8 +148,8 @@
 Keyword | Value | Description
 ------- | ----- | -----------
 `format` | `dbisopts.NSS` | Change output format to NSS-style.  This is the default output style.
-`format` | `dbisopts.STR` | Change output format to string representation of Python dictionary.
-`format` | `dbisopts.PICKLE` | Change output format to pickled representation of Python dictionary.  The Python API will unpickle the data before returning to the caller.
+`format` | `dbisopts.STR` | Change output format to string representation of Python data type.
+`format` | `dbisopts.PICKLE` | Change output format to pickled representation of Python data type.  The Python API will unpickle the data before returning to the caller.
 `format` | `dbisopts.STREAM` | Change output format to binary data stream, the format used by the NSS library.
 `format` | `dbisopts.JSON` | Change output format to JSON.
 `getnetgrent_recurse` | `True` | Request that a subsequent `getnetgrent` lookup should recurse member netgroups.

Python API modified by Mark R. Bannister

Mark R. Bannister — Wed, 15 Apr 2015 16:28:52 -0000

--- v12
+++ v13
@@ -133,7 +133,7 @@
 -----------------------
 It is possible to modify the data that the `dbis-cachemgr` server sends back to the client.  This is achieved using options that are passed through by the `dbis.client.lookup()` method to the server socket.

-These messages are set-up in a `dbis.client.opts.Options` object that is passed to the `opts` parameter to `dbis.client.initialise()` or `dbis.client.lookup()`.  For example, to request that the result should be returned as a Python object (i.e. pickled during transfer) and sorted:
+These messages are set-up in a `dbis.client.opts.Options` object that is passed to the `opts` parameter to `dbis.client.initialise()` or `dbis.client.lookup()`.  For example, to request that the result should be returned as a Python data type (i.e. pickled during transfer) and sorted:

 ~~~~
 #!/usr/bin/python

Python API modified by Mark R. Bannister

Mark R. Bannister — Wed, 15 Apr 2015 16:26:23 -0000

--- v11
+++ v12
@@ -33,7 +33,7 @@
 10.11.12.14     kilcher
 ~~~~

-This output is good for display purposes, but not so good for parsing.  If the data is to be parsed, it would be better represented as a Python object.  This can also be achieved, by requesting that the server sends the data to the client in Python pickle format.  Note that the data will be unpickled before it is returned from the API:
+This output is good for display purposes, but not so good for parsing.  If the data is to be parsed, it would be better represented as a Python tuple or dictionary.  This can also be achieved, by requesting that the server sends the data to the client in Python pickle format.  Note that the data will be unpickled before it is returned from the API:

 ~~~~
 #!/usr/bin/python

Python API modified by Mark R. Bannister

Mark R. Bannister — Wed, 15 Apr 2015 16:25:25 -0000

--- v10
+++ v11
@@ -33,7 +33,7 @@
 10.11.12.14     kilcher
 ~~~~

-This output is good for display purposes, but not so good for parsing.  If the data is to be parsed, it would be better represented as a Python dictionary.  This can also be achieved, by requesting that the server sends the data to the client in Python pickle format.  Note that the data will be unpickled before it is returned from the API:
+This output is good for display purposes, but not so good for parsing.  If the data is to be parsed, it would be better represented as a Python object.  This can also be achieved, by requesting that the server sends the data to the client in Python pickle format.  Note that the data will be unpickled before it is returned from the API:

 ~~~~
 #!/usr/bin/python
@@ -80,7 +80,7 @@

 The dictionary of attributes contains the attribute type (key) and a list of values.

-If `dbisapi.gethostbyname()` were called with no specific key, the entire map will be iterated instead.  In this case, if pickle format is requested, the resulting data structure will differ to that of a single value:
+If `dbisapi.gethostbyname()` were called with no specific key, the entire map will be iterated instead.  In this case, if pickle format is requested, the resulting unpickled data structure will differ to that of a single value:

 ~~~~
 {None: (None, 1429078604.586754, 900),

Python API modified by Mark R. Bannister

Mark R. Bannister — Wed, 15 Apr 2015 16:09:17 -0000

--- v9
+++ v10
@@ -48,7 +48,7 @@
 # Set-up options
 opts = dbisopts.Options(format=dbisopts.PICKLE)

-# Lookup entry in NSS format
+# Lookup full entry
 cmdobj = dbisapi.gethostbyname("kilcher")
 result = client.lookup(cmdobj, opts)
 print result

Python API modified by Mark R. Bannister

Mark R. Bannister — Wed, 15 Apr 2015 16:00:36 -0000

--- v8
+++ v9
@@ -6,8 +6,7 @@
 The Python API is designed to allow DBIS maps to be queried efficiently from within a third party Python program.  The API has the following pre-requisites:

 * `dbis-cachemgr` must be running.
-* Python program must be configured with DBIS client socket address (default is `/var/run/dbis/client`).
-* Python program must have permission to connect to DBIS client socket.
+* Python program must have permission to connect to DBIS client socket (default is `/var/run/dbis/client`).

 By default the data is returned by the API as a list of strings in short format.  Here is a simple example that looks up a single host entry:

Python API modified by Mark R. Bannister

Mark R. Bannister — Wed, 15 Apr 2015 06:35:51 -0000

--- v7
+++ v8
@@ -152,6 +152,7 @@
 `format` | `dbisopts.STR` | Change output format to string representation of Python dictionary.
 `format` | `dbisopts.PICKLE` | Change output format to pickled representation of Python dictionary.  The Python API will unpickle the data before returning to the caller.
 `format` | `dbisopts.STREAM` | Change output format to binary data stream, the format used by the NSS library.
+`format` | `dbisopts.JSON` | Change output format to JSON.
 `getnetgrent_recurse` | `True` | Request that a subsequent `getnetgrent` lookup should recurse member netgroups.
 `getnetgrent_recurse` | `False` | Request that a subsequent `getnetgrent` lookup should not recurse member netgroups, i.e. netgroup members will be listed by netgroup name.  This is the default.
 `sort` | `True` | Result should be sorted.

Python API modified by Mark R. Bannister

Mark R. Bannister — Wed, 15 Apr 2015 06:32:10 -0000

Python API modified by Mark R. Bannister

Mark R. Bannister — Wed, 15 Apr 2015 06:31:14 -0000

--- v5
+++ v6
@@ -61,7 +61,10 @@
 DEBUG: connecting to /var/run/dbis/client
 DEBUG: sending command: 'set format=pickle\ngethostbyname kilcher\n'
 DEBUG: unpickling result
-(('rn=kilcher,ou=lab,ou=hosts,o=infra', {'objectClass': ['top', 'ipHostObject', 'ipv4HostObject', 'ieee802Device'], 'ipv4Address': ['10.11.12.14'], 'rn': ['kilcher'], '_cfgmap': ['cn=hosts,en=sales.corp,ou=domain-mappings,o=infra'], 'macAddress': ['08:00:27:00:50:f2']}), 1429078281.088914, 900)
+(('rn=kilcher,ou=lab,ou=hosts,o=infra', {'objectClass': ['top', 'ipHostObject',
+'ipv4HostObject', 'ieee802Device'], 'ipv4Address': ['10.11.12.14'], 'rn':
+['kilcher'], '_cfgmap': ['cn=hosts,en=sales.corp,ou=domain-mappings,o=infra'],
+'macAddress': ['08:00:27:00:50:f2']}), 1429078281.088914, 900)
 ~~~~

 The result is a tuple containing a tuple containing a dictionary.  The outermost tuple contains:
@@ -95,7 +98,8 @@
              900),
 ... <snip> ...
  'www6.aja.com': (('cn=peg6.aja.com,ou=rfc2307,o=infra',
-                   {'_cfgmap': ['cn=hosts-legacy,ou=rfc2307,en=sales.corp,ou=domain-mappings,o=infra'],
+                   {'_cfgmap': ['cn=hosts-legacy,ou=rfc2307,en=sales.corp,
+ou=domain-mappings,o=infra'],
                     'bootFile': ['mach'],
                     'bootParameter': ['root=fs:/nfsroot/peg',
                                       'swap=fs:/nfsswap/peg',
@@ -140,7 +144,7 @@
 print opts.get()
 ~~~~

-The supported paramters to `dbis.client.opts.Options` are summarised in the table below.
+The supported parameters to `dbis.client.opts.Options` are summarised in the table below.

 Keyword | Value | Description
 ------- | ----- | -----------