Installation

The Python SDK provides access from Python to the Arvados API and Keep. It also includes a number of command line tools for using and administering Arvados and Keep, and some conveniences for use in Crunch scripts; see Crunch utility libraries for details.

Installation

If you are logged in to an Arvados VM, the Python SDK should be installed.

To use the Python SDK elsewhere, you can install from PyPI or a distribution package.

The Python SDK supports Python 2.7 and 3.4+

Option 1: Install with pip

This installation method is recommended to make the SDK available for use in your own Python programs. It can coexist with the system-wide installation method from a distribution package (option 2, below).

Run pip install arvados-python-client in an appropriate installation environment, such as a virtualenv.

If your version of pip is 1.4 or newer, the pip install command might give an error: “Could not find a version that satisfies the requirement arvados-python-client”. If this happens, try pip install --pre arvados-python-client.

Option 2: Install from a distribution package

This installation method is recommended to make the CLI tools available system-wide. It can coexist with the installation method described in option 1, above.

First, add the appropriate package repository for your distribution.

On Red Hat-based systems:

~$ sudo yum install python-arvados-python-client

On Debian-based systems:

~$ sudo apt-get install python-arvados-python-client

Test installation

If the SDK is installed and your ARVADOS_API_HOST and ARVADOS_API_TOKEN environment variables are set up correctly (see api-tokens for details), import arvados should produce no errors.

If you installed with pip (option 1, above):

~$ python
Python 2.7.4 (default, Sep 26 2013, 03:20:26)
[GCC 4.7.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import arvados
>>> arvados.api('v1')
<apiclient.discovery.Resource object at 0x233bb50>

If you installed from a distribution package (option 2): the package includes a virtualenv, which means the correct Python environment needs to be loaded before the Arvados SDK can be imported. This can be done by activating the virtualenv first:

~$ source /usr/share/python2.7/dist/python-arvados-python-client/bin/activate
(python-arvados-python-client) ~$ python
Python 2.7.4 (default, Sep 26 2013, 03:20:26)
[GCC 4.7.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import arvados
>>> arvados.api('v1')
<apiclient.discovery.Resource object at 0x233bb50>

Or alternatively, by using the Python executable from the virtualenv directly:

~$ /usr/share/python2.7/dist/python-arvados-python-client/bin/python
Python 2.7.4 (default, Sep 26 2013, 03:20:26)
[GCC 4.7.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import arvados
>>> arvados.api('v1')
<apiclient.discovery.Resource object at 0x233bb50>

Examples

Get the User object for the current user:

current_user = arvados.api('v1').users().current().execute()

Get the UUID of an object that was retrieved using the SDK:

my_uuid = current_user['uuid']

Retrieve an object by ID:

some_user = arvados.api('v1').users().get(uuid=my_uuid).execute()

Create an object:

test_link = arvados.api('v1').links().create(
    body={'link_class':'test','name':'test'}).execute()

Update an object:

arvados.api('v1').links().update(
    uuid=test_link['uuid'],
    body={'properties':{'foo':'bar'}}).execute()

Get a list of objects:

repos = arvados.api('v1').repositories().list().execute()
len(repos['items'])
2
repos['items'][0]['uuid']
u'qr1hi-s0uqq-kg8cawglrf74bmw'

Notes

The general form of an API call is:

arvados.api(api_version).plural_resource_type().api_method(parameter=value, ...).execute()

Many API methods accept a parameter whose name is the same as the resource type. For example, links.create accepts a parameter called link. This parameter should be given as body.

arvados.api('v1').links().create(
    uuid=test_link['uuid'],
    body={'properties':{'foo':'bar'}}).execute()

One way to make API calls slightly less verbose is:

arv = arvados.api('v1')
j = arv.jobs().list().execute()

The SDK retrieves the list of API methods from the server at run time. Therefore, the set of available methods is determined by the server version rather than the SDK version.

---

Previous: SDK Reference Next: Examples