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.  However,
  26 other users on the same system will need to reconfigure their shell in order
  27 to be able to use it. Run the following to install the package in an
  28 environment at ``~/arvclients``::
  29
  30   python3 -m venv ~/arvclients
  31   ~/arvclients/bin/pip install arvados-python-client
  32
  33 Command line tools will be installed under ``~/arvclients/bin``. You can
  34 test one by running::
  35
  36   ~/arvclients/bin/arv-get --version
  37
  38 You can run these tools by specifying the full path every time, or you can
  39 add the directory to your shell's search path by running::
  40
  41   export PATH="$PATH:$HOME/arvclients/bin"
  42
  43 You can make this search path change permanent by adding this command to
  44 your shell's configuration, for example ``~/.bashrc`` if you're using bash.
  45 You can test the change by running::
  46
  47   arv-get --version
  48
  49 Installing on Debian and Ubuntu systems
  50 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  51
  52 Arvados publishes packages for Debian 11 "bullseye," Debian 12 "bookworm," Ubuntu 20.04 "focal," and Ubuntu 22.04 "jammy." You can install the Python SDK package on any of these distributions by running the following commands::
  53
  54   sudo install -d /etc/apt/keyrings
  55   sudo curl -fsSL -o /etc/apt/keyrings/arvados.asc https://apt.arvados.org/pubkey.gpg
  56   sudo tee /etc/apt/sources.list.d/arvados.sources >/dev/null <<EOF
  57   Types: deb
  58   URIs: https://apt.arvados.org/$(lsb_release -cs)
  59   Suites: $(lsb_release -cs)
  60   Components: main
  61   Signed-by: /etc/apt/keyrings/arvados.asc
  62   EOF
  63   sudo apt update
  64   sudo apt install python3-arvados-python-client
  65
  66 Installing on Red Hat, AlmaLinux, and Rocky Linux
  67 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  68
  69 Arvados publishes packages for RHEL 8 and distributions based on it. Note that these packages depend on, and will automatically enable, the Python 3.9 module. You can install the Python SDK package on any of these distributions by running the following commands::
  70
  71   sudo tee /etc/yum.repos.d/arvados.repo >/dev/null <<EOF
  72   [arvados]
  73   name=Arvados
  74   baseurl=http://rpm.arvados.org/CentOS/\$releasever/os/\$basearch/
  75   gpgcheck=1
  76   gpgkey=http://rpm.arvados.org/CentOS/RPM-GPG-KEY-arvados
  77   EOF
  78   sudo dnf install python3-arvados-python-client
  79
  80 Configuration
  81 -------------
  82
  83 This client software needs two pieces of information to connect to
  84 Arvados: the DNS name of the API server, and an API authorization
  85 token. `The Arvados user
  86 documentation
  87 <http://doc.arvados.org/user/reference/api-tokens.html>`_ describes
  88 how to find this information in the Arvados Workbench, and install it
  89 on your system.
  90
  91 Testing and Development
  92 -----------------------
  93
  94 This package is one part of the Arvados source package, and it has
  95 integration tests to check interoperability with other Arvados
  96 components.  Our `hacking guide
  97 <https://dev.arvados.org/projects/arvados/wiki/Hacking_Python_SDK>`_
  98 describes how to set up a development environment and run tests.