# Laurent's API examples for Aspera using Python

Tested with Python3 on macOS.

This project provides code examples to use some IBM Aspera APIs and transfer files for various IBM Aspera products using python.

The sample code in `src` shows how to transfer files using:

* IBM Aspera HSTS using SSH credentials
* IBM Aspera HSTS or Shares using Node credentials, using transfer spec v1 or v2
* IBM Cloud Object Storage (COS) using IBM Cloud service credentials
* IBM Aspera Faspex 4 and 5
* IBM Aspera on Cloud using JWT and a private key

## Requirements

### Unix-like

* GNU make
* Python 3.11 +

### Windows

Install python 3.11: <https://www.python.org/downloads/windows/>

## Quick start

To run all python sample programs at once, in this folder execute:

```bash
make
```

This will run sample programs with sample files using servers as configured in the config file.

If you prefer to test a single application, you may configure only the appropriate section in the config file.
Have a look to the [`Makefile`](Makefile) to check how the example is invoked and execute just the example relevant to you.
Then run only one example, to test `node`:

```bash
make .tested/node
```

> **Note:** If the daemon does not start, you make first try to stop it: `make stop`, and then run the sample again.

By default, gRPC client source files `transfer_pb2.py` and `transfer_pb2_grpc.py` are generated by compilation of `transfer.proto`.
Alternatively, it's possible to get those file from the SDK: edit Makefile and comment out the line `PY_GRPC_SDK_DIR=`.

## Required external components

When `make` is invoked (Quick Start), it will check and install required python modules.

Check the [`Makefile`](Makefile) for details.

## SDK Selection

The examples use the current Aspera SDK: [Transfer SDK](https://developer.ibm.com/apis/catalog?search=%22aspera%20transfer%20sdk%22).
It **shall be used** for new developments.

The legacy [FASPManager API](https://developer.ibm.com/apis/catalog?search=%22fasp%20manager%20sdk%22) is now deprecated and shall not be used for new developments. (`faspmanager`)
An adapter is kept for reference, but should not be used.

## Structure of examples

Each of the sample programs are structured like this:

* `import utils.tools` : `tools.py` is located in folder `src/utils` and provides utility functions
* `import utils.transfer_client` : `transfer_client.py` is located in folder `src/utils`:
  * `test_env = utils.transfer_client.TransferClient()`
  * it reads the configuration file
  * setup debug logging
  * defines the method: `start_transfer_and_wait` which takes a **transfer_spec** as argument to start a transfer.
* get configuration, urls, username, credentials, secrets, from transfer_client.CONFIG
* call application API to build a **transfer_spec**
* call `start_transfer_and_wait` with this **transfer_spec** to start a transfer

## Known Transfer SDK Issues

Transfer fails if `http_fallback` is `True`.

## COS official documentation for Aspera SDK

<https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-aspera>

Uncomment lines in `cos.py` to use service credential file instead of individual parameters.
