Merge branch '13076-r-autogen-api'
[arvados.git] / sdk / python / README.rst
1 .. Copyright (C) The Arvados Authors. All rights reserved.
2 ..
3 .. SPDX-License-Identifier: Apache-2.0
4
5 =====================
6 Arvados Python Client
7 =====================
8
9 Overview
10 --------
11
12 This package provides the ``arvados`` module, an API client for
13 Arvados_.  It also includes higher-level functions to help you write
14 Crunch scripts, and command-line tools to store and retrieve data in
15 the Keep storage server.
16
17 .. _Arvados: https://arvados.org/
18
19 Installation
20 ------------
21
22 Installing under your user account
23 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
24
25 This method lets you install the package without root access.
26 However, other users on the same system won't be able to use it.
27
28 1. Run ``pip install --user arvados-python-client``.
29
30 2. In your shell configuration, make sure you add ``$HOME/.local/bin``
31    to your PATH environment variable.  For example, you could add the
32    command ``PATH=$PATH:$HOME/.local/bin`` to your ``.bashrc`` file.
33
34 3. Reload your shell configuration.  For example, bash users could run
35    ``source ~/.bashrc``.
36
37 Installing on Debian systems
38 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
39
40 1. Add this Arvados repository to your sources list::
41
42      deb http://apt.arvados.org/ stretch main
43
44 2. Update your package list.
45
46 3. Install the ``python-arvados-python-client`` package.
47
48 Configuration
49 -------------
50
51 This client software needs two pieces of information to connect to
52 Arvados: the DNS name of the API server, and an API authorization
53 token.  You can set these in environment variables, or the file
54 ``$HOME/.config/arvados/settings.conf``.  `The Arvados user
55 documentation
56 <http://doc.arvados.org/user/reference/api-tokens.html>`_ describes
57 how to find this information in the Arvados Workbench, and install it
58 on your system.
59
60 Testing and Development
61 -----------------------
62
63 This package is one part of the Arvados source package, and it has
64 integration tests to check interoperability with other Arvados
65 components.  Our `hacking guide
66 <https://arvados.org/projects/arvados/wiki/Hacking_Python_SDK>`_
67 describes how to set up a development environment and run tests.