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, along with a number of command line tools for using and administering Arvados and Keep.
  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 As of Arvados 2.2, the Python SDK requires Python 3.6+.  The last version to support Python 2.7 is Arvados 2.0.4.
  22
  23 h2. Option 1: Install from a distribution package
  24
  25 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.
  26
  27 First, configure the "Arvados package repositories":../../install/packages.html
  28
  29 {% assign arvados_component = 'python3-arvados-python-client' %}
  30
  31 {% include 'install_packages' %}
  32
  33 h2. Option 2: Install with pip
  34
  35 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.
  36
  37 Run @pip install arvados-python-client@ in an appropriate installation environment, such as a @virtualenv@.
  38
  39 Note:
  40
  41 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 10 this is:
  42
  43 <pre>
  44 $ apt-get install git build-essential python3-dev libcurl4-openssl-dev libssl-dev
  45 </pre>
  46
  47 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@.
  48
  49 h2. Test installation
  50
  51 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.
  52
  53 If you installed with pip (option 1, above):
  54
  55 <notextile>
  56 <pre>~$ <code class="userinput">python</code>
  57 Python 3.7.3 (default, Jul 25 2020, 13:03:44)
  58 [GCC 8.3.0] on linux
  59 Type "help", "copyright", "credits" or "license" for more information.
  60 >>> <code class="userinput">import arvados</code>
  61 >>> <code class="userinput">arvados.api('v1')</code>
  62 &lt;apiclient.discovery.Resource object at 0x233bb50&gt;
  63 </pre>
  64 </notextile>
  65
  66 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:
  67
  68 {% include 'notebox_begin_warning' %}
  69 If you are on Ubuntu 18.04, please note that the Arvados packages that use Python depend on the python-3.8 package. This means they are installed under @/usr/share/python3.8@, not @/usr/share/python3@. You will need to update the commands below accordingly.
  70 {% include 'notebox_end' %}
  71
  72 <notextile>
  73 <pre>~$ <code class="userinput">source /usr/share/python3/dist/python3-arvados-python-client/bin/activate</code>
  74 (python-arvados-python-client) ~$ <code class="userinput">python</code>
  75 Python 3.7.3 (default, Jul 25 2020, 13:03:44)
  76 [GCC 8.3.0] on linux
  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/python3/dist/python3-arvados-python-client/bin/python</code>
  88 Python 3.7.3 (default, Jul 25 2020, 13:03:44)
  89 [GCC 8.3.0] on linux
  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 h2. Usage
  98
  99 Check out the "examples":example.html and "cookbook":cookbook.html
 100
 101 h3. Notes
 102
 103 The general form of an API call is:
 104
 105 <notextile>
 106 <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()
 107 </code></pre>
 108 </notextile>
 109
 110 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@.
 111
 112 <notextile>
 113 <pre><code class="userinput">arvados.api('v1').links().create(
 114     uuid=test_link['uuid'],
 115     body={'properties':{'foo':'bar'}}).execute()
 116 </code></pre>
 117 </notextile>
 118
 119 One way to make API calls slightly less verbose is:
 120
 121 <notextile>
 122 <pre><code class="userinput">arv = arvados.api('v1')
 123 j = arv.jobs().list().execute()
 124 </code></pre>
 125 </notextile>
 126
 127 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.