gestalt-sdk 0.0.1a8__tar.gz

gestalt_sdk-0.0.1a8/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: gestalt-sdk
+Version: 0.0.1a8
+Summary: Python SDK for Gestalt executable providers
+Requires-Python: >=3.10
+Requires-Dist: grpcio<2,>=1.80.0
+Requires-Dist: pyyaml==6.0.3
+Requires-Dist: pyinstaller<7
+Requires-Dist: protobuf<8,>=6.33.1
+Requires-Dist: typing-extensions==4.12.2

gestalt_sdk-0.0.1a8/README.md

@@ -0,0 +1,105 @@
+# Gestalt Python SDK
+
+This package provides the Python authoring surface for executable Gestalt
+providers.
+
+It is intended to be used by source providers discovered through
+`[tool.gestalt].provider` in `pyproject.toml` (or the legacy
+`[tool.gestalt].plugin` key) and by packaged providers built from that
+same source tree.
+
+Python source providers are developed locally via `from.source.path` and
+released through `gestaltd provider release` for the host platform by default,
+or for every requested target platform when you pass `--platform`. In CI,
+prefer `--platform all` to build the full supported release matrix.
+
+For non-host targets, configure a matching Python build interpreter with
+`GESTALT_PYTHON_<GOOS>_<GOARCH>` or a target-specific virtualenv such as
+`.venv-<goos>-<goarch>/`.
+
+## Regenerating Protobuf Stubs
+
+The checked-in Python protobuf stubs live in `gestalt/gen/v1`.
+
+This is an SDK maintainer workflow. Provider authors consume the checked-in
+stubs through the `gestalt` package and do not need to regenerate them in
+provider repositories.
+
+Regenerate them from the repo root with:
+
+```sh
+uv run python sdk/python/scripts/generate_stubs.py
+```
+
+The script uses pinned `buf` remote Python plugins so the generated stubs stay
+reproducible while `plugin_pb2.py` tracks the protobuf `6.33.1` runtime floor
+used by this SDK package and remains compatible with protobuf 7 runtimes.
+`buf` must be available on `PATH`.
+
+## Publishing
+
+The SDK is published as the `gestalt` package to a private Python index.
+
+Release tags stay aligned with the repo's SDK tag convention:
+
+- `sdk/python/v0.0.1`
+- `sdk/python/v0.0.1-alpha.1`
+- `sdk/python/v0.0.1-beta.1`
+- `sdk/python/v0.0.1-rc.1`
+
+The release workflow normalizes those tag versions to PEP 440 before building
+and publishing with `uv`, so `sdk/python/v0.0.1-alpha.1` becomes package
+version `0.0.1a1`.
+
+The GitHub Actions workflow expects these repository secrets:
+
+- `GESTALT_PYTHON_PUBLISH_URL`
+- either `GESTALT_PYTHON_PUBLISH_TOKEN`
+- or `GESTALT_PYTHON_PUBLISH_USERNAME` and `GESTALT_PYTHON_PUBLISH_PASSWORD`
+
+## Consuming From A Private Index
+
+In an internal provider repo, pin `gestalt` to the private index with `uv` so
+the package does not fall back to PyPI:
+
+```toml
+[[tool.uv.index]]
+name = "valon-internal"
+url = "https://packages.example.com/simple"
+explicit = true
+authenticate = "always"
+
+[tool.uv.sources]
+gestalt = { index = "valon-internal" }
+
+[project]
+dependencies = ["gestalt==0.0.1a1"]
+```
+
+At install time, provide credentials via the environment variables derived from
+the index name:
+
+```sh
+export UV_INDEX_VALON_INTERNAL_USERNAME=...
+export UV_INDEX_VALON_INTERNAL_PASSWORD=...
+```
+
+That lets `~/src/gestalt-providers` depend on `gestalt` like any other Python
+package while keeping the SDK off the public package indexes.
+
+## Local SDK Checks
+
+From `sdk/python`, install the SDK plus its dev tooling and run the checks used
+in CI:
+
+```sh
+uv sync --group dev
+uv run ruff check .
+uv run ty check --exclude 'gestalt/gen/**' gestalt scripts tests
+uv run vulture --config pyproject.toml
+uv run python -m unittest discover -s tests
+```
+
+The generated protobuf stubs under `gestalt/gen` are excluded from the static
+analysis tools because they are vendored output rather than hand-maintained SDK
+code.

gestalt_sdk-0.0.1a8/gestalt/__init__.py

@@ -0,0 +1,151 @@
+from ._api import (
+    OK,
+    Access,
+    Credential,
+    Error,
+    Model,
+    Request,
+    Response,
+    Subject,
+    field,
+)
+from ._cache import Cache, CacheEntry, cache_socket_env
+from ._catalog import (
+    Catalog,
+    CatalogOperation,
+    CatalogParameter,
+    OperationAnnotations,
+    SessionCatalogProvider,
+)
+from ._indexeddb import (
+    CURSOR_NEXT,
+    CURSOR_NEXT_UNIQUE,
+    CURSOR_PREV,
+    CURSOR_PREV_UNIQUE,
+    AlreadyExistsError,
+    Cursor,
+    Index,
+    IndexedDB,
+    IndexSchema,
+    KeyRange,
+    NotFoundError,
+    ObjectStore,
+    ObjectStoreSchema,
+    indexeddb_socket_env,
+)
+from ._plugin import Plugin, operation, session_catalog
+from ._providers import (
+    AuthenticatedUser,
+    AuthProvider,
+    BeginLoginRequest,
+    BeginLoginResponse,
+    CacheProvider,
+    Closer,
+    CompleteLoginRequest,
+    ExternalTokenValidator,
+    HealthChecker,
+    MetadataProvider,
+    PluginProvider,
+    PluginProviderAdapter,
+    ProviderKind,
+    ProviderMetadata,
+    S3Provider,
+    SecretsProvider,
+    SessionTTLProvider,
+    WarningsProvider,
+)
+from ._s3 import (
+    ENV_S3_SOCKET,
+    S3,
+    ByteRange,
+    CopyOptions,
+    ListOptions,
+    ListPage,
+    ObjectMeta,
+    ObjectRef,
+    PresignMethod,
+    PresignOptions,
+    PresignResult,
+    ReadOptions,
+    S3InvalidRangeError,
+    S3NotFoundError,
+    S3Object,
+    S3PreconditionFailedError,
+    S3ReadStream,
+    WriteOptions,
+    s3_socket_env,
+)
+
+__all__ = [
+    "AlreadyExistsError",
+    "AuthProvider",
+    "AuthenticatedUser",
+    "Cache",
+    "CacheEntry",
+    "CacheProvider",
+    "Access",
+    "BeginLoginRequest",
+    "BeginLoginResponse",
+    "CURSOR_NEXT",
+    "CURSOR_NEXT_UNIQUE",
+    "CURSOR_PREV",
+    "CURSOR_PREV_UNIQUE",
+    "Catalog",
+    "CatalogOperation",
+    "CatalogParameter",
+    "Credential",
+    "Closer",
+    "CompleteLoginRequest",
+    "Cursor",
+    "Error",
+    "ENV_S3_SOCKET",
+    "ExternalTokenValidator",
+    "HealthChecker",
+    "Index",
+    "IndexedDB",
+    "IndexSchema",
+    "KeyRange",
+    "ListOptions",
+    "ListPage",
+    "MetadataProvider",
+    "Model",
+    "NotFoundError",
+    "OK",
+    "ObjectMeta",
+    "ObjectRef",
+    "ObjectStore",
+    "ObjectStoreSchema",
+    "OperationAnnotations",
+    "Plugin",
+    "PluginProvider",
+    "PluginProviderAdapter",
+    "PresignMethod",
+    "PresignOptions",
+    "PresignResult",
+    "ProviderKind",
+    "ProviderMetadata",
+    "Request",
+    "Response",
+    "ReadOptions",
+    "S3",
+    "S3InvalidRangeError",
+    "S3NotFoundError",
+    "S3Object",
+    "S3PreconditionFailedError",
+    "S3Provider",
+    "S3ReadStream",
+    "SecretsProvider",
+    "Subject",
+    "SessionCatalogProvider",
+    "SessionTTLProvider",
+    "WarningsProvider",
+    "cache_socket_env",
+    "WriteOptions",
+    "ByteRange",
+    "CopyOptions",
+    "field",
+    "indexeddb_socket_env",
+    "operation",
+    "s3_socket_env",
+    "session_catalog",
+]

gestalt_sdk-0.0.1a8/gestalt/_api.py

@@ -0,0 +1,99 @@
+import dataclasses
+from dataclasses import MISSING
+from http import HTTPStatus
+from typing import Any, Final, Generic, TypeVar
+
+from typing_extensions import dataclass_transform
+
+FIELD_DESCRIPTION_KEY: Final[str] = "description"
+FIELD_REQUIRED_KEY: Final[str] = "required"
+
+T = TypeVar("T")
+
+
+@dataclasses.dataclass(slots=True)
+class Subject:
+    id: str = ""
+    kind: str = ""
+    display_name: str = ""
+    auth_source: str = ""
+
+
+@dataclasses.dataclass(slots=True)
+class Credential:
+    mode: str = ""
+    subject_id: str = ""
+    connection: str = ""
+    instance: str = ""
+
+
+@dataclasses.dataclass(slots=True)
+class Access:
+    policy: str = ""
+    role: str = ""
+
+
+@dataclasses.dataclass(slots=True)
+class Request:
+    token: str = ""
+    connection_params: dict[str, str] = dataclasses.field(default_factory=dict)
+    subject: Subject = dataclasses.field(default_factory=Subject)
+    credential: Credential = dataclasses.field(default_factory=Credential)
+    access: Access = dataclasses.field(default_factory=Access)
+
+    def connection_param(self, name: str) -> str | None:
+        return self.connection_params.get(name)
+
+
+@dataclasses.dataclass(slots=True)
+class Response(Generic[T]):
+    status: int | None
+    body: T
+
+
+def OK(body: T) -> Response[T]:
+    return Response(status=HTTPStatus.OK, body=body)
+
+
+class Error(Exception):
+    def __init__(self, status: int | HTTPStatus, message: str = "") -> None:
+        self.status = int(status)
+        if message:
+            self.message = message
+        else:
+            try:
+                self.message = HTTPStatus(self.status).phrase
+            except ValueError:
+                self.message = ""
+        super().__init__(self.message)
+
+
+def field(
+    *,
+    description: str = "",
+    default: Any = MISSING,
+    default_factory: Any = MISSING,
+    required: bool | None = None,
+) -> Any:
+    metadata: dict[str, Any] = {}
+    if description:
+        metadata[FIELD_DESCRIPTION_KEY] = description
+    if required is not None:
+        metadata[FIELD_REQUIRED_KEY] = required
+
+    kwargs: dict[str, Any] = {"metadata": metadata}
+    if default is not MISSING:
+        kwargs["default"] = default
+    if default_factory is not MISSING:
+        kwargs["default_factory"] = default_factory
+    return dataclasses.field(**kwargs)
+
+
+@dataclass_transform(field_specifiers=(field,))
+class Model:
+    """Base class for operation input/output types. Subclasses are automatically dataclasses."""
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if "__dataclass_fields__" not in cls.__dict__:
+            dataclasses.dataclass(cls)

gestalt_sdk-0.0.1a8/gestalt/_bootstrap.py

@@ -0,0 +1,80 @@
+import json
+import pathlib
+from dataclasses import dataclass
+from typing import Final
+
+BUNDLED_CONFIG_NAME: Final[str] = "gestalt-runtime.json"
+
+
+@dataclass(frozen=True)
+class PluginTarget:
+    module_name: str
+    attribute_name: str | None = None
+
+
+@dataclass(frozen=True)
+class BundledPluginConfig:
+    target: str
+    plugin_name: str | None = None
+    runtime_kind: str | None = None
+
+
+def parse_plugin_target(target: str) -> PluginTarget:
+    module_name, sep, attribute_name = target.partition(":")
+    module_name = module_name.strip()
+    attribute_name = attribute_name.strip() or None
+    if not module_name:
+        raise RuntimeError("tool.gestalt.provider or tool.gestalt.plugin must be in module or module:attribute form")
+    if sep and attribute_name is None:
+        raise RuntimeError("tool.gestalt.provider or tool.gestalt.plugin attribute is required when ':' is present")
+
+    return PluginTarget(
+        module_name=module_name,
+        attribute_name=attribute_name,
+    )
+
+
+def read_bundled_plugin_config(*, bundle_root: pathlib.Path) -> BundledPluginConfig | None:
+    config_path = bundle_root / BUNDLED_CONFIG_NAME
+    if not config_path.exists():
+        return None
+
+    data = json.loads(config_path.read_text(encoding="utf-8"))
+    target = str(data.get("target", "")).strip()
+    if not target:
+        raise RuntimeError(f"{config_path} is missing target")
+
+    plugin_name = data.get("plugin_name")
+    if plugin_name is not None:
+        plugin_name = str(plugin_name).strip() or None
+
+    runtime_kind = data.get("runtime_kind")
+    if runtime_kind is not None:
+        runtime_kind = str(runtime_kind).strip() or None
+
+    return BundledPluginConfig(
+        target=target,
+        plugin_name=plugin_name,
+        runtime_kind=runtime_kind,
+    )
+
+
+def write_bundled_plugin_config(
+    path: pathlib.Path,
+    *,
+    target: str,
+    plugin_name: str,
+    runtime_kind: str,
+) -> None:
+    path.write_text(
+        json.dumps(
+            {
+                "target": target,
+                "plugin_name": plugin_name,
+                "runtime_kind": runtime_kind,
+            }
+        ),
+        encoding="utf-8",
+    )
+
+

gestalt_sdk-0.0.1a8/gestalt/_build.py

@@ -0,0 +1,134 @@
+import os
+import pathlib
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass
+from typing import Final
+
+from ._bootstrap import (
+    BUNDLED_CONFIG_NAME,
+    parse_plugin_target,
+    write_bundled_plugin_config,
+)
+
+USAGE: Final[str] = "usage: python -m gestalt._build ROOT MODULE[:ATTRIBUTE] OUTPUT PLUGIN_NAME RUNTIME_KIND GOOS GOARCH"
+
+
+@dataclass(frozen=True)
+class BuildArgs:
+    root: pathlib.Path
+    target: str
+    output_path: pathlib.Path
+    plugin_name: str
+    runtime_kind: str
+    goos: str
+    goarch: str
+
+
+def main(argv: list[str] | None = None) -> int:
+    build_args = _parse_build_args(sys.argv[1:] if argv is None else argv)
+    if build_args is None:
+        print(USAGE, file=sys.stderr)
+        return 2
+
+    build_plugin_binary(build_args)
+    return 0
+
+
+def _parse_build_args(args: list[str]) -> BuildArgs | None:
+    if len(args) != 7:
+        return None
+
+    root, target, output_path, plugin_name, runtime_kind, goos, goarch = args
+    return BuildArgs(
+        root=pathlib.Path(root),
+        target=target,
+        output_path=pathlib.Path(output_path),
+        plugin_name=plugin_name,
+        runtime_kind=runtime_kind,
+        goos=goos,
+        goarch=goarch,
+    )
+
+
+def build_plugin_binary(args: BuildArgs) -> None:
+    root_path = args.root.resolve()
+    output_path = args.output_path.resolve()
+    plugin_target = parse_plugin_target(args.target)
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix="gestalt-python-release-") as work_dir:
+        work_path = pathlib.Path(work_dir)
+        bundle_config_path = work_path / BUNDLED_CONFIG_NAME
+        write_bundled_plugin_config(
+            bundle_config_path,
+            target=args.target,
+            plugin_name=args.plugin_name,
+            runtime_kind=args.runtime_kind,
+        )
+
+        subprocess.run(
+            _pyinstaller_command(
+                root_path=root_path,
+                output_path=output_path,
+                module_name=plugin_target.module_name,
+                bundle_config_path=bundle_config_path,
+                target_goos=args.goos,
+                target_goarch=args.goarch,
+            ),
+            cwd=root_path,
+            check=True,
+        )
+
+
+def _pyinstaller_command(
+    *,
+    root_path: pathlib.Path,
+    output_path: pathlib.Path,
+    module_name: str,
+    bundle_config_path: pathlib.Path,
+    target_goos: str,
+    target_goarch: str,
+) -> list[str]:
+    pyinstaller_name = output_path.name.removesuffix(".exe") if target_goos == "windows" else output_path.name
+
+    command = [
+        sys.executable,
+        "-m",
+        "PyInstaller",
+        "--noconfirm",
+        "--clean",
+        "--onefile",
+        "--distpath",
+        str(output_path.parent),
+        "--workpath",
+        str(bundle_config_path.parent / "build"),
+        "--specpath",
+        str(bundle_config_path.parent / "spec"),
+        "--name",
+        pyinstaller_name,
+        "--hidden-import",
+        module_name,
+        "--paths",
+        str(root_path),
+        "--add-data",
+        f"{bundle_config_path}{os.pathsep}.",
+        str(pathlib.Path(__file__).with_name("_pyinstaller.py")),
+    ]
+    if sys.platform == "darwin" and target_goos == "darwin":
+        target_arch = _darwin_target_arch(target_goarch)
+        if target_arch:
+            command.extend(["--target-arch", target_arch])
+    return command
+
+
+def _darwin_target_arch(goarch: str) -> str | None:
+    return {
+        "amd64": "x86_64",
+        "arm64": "arm64",
+    }.get(goarch)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

gestalt_sdk-0.0.1a8/gestalt/_cache.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import datetime as _dt
+import os
+from dataclasses import dataclass
+from typing import Any, Iterable
+
+import grpc
+from google.protobuf import duration_pb2 as _duration_pb2
+
+from .gen.v1 import cache_pb2 as _pb
+from .gen.v1 import cache_pb2_grpc as _pb_grpc
+
+pb: Any = _pb
+pb_grpc: Any = _pb_grpc
+duration_pb2: Any = _duration_pb2
+
+ENV_CACHE_SOCKET = "GESTALT_CACHE_SOCKET"
+
+
+def cache_socket_env(name: str | None = None) -> str:
+    trimmed = (name or "").strip()
+    if not trimmed:
+        return ENV_CACHE_SOCKET
+    normalized = "".join(
+        ch.upper() if ch.isascii() and ch.isalnum() else "_" for ch in trimmed
+    )
+    return f"{ENV_CACHE_SOCKET}_{normalized}"
+
+
+@dataclass(frozen=True)
+class CacheEntry:
+    key: str
+    value: bytes
+
+
+class Cache:
+    def __init__(self, name: str | None = None) -> None:
+        env_name = cache_socket_env(name)
+        socket_path = os.environ.get(env_name, "")
+        if not socket_path:
+            raise RuntimeError(f"{env_name} is not set")
+        self._channel = grpc.insecure_channel(f"unix:{socket_path}")
+        self._stub = pb_grpc.CacheStub(self._channel)
+
+    def close(self) -> None:
+        self._channel.close()
+
+    def get(self, key: str) -> bytes | None:
+        resp = _grpc_call(self._stub.Get, pb.CacheGetRequest(key=key))
+        if not resp.found:
+            return None
+        return bytes(resp.value)
+
+    def get_many(self, keys: list[str]) -> dict[str, bytes]:
+        resp = _grpc_call(self._stub.GetMany, pb.CacheGetManyRequest(keys=keys))
+        out: dict[str, bytes] = {}
+        for entry in resp.entries:
+            if entry.found:
+                out[entry.key] = bytes(entry.value)
+        return out
+
+    def set(
+        self,
+        key: str,
+        value: bytes,
+        ttl: _dt.timedelta | None = None,
+    ) -> None:
+        _grpc_call(
+            self._stub.Set,
+            pb.CacheSetRequest(key=key, value=bytes(value), ttl=_duration_from_ttl(ttl)),
+        )
+
+    def set_many(
+        self,
+        entries: Iterable[CacheEntry],
+        ttl: _dt.timedelta | None = None,
+    ) -> None:
+        _grpc_call(
+            self._stub.SetMany,
+            pb.CacheSetManyRequest(
+                entries=[
+                    pb.CacheSetEntry(key=entry.key, value=bytes(entry.value))
+                    for entry in entries
+                ],
+                ttl=_duration_from_ttl(ttl),
+            ),
+        )
+
+    def delete(self, key: str) -> bool:
+        resp = _grpc_call(self._stub.Delete, pb.CacheDeleteRequest(key=key))
+        return bool(resp.deleted)
+
+    def delete_many(self, keys: list[str]) -> int:
+        resp = _grpc_call(self._stub.DeleteMany, pb.CacheDeleteManyRequest(keys=keys))
+        return int(resp.deleted)
+
+    def touch(self, key: str, ttl: _dt.timedelta) -> bool:
+        resp = _grpc_call(
+            self._stub.Touch,
+            pb.CacheTouchRequest(key=key, ttl=_duration_from_ttl(ttl)),
+        )
+        return bool(resp.touched)
+
+    def __enter__(self) -> Cache:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+def _duration_from_ttl(ttl: _dt.timedelta | None) -> Any:
+    if ttl is None:
+        return None
+    if ttl.total_seconds() <= 0:
+        return None
+    duration = duration_pb2.Duration()
+    duration.FromTimedelta(ttl)
+    return duration
+
+
+def _grpc_call(method: Any, request: Any) -> Any:
+    try:
+        return method(request)
+    except grpc.RpcError:
+        raise