Difference between revisions of "Python Database API interface"

From University Map Wiki
Jump to navigationJump to search
(Created)
 
(Link to v 2.2; update README)
 
(6 intermediate revisions by the same user not shown)
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.71.tar.gz|current version is available here]].
+
There is an (experimental) Python interface to the Database API which may make working with the API from Python a little easier. The [[Media:Python-ucammap-2.2.tar.gz|current version is available here]].  
  
Here is the README.txt file form the distributon:
+
Note that while the distribution is really called 'python-ucammap' this wiki upper-cases the initial 'P' in the name of the distributed file - adapt the installation instructions accordingly.
 +
 
 +
Here is the README.txt file from the distribution:
  
 
<pre><nowiki>
 
<pre><nowiki>
Line 7: Line 9:
 
=========================
 
=========================
  
This is a fairly simple Python 3 interface to the database API to the
+
This is a Python (>=2.6, or 3) interface to the database API to the
 
University of Cambridge Map. The underlying API is described at
 
University of Cambridge Map. The underlying API is described at
  
Line 19: Line 21:
 
setup.py.
 
setup.py.
  
   tar zxf ucammap-0.71.tar.gz
+
   tar zxf python-ucammap-<ver>.tar.gz
   cd ucammap-0.71
+
   cd python-ucammap-<ver>
   python3 setup.py install
+
   python setup.py install
  
Adapt the package version number as necessary. Note that as
+
Substitute <ver> as necessary. If you have more than one Python
distributed this is a Python v3 module and so should be installed
+
interpreter on you system then be sure to run setup.py using the one
using your system's copy of Python 3 if it has both v2 and v3
+
you will use to run scripts that use the module.
installed.
 
  
 
Use
 
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
 
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
+
look at that - in the source, via the built in Python help() function,
the ucammap.pydoc file included in the distribution.
+
or in the ucammap.pydoc file included in the distribution.
  
 
The interface is implemented by the 'ucammap' module which should be
 
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
 
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'
+
is to create a ucammap.API object and then to call its search()
method. All keyword arguments to search are converted to URL
+
method. All keyword arguments to search() are converted to URL
 
parameters and included in a call to the underlying interface - see
 
parameters and included in a call to the underlying interface - see
 
the API documentation for more detail of what's possible. The result
 
the API documentation for more detail of what's possible. The result
 
is a (possibly empty) sequence of objects representing the selected
 
is a (possibly empty) sequence of objects representing the selected
entities.
+
entities. Information about institutions, sites, buildings,
 +
etc. are represented by ucammap.Entity objects, and contact
 +
information records and addresses by ucammap.Info and ucammap.Address
 +
objects.
 +
 
 +
ucammap.API objects also provide an inflate() method to retrieve a
 +
full copy of an Entity object based on a partial one. The API class
 +
uses the standard logging module (at 'info' and 'debug') to track the
 +
retrieval of API data.
 +
 
 +
Access to information stored in Entity objects is available via
 +
attributes named after the coresponding keys described in the
 +
API. These return either simple values (string, integer, float,
 +
boolean), single instances of other ucammap objects, or
 +
possibably-empty sequences of other objects. Entity objects provide
 +
various convinience utility methods, such as
 +
ucammap.Entity.sort_name() which returns the entity's name in a form
 +
suitable for use in sorted lists.
 +
 
 +
ucammap.Info objects, representing a single row of contact
 +
information, make information available via the attributes 'type' and
 +
'value', sometimes suplimented by 'role' and 'attributes'. Values are
 +
either strings or ucammap.Address objects.
  
Throughout the API, collections of information are represented by one
+
ucammap.Address objects provide methods for extracting address
of three Python object types - Entity, Info, and Address. Information
+
information in various formats.
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')
+
Supported attributes that have no value in a particular object return
to track the retrieval of API data.
+
None for simple values or empty sequences.
  
 
The following provides a simple demonstration (also included in the
 
The following provides a simple demonstration (also included in the
 
distribution as example.py):
 
distribution as example.py):
  
#!/usr/bin/python3
+
#!/usr/bin/python
  
 
import ucammap
 
import ucammap
Line 75: Line 88:
 
for result in results:
 
for result in results:
 
     print(result.full_name())
 
     print(result.full_name())
     if result.info:
+
     for t in result.info_types():
        for k in result.info_keys():
+
        print("  " + t.capitalize() + ":")
            print("  " + k.capitalize() + ":")
+
        for i in result.filtered_info(t):
            for i in result.filtered_info(k):
+
            if i.value:
 
                 print("    ", i.value)
 
                 print("    ", i.value)
 
     print()
 
     print()
 
</nowiki></pre>
 
</nowiki></pre>

Latest revision as of 15:37, 4 October 2013

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 'python-ucammap' this wiki upper-cases the initial 'P' in the name of the distributed file - adapt the installation instructions accordingly.

Here is the README.txt file from the distribution:

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

This is a Python (>=2.6, or 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 python-ucammap-<ver>.tar.gz
  cd python-ucammap-<ver>
  python setup.py install

Substitute <ver> as necessary. If you have more than one Python
interpreter on you system then be sure to run setup.py using the one
you will use to run scripts that use the module.

Use
---

The code contains extensive in-line documentation so you may want to
look at that - in the source, via the built in Python 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 to 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. Information about institutions, sites, buildings,
etc. are represented by ucammap.Entity objects, and contact
information records and addresses by ucammap.Info and ucammap.Address
objects. 

ucammap.API objects also provide an inflate() method to retrieve a
full copy of an Entity object based on a partial one. The API class
uses the standard logging module (at 'info' and 'debug') to track the
retrieval of API data.

Access to information stored in Entity objects is available via
attributes named after the coresponding keys described in the
API. These return either simple values (string, integer, float,
boolean), single instances of other ucammap objects, or
possibably-empty sequences of other objects. Entity objects provide
various convinience utility methods, such as
ucammap.Entity.sort_name() which returns the entity's name in a form
suitable for use in sorted lists.

ucammap.Info objects, representing a single row of contact
information, make information available via the attributes 'type' and
'value', sometimes suplimented by 'role' and 'attributes'. Values are
either strings or ucammap.Address objects.

ucammap.Address objects provide methods for extracting address
information in various formats.

Supported attributes that have no value in a particular object return
None for simple values or empty sequences.

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

#!/usr/bin/python

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())
    for t in result.info_types():
        print("  " + t.capitalize() + ":")
        for i in result.filtered_info(t):
            if i.value:
                print("     ", i.value)
    print()