busabase 0.1.0__py3-none-any.whl

busabase/__init__.py

@@ -0,0 +1,28 @@
+"""Official Python SDK for the Busabase REST API.
+
+    from busabase import Busabase
+
+    bb = Busabase()  # BUSABASE_API_KEY / BUSABASE_BASE_URL / BUSABASE_SPACE_ID
+    for base in bb.bases.list():
+        print(base.slug, base.name)
+
+`Busabase` is a thin layer over the client generated by openapi-python-client
+in `busabase.generated` (models in `busabase.generated.models`, one module per
+operation in `busabase.generated.api`). Any HTTP error raises `BusabaseError`.
+"""
+
+from ._client import DEFAULT_BASE_URL, Busabase, Operation, normalize_base_url
+from ._errors import BusabaseError
+from ._version import __version__
+from .generated.types import UNSET, Unset
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "UNSET",
+    "Busabase",
+    "BusabaseError",
+    "Operation",
+    "Unset",
+    "__version__",
+    "normalize_base_url",
+]

busabase/_client.py

@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+import importlib
+import os
+from collections.abc import Awaitable, Mapping
+from types import ModuleType
+from typing import Any, Self
+
+import httpx
+
+from . import generated
+from ._errors import BusabaseError
+from ._operations import OPERATIONS
+from ._version import __version__
+from .generated import api as _generated_api  # noqa: F401  (makes `generated.api` an attribute)
+from .generated.client import AuthenticatedClient, Client
+
+DEFAULT_BASE_URL = "https://busabase.com"
+"""Busabase Cloud. Pass `base_url` (or set `BUSABASE_BASE_URL`) for a self-hosted server."""
+
+
+def _env(name: str) -> str | None:
+    value = os.environ.get(name)
+    return value or None
+
+
+def normalize_base_url(raw: str) -> str:
+    """Accept the server root with or without `/api/v1` — the generated paths already carry it."""
+    url = raw.rstrip("/")
+    return url.removesuffix("/api/v1")
+
+
+def _raise_for_status(response: httpx.Response) -> Awaitable[None] | None:
+    """httpx response hook: turn every >= 400 into a `BusabaseError`.
+
+    The generated functions return the parsed `Error` model (or `None`) for an
+    error status instead of raising, which makes a failed write easy to miss.
+    A hook fixes that once for every call, typed or not. The same `httpx_args`
+    feed both the sync and the async httpx client, so the hook serves both: an
+    async client awaits what it returns.
+    """
+    if isinstance(response.stream, httpx.AsyncByteStream):
+        return _araise_for_status(response)
+    if response.status_code >= 400:
+        response.read()
+        raise BusabaseError.from_response(response)
+    return None
+
+
+async def _araise_for_status(response: httpx.Response) -> None:
+    if response.status_code >= 400:
+        await response.aread()
+        raise BusabaseError.from_response(response)
+
+
+class _JsonBody:
+    """Lets a plain dict stand in for a generated request-body model: they only call `.to_dict()`."""
+
+    def __init__(self, data: Mapping[str, Any]) -> None:
+        self._data = dict(data)
+
+    def to_dict(self) -> dict[str, Any]:
+        return self._data
+
+
+def _prepare(kwargs: dict[str, Any]) -> dict[str, Any]:
+    body = kwargs.get("body")
+    if isinstance(body, Mapping):
+        kwargs = {**kwargs, "body": _JsonBody(body)}
+    return kwargs
+
+
+class Operation:
+    """One API operation bound to a client: `bb.records.list(base_id=...)`.
+
+    Calls the generated module's `sync()` (or `asyncio()` via `.asyncio(...)`)
+    and returns its parsed model. Arguments are the generated function's —
+    path parameters positional or by name (`bb.nodes.get("nod_1")`), the rest
+    by name; `body` may be a plain dict instead of the generated model.
+    """
+
+    def __init__(self, client: AuthenticatedClient | Client, module: ModuleType) -> None:
+        self._client = client
+        self.module = module
+        self.__doc__ = module.sync.__doc__
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self.module.sync(*args, client=self._client, **_prepare(kwargs))
+
+    async def asyncio(self, *args: Any, **kwargs: Any) -> Any:
+        return await self.module.asyncio(*args, client=self._client, **_prepare(kwargs))
+
+    def __repr__(self) -> str:
+        return f"<busabase operation {self.module.__name__.rsplit('.', 1)[1]}>"
+
+
+class _Group:
+    """A namespace of operations, e.g. `bb.records` or `bb.nodes.share` (paths from `_operations.py`)."""
+
+    def __init__(self, client: AuthenticatedClient | Client, path: str) -> None:
+        self._client = client
+        self._path = path
+
+    def __getattr__(self, name: str) -> Operation | _Group:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return _resolve(self._client, f"{self._path}.{name}" if self._path else name)
+
+    def __dir__(self) -> list[str]:
+        start = f"{self._path}." if self._path else ""
+        return sorted({path[len(start) :].split(".")[0] for path in OPERATIONS if path.startswith(start)})
+
+    def __repr__(self) -> str:
+        return f"<busabase group {self._path}: {', '.join(self.__dir__())}>"
+
+
+def _resolve(client: AuthenticatedClient | Client, path: str) -> Operation | _Group:
+    if path in OPERATIONS:
+        return Operation(client, importlib.import_module(f"{generated.api.__name__}.{OPERATIONS[path]}"))
+    if any(other.startswith(f"{path}.") for other in OPERATIONS):
+        return _Group(client, path)
+    raise AttributeError(f"Busabase has no API operation or group {path!r}")
+
+
+class Busabase:
+    """Client for the Busabase REST API — Busabase Cloud or a self-hosted server.
+
+    Every argument falls back to an environment variable, the same ones the
+    Busabase CLI and TypeScript SDK read:
+
+    - `api_key`  -> `BUSABASE_API_KEY` (omit for an open local self-hosted server)
+    - `base_url` -> `BUSABASE_BASE_URL`, then `https://busabase.com`
+    - `space`    -> `BUSABASE_SPACE_ID`, sent as `x-busabase-space`; needed on
+      Cloud when your key belongs to more than one space
+
+    Operations are grouped like the API: `bb.bases.list()`,
+    `bb.records.get(record_id=...)`, `bb.docs.create(body={...})`. Each is the
+    generated function of the same name in `busabase.generated.api`, called
+    with this client; use those directly (`records_list.sync(client=bb.client)`)
+    when you want full static typing. Any status >= 400 raises `BusabaseError`.
+
+    `headers` are sent with every request; `httpx_args` go to the underlying
+    `httpx.Client` / `httpx.AsyncClient` (e.g. `transport`, `proxy`, `verify`).
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        space: str | None = None,
+        *,
+        timeout: float | httpx.Timeout = 30.0,
+        headers: Mapping[str, str] | None = None,
+        httpx_args: Mapping[str, Any] | None = None,
+    ) -> None:
+        self.api_key = api_key or _env("BUSABASE_API_KEY")
+        self.base_url = normalize_base_url(base_url or _env("BUSABASE_BASE_URL") or DEFAULT_BASE_URL)
+        self.space = space or _env("BUSABASE_SPACE_ID")
+
+        all_headers = {
+            # Recorded as the source channel on Change Requests and audit events.
+            "x-busabase-channel": "sdk",
+            "user-agent": f"busabase-python-sdk/{__version__}",
+        }
+        if self.space:
+            all_headers["x-busabase-space"] = self.space
+        all_headers.update(headers or {})
+
+        extra = dict(httpx_args or {})
+        hooks = dict(extra.pop("event_hooks", {}))
+        hooks["response"] = [*hooks.get("response", []), _raise_for_status]
+        options: dict[str, Any] = {
+            "base_url": self.base_url,
+            "headers": all_headers,
+            "timeout": timeout if isinstance(timeout, httpx.Timeout) else httpx.Timeout(timeout),
+            # Belt and braces: an undocumented 2xx/3xx raises instead of returning None.
+            "raise_on_unexpected_status": True,
+            "httpx_args": {**extra, "event_hooks": hooks},
+        }
+        # The generated client sets `Authorization: Bearer <token>`; a local
+        # self-hosted server needs no key, and an empty bearer would be wrong.
+        self.client: AuthenticatedClient | Client = (
+            AuthenticatedClient(token=self.api_key, **options) if self.api_key else Client(**options)
+        )
+
+    def __getattr__(self, name: str) -> Operation | _Group:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return _resolve(self.client, name)
+
+    def __dir__(self) -> list[str]:
+        return sorted(set(super().__dir__()) | set(_Group(self.client, "").__dir__()))
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self.client.get_httpx_client().close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"Busabase(base_url={self.base_url!r}, space={self.space!r}, api_key={'set' if self.api_key else None})"
+
+
+__all__ = ["DEFAULT_BASE_URL", "Busabase", "BusabaseError", "Operation", "generated", "normalize_base_url"]

busabase/_errors.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class BusabaseError(Exception):
+    """A Busabase API call failed (HTTP status >= 400).
+
+    Built from the `{ error, code, data }` body every `/api/v1` endpoint returns
+    on failure, so `code` is the server's semantic outcome (`NOT_FOUND`,
+    `FORBIDDEN`, `BAD_REQUEST`, `CONFLICT`, …) rather than just the status.
+
+    Attributes:
+        status: HTTP status code.
+        code: The server's error code, or `HTTP_<status>` when the body had none.
+        message: The server's message; for a 400, field-level validation issues
+            are appended (`fields.0.slug: Required`).
+        data: The envelope's `data` (e.g. `{"issues": [...]}`), if any.
+        response: The raw `httpx.Response`.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        code: str,
+        data: Any = None,
+        response: httpx.Response | None = None,
+    ) -> None:
+        super().__init__(f"{code} ({status}): {message}")
+        self.message = message
+        self.status = status
+        self.code = code
+        self.data = data
+        self.response = response
+
+    @classmethod
+    def from_response(cls, response: httpx.Response) -> BusabaseError:
+        """Decode an error response. The body must already be read."""
+        status = response.status_code
+        try:
+            body = response.json()
+        except ValueError:
+            body = None
+        if not isinstance(body, dict) or not isinstance(body.get("error"), str):
+            text = response.text.strip()
+            return cls(text or response.reason_phrase, status=status, code=f"HTTP_{status}", response=response)
+
+        message: str = body["error"]
+        data = body.get("data")
+        issues = data.get("issues") if isinstance(data, dict) else None
+        if isinstance(issues, list) and issues:
+            details = []
+            for issue in issues:
+                if not isinstance(issue, dict):
+                    details.append(str(issue))
+                    continue
+                path = issue.get("path")
+                where = ".".join(str(step) for step in path) if isinstance(path, list) and path else ""
+                details.append(f"{where}: {issue.get('message')}" if where else str(issue.get("message")))
+            message = f"{message} — {'; '.join(details)}"
+        code = body.get("code")
+        return cls(
+            message,
+            status=status,
+            code=code if isinstance(code, str) else f"HTTP_{status}",
+            data=data,
+            response=response,
+        )

busabase/_operations.py

@@ -0,0 +1,131 @@
+# Generated by scripts/generate.py from openapi.json — do not edit.
+"""Every API operation: its Python path on `Busabase` -> its module under `busabase.generated.api`."""
+
+OPERATIONS: dict[str, str] = {
+    "activity.list_for_node": "activity.activity_list_for_node",
+    "activity.list_for_record": "activity.activity_list_for_record",
+    "activity.list_for_record_paged": "activity.activity_list_for_record_paged",
+    "activity.list_paged": "activity.activity_list_paged",
+    "agent.list_tasks": "agent.agent_list_tasks",
+    "agent_tasks.get": "agent_tasks.agent_tasks_get",
+    "agent_tasks.list": "agent_tasks.agent_tasks_list",
+    "assets.confirm": "assets.assets_confirm",
+    "assets.create_text_upload_url": "assets.assets_create_text_upload_url",
+    "assets.create_upload_url": "assets.assets_create_upload_url",
+    "assets.delete": "assets.assets_delete",
+    "assets.download": "assets.assets_download",
+    "assets.edit_content": "assets.assets_edit_content",
+    "assets.get": "assets.assets_get",
+    "assets.list": "assets.assets_list",
+    "assets.put_text": "assets.assets_put_text",
+    "assets.read_text_lines": "assets.assets_read_text_lines",
+    "assets.update_metadata": "assets.assets_update_metadata",
+    "audit_events.create": "audit.audit_events_create",
+    "audit_events.list": "audit.audit_events_list",
+    "auth.verify": "auth.auth_verify",
+    "bases.create": "bases.bases_create",
+    "bases.create_bulk_change_request": "bases.bases_create_bulk_change_request",
+    "bases.create_bulk_update_change_request": "bases.bases_create_bulk_update_change_request",
+    "bases.create_change_request": "bases.bases_create_change_request",
+    "bases.create_field": "bases.bases_create_field",
+    "bases.field_change_request": "bases.bases_field_change_request",
+    "bases.get": "bases.bases_get",
+    "bases.lifecycle_change_request": "bases.bases_lifecycle_change_request",
+    "bases.list": "bases.bases_list",
+    "bases.list_deleted_fields": "bases.bases_list_deleted_fields",
+    "bases.list_views": "views.bases_list_views",
+    "bases.preview_field_conversion": "bases.bases_preview_field_conversion",
+    "change_requests.close": "change_requests.change_requests_close",
+    "change_requests.counts": "change_requests.change_requests_counts",
+    "change_requests.create_preview_link": "change_requests.change_requests_create_preview_link",
+    "change_requests.get": "change_requests.change_requests_get",
+    "change_requests.list": "change_requests.change_requests_list",
+    "change_requests.list_page": "change_requests.change_requests_list_page",
+    "change_requests.merge": "change_requests.change_requests_merge",
+    "change_requests.review": "change_requests.change_requests_review",
+    "comments.create": "comments.comments_create",
+    "comments.list": "comments.comments_list",
+    "comments.list_mentions": "comments.comments_list_mentions",
+    "comments.mark_mentions_read": "comments.comments_mark_mentions_read",
+    "docs.create": "docs.docs_create",
+    "dump.export_asset_text": "dump.dump_export_asset_text",
+    "dump.export_doc_bodies": "dump.dump_export_doc_bodies",
+    "dump.export_tables": "dump.dump_export_tables",
+    "dump.import_abort": "dump.dump_import_abort",
+    "dump.import_begin": "dump.dump_import_begin",
+    "dump.import_commit": "dump.dump_import_commit",
+    "dump.import_tables": "dump.dump_import_tables",
+    "embed_links.create": "embed_links.embed_links_create",
+    "embed_links.list": "embed_links.embed_links_list",
+    "embed_links.list_paged": "embed_links.embed_links_list_paged",
+    "embed_links.revoke": "embed_links.embed_links_revoke",
+    "file_trees.create": "file_trees.file_trees_create",
+    "file_trees.create_change_request": "file_trees.file_trees_create_change_request",
+    "file_trees.list_files": "file_trees.file_trees_list_files",
+    "file_trees.prepare_preview": "file_trees.file_trees_prepare_preview",
+    "file_trees.preview_config": "file_trees.file_trees_preview_config",
+    "file_trees.read_file": "file_trees.file_trees_read_file",
+    "files.create": "files.files_create",
+    "forms.create": "forms.forms_create",
+    "forms.get_by_node": "forms.forms_get_by_node",
+    "forms.list": "forms.forms_list",
+    "forms.submit": "forms.forms_submit",
+    "forms.update": "forms.forms_update",
+    "grep": "search.grep",
+    "guides.list": "guides.guides_list",
+    "guides.read": "guides.guides_read",
+    "install.from_github": "install.install_from_github",
+    "install.plan_from_github": "install.install_plan_from_github",
+    "nodes.ancestors": "nodes.nodes_ancestors",
+    "nodes.create_change_request": "nodes.nodes_create_change_request",
+    "nodes.get": "nodes.nodes_get",
+    "nodes.get_agent_prompts": "nodes.nodes_get_agent_prompts",
+    "nodes.icon.confirm": "nodes.nodes_icon_confirm",
+    "nodes.icon.create_upload_url": "nodes.nodes_icon_create_upload_url",
+    "nodes.is_descendant": "nodes.nodes_is_descendant",
+    "nodes.list": "nodes.nodes_list",
+    "nodes.list_favorites": "nodes.nodes_list_favorites",
+    "nodes.move": "nodes.nodes_move",
+    "nodes.principals.add": "nodes.nodes_principals_add",
+    "nodes.principals.list": "nodes.nodes_principals_list",
+    "nodes.principals.remove": "nodes.nodes_principals_remove",
+    "nodes.purge": "nodes.nodes_purge",
+    "nodes.read_lines": "nodes.nodes_read_lines",
+    "nodes.resolve_route_state": "nodes.nodes_resolve_route_state",
+    "nodes.search_by_name": "nodes.nodes_search_by_name",
+    "nodes.share.disable": "nodes.nodes_share_disable",
+    "nodes.share.get": "nodes.nodes_share_get",
+    "nodes.share.list": "nodes.nodes_share_list",
+    "nodes.share.set": "nodes.nodes_share_set",
+    "nodes.toggle_favorite": "nodes.nodes_toggle_favorite",
+    "nodes.update_agent_prompts": "nodes.nodes_update_agent_prompts",
+    "nodes.update_content": "nodes.nodes_update_content",
+    "nodes.update_metadata": "nodes.nodes_update_metadata",
+    "nodes.update_settings": "nodes.nodes_update_settings",
+    "nodes.update_visibility": "nodes.nodes_update_visibility",
+    "operations.revise": "operations.operations_revise",
+    "playbooks.get": "playbooks.playbooks_get",
+    "playbooks.search": "playbooks.playbooks_search",
+    "records.change_request": "records.records_change_request",
+    "records.count": "records.records_count",
+    "records.get": "records.records_get",
+    "records.group_by": "records.records_group_by",
+    "records.list": "records.records_list",
+    "records.list_change_requests": "records.records_list_change_requests",
+    "records.list_links": "records.records_list_links",
+    "records.list_page": "records.records_list_page",
+    "records.search": "records.records_search",
+    "search": "search.search",
+    "system.health": "system.system_health",
+    "system.meta": "system.system_meta",
+    "templates.list": "templates.templates_list",
+    "users.me": "users.users_me",
+    "views.change_request": "views.views_change_request",
+    "webhooks.create": "webhooks.webhooks_create",
+    "webhooks.delete": "webhooks.webhooks_delete",
+    "webhooks.deliveries": "webhooks.webhooks_deliveries",
+    "webhooks.get": "webhooks.webhooks_get",
+    "webhooks.list": "webhooks.webhooks_list",
+    "webhooks.test_fire": "webhooks.webhooks_test_fire",
+    "webhooks.update": "webhooks.webhooks_update",
+}

busabase/_version.py

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

busabase/generated/__init__.py

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

busabase/generated/api/__init__.py

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

busabase/generated/api/activity/__init__.py

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