X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/2344e81e96887a08af1d659d09c0e26390cc4122..d4475f4c99f15161af3ececf3898d899bb3590c5:/doc/sdk/python/sdk-python.html.textile.liquid diff --git a/doc/sdk/python/sdk-python.html.textile.liquid b/doc/sdk/python/sdk-python.html.textile.liquid index b86a7fb40a..fa7c36c24b 100644 --- a/doc/sdk/python/sdk-python.html.textile.liquid +++ b/doc/sdk/python/sdk-python.html.textile.liquid @@ -2,69 +2,64 @@ layout: default navsection: sdk navmenu: Python -title: "Python SDK" - +title: "Installation" ... +{% comment %} +Copyright (C) The Arvados Authors. All rights reserved. -The Python SDK provides a generic set of wrappers so you can make API calls easily. It performs some validation before connecting to the API server: for example, it refuses to do an API call if a required parameter is missing. +SPDX-License-Identifier: CC-BY-SA-3.0 +{% endcomment %} -The library also includes some conveniences for use in Crunch scripts; see "Crunch utility libraries":crunch-utility-libraries.html for details. +The Python SDK provides access from Python to the Arvados API and Keep, along with a number of command line tools for using and administering Arvados and Keep. -h3. Installation +h2. 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 a distribution package, PyPI, or source. +To use the Python SDK elsewhere, you can install from PyPI or a distribution package. -{% include 'notebox_begin' %} -The Python SDK requires Python 2.7. -{% include 'notebox_end' %} +The Python SDK supports Python 2.7 and 3.4+ -h4. Option 1: Install from distribution packages +h2. Option 1: Install from a distribution package -First, "add the appropriate package repository for your distribution":{{ site.baseurl }}/install/install-manual-prerequisites.html#repos. +This installation method is recommended to make the CLI tools available system-wide. It can coexist with the installation method described in option 2, below. -{% include 'note_python27_sc' %} +First, configure the "Arvados package repositories":../../install/packages.html -On Debian-based systems: +{% assign arvados_component = 'python-arvados-python-client' %} - -
~$ sudo apt-get install python-arvados-python-client
-
-
+{% include 'install_packages' %} -On Red Hat-based systems: +h2. Option 2: Install with pip - -
~$ sudo yum install python27-python-arvados-python-client
-
-
+This installation method is recommended to use the SDK in your own Python programs. If installed into a @virtualenv@, it can coexist with the system-wide installation method from a distribution package. -h4. Option 2: Install with pip +Run @pip install arvados-python-client@ in an appropriate installation environment, such as a @virtualenv@. -Run @pip-2.7 install arvados-python-client@ in an appropriate installation environment, such as a virtualenv. +Note: -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-2.7 install --pre arvados-python-client@. +The SDK uses @pycurl@ which depends on the @libcurl@ C library. To build the module you may have to first install additional packages. On Debian 9 this is: -h4. Option 3: Install from source +
+$ apt-get install git build-essential python-dev libcurl4-openssl-dev libssl1.0-dev
+
-Install the @python-setuptools@ package from your distribution. Then run the following: +For Python 3 this is - -
~$ git clone https://github.com/curoverse/arvados.git
-~$ cd arvados/sdk/python
-~$ python2.7 setup.py install
-
-
+
+$ apt-get install git build-essential python3-dev libcurl4-openssl-dev libssl1.0-dev
+
+ +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@. -You may optionally run the final installation command in a virtualenv, or with the @--user@ option. +h2. Test installation -h4. 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":{{site.baseurl}}/user/reference/api-tokens.html for details), @import arvados@ should produce no errors. -If the SDK is installed and your @ARVADOS_API_HOST@ and @ARVADOS_API_TOKEN@ environment variables are set up correctly (see "api-tokens":{{site.baseurl}}/user/reference/api-tokens.html for details), @import arvados@ should produce no errors: +If you installed with pip (option 1, above): -
~$ python2.7
+
~$ 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.
@@ -74,56 +69,36 @@ Type "help", "copyright", "credits" or "license" for more information.
 
-h3. 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: +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: -
test_link = arvados.api('v1').links().create(
-    body={'link_class':'test','name':'test'}).execute()
-
+
~$ 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>
+
-Update an object: +Or alternatively, by using the Python executable from the virtualenv directly: -
arvados.api('v1').links().update(
-    uuid=test_link['uuid'],
-    body={'properties':{'foo':'bar'}}).execute()
-
+
~$ /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>
+
-Get a list of objects: +h2. Usage - -
repos = arvados.api('v1').repositories().list().execute()
-len(repos['items'])
-2
-repos['items'][0]['uuid']
-u'qr1hi-s0uqq-kg8cawglrf74bmw'
-
-
+Check out the "examples":example.html and "cookbook":cookbook.html h3. Notes