OUTSCALE Python SDK

The OUTSCALE Python SDK enables you to interact with the OUTSCALE API in Python development environments. It allows you to:

Configure multiple profiles using environment variables or the credentials file.
Customize retry and throttling behavior. For more information, see OUTSCALE API Throttling.
Enable detailed logging of requests and responses.

To use the OUTSCALE Python SDK, ensure that you have the following elements:

An OUTSCALE account to access the OUTSCALE API.
Network access to the OUTSCALE API endpoints of the desired Regions.

Installation

Before you begin: Make sure Python 3.10 or higher and pip are installed on your machine.

Install the OUTSCALE Python SDK from the PyPI package by running the following command in your terminal:

$ pip install osc-sdk-python

API Access Configuration

To use the OUTSCALE Python SDK, you can configure access to the OUTSCALE API with your access keys, or use basic authentication with your account email and password at initialization.

When accessing the OUTSCALE API with your account email and password, some API calls may be blocked. For more information, see the Authentication Schemes section in the OUTSCALE API documentation.

To configure access to the OUTSCALE API, you must configure a profile in a credentials file or set your access keys directly in the environment variables.

Environment variables have precedence over the credentials file. If access keys are set in the environment variables, the values set in the credentials file will be overridden.

Configuring API Access Using the Credentials File

You can set as many profiles as needed in the ~/.osc/config.json file using the following syntax:

Credentials file sample

{
  "default": {
    "access_key": "<ACCESS_KEY>",
    "secret_key": "<SECRET_KEY>",
    "region": "<REGION>"
  },
  "profile_1": {
    "access_key": "<ACCESS_KEY>",
    "secret_key": "<SECRET_KEY>",
    "region": "<REGION>"
  },
  "profile_2": {
    "access_key": "<ACCESS_KEY>",
    "secret_key": "<SECRET_KEY>",
    "region": "<REGION>"
  }
}

This file is shared with other OUTSCALE SDKs and CLIs, like oapi-cli.
If you haven’t previously created the ~/.osc/config.json file, you need to do so at this step.

You can choose which of those profiles acts as the default by setting its name in the environment variables using the following command:

$ export OSC_PROFILE=<PROFILE>            # default: "default"

Configuring API Access Using Environment Variables

You can set your access keys and Region directly in the environment variables using the following commands:

$ export OSC_ACCESS_KEY=<ACCESS_KEY>
$ export OSC_SECRET_KEY=<SECRET_KEY>
$ export OSC_REGION=<REGION>              # default: eu-west-2

Initialization

Initialization With a Profile

You can set up access to the OUTSCALE API with a profile when initializing the gateway using the following syntax:

from osc_sdk_python import Gateway

with Gateway(profile="profile_1") as gw:
    # Example: list VMs
    vms = gw.ReadVms()
    print(vms)

If you do not specify a profile, the default profile will be used.

from osc_sdk_python import Gateway

with Gateway() as gw:
    # Example: list VMs
    vms = gw.ReadVms()
    print(vms)

Initialization With Basic Authentication

You can set up access to the OUTSCALE API with basic authentication when initializing the gateway using the following syntax:

from osc_sdk_python import Gateway

with Gateway(email="your@email.com", password="yourAccountPassword") as gw:
    # Example: list VMs
    vms = gw.ReadVms()
    print(vms)

Examples

The OUTSCALE Python SDK supports two types of calling actions:

Typed methods such as gw.ReadVms() and gw.CreateVms(…)
Raw calls such as gw.raw("ReadVms") and gw.raw("CreateVms",…)

Customizing Retry Options

You can configure the retry behavior of the OUTSCALE Python SDK when initializing the gateway using the following syntax:

from osc_sdk_python import Gateway

gw = Gateway(
    max_retries=5,
    retry_backoff_factor=0.5,
    retry_backoff_jitter=1.0,
    retry_backoff_max=120,
)

This sample contains the following parameters that you can specify:

max_retries: The maximum number of retry attempts before the request fails (integer, by default 3).
retry_backoff_factor: The multiplier for the exponential backoff delay (float, by default 1.0).
retry_backoff_jitter: A value added to the delay to avoid all retries happening at the same time in multithreaded scenarios (float, by default 3.0).
retry_backoff_max: The maximum delay in seconds between retries (float, by default 30).

You can also set those parameters in the environment variables using the following commands:

$ export OSC_MAX_RETRIES=<INT>            # default: 3
$ export OSC_RETRY_BACKOFF_FACTOR=<FLOAT> # default: 1.0
$ export OSC_RETRY_BACKOFF_JITTER=<FLOAT> # default: 3.0
$ export OSC_RETRY_BACKOFF_MAX=<FLOAT>    # default: 30

Customizing Throttling Options

You can configure throttling when initializing the gateway using the following syntax:

from osc_sdk_python import Gateway

gw = Gateway(
    limiter_max_requests=20,
    limiter_window=5,
)

This sample contains the following parameters that you can specify:

limiter_max_requests: The maximum number of API calls possible in the given time window (integer, by default 5).
limiter_window: The time window, in seconds (integer, by default 1).

Listing all VM and Volume IDs

The following sample retrieves the IDs of all your VMs and volumes.

from osc_sdk_python import Gateway

if __name__ == "__main__":
    with Gateway() as gw:
        print("Your virtual machines:")
        for vm in gw.ReadVms()["Vms"]:
            print(vm["VmId"])

        print("\nYour volumes:")
        for volume in gw.ReadVolumes()["Volumes"]:
            print(volume["VolumeId"])

Enabling Logs

The following sample prints the log of the last request made to the API (here, ReadVms).

from osc_sdk_python import *

if __name__ == "__main__":
    with Gateway(profile="profile_1") as gw:
        # Prints logs in memory, standard output and standard error
        # Possible values for 'what' are LOG_KEEP_ONLY_LAST_REQ or LOG_ALL
        gw.log.config(type=LOG_MEMORY | LOG_STDIO | LOG_STDERR, what=LOG_KEEP_ONLY_LAST_REQ)

        result = gw.raw("ReadVms")

        last_request = gw.log.str()
        print(last_request)

Related Pages