aioscaleway 0.1.0__tar.gz

aioscaleway-0.1.0/.github/workflows/pull-request.yml

@@ -0,0 +1,68 @@
+name: Pull request
+
+on:
+  pull_request:
+    branches: [development]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  UV_FROZEN: "1"
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          version: "0.13.4"
+          enable-cache: true
+
+      - name: Install the project
+        run: uv sync
+
+      - name: Lint
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Check the generated code matches the specs
+        run: |
+          uv run python scripts/generate.py
+          git diff --exit-code -- src docs
+
+      - name: Type check
+        run: uv run mypy
+
+      - name: Test
+        run: uv run pytest -q
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          version: "0.13.4"
+          enable-cache: true
+
+      - name: Build the documentation site
+        run: |
+          uv sync --group docs
+          uv run zensical build --clean

aioscaleway-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,59 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+env:
+  UV_FROZEN: "1"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    # PyPI trusts this workflow over OIDC, so no token is stored; the pypi
+    # environment waits for a reviewer, since an upload cannot be taken back
+    environment:
+      name: pypi
+      url: https://pypi.org/project/aioscaleway/
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          version: "0.13.4"
+          enable-cache: true
+
+      - name: Check the tag matches the declared version
+        run: test "v$(uv version --short)" = "$GITHUB_REF_NAME"
+
+      - name: Install the project
+        run: uv sync
+
+      - name: Lint
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Check the generated code matches the specs
+        run: |
+          uv run python scripts/generate.py
+          git diff --exit-code -- src docs
+
+      - name: Type check
+        run: uv run mypy
+
+      - name: Test
+        run: uv run pytest -q
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

aioscaleway-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Profiler output
+gmon.out
+
+# Documentation site build
+site/
+.cache/
+.claude/

aioscaleway-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

aioscaleway-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+Notable changes to this project, newest first.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-11
+
+First version published on PyPI.
+
+### Added
+
+- `Scaleway`, the client, read from the `SCW_*` variables of the Scaleway CLI,
+  with `with_options()` to change defaults while sharing connections.
+- Business areas shared with aioovh: `compute`, `storage`, `network`,
+  `kubernetes`, `serverless`, `databases`, `analytics`, `messaging`, `ai`,
+  `iot`, `email`, `domains`, `web_hosting`, `observability`, `iam`,
+  `account`, `billing` and `orders`, covering the 59 API versions published
+  on the Scaleway developers website.
+- Collections iterated with `async for`, every page read, narrowed with
+  `filter()`, with `pages()` for the totals a page carries; references that act without loading and load when awaited;
+  loaded objects that are references too.
+- One method per action, including one per value of the Instance server
+  actions (`reboot()`, `power_off()`...).
+- Typed errors under `ScalewayAPIError`, retries with `stamina`, dates as
+  `whenever.Instant`, open enumerations, `Money.to_decimal()`.
+- `scw.raw`, the underlying HTTP client, for anything else.
+- Type information shipped with the package (`py.typed`).
+
+[Unreleased]: https://gitlab.com/businessagile/libraries/aioscaleway/-/compare/v0.1.0...development
+[0.1.0]: https://gitlab.com/businessagile/libraries/aioscaleway/-/tags/v0.1.0

aioscaleway-0.1.0/CITATION.cff

@@ -0,0 +1,24 @@
+cff-version: 1.2.0
+message: If you use aioscaleway in your work, please cite it as below.
+type: software
+title: aioscaleway
+abstract: Asynchronous, fully typed client for every Scaleway API, on httpx2 and pydantic.
+authors:
+  - given-names: Alexandre
+    family-names: BERREBI
+    email: alexandre.berrebi@businessagile.eu
+    affiliation: Business Agile
+    website: https://businessagile.eu/en/about
+version: 0.1.0
+date-released: 2026-11-11
+license: MIT
+url: https://aioscaleway.businessagile.eu
+repository-code: https://gitlab.com/businessagile/libraries/aioscaleway
+keywords:
+  - scaleway
+  - asyncio
+  - httpx
+  - pydantic
+  - sdk
+  - api
+  - cloud

aioscaleway-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,115 @@
+# Contributing
+
+## Issues and pull requests
+
+Report bugs, ask questions and propose changes on
+[GitHub](https://github.com/BiBzz/aioscaleway): [issues](https://github.com/BiBzz/aioscaleway/issues) and pull requests against `development`
+are welcome there, and your commits do not need to be signed.
+
+The code is reviewed and merged on
+[GitLab](https://gitlab.com/businessagile/libraries/aioscaleway), which mirrors
+itself to GitHub. A pull request is picked up into a GitLab merge request that
+links back to it, keeps you as the author of your commits, and runs the full
+CI. Once merged, the mirror brings the commits to GitHub, which marks the pull
+request as merged; if they had to be rebased, the pull request is closed with
+a link to the commit. Do not expect the GitHub merge button to work: only the
+mirror writes to `development`.
+
+## Setting up
+
+The project is managed with [uv](https://docs.astral.sh/uv/), 0.13 or later:
+
+```bash
+uv sync
+```
+
+It uses the interpreter in `.python-version`, the oldest version the library
+supports.
+
+## The checks
+
+These are the gates CI runs on every merge request on GitLab, and GitHub
+Actions on every pull request:
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run python scripts/generate.py && git diff --exit-code -- src docs
+uv run mypy
+uv run pytest -q
+```
+
+The tests run on Python 3.12, 3.13 and 3.14 in CI.
+
+## Generated code
+
+Everything under `src/aioscaleway/_operations/` and the area packages
+(`src/aioscaleway/compute/`...) is generated, as are `docs/objects.md` and
+`docs/coverage.md`; each generated file starts with a line saying so. Change
+the generators (`scripts/operations.py`, `scripts/objects.py`), the naming
+table (`mapping.yaml`) or the hand-written runtime (`src/aioscaleway/_*.py`),
+never the output, then regenerate:
+
+```bash
+uv run python scripts/generate.py
+```
+
+The generator stops on a name clash and says which entry of `mapping.yaml` to
+add. Read the diff of `docs/objects.md`: it is the public surface.
+
+To pick up what Scaleway changed in its APIs:
+
+```bash
+scripts/fetch_specs.sh
+```
+
+It downloads every OpenAPI file listed on the developers website and
+regenerates. Commit the specs and the generated code together, in a merge
+request of their own: its diff is the list of API changes.
+
+## Commits
+
+Work branches off `development`, the default branch, and lands through a
+merge request. Everything in the repository is written in English, and commit
+messages follow the Angular convention: `feat(client): ...`,
+`fix(generator): ...`, `docs: ...`. Maintainers sign their commits and tags.
+
+## The changelog
+
+Anything a user of the library would notice goes under `## [Unreleased]` in
+[CHANGELOG.md](CHANGELOG.md), in the merge request that changes the behaviour.
+The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## Releasing
+
+1. In a merge request, bump `version` in `pyproject.toml`, run `uv lock`, and
+   turn the `## [Unreleased]` section into the release:
+
+   ```bash
+   python3 scripts/roll_changelog.py 0.2.0
+   ```
+
+2. Once it is merged, from an up to date `development`:
+
+   ```bash
+   scripts/release.sh
+   ```
+
+   It checks the tree matches `origin`, the commit is signed and the
+   changelog has the section, replays the checks, signs the `v0.2.0` tag with
+   the changelog entry as its message, and pushes it after asking.
+
+3. The GitLab mirror carries the tag to GitHub, where the `Release` workflow
+   checks the tag matches the version, replays the checks, then waits for a
+   reviewer to approve the `pypi` environment. Approving it is the point of no
+   return: a version on PyPI can be yanked, but its files can never be uploaded
+   again. The workflow builds the wheel and the sdist and uploads them with
+   PyPI trusted publishing, so no token is stored anywhere.
+
+### What PyPI trusts
+
+The trusted publisher declared on PyPI for `aioscaleway` is the GitHub repository
+`BiBzz/aioscaleway`, workflow `release.yml`, environment `pypi`. Renaming the
+repository, the workflow or the environment breaks the upload until the
+publisher is updated on PyPI. Tags matching `v*` are protected on GitLab, and
+on GitHub only the mirror may create them.

aioscaleway-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandre BERREBI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aioscaleway-0.1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.5
+Name: aioscaleway
+Version: 0.1.0
+Summary: Asynchronous, fully typed client for every Scaleway API, on httpx2 and pydantic
+Project-URL: Homepage, https://aioscaleway.businessagile.eu
+Project-URL: Documentation, https://aioscaleway.businessagile.eu
+Project-URL: Repository, https://gitlab.com/businessagile/libraries/aioscaleway
+Project-URL: Mirror, https://github.com/BiBzz/aioscaleway
+Project-URL: Issues, https://github.com/BiBzz/aioscaleway/issues
+Project-URL: Changelog, https://gitlab.com/businessagile/libraries/aioscaleway/-/blob/development/CHANGELOG.md
+Author-email: Alexandre BERREBI <alexandre.berrebi@businessagile.eu>
+Maintainer-email: Business Agile <contact@businessagile.eu>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,asyncio,cloud,httpx,pydantic,scaleway,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx2>=2.16.0
+Requires-Dist: pydantic-settings>=2.16.0
+Requires-Dist: pydantic>=2.14.1
+Requires-Dist: stamina>=26.1.0
+Requires-Dist: whenever>=0.11.0
+Description-Content-Type: text/markdown
+
+# aioscaleway
+
+Asynchronous, fully typed Python client for every
+[Scaleway API](https://www.scaleway.com/en/developers/api/), built on
+[httpx2](https://pypi.org/project/httpx2/), [pydantic](https://docs.pydantic.dev/)
+and [whenever](https://whenever.readthedocs.io/).
+
+**Documentation**: https://aioscaleway.businessagile.eu
+
+```python
+from aioscaleway import Scaleway
+
+async with Scaleway() as scw:  # SCW_* from the environment
+    server = await scw.compute.servers(server_id)  # load
+    print(server.name, server.state)
+    await server.reboot()
+
+    async for server in scw.compute.servers.filter(name="web"):
+        await server.power_off()
+
+    async for line in scw.billing.consumptions.filter(billing_period="2026-10"):
+        print(line.sku, line.value.to_decimal() if line.value else 0)
+```
+
+## Why it exists
+
+The official SDK, `scaleway` and `scaleway-async`, sends its requests through
+`requests`: the `async def` methods of `scaleway-async` block the event loop
+while they wait. It also mirrors the API's own layout, one class per product
+and version (`InstanceV1API`, `BillingV2Beta1API`) with flat methods.
+
+`aioscaleway` is asynchronous down to the socket and organised around what you
+manipulate rather than where Scaleway files it:
+
+- **business areas** shared with its sibling [aioovh](https://pypi.org/project/aioovh/):
+  `compute`, `storage`, `network`, `kubernetes`, `databases`, `billing`...;
+- **collections** you iterate with `async for`, narrowed with `filter()`, every
+  page read for you;
+- **references** (`scw.compute.servers(server_id)`) that act without a
+  request to read them first, and that `await` loads;
+- **objects** that are references too, with typed fields;
+- **one method per action**: `server.reboot()`, `server.power_off()`,
+  `server.attach_volume(volume_id=volume)`;
+- **no API version in any name**: the library picks the latest stable version
+  of each API, else the latest preview, and says so in the docstring.
+
+Everything is generated from the OpenAPI files Scaleway publishes, committed in
+[`specs/`](specs/): 59 API versions and about 1,500 operations. Every
+operation is reachable, either through the objects or through `scw.raw`, and
+[`docs/coverage.md`](docs/coverage.md) says where.
+
+## Installation
+
+```bash
+uv add aioscaleway
+```
+
+Python 3.12 or later.
+
+## Usage
+
+### Client
+
+```python
+scw = Scaleway(
+    secret_key="...",
+    default_region="fr-par",
+    default_zone="fr-par-1",
+    default_project_id="...",
+)
+nl = scw.with_options(default_zone="nl-ams-1")  # same connections, other defaults
+```
+
+Every value left out is read from the variables of the Scaleway CLI
+(`SCW_SECRET_KEY`, `SCW_DEFAULT_REGION`, `SCW_DEFAULT_ZONE`,
+`SCW_DEFAULT_PROJECT_ID`, `SCW_DEFAULT_ORGANIZATION_ID`, `SCW_API_URL`).
+Use it as an async context manager, or call `await scw.aclose()`.
+
+### Collections, references, objects
+
+| You write | You get | Requests |
+| --- | --- | --- |
+| `scw.compute.servers` | a collection | none |
+| `scw.compute.servers.filter(name="web")` | the same collection, narrowed | none |
+| `async for s in scw.compute.servers` | loaded objects | one per page |
+| `scw.compute.servers(server_id)` | a reference | none |
+| `await scw.compute.servers(server_id)` | a loaded object | one |
+| `await scw.compute.servers(server_id).reboot()` | the action's result | one |
+| `await scw.compute.servers.create(name=..., commercial_type=...)` | the created object | one |
+
+`pages()` yields each page response instead, for the totals and sums an item
+does not carry (`page.total_discount_untaxed_value` of the billing
+consumptions).
+
+A loaded object is also a reference: anything that takes a reference takes an
+object. It cannot load itself when printed or read, because those are
+synchronous; mypy flags a field read on a bare reference. `repr()` tells which
+one you hold.
+
+Sub-resources hang off their parent:
+
+```python
+async for pool in scw.kubernetes.clusters(cluster_id).pools:
+    print(pool.name, pool.size)
+async for nic in scw.compute.servers(server_id).nics:
+    ...
+```
+
+A resource with a zone or a region takes it as a keyword
+(`scw.compute.servers(server_id, zone="nl-ams-1")`,
+`servers.filter(zone="nl-ams-1")`), defaulting to the client's.
+
+### Types
+
+Arguments and fields are typed. Enumerations and nested models of an area live
+in its `types` module:
+
+```python
+from aioscaleway.compute.types import ServerState, BootType
+```
+
+Dates are `whenever.Instant`, amounts `Money` (`.to_decimal()`).
+Enumerations are open: a value Scaleway adds later is accepted instead of
+failing the response.
+
+### Errors
+
+```python
+from aioscaleway import ResourceNotFoundError, ScalewayAPIError
+
+try:
+    await scw.compute.servers(server_id)
+except ResourceNotFoundError:
+    ...
+except ScalewayAPIError as error:
+    print(error.status_code, error.type, error.message)
+```
+
+`ScalewayTransportError` reports a request that got no answer. Throttling and
+transient failures are retried with [stamina](https://stamina.hynek.me/),
+honouring `Retry-After`; a `POST` is only retried when Scaleway cannot have
+processed it.
+
+### The raw layer
+
+`scw.raw` is the underlying client, for a call the objects do not cover:
+
+```python
+await scw.raw.request_json("GET", "/instance/v1/zones/fr-par-1/dashboard")
+```
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and
+[docs/architecture.md](docs/architecture.md). The full object tree is in
+[docs/objects.md](docs/objects.md).
+
+The source lives on
+[GitLab](https://gitlab.com/businessagile/libraries/aioscaleway), mirrored to
+[GitHub](https://github.com/BiBzz/aioscaleway), where
+[issues](https://github.com/BiBzz/aioscaleway/issues) and pull requests are welcome.
+
+## Author
+
+Created by [Alexandre BERREBI](https://businessagile.eu/en/about), maintained by
+[Business Agile](https://businessagile.eu).
+
+## License
+
+MIT, see [LICENSE](LICENSE).