# Installing the Reven Python API on a client workstation

To install the Reven Python API on a client workstation, you will need to download the corresponding archive from the Download
page of the Project Manager.
Choose the package corresponding to the desired OS and Python version.

The following sections assume that you are working from the root directory of the decompressed archive.

## Pre-requisites

The supported platforms for installing the Reven Python API are Debian 10 Buster 64-bit and Windows 10 64-bit. A
working 3.7 (CPython) installation is also required.

**NOTE-1:** For Debian, other dependencies will be installed over the course of this document and can be found in the
`dependencies.sh` file.

## Main installation options

Python development provides many ways of installing a Python package. This document covers the main installation
options.

* Using a **virtualenv**:
A local installation that won't conflict with any other Python environment in your system. This is the most recommended
way to make Python development, since it will guarantee that you won't break any existing Python script by accidentally
upgrading a common dependency.
On Debian 10 Buster, we provide a `sourceme` bash script that automatically creates a virtualenv containing the Reven
Python API for you.
For a virtualenv installation under Windows, you will first need to activate a virtualenv and then use `pip` normally
during the next section.

* A **user-wide** installation:
This installation does not conflict with other users on the system, but you may have to manually setup the environment
for your Python packages to be found.
For a user-wide installation, you'll need to use `pip` with a `--user` option after the `install` argument during the next section.

* A **system-wide** installation:
This installation may conflict with other users or applications on the system, and requires root privileges.
But after a system-wide installation, any user on the system will be able to use the Reven Python API.
For a system-wide installation, you will need to use `pip` with `root` privilege on Debian Buster (`sudo` for example), and
normally on Windows during the next section.


## On Windows

First, be sure to have a 64-bit 3.7 installation available with the `pip` utility installed. The default Python
installer typically provides this component. 

**NOTE:** the Reven python API is **not** compatible with a 32-bit python environment.

* Step 1 (optional): create the virtualenv
  The following Powershell lines will provide you with a virtualenv named `env` in your current working directory.
```powershell
python.exe -m pip install virtualenv  # Not required if you already have virtualenv installed
python.exe -m virtualenv --system-site-packages env
env\Scripts\activate
```

* Step 2 (required): upgrade  the `pip` utility
```powershell
python.exe -m pip install --upgrade pip
```

* Step 3 (required): install the Reven API
  Paths are given relative to this current folder.
```powershell
python.exe -m pip install (Get-Item dependencies\*.whl).FullName
python.exe -m pip install (Get-Item reven_api*.whl).FullName
python.exe -m pip install (Get-Item reven2*.whl).FullName
```

## On Debian 10 Buster

For a Debian 10 Buster client, the recommended way to use the Python API is to simply source the `sourceme` file
contained in the downloaded archive:

* Step 1 (required): install the system dependencies
  Paths are given relative to this current folder.
```bash
sudo ./dependencies.sh
```

* Step 2: source the `sourceme` file
```bash
source sourceme
```

This will leave in a virtual environment where `reven2` can be imported:

```bash
python -c "import reven2"
```

Note that the `sourceme` file is a **bash** script and may not work as intended when
sourced from different shells (`fish`, `zsh`...).

## On Debian 10 Buster, manual installation

If you prefer installing in your own virtualenv, or as user or system-wide, follow the instructions below.

First, be sure to have a Python installation available with the corresponding `pip` utility installed.

* Step 1 (required): install the system dependencies
  Paths are given relative to this current folder.
```bash
sudo ./dependencies.sh
```

* Step 2 (optional): create the virtualenv
```bash
sudo apt install python3-venv  # If venv is not already installed
python3 -m venv --system-site-packages env
source env/bin/activate
```

* Step 3 (required): upgrade the `pip` utility
```bash
python -m pip install --upgrade pip
```

* Step 4 (required): install the Reven API
  Paths are given relative to this current folder.
```bash
python -m pip install dependencies/*.whl
python -m pip install reven_api*.whl
python -m pip install reven2*.whl


## Other options

For other usage options, please refer to the full documentation available [online](https://doc.esreven.eshard.com) or in esReven.
