sws-sdk 0.1.1__tar.gz

sws_sdk-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+  id-token: write   # required for PyPI trusted publishing
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -v
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheel + sdist
+        run: |
+          pip install build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

sws_sdk-0.1.1/.gitignore

@@ -0,0 +1,30 @@
+# Build artifacts
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Test/coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.mypy_cache/
+.ruff_cache/
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+.DS_Store

sws_sdk-0.1.1/LICENSE

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

sws_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: sws-sdk
+Version: 0.1.1
+Summary: Official Python SDK for the SWS cloud platform
+Project-URL: Homepage, https://savannaa.com
+Project-URL: Documentation, https://savannaa.com/docs
+Project-URL: Repository, https://github.com/savannaacloud/sws-sdk
+Project-URL: Issues, https://github.com/savannaacloud/sws-sdk/issues
+Author: Savannaa Cloud
+License: MIT
+License-File: LICENSE
+Keywords: cloud,infrastructure,savannaa,sws
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sws-sdk
+
+Official Python SDK for the **SWS** cloud platform.
+
+## Install
+
+```bash
+# Once published to PyPI:
+pip install sws-sdk
+
+# Available now (installs the tagged release straight from GitHub):
+pip install "git+https://github.com/savannaacloud/sws-sdk@v0.1.0"
+```
+
+## Quickstart
+
+```python
+from sws import Client
+
+client = Client(api_key="ctk_...", region="ng-lagos-1")
+
+# List virtual machines
+for vm in client.compute.list_instances():
+    print(vm.name, vm.status)
+
+# Launch an instance
+instance = client.compute.create_instance(
+    name="web-01",
+    image="ubuntu-22.04",
+    plan="m1.medium",
+    network_id="net-uuid",
+    key_name="my-key",
+)
+
+# Create + attach a volume
+vol = client.storage.create_volume(name="data", size=100, type="ssd")
+client.storage.attach_volume(vol.id, instance_id=instance.id)
+
+# Open SSH (port 22) from anywhere
+sg = client.network.create_security_group("web", description="Allow SSH")
+client.network.add_security_group_rule(
+    sg.id, protocol="tcp", port_range_min=22, port_range_max=22,
+    remote_ip_prefix="0.0.0.0/0",
+)
+```
+
+Configure via constructor or environment variables:
+
+| Argument    | Env var         | Default                    |
+| ----------- | --------------- | -------------------------- |
+| `api_key`   | `SWS_API_KEY`   | _(required)_               |
+| `region`    | `SWS_REGION`    | `ng-lagos-1`               |
+| `base_url`  | `SWS_BASE_URL`  | `https://savannaa.com`     |
+
+## Resources
+
+| Namespace          | Operations                                                                                         |
+| ------------------ | -------------------------------------------------------------------------------------------------- |
+| `client.compute`   | instances (CRUD + start/stop/reboot/resize), plans, images, keypairs                               |
+| `client.network`   | networks, subnets, security groups + rules, public IPs (allocate/assign/release)                   |
+| `client.storage`   | volumes (create, delete, attach, detach)                                                           |
+| `client.database`  | managed database instances (mysql, postgresql, …)                                                  |
+
+## Error handling
+
+```python
+from sws import Client, QuotaExceededError, NotFoundError
+
+try:
+    client.compute.create_instance(...)
+except QuotaExceededError:
+    print("Out of instance quota — request a bump in the console.")
+except NotFoundError:
+    print("Image or plan does not exist in this region.")
+```
+
+All exceptions inherit from `sws.SWSError`. Subclasses: `AuthenticationError`,
+`ValidationError`, `NotFoundError`, `QuotaExceededError`, `APIError`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest                # unit tests use respx, no live API required
+ruff check sws tests
+mypy sws
+```
+
+## License
+
+MIT

sws_sdk-0.1.1/README.md

@@ -0,0 +1,91 @@
+# sws-sdk
+
+Official Python SDK for the **SWS** cloud platform.
+
+## Install
+
+```bash
+# Once published to PyPI:
+pip install sws-sdk
+
+# Available now (installs the tagged release straight from GitHub):
+pip install "git+https://github.com/savannaacloud/sws-sdk@v0.1.0"
+```
+
+## Quickstart
+
+```python
+from sws import Client
+
+client = Client(api_key="ctk_...", region="ng-lagos-1")
+
+# List virtual machines
+for vm in client.compute.list_instances():
+    print(vm.name, vm.status)
+
+# Launch an instance
+instance = client.compute.create_instance(
+    name="web-01",
+    image="ubuntu-22.04",
+    plan="m1.medium",
+    network_id="net-uuid",
+    key_name="my-key",
+)
+
+# Create + attach a volume
+vol = client.storage.create_volume(name="data", size=100, type="ssd")
+client.storage.attach_volume(vol.id, instance_id=instance.id)
+
+# Open SSH (port 22) from anywhere
+sg = client.network.create_security_group("web", description="Allow SSH")
+client.network.add_security_group_rule(
+    sg.id, protocol="tcp", port_range_min=22, port_range_max=22,
+    remote_ip_prefix="0.0.0.0/0",
+)
+```
+
+Configure via constructor or environment variables:
+
+| Argument    | Env var         | Default                    |
+| ----------- | --------------- | -------------------------- |
+| `api_key`   | `SWS_API_KEY`   | _(required)_               |
+| `region`    | `SWS_REGION`    | `ng-lagos-1`               |
+| `base_url`  | `SWS_BASE_URL`  | `https://savannaa.com`     |
+
+## Resources
+
+| Namespace          | Operations                                                                                         |
+| ------------------ | -------------------------------------------------------------------------------------------------- |
+| `client.compute`   | instances (CRUD + start/stop/reboot/resize), plans, images, keypairs                               |
+| `client.network`   | networks, subnets, security groups + rules, public IPs (allocate/assign/release)                   |
+| `client.storage`   | volumes (create, delete, attach, detach)                                                           |
+| `client.database`  | managed database instances (mysql, postgresql, …)                                                  |
+
+## Error handling
+
+```python
+from sws import Client, QuotaExceededError, NotFoundError
+
+try:
+    client.compute.create_instance(...)
+except QuotaExceededError:
+    print("Out of instance quota — request a bump in the console.")
+except NotFoundError:
+    print("Image or plan does not exist in this region.")
+```
+
+All exceptions inherit from `sws.SWSError`. Subclasses: `AuthenticationError`,
+`ValidationError`, `NotFoundError`, `QuotaExceededError`, `APIError`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest                # unit tests use respx, no live API required
+ruff check sws tests
+mypy sws
+```
+
+## License
+
+MIT

sws_sdk-0.1.1/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sws-sdk"
+dynamic = ["version"]
+description = "Official Python SDK for the SWS cloud platform"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Savannaa Cloud" }]
+keywords = ["cloud", "infrastructure", "sws", "savannaa"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "httpx>=0.25",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "pytest-cov",
+    "respx>=0.21",
+    "ruff",
+    "mypy",
+]
+
+[project.urls]
+Homepage = "https://savannaa.com"
+Documentation = "https://savannaa.com/docs"
+Repository = "https://github.com/savannaacloud/sws-sdk"
+Issues = "https://github.com/savannaacloud/sws-sdk/issues"
+
+[tool.hatch.version]
+path = "sws/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sws"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"

sws_sdk-0.1.1/sws/__init__.py

@@ -0,0 +1,41 @@
+"""Official Python SDK for the SWS cloud platform."""
+
+from sws._version import __version__
+from sws.client import Client
+from sws.exceptions import (
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    QuotaExceededError,
+    SWSError,
+    ValidationError,
+)
+from sws.models import (
+    Instance,
+    Keypair,
+    Network,
+    Plan,
+    PublicIP,
+    SecurityGroup,
+    Subnet,
+    Volume,
+)
+
+__all__ = [
+    "Client",
+    "SWSError",
+    "APIError",
+    "AuthenticationError",
+    "NotFoundError",
+    "QuotaExceededError",
+    "ValidationError",
+    "Instance",
+    "Keypair",
+    "Network",
+    "Subnet",
+    "SecurityGroup",
+    "PublicIP",
+    "Volume",
+    "Plan",
+    "__version__",
+]

sws_sdk-0.1.1/sws/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

sws_sdk-0.1.1/sws/client.py

@@ -0,0 +1,416 @@
+"""Top-level :class:`Client` and resource handlers.
+
+Resource handlers live as inner classes so users get attribute access
+(``client.compute.list_instances()``) without us having to maintain a
+service-locator dict.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from sws._version import __version__
+from sws.exceptions import (
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    QuotaExceededError,
+    ValidationError,
+)
+from sws.models import (
+    Database,
+    Instance,
+    Keypair,
+    Network,
+    Plan,
+    PublicIP,
+    SecurityGroup,
+    Subnet,
+    Volume,
+)
+
+DEFAULT_BASE_URL = "https://savannaa.com"
+DEFAULT_REGION = "ng-lagos-1"
+DEFAULT_TIMEOUT = 30.0
+
+
+def _raise_for_status(r: httpx.Response) -> None:
+    """Translate non-2xx responses into the SDK exception hierarchy.
+
+    Quota errors arrive as 403 with a body containing "Quota" — they get
+    their own subclass so callers can retry with smaller requests.
+    """
+    if r.is_success:
+        return
+    try:
+        body: Any = r.json()
+        msg = body.get("detail") or body.get("error") or body.get("message") or r.text
+    except Exception:
+        body = r.text
+        msg = r.text or r.reason_phrase
+
+    if r.status_code in (401, 403):
+        if isinstance(msg, str) and "quota" in msg.lower():
+            raise QuotaExceededError(r.status_code, msg, body)
+        raise AuthenticationError(r.status_code, msg, body)
+    if r.status_code == 404:
+        raise NotFoundError(r.status_code, msg, body)
+    if r.status_code in (400, 422):
+        raise ValidationError(r.status_code, msg, body)
+    raise APIError(r.status_code, msg, body)
+
+
+class Client:
+    """SWS API client.
+
+    Example::
+
+        from sws import Client
+
+        client = Client(api_key="ctk_...", region="ng-lagos-1")
+        for vm in client.compute.list_instances():
+            print(vm.name, vm.status)
+
+    Auth resolution order: ``api_key`` argument → ``SWS_API_KEY`` env var.
+    Region: ``region`` argument → ``SWS_REGION`` env var → ``ng-lagos-1``.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        region: str | None = None,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        verify_tls: bool = True,
+    ) -> None:
+        api_key = api_key or os.environ.get("SWS_API_KEY")
+        if not api_key:
+            raise AuthenticationError(
+                401,
+                "missing api_key (pass to Client(api_key=...) or set SWS_API_KEY env var)",
+            )
+        region = region or os.environ.get("SWS_REGION") or DEFAULT_REGION
+        base_url = base_url or os.environ.get("SWS_BASE_URL") or DEFAULT_BASE_URL
+
+        self._http = httpx.Client(
+            base_url=base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "x-region": region,
+                "User-Agent": f"sws-sdk-python/{__version__}",
+                "Accept": "application/json",
+            },
+            timeout=timeout,
+            verify=verify_tls,
+        )
+        self.region = region
+        self.compute = Compute(self._http)
+        self.network = NetworkResource(self._http)
+        self.storage = Storage(self._http)
+        self.database = DatabaseResource(self._http)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        self.close()
+
+
+class _Resource:
+    def __init__(self, http: httpx.Client) -> None:
+        self._http = http
+
+    def _get(self, path: str, **kwargs: Any) -> Any:
+        r = self._http.get(path, **kwargs)
+        _raise_for_status(r)
+        return r.json() if r.content else None
+
+    def _post(self, path: str, json: Any = None, **kwargs: Any) -> Any:
+        r = self._http.post(path, json=json, **kwargs)
+        _raise_for_status(r)
+        return r.json() if r.content else None
+
+    def _delete(self, path: str, **kwargs: Any) -> None:
+        r = self._http.delete(path, **kwargs)
+        _raise_for_status(r)
+
+
+class Compute(_Resource):
+    """Virtual machines, plans, images, keypairs."""
+
+    # ── instances ──────────────────────────────────────────────────────
+    def list_instances(self) -> list[Instance]:
+        data = self._get("/api/compute/servers") or []
+        return [Instance.from_api(d) for d in data]
+
+    def get_instance(self, instance_id: str) -> Instance:
+        return Instance.from_api(self._get(f"/api/compute/servers/{instance_id}"))
+
+    def create_instance(
+        self,
+        *,
+        name: str,
+        image: str,
+        plan: str,
+        network_id: str | None = None,
+        key_name: str | None = None,
+        security_groups: list[str] | None = None,
+        user_data: str | None = None,
+    ) -> Instance:
+        # The backend still takes flavor_id over the wire — translate the
+        # SDK's "plan" surface to it here so callers never see the legacy
+        # term.
+        payload: dict[str, Any] = {
+            "name": name,
+            "image_id": image,
+            "flavor_id": plan,
+        }
+        if network_id:
+            payload["network_id"] = network_id
+        if key_name:
+            payload["key_name"] = key_name
+        if security_groups:
+            payload["security_groups"] = security_groups
+        if user_data is not None:
+            payload["user_data"] = user_data
+        return Instance.from_api(self._post("/api/compute/servers", json=payload))
+
+    def delete_instance(self, instance_id: str) -> None:
+        self._delete(f"/api/compute/servers/{instance_id}")
+
+    def start_instance(self, instance_id: str) -> None:
+        self._post(f"/api/compute/servers/{instance_id}/start")
+
+    def stop_instance(self, instance_id: str) -> None:
+        self._post(f"/api/compute/servers/{instance_id}/stop")
+
+    def reboot_instance(self, instance_id: str, *, hard: bool = False) -> None:
+        self._post(
+            f"/api/compute/servers/{instance_id}/reboot",
+            json={"type": "HARD" if hard else "SOFT"},
+        )
+
+    def resize_instance(self, instance_id: str, *, plan: str) -> None:
+        self._post(
+            f"/api/compute/servers/{instance_id}/resize",
+            json={"flavor_id": plan},
+        )
+
+    # ── plans / images / keypairs ─────────────────────────────────────
+    def list_plans(self) -> list[Plan]:
+        data = self._get("/api/compute/plans") or []
+        return [Plan.from_api(d) for d in data]
+
+    def list_images(self) -> list[dict]:
+        data = self._get("/api/images") or []
+        return list(data)
+
+    def list_keypairs(self) -> list[Keypair]:
+        data = self._get("/api/compute/keypairs") or []
+        return [Keypair.from_api(d) for d in data]
+
+    def create_keypair(self, name: str, *, public_key: str | None = None) -> Keypair:
+        payload: dict[str, Any] = {"name": name}
+        if public_key:
+            payload["public_key"] = public_key
+        return Keypair.from_api(self._post("/api/compute/keypairs", json=payload))
+
+    def delete_keypair(self, name: str) -> None:
+        self._delete(f"/api/compute/keypairs/{name}")
+
+
+class NetworkResource(_Resource):
+    """Networks, subnets, security groups, public IPs."""
+
+    # ── networks ──────────────────────────────────────────────────────
+    def list_networks(self) -> list[Network]:
+        data = self._get("/api/network/networks") or []
+        return [Network.from_api(d) for d in data]
+
+    def create_network(self, name: str, *, description: str | None = None) -> Network:
+        payload: dict[str, Any] = {"name": name}
+        if description is not None:
+            payload["description"] = description
+        return Network.from_api(self._post("/api/network/networks", json=payload))
+
+    def delete_network(self, network_id: str) -> None:
+        self._delete(f"/api/network/networks/{network_id}")
+
+    # ── subnets ───────────────────────────────────────────────────────
+    def list_subnets(self) -> list[Subnet]:
+        data = self._get("/api/network/subnets") or []
+        return [Subnet.from_api(d) for d in data]
+
+    def create_subnet(
+        self,
+        *,
+        name: str,
+        network_id: str,
+        cidr: str,
+        ip_version: int = 4,
+        enable_dhcp: bool = True,
+        dns_nameservers: list[str] | None = None,
+    ) -> Subnet:
+        payload: dict[str, Any] = {
+            "name": name,
+            "network_id": network_id,
+            "cidr": cidr,
+            "ip_version": ip_version,
+            "enable_dhcp": enable_dhcp,
+        }
+        if dns_nameservers:
+            payload["dns_nameservers"] = dns_nameservers
+        return Subnet.from_api(self._post("/api/network/subnets", json=payload))
+
+    def delete_subnet(self, subnet_id: str) -> None:
+        self._delete(f"/api/network/subnets/{subnet_id}")
+
+    # ── security groups ───────────────────────────────────────────────
+    def list_security_groups(self) -> list[SecurityGroup]:
+        data = self._get("/api/network/security-groups") or []
+        return [SecurityGroup.from_api(d) for d in data]
+
+    def create_security_group(self, name: str, *, description: str = "") -> SecurityGroup:
+        return SecurityGroup.from_api(
+            self._post(
+                "/api/network/security-groups",
+                json={"name": name, "description": description},
+            )
+        )
+
+    def delete_security_group(self, group_id: str) -> None:
+        self._delete(f"/api/network/security-groups/{group_id}")
+
+    def add_security_group_rule(
+        self,
+        group_id: str,
+        *,
+        direction: str = "ingress",
+        protocol: str = "tcp",
+        port_range_min: int,
+        port_range_max: int,
+        remote_ip_prefix: str = "0.0.0.0/0",
+        ethertype: str = "IPv4",
+    ) -> dict:
+        return self._post(
+            "/api/network/security-group-rules",
+            json={
+                "security_group_id": group_id,
+                "direction": direction,
+                "protocol": protocol,
+                "port_range_min": port_range_min,
+                "port_range_max": port_range_max,
+                "remote_ip_prefix": remote_ip_prefix,
+                "ethertype": ethertype,
+            },
+        )
+
+    def remove_security_group_rule(self, rule_id: str) -> None:
+        self._delete(f"/api/network/security-group-rules/{rule_id}")
+
+    # ── public IPs ────────────────────────────────────────────────────
+    def list_public_ips(self) -> list[PublicIP]:
+        data = self._get("/api/network/public-ips") or []
+        return [PublicIP.from_api(d) for d in data]
+
+    def allocate_public_ip(self, *, floating_network_id: str | None = None) -> PublicIP:
+        payload: dict[str, Any] = {}
+        if floating_network_id:
+            payload["floating_network_id"] = floating_network_id
+        return PublicIP.from_api(self._post("/api/network/public-ips", json=payload))
+
+    def assign_public_ip(self, ip_id: str, *, instance_id: str) -> None:
+        self._post(
+            f"/api/network/public-ips/{ip_id}/associate",
+            json={"instance_id": instance_id},
+        )
+
+    def unassign_public_ip(self, ip_id: str) -> None:
+        self._post(f"/api/network/public-ips/{ip_id}/disassociate")
+
+    def release_public_ip(self, ip_id: str) -> None:
+        self._delete(f"/api/network/public-ips/{ip_id}")
+
+
+class Storage(_Resource):
+    """Block storage volumes."""
+
+    def list_volumes(self) -> list[Volume]:
+        data = self._get("/api/block-storage/volumes") or []
+        return [Volume.from_api(d) for d in data]
+
+    def get_volume(self, volume_id: str) -> Volume:
+        return Volume.from_api(self._get(f"/api/block-storage/volumes/{volume_id}"))
+
+    def create_volume(
+        self,
+        *,
+        name: str,
+        size: int,
+        type: str | None = None,
+        description: str | None = None,
+    ) -> Volume:
+        payload: dict[str, Any] = {"name": name, "size": size}
+        if type is not None:
+            payload["volume_type"] = type
+        if description is not None:
+            payload["description"] = description
+        return Volume.from_api(self._post("/api/block-storage/volumes", json=payload))
+
+    def delete_volume(self, volume_id: str) -> None:
+        self._delete(f"/api/block-storage/volumes/{volume_id}")
+
+    def attach_volume(self, volume_id: str, *, instance_id: str) -> None:
+        self._post(
+            f"/api/block-storage/volumes/{volume_id}/attach",
+            json={"instance_id": instance_id},
+        )
+
+    def detach_volume(self, volume_id: str) -> None:
+        self._post(f"/api/block-storage/volumes/{volume_id}/detach")
+
+
+class DatabaseResource(_Resource):
+    """Managed database instances (mysql, postgresql, etc.)."""
+
+    def list_instances(self) -> list[Database]:
+        data = self._get("/api/database/instances") or []
+        return [Database.from_api(d) for d in data]
+
+    def get_instance(self, db_id: str) -> Database:
+        return Database.from_api(self._get(f"/api/database/instances/{db_id}"))
+
+    def create_instance(
+        self,
+        *,
+        name: str,
+        datastore: str,
+        version: str,
+        plan: str,
+        size: int,
+        admin_user: str = "admin",
+        admin_password: str,
+        network_id: str | None = None,
+    ) -> Database:
+        payload: dict[str, Any] = {
+            "name": name,
+            "datastore_type": datastore,
+            "datastore_version": version,
+            "flavor": plan,
+            "size": size,
+            "admin_user": admin_user,
+            "admin_password": admin_password,
+        }
+        if network_id:
+            payload["network_id"] = network_id
+        return Database.from_api(self._post("/api/database/instances", json=payload))
+
+    def delete_instance(self, db_id: str) -> None:
+        self._delete(f"/api/database/instances/{db_id}")

sws_sdk-0.1.1/sws/exceptions.py

@@ -0,0 +1,39 @@
+"""Exception hierarchy for the SWS SDK.
+
+All errors derive from SWSError so callers can catch broadly with
+`except SWSError:` or precisely with the subclasses below.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class SWSError(Exception):
+    """Base class for all SDK errors."""
+
+
+class APIError(SWSError):
+    """Raised when the API returns a non-2xx response that is not a
+    more specific error class below."""
+
+    def __init__(self, status_code: int, message: str, body: Any = None) -> None:
+        self.status_code = status_code
+        self.body = body
+        super().__init__(f"HTTP {status_code}: {message}")
+
+
+class AuthenticationError(APIError):
+    """API key is missing, invalid, or expired (401/403)."""
+
+
+class NotFoundError(APIError):
+    """Resource does not exist (404)."""
+
+
+class ValidationError(APIError):
+    """Request payload was rejected by the server (400/422)."""
+
+
+class QuotaExceededError(APIError):
+    """The tenant has hit a per-resource quota (403 with quota detail)."""

sws_sdk-0.1.1/sws/models.py

@@ -0,0 +1,208 @@
+"""Typed dataclass models for SWS API resources.
+
+Models accept the raw API response via :meth:`from_api` and translate
+internal/legacy field names into the SDK's stable surface (e.g. the
+backend still returns ``flavor`` for what the SDK exposes as ``plan``).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+def _coerce_int(v: Any) -> int | None:
+    if v is None or v == "":
+        return None
+    try:
+        return int(v)
+    except (TypeError, ValueError):
+        return None
+
+
+@dataclass
+class Plan:
+    """A compute plan (size/SKU) — what the underlying platform calls a flavor."""
+
+    id: str
+    name: str
+    vcpus: int | None = None
+    ram: int | None = None  # MB
+    disk: int | None = None  # GB
+
+    @classmethod
+    def from_api(cls, data: dict) -> Plan:
+        return cls(
+            id=str(data.get("id", "")),
+            name=str(data.get("name", "")),
+            vcpus=_coerce_int(data.get("vcpus")),
+            ram=_coerce_int(data.get("ram")),
+            disk=_coerce_int(data.get("disk")),
+        )
+
+
+@dataclass
+class Instance:
+    id: str
+    name: str
+    status: str
+    plan: dict | None = None
+    image: dict | None = None
+    addresses: dict[str, Any] | None = None
+    key_name: str | None = None
+    created_at: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_api(cls, data: dict) -> Instance:
+        return cls(
+            id=str(data.get("id", "")),
+            name=str(data.get("name", "")),
+            status=str(data.get("status", "")),
+            plan=data.get("flavor") or data.get("plan"),
+            image=data.get("image"),
+            addresses=data.get("addresses"),
+            key_name=data.get("key_name"),
+            created_at=data.get("created") or data.get("created_at"),
+            raw=dict(data),
+        )
+
+
+@dataclass
+class Keypair:
+    name: str
+    fingerprint: str | None = None
+    public_key: str | None = None
+    private_key: str | None = None  # only present on create
+
+    @classmethod
+    def from_api(cls, data: dict) -> Keypair:
+        return cls(
+            name=str(data.get("name", "")),
+            fingerprint=data.get("fingerprint"),
+            public_key=data.get("public_key"),
+            private_key=data.get("private_key"),
+        )
+
+
+@dataclass
+class Network:
+    id: str
+    name: str
+    status: str | None = None
+    subnets: list[str] | None = None
+
+    @classmethod
+    def from_api(cls, data: dict) -> Network:
+        return cls(
+            id=str(data.get("id", "")),
+            name=str(data.get("name", "")),
+            status=data.get("status"),
+            subnets=data.get("subnets"),
+        )
+
+
+@dataclass
+class Subnet:
+    id: str
+    name: str
+    network_id: str
+    cidr: str
+    ip_version: int = 4
+    enable_dhcp: bool = True
+
+    @classmethod
+    def from_api(cls, data: dict) -> Subnet:
+        return cls(
+            id=str(data.get("id", "")),
+            name=str(data.get("name", "")),
+            network_id=str(data.get("network_id", "")),
+            cidr=str(data.get("cidr", "")),
+            ip_version=int(data.get("ip_version", 4)),
+            enable_dhcp=bool(data.get("enable_dhcp", True)),
+        )
+
+
+@dataclass
+class SecurityGroup:
+    id: str
+    name: str
+    description: str | None = None
+    rules: list[dict] = field(default_factory=list)
+
+    @classmethod
+    def from_api(cls, data: dict) -> SecurityGroup:
+        return cls(
+            id=str(data.get("id", "")),
+            name=str(data.get("name", "")),
+            description=data.get("description"),
+            rules=list(data.get("security_group_rules") or data.get("rules") or []),
+        )
+
+
+@dataclass
+class PublicIP:
+    """A public (floating) IP address."""
+
+    id: str
+    address: str
+    instance_id: str | None = None
+    status: str | None = None
+
+    @classmethod
+    def from_api(cls, data: dict) -> PublicIP:
+        return cls(
+            id=str(data.get("id", "")),
+            address=str(data.get("floating_ip_address") or data.get("address", "")),
+            instance_id=data.get("port_id") or data.get("instance_id"),
+            status=data.get("status"),
+        )
+
+
+@dataclass
+class Volume:
+    id: str
+    name: str
+    size: int  # GB
+    status: str | None = None
+    type: str | None = None
+    attached_to: str | None = None
+
+    @classmethod
+    def from_api(cls, data: dict) -> Volume:
+        attachments = data.get("attachments") or []
+        attached = (
+            attachments[0].get("server_id") if attachments and isinstance(attachments[0], dict) else None
+        )
+        return cls(
+            id=str(data.get("id", "")),
+            name=str(data.get("name", "")),
+            size=int(data.get("size", 0) or 0),
+            status=data.get("status"),
+            type=data.get("volume_type") or data.get("type"),
+            attached_to=attached,
+        )
+
+
+@dataclass
+class Database:
+    id: str
+    name: str
+    datastore: str
+    status: str | None = None
+    plan: dict | None = None
+
+    @classmethod
+    def from_api(cls, data: dict) -> Database:
+        ds = data.get("datastore")
+        if isinstance(ds, dict):
+            ds_type = str(ds.get("type", ""))
+        else:
+            ds_type = str(ds or data.get("datastore_type", ""))
+        return cls(
+            id=str(data.get("id", "")),
+            name=str(data.get("name", "")),
+            datastore=ds_type,
+            status=data.get("status"),
+            plan=data.get("flavor") or data.get("plan"),
+        )

sws_sdk-0.1.1/tests/test_client.py

@@ -0,0 +1,163 @@
+"""Mock-based tests using respx — no live API required."""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+import respx
+
+from sws import (
+    AuthenticationError,
+    Client,
+    NotFoundError,
+    QuotaExceededError,
+    ValidationError,
+)
+
+
+@pytest.fixture
+def client() -> Client:
+    return Client(api_key="sws_test", region="ng-lagos-1", base_url="https://api.example")
+
+
+@respx.mock
+def test_auth_header_and_region_sent(client: Client) -> None:
+    route = respx.get("https://api.example/api/compute/servers").mock(
+        return_value=httpx.Response(200, json=[]),
+    )
+    client.compute.list_instances()
+    req = route.calls.last.request
+    assert req.headers["authorization"] == "Bearer sws_test"
+    assert req.headers["x-region"] == "ng-lagos-1"
+    assert req.headers["user-agent"].startswith("sws-sdk-python/")
+
+
+@respx.mock
+def test_list_instances_parses_flavor_as_plan(client: Client) -> None:
+    respx.get("https://api.example/api/compute/servers").mock(
+        return_value=httpx.Response(
+            200,
+            json=[
+                {
+                    "id": "i-1",
+                    "name": "web-1",
+                    "status": "ACTIVE",
+                    "flavor": {"id": "m1.small", "vcpus": 1, "ram": 2048},
+                }
+            ],
+        )
+    )
+    instances = client.compute.list_instances()
+    assert len(instances) == 1
+    assert instances[0].id == "i-1"
+    assert instances[0].plan == {"id": "m1.small", "vcpus": 1, "ram": 2048}
+
+
+@respx.mock
+def test_create_instance_translates_plan_to_flavor_id(client: Client) -> None:
+    """SDK takes ``plan=`` from the caller but sends ``flavor_id`` over
+    the wire — the backend hasn't been renamed yet."""
+    route = respx.post("https://api.example/api/compute/servers").mock(
+        return_value=httpx.Response(
+            201,
+            json={"id": "i-2", "name": "web-2", "status": "BUILD"},
+        )
+    )
+    inst = client.compute.create_instance(
+        name="web-2",
+        image="ubuntu-22.04",
+        plan="m1.medium",
+        network_id="net-1",
+        key_name="my-key",
+    )
+    assert inst.id == "i-2"
+    body = route.calls.last.request.content.decode()
+    assert '"flavor_id":"m1.medium"' in body.replace(" ", "")
+    assert "plan" not in body  # SDK keyword shouldn't leak into the wire payload
+
+
+@respx.mock
+def test_404_raises_not_found(client: Client) -> None:
+    respx.get("https://api.example/api/compute/servers/missing").mock(
+        return_value=httpx.Response(404, json={"detail": "Not found"})
+    )
+    with pytest.raises(NotFoundError) as exc:
+        client.compute.get_instance("missing")
+    assert exc.value.status_code == 404
+
+
+@respx.mock
+def test_403_quota_message_raises_quota_exceeded(client: Client) -> None:
+    respx.post("https://api.example/api/compute/servers").mock(
+        return_value=httpx.Response(
+            403, json={"detail": "Quota exceeded for instances: 10/10"}
+        )
+    )
+    with pytest.raises(QuotaExceededError):
+        client.compute.create_instance(name="x", image="i", plan="m1.tiny")
+
+
+@respx.mock
+def test_401_raises_auth_error(client: Client) -> None:
+    respx.get("https://api.example/api/compute/servers").mock(
+        return_value=httpx.Response(401, json={"detail": "bad token"})
+    )
+    with pytest.raises(AuthenticationError):
+        client.compute.list_instances()
+
+
+@respx.mock
+def test_422_raises_validation_error(client: Client) -> None:
+    respx.post("https://api.example/api/network/subnets").mock(
+        return_value=httpx.Response(422, json={"detail": "cidr required"})
+    )
+    with pytest.raises(ValidationError):
+        client.network.create_subnet(name="s", network_id="n", cidr="")
+
+
+@respx.mock
+def test_security_group_rule_payload(client: Client) -> None:
+    route = respx.post("https://api.example/api/network/security-group-rules").mock(
+        return_value=httpx.Response(201, json={"id": "r-1"})
+    )
+    client.network.add_security_group_rule(
+        "sg-1",
+        protocol="tcp",
+        port_range_min=22,
+        port_range_max=22,
+        remote_ip_prefix="0.0.0.0/0",
+    )
+    body = route.calls.last.request.content.decode()
+    assert '"security_group_id":"sg-1"' in body.replace(" ", "")
+    assert '"direction":"ingress"' in body.replace(" ", "")
+
+
+@respx.mock
+def test_volume_attach_uses_instance_id(client: Client) -> None:
+    route = respx.post("https://api.example/api/block-storage/volumes/v-1/attach").mock(
+        return_value=httpx.Response(202)
+    )
+    client.storage.attach_volume("v-1", instance_id="i-9")
+    body = route.calls.last.request.content.decode()
+    assert '"instance_id":"i-9"' in body.replace(" ", "")
+
+
+def test_missing_api_key_raises() -> None:
+    import os
+
+    old = os.environ.pop("SWS_API_KEY", None)
+    try:
+        with pytest.raises(AuthenticationError):
+            Client()
+    finally:
+        if old:
+            os.environ["SWS_API_KEY"] = old
+
+
+def test_env_var_resolution(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("SWS_API_KEY", "sws_from_env")
+    monkeypatch.setenv("SWS_REGION", "ng-abuja-1")
+    c = Client(base_url="https://api.example")
+    assert c.region == "ng-abuja-1"
+    assert c._http.headers["authorization"] == "Bearer sws_from_env"
+    assert c._http.headers["x-region"] == "ng-abuja-1"