osc_sdk_python 0.39.2__py3-none-any.whl

osc_sdk_python/retry.py

@@ -0,0 +1,138 @@
+import requests
+import time
+import random
+from requests.exceptions import JSONDecodeError
+from .problem import ProblemDecoder, LegacyProblemDecoder, LegacyProblem, Problem
+
+MAX_RETRIES = 3
+RETRY_BACKOFF_FACTOR = 1.0
+RETRY_BACKOFF_JITTER = 3.0
+RETRY_BACKOFF_MAX = 30.0
+
+
+class Retry:
+    """
+    Hold a request attempt and try to execute it
+    """
+
+    def __init__(self, session: requests.Session, method: str, url: str, **kwargs):
+        self.session = session
+        self.method: str = method
+        self.url: str = url
+        self.request_kwargs = kwargs
+
+        # Extract all retry parameters
+        self.attempt: int = int(self.request_kwargs.pop("attempt", 0))
+        self.max_retries: int = int(
+            self.request_kwargs.get("max_retries", MAX_RETRIES)
+        )
+        self.backoff_factor: float = float(
+            self.request_kwargs.get("backoff_factor", RETRY_BACKOFF_FACTOR)
+        )
+        self.backoff_jitter: float = float(
+            self.request_kwargs.get("backoff_jitter", RETRY_BACKOFF_JITTER)
+        )
+        self.backoff_max: float = float(
+            self.request_kwargs.get("backoff_max", RETRY_BACKOFF_MAX)
+        )
+
+    def execute_once(self) -> requests.Response:
+        """
+        Execute the request without retry
+        """
+        return self.session.request(self.method, self.url, **self.request_kwargs)
+
+    def increment(self) -> "Retry":
+        """
+        Return a copy of the retry with an incremented attempt count
+        """
+        new_kwargs = self.request_kwargs.copy()
+        new_kwargs["attempt"] = self.attempt + 1
+        return Retry(self.session, self.method, self.url, **new_kwargs)
+
+    def should_retry(self, e: requests.exceptions.RequestException) -> bool:
+        if isinstance(e, requests.exceptions.TooManyRedirects):
+            return False
+
+        if isinstance(e, requests.exceptions.URLRequired):
+            return False
+
+        if isinstance(e, ValueError):
+            # can be raised on bogus request
+            return False
+
+        if e.response is not None:
+            if 400 <= e.response.status_code < 500 and e.response.status_code != 429:
+                return False
+
+        return self.attempt < self.max_retries
+
+    def get_backoff_time(self) -> float:
+        """
+        {backoff factor} * (2 ** ({number of previous retries}))
+        random.uniform(0, {backoff jitter})
+        """
+
+        backoff: float = self.backoff_factor * (2**self.attempt)
+        backoff += random.uniform(0, self.backoff_jitter)
+        return min(backoff, self.backoff_max)
+
+    def execute(self) -> requests.Response:
+        try:
+            res = self.execute_once()
+            raise_for_status(res)
+            return res
+        except requests.exceptions.RequestException as e:
+            if self.should_retry(e):
+                sleep_time = self.get_backoff_time()
+                time.sleep(sleep_time)
+                return self.increment().execute()
+            else:
+                raise e
+
+
+def raise_for_status(response: requests.Response):
+    http_error_msg = ""
+    problem = None
+    reason = get_default_reason(response)
+
+    try:
+        ct = response.headers.get("content-type") or ""
+        if "application/json" in ct:
+            problem = response.json(cls=LegacyProblemDecoder)
+            problem.status = problem.status or str(response.status_code)
+            problem.url = response.url
+        elif "application/problem+json" in ct:
+            problem = response.json(cls=ProblemDecoder)
+            problem.status = problem.status or str(response.status_code)
+    except JSONDecodeError:
+        pass
+    else:
+        if 400 <= response.status_code < 500:
+            if isinstance(problem, LegacyProblem) or isinstance(problem, Problem):
+                http_error_msg = f"Client Error --> {problem.msg()}"
+            else:
+                http_error_msg = f"{response.status_code} Client Error: {reason} for url: {response.url}"
+
+        elif 500 <= response.status_code < 600:
+            if isinstance(problem, LegacyProblem) or isinstance(problem, Problem):
+                http_error_msg = f"Server Error --> {problem.msg()}"
+            else:
+                http_error_msg = f"{response.status_code} Server Error: {reason} for url: {response.url}"
+
+        if http_error_msg:
+            raise requests.HTTPError(http_error_msg, response=response)
+
+
+def get_default_reason(response):
+    if isinstance(response.reason, bytes):
+        # We attempt to decode utf-8 first because some servers
+        # choose to localize their reason strings. If the string
+        # isn't utf-8, we fall back to iso-8859-1 for all other
+        # encodings. (See PR #3538)
+        try:
+            return response.reason.decode("utf-8")
+        except UnicodeDecodeError:
+            return response.reason.decode("iso-8859-1")
+    else:
+        return response.reason

osc_sdk_python/version.py

@@ -0,0 +1,7 @@
+import os
+
+
+def get_version() -> str:
+    osc_sdk_python_path = os.path.dirname(os.path.abspath(__file__))
+    with open(os.path.join(osc_sdk_python_path, "VERSION"), "r") as fd:
+        return fd.read().strip()

osc_sdk_python-0.39.2.dist-info/METADATA

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: osc_sdk_python
+Version: 0.39.2
+Summary: Outscale Gateway python SDK
+Project-URL: Homepage, https://github.com/outscale/osc-sdk-python
+Author-email: Outscal SAS <opensource@outscale.com>
+License: BSD
+License-File: LICENSE
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.20.0
+Requires-Dist: ruamel-yaml==0.19.1
+Requires-Dist: urllib3>=2.6.3
+Description-Content-Type: text/markdown
+
+[![Project Graduated](https://docs.outscale.com/fr/userguide/_images/Project-Graduated-green.svg)](https://docs.outscale.com/en/userguide/Open-Source-Projects.html) [![](https://dcbadge.limes.pink/api/server/HUVtY5gT6s?style=flat&theme=default-inverted)](https://discord.gg/HUVtY5gT6s)
+
+# Outscale Python SDK
+
+<p align="center">
+  <img alt="Outscale Python SDK" src="https://img.icons8.com/?size=100&id=2866&format=png&color=000000" width="100px">
+</p>
+
+---
+
+## 🌐 Links
+
+- Documentation: <https://docs.outscale.com/api.html?python#3ds-outscale-api>
+- Project repository: <https://github.com/outscale/osc-sdk-python>
+- Outscale website: <https://outscale.com/>
+- Join our community on [Discord](https://discord.gg/HUVtY5gT6s)
+
+---
+
+## 📄 Table of Contents
+
+- [Overview](#-overview)
+- [Requirements](#-requirements)
+- [Installation](#-installation)
+- [Configuration](#-configuration)
+- [Usage](#-usage)
+- [Examples](#-examples)
+- [Known Issues & Troubleshooting](#-known-issues--troubleshooting)
+- [License](#-license)
+- [Contributing](#-contributing)
+
+---
+
+## 🧭 Overview
+
+**Outscale Python SDK** (`osc-sdk-python`) is the official Python SDK to interact with the [OUTSCALE API](https://docs.outscale.com/api.html?python#3ds-outscale-api).
+
+It allows you to:
+
+- Configure multiple profiles through environment variables or credential files.
+- Customize retry and rate-limit behavior.
+- Enable detailed logging of requests and responses.
+
+You will need an Outscale account and API credentials. If you do not have one yet, please visit the [Outscale website](https://outscale.com/).
+
+---
+
+## ✅ Requirements
+
+- Python 3.x
+- `pip` (Python package manager)
+- Access to the OUTSCALE API (valid access key / secret key or basic auth)
+- Network access to the Outscale API endpoints
+
+---
+
+## ⚙ Installation
+
+### Option 1: Install from PyPI
+
+Install the pre-built Python package:
+
+```bash
+pip install osc-sdk-python
+````
+
+### Option 2: Install from source
+
+Clone the repository and build the package:
+
+```bash
+git clone https://github.com/outscale/osc-sdk-python.git
+cd osc-sdk-python
+make package
+```
+
+Then install the built wheel:
+
+```bash
+pip install dist/osc_sdk_python-0.39.2-py3-none-any.whl
+```
+
+---
+
+## 🛠 Configuration
+
+When you use the SDK, you can choose a **profile**. Profiles can be defined via **environment variables** or in a **credentials file**.
+Environment variables take precedence over files.
+
+In the credentials file, you can set a default profile named `default`. It will be used if you do not explicitly specify a profile.
+
+### Environment variables
+
+The SDK understands the following environment variables:
+
+```bash
+export OSC_PROFILE=<PROFILE>            # default: "default"
+
+# or explicit credentials:
+export OSC_ACCESS_KEY=<ACCESS_KEY>
+export OSC_SECRET_KEY=<SECRET_KEY>
+
+# optional:
+export OSC_REGION=<REGION>              # default: eu-west-2
+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
+```
+
+### Credentials files
+
+By default, the SDK looks for a JSON configuration file at `~/.osc/config.json`.
+
+Example:
+
+```json
+{
+  "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>"
+  }
+}
+```
+
+Notes:
+
+* If `~/.osc/config.json` is not found, `~/.oapi_credentials` will be used as a fallback.
+* Environment variables have priority over credentials files.
+
+### Basic Authentication
+
+You can also use `osc-sdk-python` with **basic authentication** using your account email and password.
+Note that some API calls may be blocked with this method. See the [authentication documentation](https://docs.outscale.com/api#authentication) for more details.
+
+Example:
+
+```python
+from osc_sdk_python import Gateway
+
+with Gateway(email="your@email.com", password="yourAccountPassword") as gw:
+    keys = gw.ReadAccessKeys()
+```
+
+### Retry Options
+
+The following options can be provided when initializing the `Gateway` to customize the retry behavior of the SDK:
+
+* `max_retries` (integer, default `3`)
+* `retry_backoff_factor` (float, default `1.0`)
+* `retry_backoff_jitter` (float, default `3.0`)
+* `retry_backoff_max` (float, default `30`)
+
+These correspond to their counterparts in [`urllib3.util.Retry`](https://urllib3.readthedocs.io/en/stable/reference/urllib3.util.html#urllib3.util.Retry).
+
+Example:
+
+```python
+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,
+)
+```
+
+### Rate Limit Options
+
+You can also configure rate limiting when initializing the `Gateway`:
+
+* `limiter_max_requests` (integer, default `5`)
+* `limiter_window` (integer, default `1`)
+
+Example:
+
+```python
+from osc_sdk_python import Gateway
+
+gw = Gateway(
+    limiter_max_requests=20,
+    limiter_window=5,
+)
+```
+
+More usage patterns and logging examples are documented in:
+
+* [docs/examples.md](docs/examples.md)
+
+---
+
+## 🧪 Examples
+
+Some example topics covered in `docs/examples.md`:
+
+* Listing VMs and volumes
+* Using profiles and regions
+* Raw calls with `gw.raw("ActionName", **params)`
+* Enabling and reading logs
+
+---
+
+## 🧩 Known Issues & Troubleshooting
+
+Common issues (such as UTF-8 / locale errors when reading the API spec) and their workarounds are documented in:
+
+* [docs/troubleshooting.md](docs/troubleshooting.md)
+
+---
+
+## 📜 License
+
+**Outscale Python SDK** is released under the BSD-3-Clause.
+
+© 2025 OUTSCALE SAS
+
+See [LICENSE](./LICENSE) for full details.
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions!
+
+Please read our [Contributing Guidelines](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) before submitting a pull request.

osc_sdk_python-0.39.2.dist-info/RECORD

@@ -0,0 +1,17 @@
+osc_sdk_python/VERSION,sha256=HK3l2Xm_A7QsVN4d-o0_r11-a8uYN5Dy9Cfyem1B3BQ,7
+osc_sdk_python/__init__.py,sha256=kAIzZAGD6A--uVJObIdSlFRG3MdCt_30SmE-bMt1uyk,766
+osc_sdk_python/authentication.py,sha256=FKcLo9GPjFPGswqFkxBUDbjxTGaHQFPImLiUj0PJK4U,6571
+osc_sdk_python/call.py,sha256=Ed0ROJC1ORxz-lOgiZFCkBzEs7i0ov6GYGDrr2PVsOY,3290
+osc_sdk_python/credentials.py,sha256=98Y0WD81jPOzYRg6WurMO-iyk-dBET5tFNzEFV9sb3s,7202
+osc_sdk_python/limiter.py,sha256=udIFlBeXFGabF7YkWLiJsDMmyQfYlglJo_-EEwQm-GQ,913
+osc_sdk_python/outscale_gateway.py,sha256=xF324XYX2s3b1YrN1_PO5iypJn26fHXMiuKwN5J3lx8,9971
+osc_sdk_python/problem.py,sha256=ScgRAK79yrhZFb1WUIVnt9c6byygnQyqZTp5S5heYO0,3095
+osc_sdk_python/requester.py,sha256=7LPCNzw0qq-alJJVHw-07C27jGw3XO9Ioq2hwaNgbm8,914
+osc_sdk_python/retry.py,sha256=5y1sK8kSjylh0yoMZrhL-aqNTikf1J_isSkyHs4lgL4,4893
+osc_sdk_python/version.py,sha256=R1dZvsRZ0qORIvX1l2RMZjrwCSF9MuM1nzvVCZb8aU0,212
+osc_sdk_python/resources/gateway_errors.yaml,sha256=7RbhfR_u_VCN9gln-_OxIoOve3nI31M94glycMb8b3M,24496
+osc_sdk_python/resources/outscale.yaml,sha256=hlBUZMTJEWCgdQsCkxi_vJUNzdFIaOZ6Gt8dABa42Zg,962417
+osc_sdk_python-0.39.2.dist-info/METADATA,sha256=QOxGUuYHmm3YWlDlIpZYnqjXn7SuCiJAtIp5Bo-7IQA,6835
+osc_sdk_python-0.39.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+osc_sdk_python-0.39.2.dist-info/licenses/LICENSE,sha256=eAtKefmWuj4G96ORsmNbY1PqGZj2sx5SkgiNYL5LocU,1512
+osc_sdk_python-0.39.2.dist-info/RECORD,,

osc_sdk_python-0.39.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

osc_sdk_python-0.39.2.dist-info/licenses/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2019, Outscale SAS
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.