Update arvbox docs to describe how to install root cert

[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 72a6933ad389fb4312a35ec18c79c22bbf77eb8d..be824399a4c94def5b64af218fa0b93d154d739b 100644 (file)
--- a/doc/sdk/python/sdk-python.html.textile.liquid
+++ b/doc/sdk/python/sdk-python.html.textile.liquid
@@ -2,77 +2,89 @@
 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.
+
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}

 
 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.
 
 
 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.
+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' %}
 
 
 {% include 'notebox_begin' %}
 The Python SDK requires Python 2.7.
 {% include 'notebox_end' %}
 

-h4. Option 1: Install from distribution packages
+h3. Option 1: Install with pip

 
 

-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 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).

 
 

-{% assign rh_version = "6" %}
-{% include 'note_python_sc' %}
+Run @pip-2.7 install arvados-python-client@ in an appropriate installation environment, such as a virtualenv.

 
 

-On CentOS 6 and RHEL 6:
+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@.

 
 

-<notextile>
-<pre><code>~$ <span class="userinput">sudo yum install python27-python-arvados-python-client python27-python-arvados-cwl-runner</code>
-</code></pre>
-</notextile>
+h3. Option 2: 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 1, above.
+
+First, "add the appropriate package repository for your distribution":{{ site.baseurl }}/install/install-manual-prerequisites.html#repos.
+
+On Red Hat-based systems:

 
 <notextile>
 
 <notextile>

-<pre><code>~$ <span class="userinput">sudo yum install python-arvados-python-client python-arvados-cwl-runner</code>
+<pre><code>~$ <span class="userinput">sudo yum install python-arvados-python-client</code>

 </code></pre>
 </notextile>
 
 On Debian-based systems:
 
 <notextile>
 </code></pre>
 </notextile>
 
 On Debian-based systems:
 
 <notextile>

-<pre><code>~$ <span class="userinput">sudo apt-get install python-arvados-python-client python-arvados-cwl-runner</code>
+<pre><code>~$ <span class="userinput">sudo apt-get install python-arvados-python-client</code>

 </code></pre>
 </notextile>
 
 </code></pre>
 </notextile>
 

-h4. Option 2: Install with pip
+h3. Test installation

 
 

-Run @pip-2.7 install arvados-python-client arvados-cwl-runner@ 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-2.7 install --pre arvados-python-client@.
+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.

 
 

-h4. Option 3: Install from source
-
-Install the @python-setuptools@ package from your distribution.  Then run the following:
+If you installed with pip (option 1, above):

 
 <notextile>
 
 <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>
-~$ <span class="userinput">cd ~/arvados/sdk/cwl</span>
-~$ <span class="userinput">python2.7 setup.py install</span>
-</code></pre>
+<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.
+>>> <code class="userinput">import arvados</code>
+>>> <code class="userinput">arvados.api('v1')</code>
+&lt;apiclient.discovery.Resource object at 0x233bb50&gt;
+</pre>

 </notextile>
 
 </notextile>
 

-You may optionally run the final installation command in a virtualenv, or with the @--user@ option.
+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:

 
 

-h4. Test installation
+<notextile>
+<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>

 
 

-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:
+Or alternatively, by using the Python executable from the virtualenv directly:

 
 <notextile>
 
 <notextile>

-<pre>~$ <code class="userinput">python2.7</code>
+<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.
 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.