cloady 0.5.0__tar.gz

cloady-0.5.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.3
+Name: cloady
+Version: 0.5.0
+Summary: A client library for accessing Cloady API
+Requires-Dist: httpx>=0.23.1,<0.29.0
+Requires-Dist: attrs>=22.2.0
+Requires-Dist: boto3>=1.34 ; extra == 's3'
+Requires-Python: >=3.11
+Provides-Extra: s3
+Description-Content-Type: text/markdown
+
+# cloady
+A client library for accessing the Cloady API.
+
+## Usage
+Create a client:
+
+```python
+from cloady import Cloady
+
+cloady = Cloady(base_url="https://cloady.com", token="cldy_…")
+```
+
+`Cloady` is an `AuthenticatedClient` that also carries `cloady.files` — file
+operations over app volumes, speaking S3 (SigV4 via boto3) against the
+same-origin `/s3` endpoint internally:
+
+```python
+from cloady.files import VolumeRef
+
+ref = VolumeRef(slug="neptolab", region="hil1", env="prod",
+                svc_id="dailyfrog", volume="dailyfrog-data")
+
+cloady.files.list(ref, "")
+cloady.files.upload(ref, "logs", "out.txt", b"hi")
+cloady.files.download(ref, "logs/out.txt", "./out.txt")
+cloady.files.rename(ref, "", "old", "new", is_dir=True)
+cloady.files.remove(ref, "", [("cache", True)])
+```
+
+File operations need the `s3` extra: `pip install 'cloady[s3]'`.
+
+For unauthenticated endpoints a plain `Client` is available:
+
+```python
+from cloady import Client
+
+client = Client(base_url="https://cloady.com")
+```
+
+REST endpoints live under `cloady.generated.api` — one module per
+path/method combo, with `sync`, `sync_detailed`, `asyncio`, and
+`asyncio_detailed` variants:
+
+```python
+from cloady.generated.api.default import list_workspaces
+from cloady.generated.types import Response
+
+with cloady as client:
+    workspaces = list_workspaces.sync(client=client)
+    response = list_workspaces.sync_detailed(client=client)
+```
+
+Or async:
+
+```python
+async with cloady as client:
+    workspaces = await list_workspaces.asyncio(client=client)
+```
+
+Models are in `cloady.generated.models`, error types in
+`cloady.generated.errors`.
+
+TLS behaves like httpx: pass `verify_ssl="/path/to/bundle.pem"` for a custom
+CA bundle, or `verify_ssl=False` to disable verification (a security risk).
+The underlying `httpx.Client` can be customized via `httpx_args` or replaced
+with `set_httpx_client` — see the docstrings on `Client`.
+
+## Layout
+
+`cloady/generated/` is produced by `openapi-python-client` from the repo's
+`openapi.json` (`npm run gen:python`) and is fully overwritten on every
+regeneration — never edit it. Everything outside it (`__init__.py`,
+`files.py`, `pyproject.toml`, this README) is handwritten.
+
+## Building / publishing
+This project uses [uv](https://github.com/astral-sh/uv):
+1. Update the metadata in `pyproject.toml` (e.g. version).
+2. Build with `uv build`, publish with `uv publish`.

cloady-0.5.0/README.md

@@ -0,0 +1,78 @@
+# cloady
+A client library for accessing the Cloady API.
+
+## Usage
+Create a client:
+
+```python
+from cloady import Cloady
+
+cloady = Cloady(base_url="https://cloady.com", token="cldy_…")
+```
+
+`Cloady` is an `AuthenticatedClient` that also carries `cloady.files` — file
+operations over app volumes, speaking S3 (SigV4 via boto3) against the
+same-origin `/s3` endpoint internally:
+
+```python
+from cloady.files import VolumeRef
+
+ref = VolumeRef(slug="neptolab", region="hil1", env="prod",
+                svc_id="dailyfrog", volume="dailyfrog-data")
+
+cloady.files.list(ref, "")
+cloady.files.upload(ref, "logs", "out.txt", b"hi")
+cloady.files.download(ref, "logs/out.txt", "./out.txt")
+cloady.files.rename(ref, "", "old", "new", is_dir=True)
+cloady.files.remove(ref, "", [("cache", True)])
+```
+
+File operations need the `s3` extra: `pip install 'cloady[s3]'`.
+
+For unauthenticated endpoints a plain `Client` is available:
+
+```python
+from cloady import Client
+
+client = Client(base_url="https://cloady.com")
+```
+
+REST endpoints live under `cloady.generated.api` — one module per
+path/method combo, with `sync`, `sync_detailed`, `asyncio`, and
+`asyncio_detailed` variants:
+
+```python
+from cloady.generated.api.default import list_workspaces
+from cloady.generated.types import Response
+
+with cloady as client:
+    workspaces = list_workspaces.sync(client=client)
+    response = list_workspaces.sync_detailed(client=client)
+```
+
+Or async:
+
+```python
+async with cloady as client:
+    workspaces = await list_workspaces.asyncio(client=client)
+```
+
+Models are in `cloady.generated.models`, error types in
+`cloady.generated.errors`.
+
+TLS behaves like httpx: pass `verify_ssl="/path/to/bundle.pem"` for a custom
+CA bundle, or `verify_ssl=False` to disable verification (a security risk).
+The underlying `httpx.Client` can be customized via `httpx_args` or replaced
+with `set_httpx_client` — see the docstrings on `Client`.
+
+## Layout
+
+`cloady/generated/` is produced by `openapi-python-client` from the repo's
+`openapi.json` (`npm run gen:python`) and is fully overwritten on every
+regeneration — never edit it. Everything outside it (`__init__.py`,
+`files.py`, `pyproject.toml`, this README) is handwritten.
+
+## Building / publishing
+This project uses [uv](https://github.com/astral-sh/uv):
+1. Update the metadata in `pyproject.toml` (e.g. version).
+2. Build with `uv build`, publish with `uv publish`.

cloady-0.5.0/cloady/__init__.py

@@ -0,0 +1,21 @@
+from typing import TYPE_CHECKING
+
+from .generated.client import AuthenticatedClient, Client
+
+if TYPE_CHECKING:
+    from .files import CloadyFiles
+
+
+class Cloady(AuthenticatedClient):
+    @property
+    def files(self) -> "CloadyFiles":
+        cached = self.__dict__.get("_files")
+        if cached is None:
+            from .files import CloadyFiles
+
+            cached = CloadyFiles(self._base_url, self.token)
+            self.__dict__["_files"] = cached
+        return cached
+
+
+__all__ = ("AuthenticatedClient", "Client", "Cloady")

cloady-0.5.0/cloady/files.py

@@ -0,0 +1,234 @@
+"""S3-backed volume file operations — the Python mirror of the JS SDK's
+``cloady.files.*``.
+
+The Cloady ``/s3`` endpoint is an S3-compatible face over each app volume, so
+this module is a thin wrapper over :mod:`boto3` (which handles SigV4 signing,
+XML, multipart, and pagination). It authenticates with short-lived credentials
+exchanged from ``POST /api/workspaces/{slug}/s3/session`` using your API token,
+refreshing them automatically before expiry.
+
+    from cloady import Cloady
+    from cloady.files import VolumeRef
+
+    cloady = Cloady(base_url="https://cloady.com", token="cldy_…")
+    ref = VolumeRef(slug="neptolab", region="hil1", env="prod",
+                    svc_id="dailyfrog", volume="dailyfrog-data")
+
+    cloady.files.list(ref, "")               # -> [FileEntry(...), ...]
+    cloady.files.upload(ref, "logs", "out.txt", b"hi")
+    cloady.files.download(ref, "logs/out.txt", "./out.txt")
+    cloady.files.rename(ref, "", "old", "new", is_dir=True)   # atomic server-side mv
+    cloady.files.remove(ref, "", [("cache", True)])           # recursive rm -rf
+
+Requires the ``boto3`` extra: ``pip install 'cloady[s3]'`` (or add boto3).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+import httpx
+
+try:  # boto3 is an optional extra; only needed for file operations.
+    import boto3
+    from botocore.config import Config
+    from botocore.credentials import RefreshableCredentials
+    from botocore.session import get_session
+except ImportError as exc:  # pragma: no cover
+    raise ImportError("cloady.files requires boto3 — install it with: pip install 'cloady[s3]'") from exc
+
+
+@dataclass(frozen=True)
+class VolumeRef:
+    """Addresses one volume of one app instance (an S3 'bucket')."""
+
+    slug: str
+    region: str
+    env: str
+    svc_id: str
+    volume: str
+
+    def bucket(self) -> str:
+        return ".".join([self.slug, self.region, self.env, self.svc_id, self.volume])
+
+
+@dataclass(frozen=True)
+class FileEntry:
+    name: str
+    type: str  # "dir" | "file"
+    size: int
+    modified_ms: int
+
+
+def _join(path: str, name: str) -> str:
+    return f"{path}/{name}" if path else name
+
+
+def _parse_expiry(iso: str) -> datetime:
+    # Server sends e.g. "2026-07-14T20:06:55.987Z"; make it tz-aware.
+    try:
+        return datetime.fromisoformat(iso.replace("Z", "+00:00"))
+    except ValueError:  # pragma: no cover — fall back to a short lifetime
+        return datetime.now(UTC)
+
+
+class CloadyFiles:
+    """File operations over a Cloady volume via its S3 endpoint.
+
+    One instance per API token; boto3 clients (with auto-refreshing session
+    credentials) are cached per (workspace slug, access). Read operations
+    exchange a read-scoped session, write operations a write-scoped one —
+    same as the JS SDK.
+    """
+
+    def __init__(self, base_url: str, token: str):
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+        self._clients: dict[tuple[str, str], boto3.client] = {}
+        self._http = httpx.Client(timeout=30.0)
+
+    # -- credential exchange ------------------------------------------------
+
+    def _mint(self, slug: str, access: str) -> dict:
+        res = self._http.post(
+            f"{self._base_url}/api/workspaces/{slug}/s3/session",
+            headers={"authorization": f"Bearer {self._token}"},
+            json={"access": access},
+        )
+        if res.status_code >= 400:
+            detail = ""
+            try:
+                detail = res.json().get("error", {}).get("message", "")
+            except Exception:  # noqa: BLE001
+                pass
+            raise RuntimeError(f"Could not obtain file access ({res.status_code}): {detail}")
+        return res.json()
+
+    def _client(self, slug: str, access: str = "read"):
+        cached = self._clients.get((slug, access))
+        if cached is not None:
+            return cached
+
+        first = self._mint(slug, access)
+        endpoint = first["endpoint"]
+
+        def refresh() -> dict:
+            data = self._mint(slug, access)
+            return {
+                "access_key": data["accessKeyId"],
+                "secret_key": data["secretAccessKey"],
+                "token": None,
+                "expiry_time": _parse_expiry(data["expiresAt"]).isoformat(),
+            }
+
+        creds = RefreshableCredentials.create_from_metadata(
+            metadata={
+                "access_key": first["accessKeyId"],
+                "secret_key": first["secretAccessKey"],
+                "token": None,
+                "expiry_time": _parse_expiry(first["expiresAt"]).isoformat(),
+            },
+            refresh_using=refresh,
+            method="cloady-session",
+        )
+        creds._advisory_refresh_timeout = 300  # noqa: SLF001 — botocore defaults (900s) exceed the 15-min session TTL, forcing a re-mint on every request
+        creds._mandatory_refresh_timeout = 60  # noqa: SLF001
+        botocore_session = get_session()
+        botocore_session._credentials = creds  # noqa: SLF001 — documented botocore pattern
+        client = boto3.Session(botocore_session=botocore_session).client(
+            "s3",
+            endpoint_url=endpoint,
+            region_name="auto",
+            config=Config(s3={"addressing_style": "path"}, signature_version="s3v4"),
+        )
+        self._clients[(slug, access)] = client
+        return client
+
+    def clear_sessions(self) -> None:
+        """Drop cached credentials/clients (e.g. after rotating the token)."""
+        self._clients.clear()
+
+    # -- operations ---------------------------------------------------------
+
+    def list(self, ref: VolumeRef, path: str) -> list[FileEntry]:
+        """One-level listing: folders (as dirs) and files."""
+        prefix = (path.rstrip("/") + "/") if path else ""
+        client = self._client(ref.slug)
+        entries: list[FileEntry] = []
+        for page in client.get_paginator("list_objects_v2").paginate(Bucket=ref.bucket(), Prefix=prefix, Delimiter="/"):
+            for cp in page.get("CommonPrefixes", []):
+                name = cp["Prefix"].rstrip("/").split("/")[-1]
+                if name:
+                    entries.append(FileEntry(name=name, type="dir", size=0, modified_ms=0))
+            for obj in page.get("Contents", []):
+                key = obj["Key"]
+                if not key or key.endswith("/"):
+                    continue
+                name = key.split("/")[-1]
+                lm = obj.get("LastModified")
+                entries.append(
+                    FileEntry(
+                        name=name,
+                        type="file",
+                        size=int(obj.get("Size", 0)),
+                        modified_ms=int(lm.timestamp() * 1000) if lm else 0,
+                    )
+                )
+        return entries
+
+    def read(self, ref: VolumeRef, key: str) -> bytes:
+        """Read a whole object's bytes (ranged internally if it exceeds the cap)."""
+        client = self._client(ref.slug)
+        head = client.head_object(Bucket=ref.bucket(), Key=key)
+        size = int(head.get("ContentLength", 0))
+        cap = 50 * 1024 * 1024
+        if size <= cap:
+            return client.get_object(Bucket=ref.bucket(), Key=key)["Body"].read()
+        chunks: list[bytes] = []
+        for off in range(0, size, cap):
+            rng = f"bytes={off}-{min(off + cap, size) - 1}"
+            chunks.append(client.get_object(Bucket=ref.bucket(), Key=key, Range=rng)["Body"].read())
+        return b"".join(chunks)
+
+    def read_text(self, ref: VolumeRef, key: str, encoding: str = "utf-8") -> str:
+        return self.read(ref, key).decode(encoding)
+
+    def upload(self, ref: VolumeRef, path: str, name: str, data: bytes) -> None:
+        """Upload a file (multipart for large blobs, handled by boto3)."""
+        import io
+
+        self._client(ref.slug, "write").upload_fileobj(io.BytesIO(data), ref.bucket(), _join(path, name))
+
+    def download(self, ref: VolumeRef, key: str, dest_path: str) -> None:
+        with open(dest_path, "wb") as fh:
+            fh.write(self.read(ref, key))
+
+    def mkdir(self, ref: VolumeRef, path: str, name: str) -> None:
+        self._client(ref.slug, "write").put_object(Bucket=ref.bucket(), Key=_join(path, name) + "/", Body=b"")
+
+    def remove(self, ref: VolumeRef, path: str, items: Iterable[tuple[str, bool]]) -> None:
+        """Delete files/folders. ``items`` is (name, is_dir); folders are
+        removed recursively server-side via a trailing-slash key."""
+        client = self._client(ref.slug, "write")
+        for name, is_dir in items:
+            key = _join(path, name) + ("/" if is_dir else "")
+            client.delete_object(Bucket=ref.bucket(), Key=key)
+
+    def rename(self, ref: VolumeRef, path: str, frm: str, to: str, is_dir: bool) -> None:
+        """Atomic rename/move (files and folders) via the ``x-cloady-move``
+        server extension — one call, no client-side copy+delete."""
+        client = self._client(ref.slug, "write")
+        bucket = ref.bucket()
+        suffix = "/" if is_dir else ""
+        src = f"{bucket}/{_join(path, frm)}{suffix}"
+
+        def _add_move_header(request, **_kwargs):
+            request.headers["x-cloady-move"] = "true"
+
+        client.meta.events.register("before-send.s3.CopyObject", _add_move_header)
+        try:
+            client.copy_object(Bucket=bucket, Key=_join(path, to) + suffix, CopySource=src)
+        finally:
+            client.meta.events.unregister("before-send.s3.CopyObject", _add_move_header)

cloady-0.5.0/cloady/generated/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing Cloady API"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

cloady-0.5.0/cloady/generated/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

cloady-0.5.0/cloady/generated/api/default/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""

cloady-0.5.0/cloady/generated/api/default/accept_invitation.py

@@ -0,0 +1,176 @@
+from http import HTTPStatus
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.accept_invitation_response_200 import AcceptInvitationResponse200
+from ...models.error_response import ErrorResponse
+from ...types import Response
+
+
+def _get_kwargs(
+    token: str,
+) -> dict[str, Any]:
+
+    _kwargs: dict[str, Any] = {
+        "method": "post",
+        "url": "/api/invitations/{token}/accept".format(
+            token=quote(str(token), safe=""),
+        ),
+    }
+
+    return _kwargs
+
+
+def _parse_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> AcceptInvitationResponse200 | ErrorResponse | None:
+    if response.status_code == 200:
+        response_200 = AcceptInvitationResponse200.from_dict(response.json())
+
+        return response_200
+
+    if response.status_code == 400:
+        response_400 = ErrorResponse.from_dict(response.json())
+
+        return response_400
+
+    if response.status_code == 401:
+        response_401 = ErrorResponse.from_dict(response.json())
+
+        return response_401
+
+    if response.status_code == 403:
+        response_403 = ErrorResponse.from_dict(response.json())
+
+        return response_403
+
+    if response.status_code == 404:
+        response_404 = ErrorResponse.from_dict(response.json())
+
+        return response_404
+
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Response[AcceptInvitationResponse200 | ErrorResponse]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    token: str,
+    *,
+    client: AuthenticatedClient | Client,
+) -> Response[AcceptInvitationResponse200 | ErrorResponse]:
+    """Accept a workspace invitation
+
+    Args:
+        token (str):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[AcceptInvitationResponse200 | ErrorResponse]
+    """
+
+    kwargs = _get_kwargs(
+        token=token,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    token: str,
+    *,
+    client: AuthenticatedClient | Client,
+) -> AcceptInvitationResponse200 | ErrorResponse | None:
+    """Accept a workspace invitation
+
+    Args:
+        token (str):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        AcceptInvitationResponse200 | ErrorResponse
+    """
+
+    return sync_detailed(
+        token=token,
+        client=client,
+    ).parsed
+
+
+async def asyncio_detailed(
+    token: str,
+    *,
+    client: AuthenticatedClient | Client,
+) -> Response[AcceptInvitationResponse200 | ErrorResponse]:
+    """Accept a workspace invitation
+
+    Args:
+        token (str):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[AcceptInvitationResponse200 | ErrorResponse]
+    """
+
+    kwargs = _get_kwargs(
+        token=token,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    token: str,
+    *,
+    client: AuthenticatedClient | Client,
+) -> AcceptInvitationResponse200 | ErrorResponse | None:
+    """Accept a workspace invitation
+
+    Args:
+        token (str):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        AcceptInvitationResponse200 | ErrorResponse
+    """
+
+    return (
+        await asyncio_detailed(
+            token=token,
+            client=client,
+        )
+    ).parsed