Python API

Python API

Introduction

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 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:

#!/usr/bin/python
import sys
import dbis.client
import dbis.client.api as dbisapi

# Initialise client object
client = dbis.client.initialise(fpdebug=sys.stderr)

# Lookup entry in NSS format
cmdobj = dbisapi.gethostbyname("kilcher")
result = client.lookup(cmdobj)
print "\n".join(result)

The output is:

DEBUG: connecting to /var/run/dbis/client
DEBUG: sending command: 'gethostbyname kilcher\n'
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 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
import sys
import dbis.client
import dbis.client.api as dbisapi
import dbis.client.opts as dbisopts

# Initialise client object
client = dbis.client.initialise(fpdebug=sys.stderr)

# Set-up options
opts = dbisopts.Options(format=dbisopts.PICKLE)

# Lookup full entry
cmdobj = dbisapi.gethostbyname("kilcher")
result = client.lookup(cmdobj, opts)
print result

The output is:

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)

The result is a tuple containing a tuple containing a dictionary. The outermost tuple contains:

(LDAP search result, time last updated, TTL)

The LDAP search result is itself a tuple containing:

(DN of entry, dictionary of attributes)

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 unpickled data structure will differ to that of a single value:

{None: (None, 1429078604.586754, 900),
 'kilcher': (('rn=kilcher,ou=lab,ou=hosts,o=infra',
              {'_cfgmap': ['cn=hosts,en=sales.corp,ou=domain-mappings,o=infra'],
               'ipv4Address': ['10.11.12.14'],
               'macAddress': ['08:00:27:00:50:f2'],
               'objectClass': ['top',
                               'ipHostObject',
                               'ipv4HostObject',
                               'ieee802Device'],
               'rn': ['kilcher']}),
             1429078604.585119,
             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'],
                    'bootFile': ['mach'],
                    'bootParameter': ['root=fs:/nfsroot/peg',
                                      'swap=fs:/nfsswap/peg',
                                      'dump=fs:/nfsdump/peg'],
                    'cn': ['peg6.aja.com', 'www6.aja.com'],
                    'ipHostNumber': ['23:0:7:0:1:2:3:4'],
                    'ipv6Address': ['23:0:7:0:1:2:3:4'],
                    'macAddress': ['00:00:92:90:ee:e3'],
                    'objectClass': ['top',
                                    'device',
                                    'ipHost',
                                    'bootableDevice',
                                    'ieee802Device',
                                    'ipHostObject',
                                    'ipv6HostObject'],
                    'rn': ['peg6.aja.com', 'www6.aja.com']}),
                  1429078604.585982,
                  900)}

This is a dictionary, where the key in the dictionary is the key of the entry and the value is the (LDAP search result, time last updated, TTL) tuple. The None entry represents when the entire map was last updated, i.e. the last time someone iterated through every entry in the map.

There are multiple methods per map. To obtain a full list of available methods and their supported parameters, run:

$ python
>>> import dbis.client.api
>>> help(dbis.client.api)

Server control messages

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 data type (i.e. pickled during transfer) and sorted:

#!/usr/bin/python
import dbis.client.opts as dbisopts

opts = dbisopts.Options(format=dbisopts.PICKLE, sort=True)
print opts.get()

The supported parameters to dbis.client.opts.Options are summarised in the table below.

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 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.
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.
sort	False	Result should not be sorted. This is the default.

There is also online help available:

$ python
>>> import dbis.client.opts
>>> help(dbis.client.opts)

For more information on the other components of DBIS, see [Using DBIS].