tilebox-core 0.68.0__tar.gz

tilebox_core-0.68.0/.gitignore

@@ -0,0 +1,23 @@
+.venv/
+
+__pycache__/
+.ipynb_checkpoints/
+.virtual_documents/
+
+.idea/
+
+.hypothesis/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+dist/
+
+coverage.xml
+.coverage*
+test-report.xml
+
+*.egg-info/
+
+.amp/*
+!.amp/services.yaml

tilebox_core-0.68.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.5
+Name: tilebox-core
+Version: 0.68.0
+Summary: Shared types and client infrastructure for Tilebox
+Project-URL: Homepage, https://tilebox.com
+Project-URL: Documentation, https://docs.tilebox.com/
+Author-email: "Tilebox, Inc." <support@tilebox.com>
+License: MIT License
+Requires-Python: >=3.11
+Requires-Dist: anyio>=4
+Requires-Dist: connectrpc<0.14,>=0.13.0
+Requires-Dist: protobuf-py<0.8,>=0.7.0
+Requires-Dist: pyqwest>=0.7.0
+Description-Content-Type: text/markdown
+
+# Tilebox Core
+
+Shared types and client infrastructure for the Tilebox Python SDKs.
+
+Public imports are `tilebox.query` for `TimeInterval`, `IDInterval`, and `Pagination`,
+and `tilebox.errors` for SDK exceptions. The `_tilebox` namespace contains private
+connections, generated messages, conversions, retries, pagination, and test utilities.
+
+Core does not depend on datasets or its scientific libraries. Parsing ordinary Python
+datetimes requires no optional libraries. Strings and scientific datetime values use
+pandas when parsed; xarray inputs also require xarray. Install pandas explicitly for
+these parsing conveniences in workflows-only environments. Datasets already installs
+these libraries.
+
+Run tests in the workspace with `uv sync --all-packages` followed by
+`uv run --no-sync pytest tilebox-core`. Transport tests use generated datasets clients.

tilebox_core-0.68.0/README.md

@@ -0,0 +1,16 @@
+# Tilebox Core
+
+Shared types and client infrastructure for the Tilebox Python SDKs.
+
+Public imports are `tilebox.query` for `TimeInterval`, `IDInterval`, and `Pagination`,
+and `tilebox.errors` for SDK exceptions. The `_tilebox` namespace contains private
+connections, generated messages, conversions, retries, pagination, and test utilities.
+
+Core does not depend on datasets or its scientific libraries. Parsing ordinary Python
+datetimes requires no optional libraries. Strings and scientific datetime values use
+pandas when parsed; xarray inputs also require xarray. Install pandas explicitly for
+these parsing conveniences in workflows-only environments. Datasets already installs
+these libraries.
+
+Run tests in the workspace with `uv sync --all-packages` followed by
+`uv run --no-sync pytest tilebox-core`. Transport tests use generated datasets clients.

tilebox_core-0.68.0/_tilebox/__init__.py

@@ -0,0 +1 @@
+"""Shared native Connect transport support for Tilebox SDKs."""

tilebox_core-0.68.0/_tilebox/aio/__init__.py

@@ -0,0 +1 @@
+"""Asynchronous pagination and concurrency helpers."""

tilebox_core-0.68.0/_tilebox/aio/concurrency.py

@@ -0,0 +1,65 @@
+import asyncio
+import inspect
+from collections.abc import AsyncIterator, Awaitable, Callable
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, TypeVar
+
+from anyio import EndOfStream, create_memory_object_stream, create_task_group
+from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+
+T = TypeVar("T")
+
+
+async def async_producer_consumer(
+    producer: AsyncIterator[T],
+    consumer: Callable[[T], None] | Callable[[T], Awaitable[Any]],
+    buffer_size: int = 10,
+) -> None:
+    """
+    Consume messages from a async producer (e.g. a service endpoint) as they come in. This ensures that the consumer
+    is already computing each produced message while the next message is being produced.
+
+    If the consumer is actually slower than the producer producing new message, the messages are buffered up to the
+    given buffer size. If the buffer is full, the producer will block until the consumer has consumed a message.
+
+    Args:
+        producer: The async generator to consume from
+        consumer: The consumer function to call for each message
+        buffer_size: The maximum number of messages to buffer before blocking the producer
+    """
+    streams: Any = create_memory_object_stream(max_buffer_size=buffer_size)
+    send: MemoryObjectSendStream[T] = streams[0]
+    receive: MemoryObjectReceiveStream[T] = streams[1]
+    async with create_task_group() as task_group:
+        task_group.start_soon(_producer, producer, send)
+        task_group.start_soon(_consumer, consumer, receive)
+
+
+async def _producer(producer: AsyncIterator[T], send_stream: MemoryObjectSendStream[T]) -> None:
+    """
+    Forward all messages from a producer (async iterator) and send them to a buffered send stream.
+    """
+    async with send_stream:
+        async for message in producer:
+            await send_stream.send(message)
+
+
+async def _consumer(
+    consume: Callable[[T], None] | Callable[[T], Awaitable[Any]], receive_stream: MemoryObjectReceiveStream[T]
+) -> None:
+    """
+    Receive messages from a buffered receive stream and forward them to a consumer until no more messages are available.
+    """
+
+    loop = asyncio.get_running_loop()
+
+    with ThreadPoolExecutor(max_workers=1) as executor, receive_stream:
+        try:
+            while True:
+                message = await receive_stream.receive()
+                # result = consume(message), but in a background thread so that async loop can continue in the meantime:
+                result = await loop.run_in_executor(executor, consume, message)
+                if inspect.isawaitable(result):
+                    await result
+        except EndOfStream:
+            pass

tilebox_core-0.68.0/_tilebox/aio/pagination.py

@@ -0,0 +1,29 @@
+from collections.abc import AsyncIterator, Awaitable, Callable
+
+from _tilebox.pagination import AnyResultPage, Pagination
+
+
+async def paginated_request(
+    paging_request: Callable[[Pagination], Awaitable[AnyResultPage]],
+    initial_page: Pagination,
+) -> AsyncIterator[AnyResultPage]:
+    """Make a paginated request to a service endpoint.
+
+    The endpoint is expected to return a next_page field, which is used for subsequent requests. Once no such
+    next_page field is returned, the request is completed.
+
+    Args:
+        paging_request: A function that takes a page as input and returns a Datapoints object
+            Often this will be a functools.partial object that wraps a gRPC service endpoint
+            and only leaves the page argument remaining
+        initial_page: The initial page to request
+
+    Yields:
+        Datapoints: The individual pages of the response
+    """
+    response = await paging_request(initial_page)
+    yield response
+
+    while response.next_page.starting_after is not None:
+        response = await paging_request(response.next_page)
+        yield response

tilebox_core-0.68.0/_tilebox/client.py

@@ -0,0 +1,211 @@
+"""Owned HTTP transports for native Connect clients."""
+
+import asyncio
+import time
+from collections.abc import Awaitable, Callable, Iterable
+from typing import Literal, Self, TypeAlias, TypeVar
+from urllib.parse import urlsplit, urlunsplit
+
+from connectrpc.client import ConnectClient, ConnectClientSync
+from connectrpc.code import Code
+from connectrpc.errors import ConnectError
+from connectrpc.interceptor import Interceptor, InterceptorSync
+from connectrpc.request import RequestContext
+from pyqwest import Client, HTTPTransport, HTTPVersion, SyncClient, SyncHTTPTransport
+
+from _tilebox.client_metadata import client_metadata
+from _tilebox.errors import translate_connect_error
+
+Transport: TypeAlias = Literal["http2", "http1", "grpc"]
+
+Sync = TypeVar("Sync", bound=ConnectClientSync)
+Async = TypeVar("Async", bound=ConnectClient)
+Req = TypeVar("Req")
+Res = TypeVar("Res")
+
+
+def _http_version(transport: Transport) -> HTTPVersion:
+    match transport:
+        case "http2":
+            return HTTPVersion.HTTP2
+        case "http1":
+            return HTTPVersion.HTTP1
+        case _:
+            raise ValueError(f"Unsupported transport {transport!r}; use 'http2' or 'http1' (both use Connect)")
+
+
+def _retry_delay(ctx: RequestContext, error: ConnectError, attempt: int) -> float | None:
+    delay = min(0.02 * 3**attempt, 1.0)
+    if (
+        attempt >= 4
+        or error.code not in {Code.UNAVAILABLE, Code.RESOURCE_EXHAUSTED}
+        or ctx.timeout_ms is None
+        or ctx.timeout_ms <= delay * 1000
+    ):
+        return None
+    return delay
+
+
+def connect_address(url: str, rpc_method_prefix: str | None = None) -> str:
+    """Normalize endpoints, defaulting bare hosts to TLS and development ports to HTTP."""
+    if url.startswith("unix:"):
+        raise ValueError("Connect HTTP transport does not support unix socket URLs")
+    if "://" not in url:
+        parsed = urlsplit(f"//{url}")
+        scheme = "http" if parsed.port not in (None, 443) else "https"
+        url = f"{scheme}://{url}"
+    parsed = urlsplit(url)
+    if (
+        parsed.scheme not in {"http", "https"}
+        or not parsed.hostname
+        or parsed.username
+        or parsed.password
+        or parsed.query
+        or parsed.fragment
+        or any(character.isspace() for character in url)
+    ):
+        raise ValueError(f"Invalid URL: {url}")
+    if parsed.scheme == "http" and parsed.port is None:
+        raise ValueError("Explicit port required for insecure HTTP connection")
+    if parsed.scheme == "https" and parsed.port == 443:
+        url = urlunsplit((parsed.scheme, parsed.netloc.removesuffix(":443"), parsed.path, "", ""))
+    prefix = (rpc_method_prefix or "").strip("/")
+    return url.rstrip("/") + (f"/{prefix}" if prefix else "")
+
+
+class _MetadataErrors:
+    def __init__(self, token: str | None, address: str) -> None:
+        self.headers = client_metadata()
+        self.token = token
+        self.prefix = urlsplit(address).path.rstrip("/")
+
+    def _prepare(self, ctx: RequestContext) -> str:
+        for name, value in self.headers.items():
+            ctx.request_headers[name] = value
+        if self.token is not None:
+            ctx.request_headers["authorization"] = f"Bearer {self.token}"
+        return f"{self.prefix}/{ctx.method.service_name}/{ctx.method.name}"
+
+    def intercept_unary_sync(
+        self,
+        call_next: Callable[[Req, RequestContext], Res],
+        request: Req,
+        ctx: RequestContext,
+    ) -> Res:
+        method = self._prepare(ctx)
+        attempt = 0
+        while True:
+            try:
+                return call_next(request, ctx)
+            except ConnectError as error:
+                delay = _retry_delay(ctx, error, attempt)
+                if delay is None:
+                    raise translate_connect_error(error, method) from None
+                time.sleep(delay)
+                attempt += 1
+
+    async def intercept_unary(
+        self,
+        call_next: Callable[[Req, RequestContext], Awaitable[Res]],
+        request: Req,
+        ctx: RequestContext,
+    ) -> Res:
+        method = self._prepare(ctx)
+        attempt = 0
+        while True:
+            try:
+                return await call_next(request, ctx)
+            except ConnectError as error:
+                delay = _retry_delay(ctx, error, attempt)
+                if delay is None:
+                    raise translate_connect_error(error, method) from None
+                await asyncio.sleep(delay)
+                attempt += 1
+
+
+class Connection:
+    """Share one explicitly owned HTTP transport across generated synchronous clients."""
+
+    def __init__(
+        self,
+        url: str,
+        token: str | None = None,
+        rpc_method_prefix: str | None = None,
+        *,
+        transport: Transport = "http2",
+        interceptors: Iterable[InterceptorSync] = (),
+    ) -> None:
+        self.address = connect_address(url, rpc_method_prefix)
+        self.transport = "http2" if transport == "grpc" else transport
+        self._transport = SyncHTTPTransport(http_version=_http_version(self.transport), tls_include_system_certs=True)
+        self._http = SyncClient(self._transport)
+        self._interceptors = (_MetadataErrors(token, self.address), *interceptors)
+        self._closed = False
+
+    def client(self, client_class: type[Sync]) -> Sync:
+        """Construct a native generated client using this connection's HTTP client."""
+        if self._closed:
+            raise RuntimeError("Connection is closed")
+        return client_class(
+            self.address,
+            http_client=self._http,
+            interceptors=self._interceptors,
+            read_max_bytes=512 * 1024 * 1024,
+            timeout_ms=60_000,
+        )
+
+    def close(self) -> None:
+        """Release this connection's transport; safe to call more than once."""
+        if not self._closed:
+            self._closed = True
+            self._transport.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class AsyncConnection:
+    """Share one explicitly owned HTTP transport across generated asynchronous clients."""
+
+    def __init__(
+        self,
+        url: str,
+        token: str | None = None,
+        rpc_method_prefix: str | None = None,
+        *,
+        transport: Transport = "http2",
+        interceptors: Iterable[Interceptor] = (),
+    ) -> None:
+        self.address = connect_address(url, rpc_method_prefix)
+        self.transport = "http2" if transport == "grpc" else transport
+        self._transport = HTTPTransport(http_version=_http_version(self.transport), tls_include_system_certs=True)
+        self._http = Client(self._transport)
+        self._interceptors = (_MetadataErrors(token, self.address), *interceptors)
+        self._closed = False
+
+    def client(self, client_class: type[Async]) -> Async:
+        """Construct a native generated client without opening an event loop."""
+        if self._closed:
+            raise RuntimeError("Connection is closed")
+        return client_class(
+            self.address,
+            http_client=self._http,
+            interceptors=self._interceptors,
+            read_max_bytes=512 * 1024 * 1024,
+            timeout_ms=60_000,
+        )
+
+    async def close(self) -> None:
+        """Release this connection's transport; safe to call more than once."""
+        if not self._closed:
+            self._closed = True
+            await self._transport.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()

tilebox_core-0.68.0/_tilebox/client_metadata.py

@@ -0,0 +1,210 @@
+import builtins
+import os
+import platform
+import sys
+from collections.abc import Mapping
+from functools import lru_cache
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as package_version
+
+CLIENT_HEADER = "Tilebox-Client"
+
+_MAX_FIELD_BYTES = 256
+_MAX_HEADER_BYTES = 2 * 1024
+
+
+@lru_cache(maxsize=1)
+def client_metadata() -> dict[str, str]:
+    """Return cached metadata identifying this SDK and its execution context."""
+    return {CLIENT_HEADER: _client_header()}
+
+
+def _client_header() -> str:
+    fields = {
+        "name": "python",
+        "version": _package_version(),
+        "runtime": "python",
+        "runtime-version": platform.python_version(),
+        "os": _os_name(),
+        "os-version": platform.release(),
+        "arch": _architecture(),
+        "execution-environment": _execution_environment(os.environ),
+        **_invoker(os.environ),
+        **_cloud_environment(os.environ),
+    }
+    return _serialize_dictionary(fields)
+
+
+def _package_version() -> str | None:
+    try:
+        return package_version("tilebox-python")
+    except PackageNotFoundError:
+        try:
+            return package_version("tilebox-core")
+        except PackageNotFoundError:
+            return None
+
+
+def _os_name() -> str | None:
+    return platform.system().lower() or None
+
+
+def _architecture() -> str | None:
+    machine = platform.machine().lower()
+    architectures = {
+        "aarch64": "arm64",
+        "amd64": "amd64",
+        "arm64": "arm64",
+        "armv6l": "arm",
+        "armv7l": "arm",
+        "i386": "386",
+        "i686": "386",
+        "x86": "386",
+        "x86_64": "amd64",
+    }
+    return architectures.get(machine, machine or None)
+
+
+def _execution_environment(environ: Mapping[str, str]) -> str | None:
+    signals = (
+        (environ.get("GITHUB_ACTIONS") == "true", "github-actions"),
+        (environ.get("GITLAB_CI") == "true", "gitlab-ci"),
+        (_env_set(environ, "BUILDKITE"), "buildkite"),
+        (_env_set(environ, "CIRCLECI"), "circleci"),
+        (_env_set(environ, "JENKINS_URL"), "jenkins"),
+        (_env_set(environ, "TEAMCITY_VERSION"), "teamcity"),
+        (_env_set(environ, "TF_BUILD"), "azure-pipelines"),
+        (_env_set(environ, "K_SERVICE", "CLOUD_RUN_JOB"), "google-cloud-run"),
+        (environ.get("AWS_EXECUTION_ENV", "").startswith("AWS_Lambda_"), "aws-lambda"),
+        (_env_set(environ, "FUNCTIONS_WORKER_RUNTIME"), "azure-functions"),
+        (_env_set(environ, "KUBERNETES_SERVICE_HOST"), "kubernetes"),
+    )
+    environment = next((name for detected, name in signals if detected), None)
+
+    if environment is not None:
+        return environment
+
+    shell = _interactive_shell()
+    if _env_set(environ, "COLAB_RELEASE_TAG") or shell == "google-colab":
+        environment = "google-colab"
+    elif shell == "jupyter" or _env_set(environ, "JPY_PARENT_PID"):
+        jupyterlab_variables = ("JUPYTERLAB_DIR", "JUPYTERLAB_SETTINGS_DIR", "JUPYTERLAB_WORKSPACES_DIR")
+        environment = "jupyterlab" if _env_set(environ, *jupyterlab_variables) else "jupyter"
+    elif shell == "terminal" or hasattr(sys, "ps1") or (sys.stdin is not None and sys.stdin.isatty()):
+        environment = "terminal"
+    return environment
+
+
+def _interactive_shell() -> str | None:
+    get_ipython = getattr(builtins, "get_ipython", None)
+    if not callable(get_ipython):
+        return None
+    shell = get_ipython()
+    shell_type = type(shell)
+    qualified_name = f"{shell_type.__module__}.{shell_type.__name__}".lower()
+    if "google.colab" in qualified_name:
+        return "google-colab"
+    if "zmqinteractiveshell" in qualified_name:
+        return "jupyter"
+    if "terminalinteractiveshell" in qualified_name:
+        return "terminal"
+    return None
+
+
+def _invoker(environ: Mapping[str, str]) -> dict[str, str]:
+    invoker = None
+    version = None
+    if environ.get("AGENT") == "amp":
+        invoker = "amp"
+    elif _env_set(environ, "COPILOT_AGENT_SESSION_ID"):
+        invoker = "github-copilot"
+    elif environ.get("OPENCODE") == "1":
+        invoker = "opencode"
+    elif _env_set(environ, "CLAUDECODE"):
+        invoker = "claude-code"
+    elif _env_set(environ, "CURSOR_AGENT"):
+        invoker = "cursor"
+    elif _env_set(environ, "CODEX_SESSION_ID", "CODEX_THREAD_ID"):
+        invoker = "codex"
+        version = environ.get("CODEX_VERSION")
+    elif _env_set(environ, "GEMINI_CLI"):
+        invoker = "gemini-cli"
+    return _optional_version(invoker, version) if invoker else {}
+
+
+def _optional_version(invoker: str, version: str | None) -> dict[str, str]:
+    metadata = {"invoker": invoker}
+    if version:
+        metadata["invoker-version"] = version
+    return metadata
+
+
+def _cloud_environment(environ: Mapping[str, str]) -> dict[str, str]:
+    provider, platform_name, region = _detect_cloud_environment(environ)
+    return {
+        key: value
+        for key, value in (
+            ("cloud-provider", provider),
+            ("cloud-platform", platform_name),
+            ("cloud-region", region),
+        )
+        if value
+    }
+
+
+def _detect_cloud_environment(environ: Mapping[str, str]) -> tuple[str | None, str | None, str | None]:
+    if _env_set(environ, "AWS_EXECUTION_ENV", "AWS_REGION", "AWS_DEFAULT_REGION"):
+        execution_environment = environ.get("AWS_EXECUTION_ENV", "")
+        platform_name = None
+        if execution_environment.startswith("AWS_Lambda_"):
+            platform_name = "aws_lambda"
+        elif execution_environment.startswith("AWS_ECS_"):
+            platform_name = "aws_ecs"
+        return "aws", platform_name, _first_environment_value(environ, "AWS_REGION", "AWS_DEFAULT_REGION")
+
+    if _env_set(environ, "K_SERVICE", "CLOUD_RUN_JOB", "GAE_ENV"):
+        platform_name = "gcp_cloud_run" if _env_set(environ, "K_SERVICE", "CLOUD_RUN_JOB") else "gcp_app_engine"
+        region = _first_environment_value(environ, "GOOGLE_CLOUD_REGION", "CLOUD_RUN_REGION", "FUNCTION_REGION")
+        return "gcp", platform_name, region
+
+    if _env_set(environ, "WEBSITE_INSTANCE_ID", "FUNCTIONS_WORKER_RUNTIME", "REGION_NAME"):
+        platform_name = None
+        if _env_set(environ, "FUNCTIONS_WORKER_RUNTIME"):
+            platform_name = "azure_functions"
+        elif _env_set(environ, "WEBSITE_INSTANCE_ID"):
+            platform_name = "azure_app_service"
+        return "azure", platform_name, environ.get("REGION_NAME")
+
+    return None, None, None
+
+
+def _env_set(environ: Mapping[str, str], *names: str) -> bool:
+    return any(environ.get(name) for name in names)
+
+
+def _first_environment_value(environ: Mapping[str, str], *names: str) -> str | None:
+    return next((value for name in names if (value := environ.get(name))), None)
+
+
+def _serialize_dictionary(fields: Mapping[str, str | None]) -> str:
+    members: list[str] = []
+    header_size = 0
+    for key, value in fields.items():
+        if not value or not _valid_string(value):
+            continue
+        escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+        member = f'{key}="{escaped}"'
+        member_size = len(member.encode("ascii")) + (2 if members else 0)
+        if header_size + member_size > _MAX_HEADER_BYTES:
+            continue
+        members.append(member)
+        header_size += member_size
+    return ", ".join(members)
+
+
+def _valid_string(value: str) -> bool:
+    try:
+        encoded = value.encode("ascii")
+    except UnicodeEncodeError:
+        return False
+    return len(encoded) <= _MAX_FIELD_BYTES and all(0x20 <= byte <= 0x7E for byte in encoded)

tilebox_core-0.68.0/_tilebox/concurrency.py

@@ -0,0 +1,45 @@
+"""Bounded producer/consumer concurrency with exception propagation."""
+
+from collections.abc import Callable, Iterator
+from concurrent.futures import ThreadPoolExecutor
+from queue import Empty, Full, Queue
+from threading import Event
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+def concurrent_producer_consumer(
+    producer: Iterator[T],
+    consumer: Callable[[T], object],
+    buffer_size: int = 10,
+) -> None:
+    """Produce on the calling thread and consume on one worker, propagating failures."""
+    if buffer_size < 1:
+        raise ValueError("buffer_size must be positive")
+    queue: Queue[T] = Queue(buffer_size)
+    done = Event()
+
+    def consume() -> None:
+        while not done.is_set() or not queue.empty():
+            try:
+                item = queue.get(timeout=0.05)
+            except Empty:
+                continue
+            consumer(item)
+
+    with ThreadPoolExecutor(max_workers=1) as executor:
+        future = executor.submit(consume)
+        try:
+            for item in producer:
+                while True:
+                    if future.done():
+                        future.result()
+                    try:
+                        queue.put(item, timeout=0.05)
+                        break
+                    except Full:
+                        continue
+        finally:
+            done.set()
+        future.result()