agraph-python 6.1.5

AllegroGraph Python client

The AllegroGraph Python API offers convenient and efficient access to an AllegroGraph server from a Python-based application. This API provides methods for creating, querying and maintaining RDF data, and for managing the stored triples. The AllegroGraph Python API deliberately emulates the Aduna Sesame API to make it easier to migrate from Sesame to AllegroGraph. The AllegroGraph Python API has also been extended in ways that make it easier and more intuitive than the Sesame API.

Requirements

Python versions 2.6+ and 3.3+ are supported.

The Python client depends on a few third-party Python modules. These will be downloaded from PyPI during installation and compiled on the target systems. Since some of the required packages use native extensions, it is necessary to have a proper development environment set up so that the compilation may succeed. This environment must include:

• A C compiler

• Python development headers

• libcurl development headers

Below we describe more detailed setup instructions for some of the supported systems.

Windows

The required packages are available in binary form for Windows, so it is not necessary to install any compilers or headers.

RHEL 6/7 and compatible systems

On RHEL-like systems the requirements mentioned above can be satisfied by following these steps (note that root privileges are required):

• Enable EPEL repositories, since some of the required packages are only available there. The detailed instructions can be found here. On CentOS systems, simply run:

  yum -y install epel-release

• Install the required packages:

  yum -y install python-devel python-pip libcurl-devel gcc

• Before installing the AllegroGraph Python client make sure that the following environment variable is set:

  export PYCURL_SSL_LIBRARY=nss

• To use virtual environments (recommended) an additional package is needed:

  yum -y install python-virtualenv

Ubuntu

The following packages are required to use the client with Python 2:

apt-get install python-pip libcurl-gnutls libcurl4-gnutls-dev libgnutls28-dev

For Python 3 this becomes:

apt-get install python3-pip libcurl-gnutls libcurl4-gnutls-dev libgnutls28-dev

Note

Using different SSL backends.

Ubuntu offers three variants of curl, built using different SSL libraries. These variants differ in their licensing and SSL related capabilities (see https://curl.haxx.se/docs/ssl-compared.html for more details). The instructions above use the GnuTLS version. In most cases this is an acceptable choice, but it is possible to use a different SSL implementation by installing appropriate packages before installing the AllegroGraph Python client.

To use the OpenSSL backend in curl:

apt-get install libcurl4-openssl-dev libssl-dev

For GnuTLS:

apt-get install libcurl4-gnutls-dev libgnutls28-dev

For NSS:

apt-get install libcurl4-nss-dev libnss3-dev

Note that if the client has already been installed it is necessary to reinstall the pycurl package in order to switch SSL backends:

# Uninstall old package
pip uninstall pycurl

# Reinstall, ignoring PIP cache (to force recompilation)
pip install --no-cache-dir pycurl

Arch Linux

On Arch the following packages are needed to use the client with Python 2:

pacman -S gcc python2 python2-pip libcurl

For Python 3 use:

pacman -S gcc python python-pip libcurl

Installation

Important

It is highly recommended to perform the install in a virtualenv environment.

A distribution archive can be obtained from http://franz.com/agraph/downloads/clients and installed using pip:

pip install agraph-<VERSION>-python-client.tar.gz

Testing

To validate the installation make sure that you have access to an AllegroGraph server and run the following Python script:

from franz.openrdf.connect import ag_connect
with ag_connect('repo', host='HOST', port='PORT',
                user='USER', password='PASS') as conn:
    print conn.size()

Substitute appropriate values for the HOST/PORT/USER/PASS placeholders. If the script runs successfully a new repository named repo will be created.

Unit tests

The Python client includes a suite of unit tests that can be run after installation. The tests are executed using the pytest framework and also use a few utilities from nose, so these two packages have to be installed:

pip install pytest nose

The tests require a running AllegroGraph server instance. The configuration of this server is passed to the tests through environment variables:

# Host and port where the server can be reached. These values are the
# default, it is only necessary to define the variables below if your
# setup is different
export AGRAPH_HOST=localhost
export AGRAPH_PORT=10035

# Tests will create repositories in this catalog.
# It must exist on the server. Use "/" for the root catalog.
export AGRAPH_CATALOG=tests

# Login credentials for the AG server.
# The user must have superuser privileges.
export AGRAPH_USER=test

# Use a prompt to read the password
read -s -r -p "Password for user ${AGRAPH_USER}: " AGRAPH_PASSWORD
export AGRAPH_PASSWORD

To run the tests, type:

pytest --pyargs franz

Troubleshooting

If you see an error similar to the following:

ImportError: pycurl: libcurl link-time ssl backend (nss) is
different from compile-time ssl backend (none/other)

Perform this procedure (replacing <VERSION> with the actual version):

# Uninstall pycurl:
pip uninstall pycurl

# Set the required compile-time option for pycurl
export PYCURL_SSL_LIBRARY=nss

# Reinstall, but ignore cached packages (force recompile)
pip install --no-cache-dir agraph-<VERSION>-python-client.tar.gz