Difference between revisions of "Python Database API interface"

From University Map Wiki
Jump to navigationJump to search
(Bump to 0.73 (fixes mis-handling of resords with no info records))
Line 1: Line 1:
There is an (experimental) Python interface to the Database API which may make working with the API from Python a little easier. The [[Media:ucammap-0.72.tar.gz|current version is available here]]. Note that while the distribution is really called 'ucammap' this wiki will upper-case the initial 'U' in the name of the distributed file - adapt the installation instructions accordingly.
+
There is an (experimental) Python interface to the Database API which may make working with the API from Python a little easier. The [[Media:ucammap-0.73.tar.gz|current version is available here]]. Note that while the distribution is really called 'ucammap' this wiki will upper-case the initial 'U' in the name of the distributed file - adapt the installation instructions accordingly.
  
 
Here is the README.txt file form the distribution:
 
Here is the README.txt file form the distribution:
Line 19: Line 19:
 
setup.py.
 
setup.py.
  
   tar zxf ucammap-0.72.tar.gz
+
   tar zxf ucammap-0.73.tar.gz
   cd ucammap-0.72
+
   cd ucammap-0.73
 
   python3 setup.py install
 
   python3 setup.py install
  

Revision as of 08:32, 2 November 2012

There is an (experimental) Python interface to the Database API which may make working with the API from Python a little easier. The current version is available here. Note that while the distribution is really called 'ucammap' this wiki will upper-case the initial 'U' in the name of the distributed file - adapt the installation instructions accordingly.

Here is the README.txt file form the distribution:

University Map Python API
=========================

This is a fairly simple Python 3 interface to the database API to the
University of Cambridge Map. The underlying API is described at

  https://wiki.cam.ac.uk/university-map/The_Database_API

Installation
------------

Unpack the distribution, move into the directory created, and run
setup.py. You will probably need privileged (i.e. root) access to run
setup.py.

  tar zxf ucammap-0.73.tar.gz
  cd ucammap-0.73
  python3 setup.py install

Adapt the package version number as necessary. Note that as
distributed this is a Python v3 module and so should be installed
using your system's copy of Python 3 if it has both v2 and v3
installed.

Use
---

Note, again, that as distributed this is a Python v3 module. It should
be easy enough to convert it to run under Python 2 if needed.

The code contains extensive in-line documentation so you may want to
look at that, in the source, via the built in help() function, or in
the ucammap.pydoc file included in the distribution.

The interface is implemented by the 'ucammap' module which should be
imported in the usual way. The primary (close to only) way to use this
is to create a ucammap.API object and then call its 'search'
method. All keyword arguments to search are converted to URL
parameters and included in a call to the underlying interface - see
the API documentation for more detail of what's possible. The result
is a (possibly empty) sequence of objects representing the selected
entities.

Throughout the API, collections of information are represented by one
of three Python object types - Entity, Info, and Address. Information
about the objects can be retrieved via attributes of the objects -
these return either strings or other objects, or sequences of strings
or objects as appropriate. See the underlying API documentation for
more details of what's available, and the module documentation for how
to access it. Objects also provide utility methods for transforming
their data - for example Entity provides a sort_name method to format
names in a format suitable for sorting.

The API class uses the standard logging module (at 'info' and 'debug')
to track the retrieval of API data.

The following provides a simple demonstration (also included in the
distribution as example.py):

#!/usr/bin/python3

import ucammap
import logging
logging.basicConfig(level=logging.INFO)

database = ucammap.API()

results = database.search(q = 'computing')

for result in results:
    print(result.full_name())
    if result.info:
        for k in result.info_keys():
            print("  " + k.capitalize() + ":")
            for i in result.filtered_info(k):
                print("     ", i.value)
    print()