doc/sdk/python/sdk-python.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: sdk
   4 navmenu: Python
   5 title: "Installation"
   6 ...
   7 {% comment %}
   8 Copyright (C) The Arvados Authors. All rights reserved.
   9
  10 SPDX-License-Identifier: CC-BY-SA-3.0
  11 {% endcomment %}
  12
  13 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":crunch-utility-libraries.html for details.
  14
  15 h2. Installation
  16
  17 If you are logged in to an Arvados VM, the Python SDK should be installed.
  18
  19 To use the Python SDK elsewhere, you can install from PyPI or a distribution package.
  20
  21 {% include 'notebox_begin' %}
  22 The Python SDK requires Python 2.7.
  23 {% include 'notebox_end' %}
  24
  25 h3. Option 1: Install with pip
  26
  27 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).
  28
  29 Run @pip-2.7 install arvados-python-client@ in an appropriate installation environment, such as a virtualenv.
  30
  31 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@.
  32
  33 h3. Option 2: Install from a distribution package
  34
  35 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.
  36
  37 First, "add the appropriate package repository for your distribution":{{ site.baseurl }}/install/install-manual-prerequisites.html#repos.
  38
  39 On Red Hat-based systems:
  40
  41 <notextile>
  42 <pre><code>~$ <span class="userinput">sudo yum install python-arvados-python-client</code>
  43 </code></pre>
  44 </notextile>
  45
  46 On Debian-based systems:
  47
  48 <notextile>
  49 <pre><code>~$ <span class="userinput">sudo apt-get install python-arvados-python-client</code>
  50 </code></pre>
  51 </notextile>
  52
  53 h3. Test installation
  54
  55 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.
  56
  57 If you installed with pip (option 1, above):
  58
  59 <notextile>
  60 <pre>~$ <code class="userinput">python</code>
  61 Python 2.7.4 (default, Sep 26 2013, 03:20:26)
  62 [GCC 4.7.3] on linux2
  63 Type "help", "copyright", "credits" or "license" for more information.
  64 >>> <code class="userinput">import arvados</code>
  65 >>> <code class="userinput">arvados.api('v1')</code>
  66 &lt;apiclient.discovery.Resource object at 0x233bb50&gt;
  67 </pre>
  68 </notextile>
  69
  70 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:
  71
  72 <notextile>
  73 <pre>~$ <code class="userinput">source /usr/share/python2.7/dist/python-arvados-python-client/bin/activate</code>
  74 (python-arvados-python-client) ~$ <code class="userinput">python</code>
  75 Python 2.7.4 (default, Sep 26 2013, 03:20:26)
  76 [GCC 4.7.3] on linux2
  77 Type "help", "copyright", "credits" or "license" for more information.
  78 >>> <code class="userinput">import arvados</code>
  79 >>> <code class="userinput">arvados.api('v1')</code>
  80 &lt;apiclient.discovery.Resource object at 0x233bb50&gt;
  81 </pre>
  82 </notextile>
  83
  84 Or alternatively, by using the Python executable from the virtualenv directly:
  85
  86 <notextile>
  87 <pre>~$ <code class="userinput">/usr/share/python2.7/dist/python-arvados-python-client/bin/python</code>
  88 Python 2.7.4 (default, Sep 26 2013, 03:20:26)
  89 [GCC 4.7.3] on linux2
  90 Type "help", "copyright", "credits" or "license" for more information.
  91 >>> <code class="userinput">import arvados</code>
  92 >>> <code class="userinput">arvados.api('v1')</code>
  93 &lt;apiclient.discovery.Resource object at 0x233bb50&gt;
  94 </pre>
  95 </notextile>
  96
  97 h3. Examples
  98
  99 Get the User object for the current user:
 100
 101 <notextile>
 102 <pre><code class="userinput">current_user = arvados.api('v1').users().current().execute()
 103 </code></pre>
 104 </notextile>
 105
 106 Get the UUID of an object that was retrieved using the SDK:
 107
 108 <notextile>
 109 <pre><code class="userinput">my_uuid = current_user['uuid']
 110 </code></pre>
 111 </notextile>
 112
 113 Retrieve an object by ID:
 114
 115 <notextile>
 116 <pre><code class="userinput">some_user = arvados.api('v1').users().get(uuid=my_uuid).execute()
 117 </code></pre>
 118 </notextile>
 119
 120 Create an object:
 121
 122 <notextile>
 123 <pre><code class="userinput">test_link = arvados.api('v1').links().create(
 124     body={'link_class':'test','name':'test'}).execute()
 125 </code></pre>
 126 </notextile>
 127
 128 Update an object:
 129
 130 <notextile>
 131 <pre><code class="userinput">arvados.api('v1').links().update(
 132     uuid=test_link['uuid'],
 133     body={'properties':{'foo':'bar'}}).execute()
 134 </code></pre>
 135 </notextile>
 136
 137 Get a list of objects:
 138
 139 <notextile>
 140 <pre><code class="userinput">repos = arvados.api('v1').repositories().list().execute()
 141 len(repos['items'])</code>
 142 2
 143 <code class="userinput">repos['items'][0]['uuid']</code>
 144 u'qr1hi-s0uqq-kg8cawglrf74bmw'
 145 </code></pre>
 146 </notextile>
 147
 148 h3. Notes
 149
 150 The general form of an API call is:
 151
 152 <notextile>
 153 <pre><code class="userinput">arvados.api(<i>api_version</i>).<i>plural_resource_type</i>().<i>api_method</i>(<i>parameter</i>=<i>value</i>, ...).execute()
 154 </code></pre>
 155 </notextile>
 156
 157 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@.
 158
 159 <notextile>
 160 <pre><code class="userinput">arvados.api('v1').links().create(
 161     uuid=test_link['uuid'],
 162     body={'properties':{'foo':'bar'}}).execute()
 163 </code></pre>
 164 </notextile>
 165
 166 One way to make API calls slightly less verbose is:
 167
 168 <notextile>
 169 <pre><code class="userinput">arv = arvados.api('v1')
 170 j = arv.jobs().list().execute()
 171 </code></pre>
 172 </notextile>
 173
 174 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.