h2o-connector-service 0.1.0.dev6001__tar.gz

h2o_connector_service-0.1.0.dev6001/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: h2o-connector-service
+Version: 0.1.0.dev6001
+Summary: Python client SDK for the H2O Connector Service gRPC API
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: grpcio>=1.64
+Requires-Dist: protobuf>=4.25
+Requires-Dist: googleapis-common-protos>=1.72
+Requires-Dist: h2o-cloud-discovery>=3.3.0
+Requires-Dist: h2o-authn>=3.1.0
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == "pandas"
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=14; extra == "parquet"
+Provides-Extra: datatable
+Requires-Dist: datatable>=1.0; extra == "datatable"
+Provides-Extra: h2o
+Requires-Dist: pandas>=1.5; extra == "h2o"
+Requires-Dist: h2o>=3.44; extra == "h2o"
+Requires-Dist: pyarrow>=14; extra == "h2o"
+Provides-Extra: test
+Requires-Dist: pytest<9,>=8.0; extra == "test"
+Requires-Dist: requests>=2.31; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8.0; extra == "dev"
+Requires-Dist: requests>=2.31; extra == "dev"
+Requires-Dist: grpcio-tools>=1.64; extra == "dev"

h2o_connector_service-0.1.0.dev6001/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "h2o-connector-service"
+version = "0.1.0.dev6001"
+description = "Python client SDK for the H2O Connector Service gRPC API"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.27",
+    "grpcio>=1.64",
+    "protobuf>=4.25",
+    "googleapis-common-protos>=1.72",
+    "h2o-cloud-discovery>=3.3.0",
+    "h2o-authn>=3.1.0",
+]
+
+[project.optional-dependencies]
+pandas = ["pandas>=1.5"]
+parquet = ["pyarrow>=14"]
+datatable = ["datatable>=1.0"]
+h2o = ["pandas>=1.5", "h2o>=3.44", "pyarrow>=14"]
+test = [
+    "pytest>=8.0,<9",
+    "requests>=2.31",
+]
+dev = [
+    "pytest>=8.0,<9",
+    "requests>=2.31",
+    "grpcio-tools>=1.64",
+]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+h2o_connector_service = ["gen/**/*.py", "gen/**/*.pyi"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"

h2o_connector_service-0.1.0.dev6001/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

h2o_connector_service-0.1.0.dev6001/src/h2o_connector_service/__init__.py

@@ -0,0 +1,35 @@
+"""connector-service Python SDK — REST control plane + gRPC worker data plane clients."""
+
+from h2o_connector_service._base import Client
+from h2o_connector_service.browse_storage_client import BrowseStorageClient
+from h2o_connector_service.connection_client import ConnectionServiceClient
+from h2o_connector_service.connector_client import ConnectorServiceClient
+from h2o_connector_service.connector_service_facade import ConnectorService
+from h2o_connector_service.connector_session import ConnectorSession
+from h2o_connector_service.connector_template_client import ConnectorTemplateServiceClient
+from h2o_connector_service.data_source_profile_client import DataSourceProfileServiceClient
+from h2o_connector_service.exceptions import ConnectorServiceError
+from h2o_connector_service.grpc_worker_client import WorkerClient
+from h2o_connector_service.models import ConnectionStatus, ConnectorMeta, StorageEntry
+from h2o_connector_service.worker_client import WorkerServiceClient
+from h2o_connector_service.worker_image_client import WorkerImageServiceClient
+from h2o_connector_service.worker_template_client import WorkerTemplateServiceClient
+
+__all__ = [
+    "Client",
+    "BrowseStorageClient",
+    "ConnectionServiceClient",
+    "ConnectionStatus",
+    "ConnectorMeta",
+    "ConnectorService",
+    "ConnectorServiceClient",
+    "ConnectorServiceError",
+    "ConnectorSession",
+    "ConnectorTemplateServiceClient",
+    "DataSourceProfileServiceClient",
+    "StorageEntry",
+    "WorkerClient",
+    "WorkerImageServiceClient",
+    "WorkerServiceClient",
+    "WorkerTemplateServiceClient",
+]

h2o_connector_service-0.1.0.dev6001/src/h2o_connector_service/_base.py

@@ -0,0 +1,141 @@
+"""Base HTTP client for the connector-service Python SDK."""
+
+from __future__ import annotations
+
+import os
+import warnings
+from typing import Callable, Generator
+
+import httpx
+
+from h2o_connector_service.exceptions import ConnectorServiceError
+
+
+class _TokenAuth(httpx.Auth):
+    """Per-request Bearer token injection via callable token provider."""
+
+    def __init__(self, token_provider: Callable[[], str]) -> None:
+        self._token_provider = token_provider
+
+    def auth_flow(
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response, None]:
+        request.headers["Authorization"] = f"Bearer {self._token_provider()}"
+        yield request
+
+
+class Client:
+    """Base httpx client that injects ``Authorization: Bearer <token>`` on every request.
+
+    Args:
+        base_url: Base URL of the api-server (e.g. ``"http://localhost:8080"``).
+        token: OIDC bearer token. Injected as ``Authorization: Bearer <token>``.
+        workspace_id: Default workspace ID for workspace-scoped operations.
+
+    .. deprecated::
+        Use :meth:`from_discovery` instead to construct a client with automatic
+        URL resolution and token refresh from h2o Cloud Discovery.
+    """
+
+    def __init__(self, base_url: str, token: str, workspace_id: str) -> None:
+        warnings.warn(
+            "Client(base_url, token, workspace_id) is deprecated. "
+            "Use Client.from_discovery() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.workspace_id = workspace_id
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            headers={"Authorization": f"Bearer {token}"},
+        )
+
+    @classmethod
+    def from_discovery(
+        cls,
+        environment: str,
+        workspace_id: str,
+        *,
+        token_provider=None,
+    ) -> "Client":
+        """Construct a Client by resolving the connector-service URL from h2o Cloud Discovery.
+
+        Args:
+            environment: H2O Cloud environment URL (e.g. ``"https://cloud.h2o.ai"``).
+            workspace_id: Workspace ID for workspace-scoped operations.
+            token_provider: Optional ``h2o_authn.TokenProvider``. If ``None``,
+                auto-created from discovery credentials.
+
+        Raises:
+            LookupError: If connector-service URL cannot be determined or
+                token provider cannot be created from discovery.
+        """
+        import h2o_discovery
+
+        discovery = None
+        try:
+            discovery = h2o_discovery.discover(environment=environment)
+        except (OSError, ConnectionError, TimeoutError) as e:
+            base_url = os.environ.get("H2O_CONNECTOR_SERVICE_URL")
+            if not base_url:
+                raise LookupError(
+                    "Cannot resolve connector-service from h2o Cloud Discovery and "
+                    "H2O_CONNECTOR_SERVICE_URL is not set."
+                ) from e
+        else:
+            # Resolve connector-service URL with env var fallback (D-11)
+            svc = discovery.services.get("connector-service")
+            if svc is not None:
+                base_url = svc.uri
+            else:
+                base_url = os.environ.get("H2O_CONNECTOR_SERVICE_URL")
+                if not base_url:
+                    raise LookupError(
+                        "connector-service not found in h2o Cloud Discovery and "
+                        "H2O_CONNECTOR_SERVICE_URL is not set."
+                    )
+
+        # Auto-create token provider from discovery credentials (D-05)
+        if token_provider is None:
+            if discovery is None:
+                raise LookupError(
+                    "Cannot create token provider without discovery. "
+                    "Provide token_provider when using H2O_CONNECTOR_SERVICE_URL fallback."
+                )
+            import h2o_authn.discovery as _authn_discovery
+
+            try:
+                token_provider = _authn_discovery.create(discovery)
+            except (KeyError, ValueError) as e:
+                raise LookupError(
+                    "Cannot create token provider from discovery. "
+                    "Configure the H2O CLI or set H2O_CLOUD_CLIENT_PLATFORM_TOKEN."
+                ) from e
+
+        # Build Client bypassing deprecated __init__ (D-12: cached at construction)
+        instance = cls.__new__(cls)
+        instance.base_url = base_url.rstrip("/")
+        instance.token = None  # Not applicable for discovery-based clients
+        instance.workspace_id = workspace_id
+        instance._http = httpx.Client(
+            base_url=instance.base_url,
+            auth=_TokenAuth(token_provider),
+        )
+        return instance
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        """Raise :class:`ConnectorServiceError` if *response* is not 2xx."""
+        if response.is_error:
+            raise ConnectorServiceError(response.status_code, response.text)
+
+    def close(self) -> None:
+        """Close the underlying httpx client."""
+        self._http.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()

h2o_connector_service-0.1.0.dev6001/src/h2o_connector_service/browse_storage_client.py

@@ -0,0 +1,82 @@
+"""REST client for StorageBrowseService (data plane proxy via api-server)."""
+
+from __future__ import annotations
+
+from h2o_connector_service._base import Client
+
+
+class BrowseStorageClient(Client):
+    """Wraps StorageBrowseService.BrowseStorage via the api-server REST proxy.
+
+    The api-server proxies the gRPC ``BrowseStorage`` call to the worker pod
+    identified by *connection_id*. Clients call the api-server HTTP endpoint
+    rather than the worker pod directly, using the workspace OIDC ``authorization``
+    token (Bearer).
+
+    Args:
+        base_url: Base URL of the api-server (e.g. ``"http://localhost:8080"``).
+        token: OIDC bearer token injected as ``Authorization: Bearer <token>``.
+    """
+
+    def __init__(self, base_url: str, token: str) -> None:
+        # workspace_id is not used for connection-scoped browse calls;
+        # the api-server resolves the workspace from the connection record.
+        super().__init__(base_url, token, workspace_id="")
+
+    # ------------------------------------------------------------------
+    # GRPC-04: StorageBrowseService.BrowseStorage
+    # ------------------------------------------------------------------
+
+    def browse(
+        self,
+        connection_id: str,
+        prefix: str = "",
+        delimiter: str = "/",
+        page_size: int = 0,
+        page_token: str = "",
+    ) -> dict:
+        """Browse storage entries for a connection.
+
+        Wraps ``GET /v1alpha/connections/{connection_id}/browse``.
+
+        Args:
+            connection_id: UUID of the connection whose worker pod to browse.
+            prefix: Path prefix to browse (default ``""`` — root).
+            delimiter: Separator for folder-style listing (default ``"/"``).
+                Pass ``""`` for a flat listing of all objects under *prefix*.
+            page_size: Maximum number of entries to return per page
+                (``0`` uses the server default).
+            page_token: Opaque page token returned by a previous call
+                (``""`` for the first page).
+
+        Returns:
+            A dict with the following keys:
+
+            - ``entries``: list of ``StorageEntry`` dicts
+            - ``next_page_token``: empty string when no further pages remain
+            - ``current_prefix``: the effective prefix used for this page
+
+        Raises:
+            :class:`~h2o_connector_service.exceptions.ConnectorServiceError`:
+                If the server returns a non-2xx HTTP status.
+        """
+        params: dict = {}
+        if prefix:
+            params["prefix"] = prefix
+        if delimiter != "/":
+            # Only override when caller explicitly changes the default
+            params["delimiter"] = delimiter
+        if page_size:
+            params["page_size"] = page_size
+        if page_token:
+            params["page_token"] = page_token
+
+        # Always send delimiter so the server gets explicit folder-vs-flat intent
+        params["delimiter"] = delimiter
+
+        resp = self._http.get(
+            f"/v1alpha/connections/{connection_id}/browse",
+            params=params,
+        )
+        self._raise_for_status(resp)
+        return resp.json()

h2o_connector_service-0.1.0.dev6001/src/h2o_connector_service/connection_client.py

@@ -0,0 +1,178 @@
+"""REST client for ConnectionService (control plane)."""
+
+from __future__ import annotations
+
+import time
+from typing import Union
+
+from h2o_connector_service._base import Client
+from h2o_connector_service.models import ConnectionStatus
+
+
+class ConnectionServiceClient:
+    """Wraps ConnectionService REST RPCs.
+
+    Args:
+        client: Authenticated :class:`~h2o_connector_service._base.Client` instance.
+    """
+
+    def __init__(self, client: Client) -> None:
+        self._c = client
+
+    # ------------------------------------------------------------------
+    # CRUD RPCs
+    # ------------------------------------------------------------------
+
+    def create_connection(self, workspace_id: str, connection: dict) -> dict:
+        """Create a new connection (POST /v1alpha/workspaces/{workspace_id}/connections)."""
+        resp = self._c._http.post(
+            f"/v1alpha/workspaces/{workspace_id}/connections",
+            json={"connection": connection},
+        )
+        self._c._raise_for_status(resp)
+        return resp.json()
+
+    def get_connection(self, workspace_id: str, connection_id: str) -> dict:
+        """Get a connection by ID (GET /v1alpha/workspaces/{workspace_id}/connections/{connection_id})."""
+        resp = self._c._http.get(
+            f"/v1alpha/workspaces/{workspace_id}/connections/{connection_id}",
+        )
+        self._c._raise_for_status(resp)
+        return resp.json()
+
+    def list_connections(self, workspace_id: str, **params: object) -> dict:
+        """List connections in a workspace (GET /v1alpha/workspaces/{workspace_id}/connections).
+
+        Optional keyword params are forwarded as query parameters
+        (e.g., ``page_size``, ``page_token``, ``filter``, ``order_by``).
+        """
+        resp = self._c._http.get(
+            f"/v1alpha/workspaces/{workspace_id}/connections",
+            params={k: v for k, v in params.items() if v is not None},
+        )
+        self._c._raise_for_status(resp)
+        return resp.json()
+
+    def cancel_connection(self, workspace_id: str, connection_id: str) -> dict:
+        """Cancel a running connection (POST .../connections/{connection_id}:cancel)."""
+        resp = self._c._http.post(
+            f"/v1alpha/workspaces/{workspace_id}/connections/{connection_id}:cancel",
+            json={},
+        )
+        self._c._raise_for_status(resp)
+        return resp.json()
+
+    def pause_connection(
+        self, workspace_id: str, connection_id: str, reason: str = ""
+    ) -> dict:
+        """Pause a running connection (POST .../connections/{connection_id}:pause)."""
+        body: dict = {}
+        if reason:
+            body["reason"] = reason
+        resp = self._c._http.post(
+            f"/v1alpha/workspaces/{workspace_id}/connections/{connection_id}:pause",
+            json=body,
+        )
+        self._c._raise_for_status(resp)
+        return resp.json()
+
+    def resume_connection(self, workspace_id: str, connection_id: str) -> dict:
+        """Resume a paused connection (POST .../connections/{connection_id}:resume)."""
+        resp = self._c._http.post(
+            f"/v1alpha/workspaces/{workspace_id}/connections/{connection_id}:resume",
+            json={},
+        )
+        self._c._raise_for_status(resp)
+        return resp.json()
+
+    def delete_connection(self, workspace_id: str, connection_id: str) -> None:
+        """Delete a connection (DELETE /v1alpha/workspaces/{workspace_id}/connections/{connection_id})."""
+        resp = self._c._http.delete(
+            f"/v1alpha/workspaces/{workspace_id}/connections/{connection_id}",
+        )
+        self._c._raise_for_status(resp)
+
+    def generate_connection_token(self, workspace_id: str, connection_id: str) -> dict:
+        """Generate an auth token for a connection (POST .../connections/{connection_id}:generateToken).
+
+        Returns a dict with ``auth_token`` key containing the bearer token
+        for authenticating with the worker gRPC endpoint.
+        """
+        resp = self._c._http.post(
+            f"/v1alpha/workspaces/{workspace_id}/connections/{connection_id}:generateToken",
+            json={},
+        )
+        self._c._raise_for_status(resp)
+        return resp.json()
+
+    def revoke_connection_token(self, workspace_id: str, connection_id: str, auth_token: str) -> dict:
+        """Revoke an auth token for a connection (POST .../connections/{connection_id}:revokeToken).
+
+        The token is immediately invalidated; the connection itself remains active.
+        Returns an empty dict on success (proto Empty / RevokeConnectionTokenResponse).
+        """
+        resp = self._c._http.post(
+            f"/v1alpha/workspaces/{workspace_id}/connections/{connection_id}:revokeToken",
+            json={"auth_token": auth_token},
+        )
+        self._c._raise_for_status(resp)
+        return resp.json()
+
+    # ------------------------------------------------------------------
+    # Typed status accessor
+    # ------------------------------------------------------------------
+
+    def get_connection_status(self, workspace_id: str, connection_id: str) -> ConnectionStatus:
+        """Get a typed connection status snapshot.
+
+        Wraps :meth:`get_connection` and returns a :class:`ConnectionStatus`
+        dataclass with ``connection_id``, ``status``, and ``worker_endpoint`` fields.
+        """
+        raw = self.get_connection(workspace_id, connection_id)
+        return ConnectionStatus.from_dict(raw)
+
+    # ------------------------------------------------------------------
+    # Polling helper (REST-07)
+    # ------------------------------------------------------------------
+
+    def poll_connection_status(
+        self,
+        workspace_id: str,
+        connection_id: str,
+        until_status: Union[str, list[str]],
+        interval: float = 2.0,
+        timeout: float = 300.0,
+    ) -> dict:
+        """Poll :meth:`get_connection` until the connection reaches a target status.
+
+        Replaces ``WatchConnection`` (server-streaming SSE) which is not
+        supported by the gRPC-Gateway configuration in this project.
+
+        Args:
+            workspace_id: Workspace that owns the connection.
+            connection_id: UUID of the connection to watch.
+            until_status: Target status string or list of status strings
+                (e.g. ``"CONNECTION_STATUS_WORKER_READY"`` or
+                ``["CONNECTION_STATUS_WORKER_READY", "CONNECTION_STATUS_WORKER_ACTIVE"]``).
+            interval: Polling interval in seconds (default 2.0).
+            timeout: Maximum total wait time in seconds (default 300.0).
+
+        Returns:
+            The connection dict when a target status is reached.
+
+        Raises:
+            TimeoutError: If the connection does not reach *until_status* within *timeout* seconds.
+        """
+        if isinstance(until_status, str):
+            until_status = [until_status]
+        deadline = time.monotonic() + timeout
+        while True:
+            conn = self.get_connection(workspace_id, connection_id)
+            if conn.get("status") in until_status:
+                return conn
+            if time.monotonic() >= deadline:
+                raise TimeoutError(
+                    f"Connection {connection_id!r} did not reach {until_status!r} "
+                    f"within {timeout}s"
+                )
+            time.sleep(interval)

h2o_connector_service-0.1.0.dev6001/src/h2o_connector_service/connector_client.py

@@ -0,0 +1,85 @@
+"""REST client for ConnectorService (control plane)."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from h2o_connector_service._base import Client
+
+
+class ConnectorServiceClient:
+    """Wraps ConnectorService REST RPCs (workspace-scoped connectors).
+
+    Args:
+        client: Authenticated :class:`~h2o_connector_service._base.Client` instance.
+    """
+
+    def __init__(self, client: Client) -> None:
+        self._c = client
+
+    def create_connector(self, workspace_id: str, connector: dict) -> dict:
+        """Create a new connector (POST /v1alpha/workspaces/{workspace_id}/connectors).
+
+        Args:
+            workspace_id: Workspace to create the connector in.
+            connector: Connector resource dict (sent as ``{"connector": connector}`` body).
+        """
+        resp = self._c._http.post(
+            f"/v1alpha/workspaces/{workspace_id}/connectors",
+            json={"connector": connector},
+        )
+        self._c._raise_for_status(resp)
+        return resp.json()
+
+    def get_connector(self, name: str) -> dict:
+        """Get a connector by resource name (GET /v1alpha/{name}).
+
+        Args:
+            name: Full resource name, e.g. ``"workspaces/my-ws/connectors/my-connector"``.
+        """
+        resp = self._c._http.get(f"/v1alpha/{name}")
+        self._c._raise_for_status(resp)
+        return resp.json()
+
+    def list_connectors(self, workspace_id: str, **params: object) -> dict:
+        """List connectors in a workspace (GET /v1alpha/workspaces/{workspace_id}/connectors).
+
+        Optional keyword params are forwarded as query parameters
+        (e.g., ``page_size``, ``page_token``, ``filter``, ``order_by``).
+        """
+        resp = self._c._http.get(
+            f"/v1alpha/workspaces/{workspace_id}/connectors",
+            params={k: v for k, v in params.items() if v is not None},
+        )
+        self._c._raise_for_status(resp)
+        return resp.json()
+
+    def update_connector(
+        self, connector: dict, update_mask: Optional[str] = None
+    ) -> dict:
+        """Update a connector (PATCH /v1alpha/{connector.metadata.name}).
+
+        Args:
+            connector: Connector dict with ``metadata.name`` set to the full resource name.
+            update_mask: Comma-separated field mask (e.g. ``"enabled,flow_control"``).
+        """
+        name = connector["metadata"]["name"]
+        params: dict = {}
+        if update_mask:
+            params["update_mask"] = update_mask
+        resp = self._c._http.patch(
+            f"/v1alpha/{name}",
+            json={"connector": connector},
+            params=params,
+        )
+        self._c._raise_for_status(resp)
+        return resp.json()
+
+    def delete_connector(self, name: str) -> None:
+        """Delete a connector (DELETE /v1alpha/{name}).
+
+        Args:
+            name: Full resource name, e.g. ``"workspaces/my-ws/connectors/my-connector"``.
+        """
+        resp = self._c._http.delete(f"/v1alpha/{name}")
+        self._c._raise_for_status(resp)