X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/6c78b28f9f54664babc57a4b4372c502065ed5d1..4d3508cefb40ad5b53af22d8f3dda13593b598d2:/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 9c0ec475b4..4a6ba029fe 100644
--- a/doc/sdk/python/sdk-python.html.textile.liquid
+++ b/doc/sdk/python/sdk-python.html.textile.liquid
@@ -10,68 +10,35 @@ 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, along with a number of command line tools for using and administering Arvados and Keep.
h2. Installation
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 PyPI or a distribution package.
+To use the Python SDK elsewhere, you can install it "from an Arvados distribution package":#package-install or "from PyPI using pip":#pip-install.
-The Python SDK supports Python 2.7 and 3.4+
+{% include 'notebox_begin_warning' %}
+As of Arvados 3.0, the Python SDK requires Python 3.8+.
+{% include 'notebox_end' %}
-h3. Option 1: Install with pip
+h2(#package-install). Install from a distribution package
-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).
+This installation method is recommended to make the CLI tools available system-wide. It can coexist with the pip installation method described below.
-Run @pip install arvados-python-client@ in an appropriate installation environment, such as a virtualenv.
+First, configure the "Arvados package repositories":../../install/packages.html
-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@.
+{% assign arvados_component = 'python3-arvados-python-client' %}
-h3. Option 2: Install from a distribution package
+{% include 'install_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.
-
-On Red Hat-based systems:
-
-
-~$ sudo yum install python-arvados-python-client
-
-
-
-On Debian-based systems:
-
-
-~$ sudo apt-get install python-arvados-python-client
-
-
-
-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 you installed with pip (option 1, above):
+The package includes a virtualenv, which means the correct Python environment needs to be loaded before the Arvados SDK can be imported. You can test the installation by doing that, then creating a client object. Ensure your "@ARVADOS_API_HOST@ and @ARVADOS_API_TOKEN@ credentials are set up correctly":{{site.baseurl}}/user/reference/api-tokens.html. Then you should be able to run the following without any errors:
-~$ python
-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.
->>> import arvados
->>> arvados.api('v1')
-<apiclient.discovery.Resource object at 0x233bb50>
-
-
-
-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:
-
-
-~$ source /usr/share/python2.7/dist/python-arvados-python-client/bin/activate
+~$ source /usr/lib/python3-arvados-python-client/bin/activate
(python-arvados-python-client) ~$ python
-Python 2.7.4 (default, Sep 26 2013, 03:20:26)
-[GCC 4.7.3] on linux2
+Python 3.7.3 (default, Jul 25 2020, 13:03:44)
+[GCC 8.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import arvados
>>> arvados.api('v1')
@@ -79,12 +46,12 @@ Type "help", "copyright", "credits" or "license" for more information.
-Or alternatively, by using the Python executable from the virtualenv directly:
+Alternatively, you can run the Python executable inside the @virtualenv@ directly:
-~$ /usr/share/python2.7/dist/python-arvados-python-client/bin/python
-Python 2.7.4 (default, Sep 26 2013, 03:20:26)
-[GCC 4.7.3] on linux2
+~$ /usr/lib/python3-arvados-python-client/bin/python
+Python 3.7.3 (default, Jul 25 2020, 13:03:44)
+[GCC 8.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import arvados
>>> arvados.api('v1')
@@ -92,81 +59,36 @@ Type "help", "copyright", "credits" or "license" for more information.
-h3. Examples
+After you have successfully tested your installation, proceed to the the "API client overview":api-client.html and "cookbook":cookbook.html to learn how to use the SDK.
-Get the User object for the current user:
+h2(#pip-install). Install from PyPI with pip
-
-current_user = arvados.api('v1').users().current().execute()
-
-
+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.
-Get the UUID of an object that was retrieved using the SDK:
+Note the Python SDK uses @pycurl@ which depends on the @libcurl@ C library. To build the module you may have to first install additional packages. On Debian-based distributions you can install them by running:
-my_uuid = current_user['uuid']
+# apt install git build-essential python3-dev libcurl4-openssl-dev libssl-dev
-Retrieve an object by ID:
+Run @python3 -m pip install arvados-python-client@ in an appropriate installation environment, such as a @virtualenv@.
-
-some_user = arvados.api('v1').users().get(uuid=my_uuid).execute()
-
-
+{% include 'notebox_begin_warning' %}
+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 @python3 -m pip install --pre arvados-python-client@.
+{% include 'notebox_end' %}
-Create an object:
+You can test the installation by creating a client object. Ensure your "@ARVADOS_API_HOST@ and @ARVADOS_API_TOKEN@ credentials are set up correctly":{{site.baseurl}}/user/reference/api-tokens.html. Then you should be able to run the following without any errors:
-test_link = arvados.api('v1').links().create(
- body={'link_class':'test','name':'test'}).execute()
-
-
-
-Update an object:
-
-
-arvados.api('v1').links().update(
- uuid=test_link['uuid'],
- body={'properties':{'foo':'bar'}}).execute()
-
-
-
-Get a list of objects:
-
-
-repos = arvados.api('v1').repositories().list().execute()
-len(repos['items'])
-2
-repos['items'][0]['uuid']
-u'qr1hi-s0uqq-kg8cawglrf74bmw'
-
-
-
-h3. Notes
-
-The general form of an API call is:
-
-
-arvados.api(api_version).plural_resource_type().api_method(parameter=value, ...).execute()
-
-
-
-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@.
-
-
-arvados.api('v1').links().create(
- uuid=test_link['uuid'],
- body={'properties':{'foo':'bar'}}).execute()
-
-
-
-One way to make API calls slightly less verbose is:
-
-
-arv = arvados.api('v1')
-j = arv.jobs().list().execute()
-
+~$ python3
+Python 3.7.3 (default, Jul 25 2020, 13:03:44)
+[GCC 8.3.0] on linux
+Type "help", "copyright", "credits" or "license" for more information.
+>>> import arvados
+>>> arvados.api('v1')
+<apiclient.discovery.Resource object at 0x233bb50>
+
-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.
+After you have successfully tested your installation, proceed to the the "API client overview":api-client.html and "cookbook":cookbook.html to learn how to use the SDK.