vertracloud-api 0.1.0__tar.gz

vertracloud_api-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e .[dev]
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy src
+      - run: python -m pytest -q

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

@@ -0,0 +1,37 @@
+name: release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.rp.outputs.release_created }}
+    steps:
+      - id: rp
+        uses: googleapis/release-please-action@v4
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  publish:
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # trusted publishing no PyPI, sem token
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

vertracloud_api-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.venv
+__pycache__
+dist
+build
+*.egg-info
+.pytest_cache
+.mypy_cache
+.ruff_cache
+.env*
+# Local AI-agent guidance (never published)
+AGENTS.md
+AGENT.md
+CLAUDE.md
+.claude/

vertracloud_api-0.1.0/.release-please-manifest.json

@@ -0,0 +1 @@
+{".":"0.1.0"}

vertracloud_api-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 (2026-09-23)
+
+
+### Features
+
+* add apps, databases, snapshots, account, workspaces and billing resources ([9c67589](https://github.com/vertracloud/sdk-api-py/commit/9c6758937e20b4fadb4f413cadba2884868b6e14))
+* add HTTP transport and error types ([0ff9ac5](https://github.com/vertracloud/sdk-api-py/commit/0ff9ac5ef13235ab10d83d5e869235ec1f73bd36))
+* add SSE realtime log streaming ([753cd7f](https://github.com/vertracloud/sdk-api-py/commit/753cd7f0433539eb5f291a7f5b582ac1dc0c043a))
+
+## Changelog

vertracloud_api-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vertra Cloud
+
+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.

vertracloud_api-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.5
+Name: vertracloud-api
+Version: 0.1.0
+Summary: Official Python SDK for the public API of Vertra Cloud, a Brazilian application hosting platform (PaaS).
+Project-URL: Homepage, https://vertracloud.app
+Project-URL: Documentation, https://docs.vertracloud.app/sdks
+Project-URL: Repository, https://github.com/vertracloud/sdk-api-py
+Project-URL: Issues, https://github.com/vertracloud/sdk-api-py/issues
+Author: Vertra Cloud
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Vertra Cloud Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/vertracloud-api.svg)](https://pypi.org/project/vertracloud-api/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Official Python SDK for the [Vertra Cloud](https://vertracloud.app) public API: apps, databases, snapshots, account, workspaces and billing — one typed method per route.
+
+- Python 3.10+, fully typed (`py.typed`), with `TypedDict` payloads.
+- Zero dependencies outside the standard library.
+- No hidden retries, caching or state: errors come back as they happened.
+
+## Installation
+
+```bash
+pip install vertracloud-api
+```
+
+## Getting an API key
+
+Sign in to the [dashboard](https://vertracloud.app), open **Settings → API keys** and create a key with only the scopes your code needs (e.g. `apps:read`, `apps:write`). Keep it out of your source code — the examples read it from `VERTRA_API_KEY`.
+
+## Quick start
+
+```python
+import os
+
+from vertracloud import VertraClient
+
+client = VertraClient(api_key=os.environ["VERTRA_API_KEY"])
+
+me = client.account.get()
+print(f"Hi {me['name']}! Plan: {me['plan']['name']}")
+
+for app in me["applications"]:
+    print(app["id"], app["name"], app["status"])
+```
+
+## Documentation
+
+- Guide: [docs.vertracloud.app/sdks](https://docs.vertracloud.app/sdks)
+- API reference and scopes: [docs.vertracloud.app/api-reference](https://docs.vertracloud.app/api-reference/introduction)
+
+Every method has a docstring with its HTTP route and the API key scope it needs.
+
+## Usage
+
+### Client options
+
+```python
+client = VertraClient(
+    api_key=os.environ["VERTRA_API_KEY"],
+    timeout=10,  # seconds, default 30 per call
+    # base_url, user_agent and a custom transport are also accepted
+)
+```
+
+### Per-call options
+
+Methods on apps and databases take a keyword-only `workspace_id`; downloads, uploads and streams also take `timeout`:
+
+```python
+# Act on a resource that belongs to a workspace
+app = client.apps.get(app_id, workspace_id=workspace_id)
+
+# Give one slow call more time
+zip_bytes = client.apps.download(app_id, timeout=300)
+```
+
+Nested resources are attributes: `client.apps.deploys`, `client.apps.envs`, `client.workspaces.members`, `client.billing.orders`, …
+
+### Apps
+
+```python
+app = client.apps.get(app_id)
+
+client.apps.restart(app_id)  # normal restart
+client.apps.restart(app_id, {"reinstall_dependencies": True})
+
+metrics = client.apps.metrics(app_id, range="24h")
+logs = client.apps.logs(app_id)
+```
+
+### Uploading and downloading
+
+Uploads take `bytes`; downloads return `bytes`.
+
+```python
+with open("app.zip", "rb") as f:
+    app = client.apps.create({"name": "my-app", "memory": 512}, file=f.read())
+
+with open("backup.zip", "wb") as f:
+    f.write(client.apps.download(app_id))
+```
+
+`client.snapshots.download` works the same way.
+
+### Realtime logs (SSE)
+
+```python
+stream = client.apps.realtime(app_id)
+try:
+    for event in stream:
+        print(event.event, event.data)
+finally:
+    stream.close()
+```
+
+Stop the stream with `break` or `stream.close()`. Pass `since=` to resume. There is no automatic reconnection.
+
+### Errors
+
+Every non-2xx response raises a `VertraAPIError` carrying the HTTP `status`, the API `code` (e.g. `APP_NOT_FOUND`) and `details`; `str(err)` includes the message. The API key is never part of the error, even when it is printed:
+
+```python
+from vertracloud import NotFoundError, RateLimitError, VertraAPIError
+
+try:
+    client.apps.get(app_id)
+except NotFoundError:
+    ...  # 404
+except RateLimitError as err:
+    print("retry after", err.retry_after, "s")
+except VertraAPIError as err:
+    print(err.status, err.code, err)
+```
+
+Other subclasses: `AuthenticationError` (401), `ScopeDeniedError` (403 — including a missing key scope) and `ValidationError` (400/422). The error codes are listed in the [API reference](https://docs.vertracloud.app/api-reference/introduction).
+
+### Testing your code
+
+Pass your own `vertracloud.Transport` to the client to answer requests without touching the network:
+
+```python
+client = VertraClient(api_key="test", transport=my_fake_transport)
+```
+
+## Coverage
+
+| Domain | Resource | Routes |
+|---|---|---|
+| Apps | `client.apps` (+ `.deploys`, `.network`, `.envs`, `.files`) | 36 |
+| Databases | `client.databases` (+ `.credentials`) | 13 |
+| Snapshots | `client.snapshots` | 5 |
+| Account | `client.account` (+ `.sessions`, `.folders`, `.favorites`) | 10 |
+| Workspaces | `client.workspaces` (+ `.members`, `.roles`, `.invites`, `.action_requests`, `.apps`, `.databases`, `.folders`, `.favorites`) | 30 |
+| Billing | `client.billing` (+ `.orders`) | 5 |
+
+Dashboard-only features (activity log, notifications, API key management, the database **Data** tab, plan downgrade, creating workspace invites, transferring workspace ownership and approving action requests) are not part of the public API. See [what an API key cannot do](https://docs.vertracloud.app/sdks).
+
+## Versioning
+
+The SDK follows semantic versioning. Until `1.0.0`, minor releases may contain breaking changes; they are always called out in the [changelog](CHANGELOG.md).
+
+## Contributing
+
+Issues and pull requests are welcome. Before sending a change, run:
+
+```bash
+pip install -e ".[dev]"
+ruff check . && ruff format --check . && mypy src && python -m pytest -q
+```
+
+## License
+
+[MIT](LICENSE)

vertracloud_api-0.1.0/README.md

@@ -0,0 +1,165 @@
+# Vertra Cloud Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/vertracloud-api.svg)](https://pypi.org/project/vertracloud-api/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Official Python SDK for the [Vertra Cloud](https://vertracloud.app) public API: apps, databases, snapshots, account, workspaces and billing — one typed method per route.
+
+- Python 3.10+, fully typed (`py.typed`), with `TypedDict` payloads.
+- Zero dependencies outside the standard library.
+- No hidden retries, caching or state: errors come back as they happened.
+
+## Installation
+
+```bash
+pip install vertracloud-api
+```
+
+## Getting an API key
+
+Sign in to the [dashboard](https://vertracloud.app), open **Settings → API keys** and create a key with only the scopes your code needs (e.g. `apps:read`, `apps:write`). Keep it out of your source code — the examples read it from `VERTRA_API_KEY`.
+
+## Quick start
+
+```python
+import os
+
+from vertracloud import VertraClient
+
+client = VertraClient(api_key=os.environ["VERTRA_API_KEY"])
+
+me = client.account.get()
+print(f"Hi {me['name']}! Plan: {me['plan']['name']}")
+
+for app in me["applications"]:
+    print(app["id"], app["name"], app["status"])
+```
+
+## Documentation
+
+- Guide: [docs.vertracloud.app/sdks](https://docs.vertracloud.app/sdks)
+- API reference and scopes: [docs.vertracloud.app/api-reference](https://docs.vertracloud.app/api-reference/introduction)
+
+Every method has a docstring with its HTTP route and the API key scope it needs.
+
+## Usage
+
+### Client options
+
+```python
+client = VertraClient(
+    api_key=os.environ["VERTRA_API_KEY"],
+    timeout=10,  # seconds, default 30 per call
+    # base_url, user_agent and a custom transport are also accepted
+)
+```
+
+### Per-call options
+
+Methods on apps and databases take a keyword-only `workspace_id`; downloads, uploads and streams also take `timeout`:
+
+```python
+# Act on a resource that belongs to a workspace
+app = client.apps.get(app_id, workspace_id=workspace_id)
+
+# Give one slow call more time
+zip_bytes = client.apps.download(app_id, timeout=300)
+```
+
+Nested resources are attributes: `client.apps.deploys`, `client.apps.envs`, `client.workspaces.members`, `client.billing.orders`, …
+
+### Apps
+
+```python
+app = client.apps.get(app_id)
+
+client.apps.restart(app_id)  # normal restart
+client.apps.restart(app_id, {"reinstall_dependencies": True})
+
+metrics = client.apps.metrics(app_id, range="24h")
+logs = client.apps.logs(app_id)
+```
+
+### Uploading and downloading
+
+Uploads take `bytes`; downloads return `bytes`.
+
+```python
+with open("app.zip", "rb") as f:
+    app = client.apps.create({"name": "my-app", "memory": 512}, file=f.read())
+
+with open("backup.zip", "wb") as f:
+    f.write(client.apps.download(app_id))
+```
+
+`client.snapshots.download` works the same way.
+
+### Realtime logs (SSE)
+
+```python
+stream = client.apps.realtime(app_id)
+try:
+    for event in stream:
+        print(event.event, event.data)
+finally:
+    stream.close()
+```
+
+Stop the stream with `break` or `stream.close()`. Pass `since=` to resume. There is no automatic reconnection.
+
+### Errors
+
+Every non-2xx response raises a `VertraAPIError` carrying the HTTP `status`, the API `code` (e.g. `APP_NOT_FOUND`) and `details`; `str(err)` includes the message. The API key is never part of the error, even when it is printed:
+
+```python
+from vertracloud import NotFoundError, RateLimitError, VertraAPIError
+
+try:
+    client.apps.get(app_id)
+except NotFoundError:
+    ...  # 404
+except RateLimitError as err:
+    print("retry after", err.retry_after, "s")
+except VertraAPIError as err:
+    print(err.status, err.code, err)
+```
+
+Other subclasses: `AuthenticationError` (401), `ScopeDeniedError` (403 — including a missing key scope) and `ValidationError` (400/422). The error codes are listed in the [API reference](https://docs.vertracloud.app/api-reference/introduction).
+
+### Testing your code
+
+Pass your own `vertracloud.Transport` to the client to answer requests without touching the network:
+
+```python
+client = VertraClient(api_key="test", transport=my_fake_transport)
+```
+
+## Coverage
+
+| Domain | Resource | Routes |
+|---|---|---|
+| Apps | `client.apps` (+ `.deploys`, `.network`, `.envs`, `.files`) | 36 |
+| Databases | `client.databases` (+ `.credentials`) | 13 |
+| Snapshots | `client.snapshots` | 5 |
+| Account | `client.account` (+ `.sessions`, `.folders`, `.favorites`) | 10 |
+| Workspaces | `client.workspaces` (+ `.members`, `.roles`, `.invites`, `.action_requests`, `.apps`, `.databases`, `.folders`, `.favorites`) | 30 |
+| Billing | `client.billing` (+ `.orders`) | 5 |
+
+Dashboard-only features (activity log, notifications, API key management, the database **Data** tab, plan downgrade, creating workspace invites, transferring workspace ownership and approving action requests) are not part of the public API. See [what an API key cannot do](https://docs.vertracloud.app/sdks).
+
+## Versioning
+
+The SDK follows semantic versioning. Until `1.0.0`, minor releases may contain breaking changes; they are always called out in the [changelog](CHANGELOG.md).
+
+## Contributing
+
+Issues and pull requests are welcome. Before sending a change, run:
+
+```bash
+pip install -e ".[dev]"
+ruff check . && ruff format --check . && mypy src && python -m pytest -q
+```
+
+## License
+
+[MIT](LICENSE)

vertracloud_api-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vertracloud-api"
+version = "0.1.0"
+description = "Official Python SDK for the public API of Vertra Cloud, a Brazilian application hosting platform (PaaS)."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Vertra Cloud" }]
+dependencies = []
+
+[project.urls]
+Homepage = "https://vertracloud.app"
+Documentation = "https://docs.vertracloud.app/sdks"
+Repository = "https://github.com/vertracloud/sdk-api-py"
+Issues = "https://github.com/vertracloud/sdk-api-py/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6", "mypy>=1.11", "build>=1.2"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vertracloud"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["vertracloud"]
+mypy_path = "src"
+
+# `resources/*` returns the `Any` from `request_json`/`request_multipart` already annotated
+# with the contract's TypedDict/type — there's no real value in requiring `cast()` on every call.
+[[tool.mypy.overrides]]
+module = "vertracloud.resources.*"
+warn_return_any = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

vertracloud_api-0.1.0/release-please-config.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "packages": {
+    ".": {
+      "release-type": "python",
+      "package-name": "vertracloud-api",
+      "bump-minor-pre-major": true,
+      "extra-files": [
+        "src/vertracloud/client.py"
+      ],
+      "changelog-sections": [
+        {
+          "type": "feat",
+          "section": "Features"
+        },
+        {
+          "type": "fix",
+          "section": "Bug Fixes"
+        },
+        {
+          "type": "perf",
+          "section": "Performance"
+        },
+        {
+          "type": "docs",
+          "section": "Documentation",
+          "hidden": true
+        },
+        {
+          "type": "chore",
+          "hidden": true
+        },
+        {
+          "type": "refactor",
+          "hidden": true
+        },
+        {
+          "type": "test",
+          "hidden": true
+        },
+        {
+          "type": "ci",
+          "hidden": true
+        }
+      ],
+      "release-as": "0.1.0"
+    }
+  },
+  "include-component-in-tag": false
+}

vertracloud_api-0.1.0/src/vertracloud/__init__.py

@@ -0,0 +1,29 @@
+"""Typed Python client for the Vertra Cloud public API (`import vertracloud`)."""
+
+from .client import VertraClient, __version__
+from .errors import (
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    ScopeDeniedError,
+    ValidationError,
+    VertraAPIError,
+)
+from .sse import SseEvent, SseStream
+from .transport import Response, Transport, UrllibTransport
+
+__all__ = [
+    "VertraClient",
+    "__version__",
+    "VertraAPIError",
+    "AuthenticationError",
+    "ScopeDeniedError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "SseEvent",
+    "SseStream",
+    "Transport",
+    "UrllibTransport",
+    "Response",
+]