phenoworks-sdk 0.1.0__py3-none-any.whl

phenoworks_sdk/__init__.py

@@ -0,0 +1,27 @@
+"""Standalone Python and async clients for the PhenoWorks HTTP API."""
+
+from .async_client import AsyncPhenoWorksClient, AsyncPipelineRun
+from .client import PhenoWorksClient, PipelineRun
+from .errors import (
+    AuthenticationError,
+    NotFoundError,
+    PermissionDeniedError,
+    PhenoWorksAPIError,
+    PhenoWorksError,
+    PipelineFailedError,
+    PipelineTimeoutError,
+)
+
+__all__ = [
+    "PhenoWorksClient",
+    "AsyncPhenoWorksClient",
+    "PipelineRun",
+    "AsyncPipelineRun",
+    "PhenoWorksError",
+    "PhenoWorksAPIError",
+    "AuthenticationError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "PipelineFailedError",
+    "PipelineTimeoutError",
+]

phenoworks_sdk/__main__.py

@@ -0,0 +1,6 @@
+"""Allow python -m phenoworks_sdk to run the CLI."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

phenoworks_sdk/_common.py

@@ -0,0 +1,110 @@
+"""Transport validation and atomic local download helpers."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import BinaryIO
+from urllib.parse import unquote, urlsplit, urlunsplit
+
+import httpx
+
+from .errors import AuthenticationError, NotFoundError, PermissionDeniedError, PhenoWorksAPIError
+
+
+def normalize_base_url(value: str) -> str:
+    """Normalize value, an HTTP(S) server or API URL, to an API root ending in /.
+
+    Returns:
+        Validated API base URL, preserving reverse-proxy path prefixes.
+    Raises:
+        ValueError: Credentials, query strings, fragments, or non-HTTP URLs were supplied.
+    """
+    parts = urlsplit(value.strip())
+    if (
+        parts.scheme not in {"https", "http"}
+        or not parts.netloc
+        or parts.username
+        or parts.password
+        or parts.query
+        or parts.fragment
+    ):
+        raise ValueError(
+            "base_url must be an HTTP(S) server URL without credentials, query, or fragment."
+        )
+    path = parts.path.rstrip("/")
+    if not path.endswith("/api"):
+        path += "/api"
+    return urlunsplit((parts.scheme, parts.netloc, path + "/", "", ""))
+
+
+def api_path(value: str) -> str:
+    """Validate value as an API-relative path and return it without the /api prefix.
+
+    Raises:
+        ValueError: The path could escape the configured API root.
+    """
+    parts = urlsplit(value)
+    decoded = unquote(value)
+    if (
+        parts.scheme
+        or parts.netloc
+        or parts.query
+        or parts.fragment
+        or "\\" in decoded
+        or any(p in {".", ".."} for p in decoded.split("/"))
+    ):
+        raise ValueError("Use an API-relative path and pass query parameters through params.")
+    return value.removeprefix("/api/").lstrip("/")
+
+
+def check_response(response: httpx.Response, api_key: str = "") -> None:
+    """Raise a typed error for an unsuccessful response, redacting api_key.
+
+    Args:
+        response: Response whose error body has been read.
+        api_key: Credential to remove from server error text.
+    Raises:
+        PhenoWorksAPIError: Any non-2xx response, including redirects.
+    """
+    if response.is_success:
+        return
+    detail = response.text[:4000]
+    if api_key:
+        detail = detail.replace(api_key, "[REDACTED]")
+    error = {401: AuthenticationError, 403: PermissionDeniedError, 404: NotFoundError}.get(
+        response.status_code, PhenoWorksAPIError
+    )
+    raise error(response.status_code, detail)
+
+
+@contextmanager
+def atomic_download(destination: str | Path, overwrite: bool) -> Iterator[tuple[Path, BinaryIO]]:
+    """Write a unique temporary file and publish it only after success.
+
+    Args:
+        destination: Exact destination filename; filenames from HTTP are never trusted.
+        overwrite: Allow replacing an existing destination.
+    Yields:
+        Destination path and writable temporary stream.
+    Raises:
+        FileExistsError: Destination exists and overwrite is false.
+    """
+    target = Path(destination).expanduser()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if target.exists() and not overwrite:
+        raise FileExistsError(target)
+    fd, name = tempfile.mkstemp(prefix=f".{target.name}.", suffix=".part", dir=target.parent)
+    temporary = Path(name)
+    try:
+        with os.fdopen(fd, "wb") as output:
+            yield target, output
+        if overwrite:
+            os.replace(temporary, target)
+        else:
+            os.link(temporary, target)
+    finally:
+        temporary.unlink(missing_ok=True)