Merge branch '15000-config-api'

[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 81aa20e3b762cf35913c4f92c4eb554eff4acae9..c8b2b67b111166e0662e4c70e431c10a4ea0a3f1 100644 (file)
--- a/doc/sdk/python/sdk-python.html.textile.liquid
+++ b/doc/sdk/python/sdk-python.html.textile.liquid
@@ -16,32 +16,27 @@ 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' %}
+The Python SDK supports Python 2.7 and 3.4+

 
 h3. Option 1: Install with pip
 
 
 h3. Option 1: 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 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).

 
 

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

 
 

-h3. Option 2: 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>
-~/arvados/sdk/python$ <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.
+h3. Option 2: Install from a distribution package

 
 

-h3. Option 3: Install from distribution packages
+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.
 
 
 First, "add the appropriate package repository for your distribution":{{ site.baseurl }}/install/install-manual-prerequisites.html#repos.
 


@@ -63,7 +58,7 @@ h3. 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 or from source (option 1 or 2 above):
+If you installed with pip (option 1, above):

 
 <notextile>
 <pre>~$ <code class="userinput">python</code>
 
 <notextile>
 <pre>~$ <code class="userinput">python</code>


@@ -76,7 +71,21 @@ Type "help", "copyright", "credits" or "license" for more information.
 </pre>
 </notextile>
 
 </pre>
 </notextile>
 

-If you installed from distribution packages (option 3): the packages include a virtualenv, which means the correct python environment needs to be loaded to import the Arvados 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>
+<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>
+
+Or alternatively, by using the Python executable from the virtualenv directly:

 
 <notextile>
 <pre>~$ <code class="userinput">/usr/share/python2.7/dist/python-arvados-python-client/bin/python</code>
 
 <notextile>
 <pre>~$ <code class="userinput">/usr/share/python2.7/dist/python-arvados-python-client/bin/python</code>