Python VO Client Library – Version 1.0

The Python VO Client Library is a collection of python classes that provide simple access to astronomical data via VO protocols. This library is entirely written in python (see http://www.python.org). Only client-side access functionality is included in this package. It is assumed that users have already been acquainted with VO protocols, web-services, and object-oriented programming in general.

Requirements

Python version 2.4.1 was used to develop and test this package. Earlier versions of python may work but are not tested. For XML processing, the python packages xml.sax.* are used. These packages are included in the standard python installation since version 2.3. The package SOAPpy is required for SOAP and WSDL handling and requires Python version 2.3.

Directories

This software package contains the following directories:

• lib contains core library classes;

• samples contains examples of how to use the core library classes; and

• data contains sample XML files for testing.

The PYTHONPATH environment variable should include the path of lib and sample.

Summary of core classes

The current version includes the following files in the directory lib:

• Sesame.py

• VOTable.py,

• ConeSearch.py,

• VORegistry,

• SIAP.py,

• SkyNode.py,

• SkyPortal.py, as well as the supporting modules

• printStruct.py and __init__.py.

Sesame.py

The Sesame class implements the interface to the Sesame name resolver service. See http://cdsweb.u-strasbg.fr/doc/sesame.htx for more information. Sesame uses the services of Simbad, NED and Vizier to resolve names. It returns RA and DEC, as well as aliases.

VOTable.py

The VOTable class provides methods to parse a VOTable source, which can be a file, a URL or a string, as well as methods to access the nodes within the VOTable. Convenient functions such as getFields() and getFieldAttrs () hide the internal complexity of VOTables.

The VNode class represents node in the XML file corresponding to one tag. VOTable uses python's xml.sax parser.

ConeSearch.py

The class ConeSearch offers two main methods: getRaw() and getVOTable(). They submit query to the ConeSearch service providers and retrieve results in raw form (string) and as VOTable. ConeSearch uses python's built-in urllib package to perform HTTP GET queries and VOTable class to store results from queries.

SIAP.py

The SIAP class is similar to ConeSearch. It also offers getRaw() and getVOTable (). Results of SIAP queries are returned in VOTable format with links to the actual images.

SkyNode.py

The current implementation is based on http://www.openskyquery/nodes/SDSS/nodeb.asmx?wsdl, and uses ADQL 0.7.4 instead of 1.0. This may change in order to be in sync with the service providers, once they switch to http://www.ivoa.net/xml/SNI/SkyNode-v1.0.wsdl . SkyNode requires the SOAPpy package and WSDLs from the corresponding services.

Note that SkyPortal interface can also be used to access SkyNodes.

SkyPortal.py

The SkyPortal class implements the interface as defined in http://www.openskyquery.net/Sky/SkyPortal/SkyPortal.asmx?WSDL. This interface offers methods to retrieve information about SkyNodes, and their tables, and columns, as well as the SubmitQuery() method, which takes a ADQL select statement, performs the query, and stores result in a VOTable. SkyPortal requires SOAPpy.

VORegistry.py

The VORegistry class implements the interface as defined in http://nvo.stsci.edu/VORegistry/registry.asmx?WSDL. This interface provides only retrieval methods. Registration and modification methods are not available. VORegistry requires SOAPpy.

printStruct.py

This module provides a class InspectStruct and a convenient method to output the content of a given structure, as well as the names of the variables.

__init__.py

Dummy module to make python package.

Summary of examples

Examples in the directory samples show simple ways to consume VO services. Each core class has a corresponding example file. Examples are implemented as functions that can be invoked directly from the command line. To run the example, printVOTable of VOTableEx.py, enter the command:

python VOTableEx.py printVOTable ../data/votable.xml

where VOTableEx.py is the python file containing the example printVOTable. This example reads the given XML file, ../data/votable.xml, and outputs its content.

Included in each example file is a special function, called runAll, which executes all examples in that file.

The following example files are in the directory samples.

• SesameEx.py
  Examples of how to use the Sesame class to find RA/DEC for given targets, as well as to find aliases.

• VOTableEx.py
  Examples of how to use the VOTable class.

• ConeSearchEx.py
  Examples of how to use the ConeSearch class to perform queries.

• VORegistryEx.py
  Examples of querying the VO registry.

• SIAPEx.py
  Examples of how to perform SIAP queries.

• SkyPortalEx.py
  Examples of how to use the SkyPortal interface.

• SkyNodeEx.py
  Examples of how to access a SkyNode service.

Summary of sample data files

• l.xml, uvi.xml, votable.xml
  Examples of VOTable.

• SkyNode.wsdl, SkyPortal.wsdl, registry.wsdl
  Local copies of WSDL files for VO services that use SOAP.

• targets.csv
  Input data file for an example.

Running the documentation web server locally

The companion program pydoc can be used to run a documentation server on any machine. From the parent directory of lib and samples run the command:

pydoc -p 5000

where -p 5000 indicates the a Web server be run on TCP port 5000. Using a web browser pointing to http://localhost:5000/ , one can see the python main documentation page. All the installed packages are listed together with packages included in the PYTHONPATH environment variable. The packages lib and samples should be listed also. The inline documentation of ConeSearch for example can be reached by following the link to lib/ConeSearch.

Shui Hung Kwok, shkwok@computer.org

VO summer school 2005, Aspen, Colorado