projects / arvados.git / blobdiff
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
15572: Epic documentation commit
[arvados.git] / 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 a6a0b565c9cb3bcdf8b5a03a6eb79370ce34ab47..381c01d53f05eae8e8ff11615f1efa34851c1b8e 100644 (file)
--- a/doc/sdk/python/sdk-python.html.textile.liquid
+++ b/doc/sdk/python/sdk-python.html.textile.liquid
@@ -2,77 +2,56 @@
 layout: default
 navsection: sdk
 navmenu: Python
 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.  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.
 
 
-h3. Installation
+h2. Installation
 
 If you are logged in to an Arvados VM, the Python SDK should be installed.
 
 
 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.
-
-{% include 'notebox_begin' %}
-The Python SDK requires Python 2.7.
-{% include 'notebox_end' %}
-
-h4. Option 1: Install from distribution packages
-
-First, "add the appropriate package repository for your distribution":{{ site.baseurl }}/install/install-manual-prerequisites.html#repos.
+To use the Python SDK elsewhere, you can install from PyPI or a distribution package.
 
 
-{% assign rh_version = "6" %}
-{% include 'note_python_sc' %}
+The Python SDK supports Python 2.7 and 3.4+
 
 
-On CentOS 6 and RHEL 6:
-
-<notextile>
-<pre><code>~$ <span class="userinput">sudo yum install python27-python-arvados-python-client</code>
-</code></pre>
-</notextile>
+h2. Option 1: Install from a distribution package
 
 
-On other Red Hat-based systems:
+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.
 
 
-<notextile>
-<pre><code>~$ <span class="userinput">sudo yum install python-arvados-python-client</code>
-</code></pre>
-</notextile>
+First, configure the "Arvados package repositories":../../install/packages.html
 
 
-On Debian-based systems:
+{% assign arvados_component = 'python-arvados-python-client' %}
 
 
-<notextile>
-<pre><code>~$ <span class="userinput">sudo apt-get install python-arvados-python-client</code>
-</code></pre>
-</notextile>
+{% include 'install_packages' %}
 
 
-h4. Option 2: Install with pip
+h2. Option 2: Install with pip
 
 
-Run @pip-2.7 install arvados-python-client@ in an appropriate installation environment, such as a virtualenv.
+This installation method is recommended to use the SDK in your own Python programs. It can coexist with the system-wide installation method from a distribution package (option 2, below).
 
 
-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@.
+Run @pip install arvados-python-client@ in an appropriate installation environment, such as a @virtualenv@.
 
 
-h4. Option 3: Install from source
+The SDK uses @pycurl@ which depends on the @libcurl@ C library.  To build the module you may have to install additional packages.  On Debian 9 this is:
 
 
-Install the @python-setuptools@ package from your distribution.  Then run the following:
+<pre>
+$ apt-get install git build-essential python3-dev libcurl4-openssl-dev libssl1.0-dev
+</pre>
 
 
-<notextile>
-<pre><code>~$ <span class="userinput">git clone https://github.com/curoverse/arvados.git</span>
-~$ <span class="userinput">cd arvados/sdk/python</span>
-~$ <span class="userinput">python2.7 setup.py install</span>
-</code></pre>
-</notextile>
+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):
 
 <notextile>
 
 <notextile>
-<pre>~$ <code class="userinput">python2.7</code>
+<pre>~$ <code class="userinput">python</code>
 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.
 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.
@@ -82,56 +61,36 @@ Type "help", "copyright", "credits" or "license" for more information.
 </pre>
 </notextile>
 
 </pre>
 </notextile>
 
-h3. Examples
-
-Get the User object for the current user:
-
-<notextile>
-<pre><code class="userinput">current_user = arvados.api('v1').users().current().execute()
-</code></pre>
-</notextile>
-
-Get the UUID of an object that was retrieved using the SDK:
+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:
 
 <notextile>
 
 <notextile>
-<pre><code class="userinput">my_uuid = current_user['uuid']
-</code></pre>
-</notextile>
-
-Retrieve an object by ID:
-
-<notextile>
-<pre><code class="userinput">some_user = arvados.api('v1').users().get(uuid=my_uuid).execute()
-</code></pre>
-</notextile>
-
-Create an object:
-
-<notextile>
-<pre><code class="userinput">test_link = arvados.api('v1').links().create(
-    body={'link_class':'test','name':'test'}).execute()
-</code></pre>
+<pre>~$ <code class="userinput">source /usr/share/python2.7/dist/python-arvados-python-client/bin/activate</code>
+(python-arvados-python-client) ~$ <code class="userinput">python</code>
+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.
+>>> <code class="userinput">import arvados</code>
+>>> <code class="userinput">arvados.api('v1')</code>
+&lt;apiclient.discovery.Resource object at 0x233bb50&gt;
+</pre>
 </notextile>
 
 </notextile>
 
-Update an object:
+Or alternatively, by using the Python executable from the virtualenv directly:
 
 <notextile>
 
 <notextile>
-<pre><code class="userinput">arvados.api('v1').links().update(
-    uuid=test_link['uuid'],
-    body={'properties':{'foo':'bar'}}).execute()
-</code></pre>
+<pre>~$ <code class="userinput">/usr/share/python2.7/dist/python-arvados-python-client/bin/python</code>
+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.
+>>> <code class="userinput">import arvados</code>
+>>> <code class="userinput">arvados.api('v1')</code>
+&lt;apiclient.discovery.Resource object at 0x233bb50&gt;
+</pre>
 </notextile>
 
 </notextile>
 
-Get a list of objects:
+h2. Usage
 
 
-<notextile>
-<pre><code class="userinput">repos = arvados.api('v1').repositories().list().execute()
-len(repos['items'])</code>
-2
-<code class="userinput">repos['items'][0]['uuid']</code>
-u'qr1hi-s0uqq-kg8cawglrf74bmw'
-</code></pre>
-</notextile>
+Check out the "examples":example.html and "cookbook":cookbook.html
 
 h3. Notes
 
 
 h3. Notes