Allow anonymous access to open data datasets

Author: lukasbindreiter

.pre-commit-config.yaml

@@ -9,7 +9,7 @@ repos:
     hooks:
       - id: sync-with-uv
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: v0.14.14
+    rev: v0.15.7
     hooks:
       - id: ruff-check
         args: [--fix, --exit-non-zero-on-fix]

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.50.1] - 2026-03-31
+
+### Added
+
+- `tilebox-datasets`: Allow anonymous access to open data datasets.
+
 ## [0.50.0] - 2026-03-06
 
 ### Added
@@ -342,6 +348,7 @@ the first client that does not cache data (since it's already on the local file
 - Released packages: `tilebox-datasets`, `tilebox-workflows`, `tilebox-storage`, `tilebox-grpc`
 
 [Unreleased]: https://github.com/tilebox/tilebox-python/compare/v0.50.0...HEAD
+[0.50.1]: https://github.com/tilebox/tilebox-python/compare/v0.50.0...v0.50.1
 [0.50.0]: https://github.com/tilebox/tilebox-python/compare/v0.49.0...v0.50.0
 [0.49.0]: https://github.com/tilebox/tilebox-python/compare/v0.48.0...v0.49.0
 [0.48.0]: https://github.com/tilebox/tilebox-python/compare/v0.47.0...v0.48.0

pyproject.toml

@@ -26,7 +26,8 @@ dev = [
     "ruff>=0.14.10",
     "types-protobuf>=6.30",
     "junitparser>=3.2.0",
-    "ty>=0.0.14",
+    # https://github.com/astral-sh/ty/issues/2759
+    "ty==0.0.14",
     "prek>=0.2.27",
 ]
 
@@ -116,5 +117,5 @@ exclude = [
     # auto-generated code
     "**/*_pb2.py",
     "**/*_pb2.pyi",
-    "**/*pb2_grpc.py"
+    "**/*pb2_grpc.py",
 ]

tilebox-datasets/tilebox/datasets/aio/client.py

@@ -1,11 +1,14 @@
+import os
 from uuid import UUID
 
+from loguru import logger
+
 from _tilebox.grpc.aio.channel import open_channel
 from _tilebox.grpc.aio.error import with_pythonic_errors
 from _tilebox.grpc.error import NotFoundError
 from tilebox.datasets.aio.dataset import DatasetClient
+from tilebox.datasets.client import _TILEBOX_API_KEY_ENV_VAR, _TILEBOX_API_URL
 from tilebox.datasets.client import Client as BaseClient
-from tilebox.datasets.client import token_from_env
 from tilebox.datasets.data.datasets import DatasetKind, FieldDict
 from tilebox.datasets.datasets.v1.collections_pb2_grpc import CollectionServiceStub
 from tilebox.datasets.datasets.v1.data_access_pb2_grpc import DataAccessServiceStub
@@ -16,15 +19,31 @@
 
 
 class Client:
-    def __init__(self, *, url: str = "https://api.tilebox.com", token: str | None = None) -> None:
+    def __init__(
+        self, *, url: str = _TILEBOX_API_URL, token: str | None = None, warn_if_unauthenticated: bool = True
+    ) -> None:
         """
         Create a Tilebox datasets client.
 
         Args:
             url: Tilebox API Url. Defaults to "https://api.tilebox.com".
             token: The API Key to authenticate with. If not set the `TILEBOX_API_KEY` environment variable will be used.
+                If no token is provided or found, anonymous open data access will be used.
+            warn_if_unauthenticated: Whether to warn if no API key is provided and the client is used with the default
+                Tilebox API URL. Defaults to True.
         """
-        channel = open_channel(url, token_from_env(url, token))
+        if token is None:
+            token = os.environ.get(_TILEBOX_API_KEY_ENV_VAR, None)
+
+        if token is None and url == _TILEBOX_API_URL and warn_if_unauthenticated:
+            logger.opt(colors=True).info(
+                "<yellow>"
+                "No Tilebox API key detected. Using anonymous Open Data access without authentication. "
+                "For higher throughput and rate limits, sign up for a free Tilebox at https://console.tilebox.com."
+                "</yellow>"
+            )
+
+        channel = open_channel(url, token)
         dataset_service_stub = with_pythonic_errors(DatasetServiceStub(channel))
         collection_service_stub = with_pythonic_errors(CollectionServiceStub(channel))
         data_access_service_stub = with_pythonic_errors(DataAccessServiceStub(channel))

tilebox-datasets/tilebox/datasets/client.py

@@ -6,13 +6,15 @@
 from loguru import logger
 from promise import Promise
 
-from _tilebox.grpc.channel import parse_channel_info
 from tilebox.datasets.data.datasets import Dataset, DatasetGroup, DatasetKind, FieldDict, ListDatasetsResponse
 from tilebox.datasets.group import Group
 from tilebox.datasets.message_pool import register_once
 from tilebox.datasets.service import TileboxDatasetService
 from tilebox.datasets.uuid import as_uuid
 
+_TILEBOX_API_URL = "https://api.tilebox.com"
+_TILEBOX_API_KEY_ENV_VAR = "TILEBOX_API_KEY"
+
 
 class TimeseriesDatasetLike(Protocol):
     def __init__(self, service: TileboxDatasetService, dataset: Dataset) -> None:
@@ -81,19 +83,6 @@ def _dataset_by_id(self, dataset_id: str | UUID, dataset_type: type[T]) -> Promi
         )
 
 
-def token_from_env(url: str, token: str | None) -> str | None:
-    if token is None:  # if no token is provided, try to get it from the environment
-        token = os.environ.get("TILEBOX_API_KEY", None)
-
-    if token is None and parse_channel_info(url).address == "api.tilebox.com":
-        raise ValueError(
-            "No API key provided and no TILEBOX_API_KEY environment variable set. Please specify an API key using "
-            "the token argument. For example: `Client(token='YOUR_TILEBOX_API_KEY')`"
-        )
-
-    return token
-
-
 def _log_server_message(response: ListDatasetsResponse) -> ListDatasetsResponse:
     if response.server_message:
         logger.opt(colors=True).info(response.server_message + "\n")

tilebox-datasets/tilebox/datasets/sync/client.py

@@ -1,9 +1,12 @@
+import os
 from uuid import UUID
 
+from loguru import logger
+
 from _tilebox.grpc.channel import open_channel
 from _tilebox.grpc.error import NotFoundError, with_pythonic_errors
+from tilebox.datasets.client import _TILEBOX_API_KEY_ENV_VAR, _TILEBOX_API_URL
 from tilebox.datasets.client import Client as BaseClient
-from tilebox.datasets.client import token_from_env
 from tilebox.datasets.data.datasets import DatasetKind, FieldDict
 from tilebox.datasets.datasets.v1.collections_pb2_grpc import CollectionServiceStub
 from tilebox.datasets.datasets.v1.data_access_pb2_grpc import DataAccessServiceStub
@@ -15,15 +18,31 @@
 
 
 class Client:
-    def __init__(self, *, url: str = "https://api.tilebox.com", token: str | None = None) -> None:
+    def __init__(
+        self, *, url: str = _TILEBOX_API_URL, token: str | None = None, warn_if_unauthenticated: bool = True
+    ) -> None:
         """
         Create a Tilebox datasets client.
 
         Args:
             url: Tilebox API Url. Defaults to "https://api.tilebox.com".
             token: The API Key to authenticate with. If not set the `TILEBOX_API_KEY` environment variable will be used.
+                If no token is provided or found, anonymous open data access will be used.
+            warn_if_unauthenticated: Whether to warn if no API key is provided and the client is used with the default
+                Tilebox API URL. Defaults to True.
         """
-        channel = open_channel(url, token_from_env(url, token))
+        if token is None:
+            token = os.environ.get(_TILEBOX_API_KEY_ENV_VAR, None)
+
+        if token is None and url == _TILEBOX_API_URL and warn_if_unauthenticated:
+            logger.opt(colors=True).info(
+                "<yellow>"
+                "No Tilebox API key detected. Using anonymous Open Data access without authentication. "
+                "For higher throughput and rate limits, sign up for a free Tilebox at https://console.tilebox.com."
+                "</yellow>"
+            )
+
+        channel = open_channel(url, token)
         dataset_service_stub = with_pythonic_errors(DatasetServiceStub(channel))
         collection_service_stub = with_pythonic_errors(CollectionServiceStub(channel))
         data_access_service_stub = with_pythonic_errors(DataAccessServiceStub(channel))

tilebox-workflows/pyproject.toml

@@ -32,6 +32,7 @@ dependencies = [
     "boto3-stubs[essential]>=1.33",
     "ipywidgets>=8.1.7",
     "python-dateutil>=2.9.0.post0",
+    "obstore>=0.8.2",
 ]
 
 [dependency-groups]

tilebox-workflows/tilebox/workflows/client.py

@@ -104,7 +104,7 @@ def runner(
         runner_context_type = context or RunnerContext
         runner_context = runner_context_type(
             tracer._tracer,  # noqa: SLF001
-            datasets_client=DatasetsClient(**self._auth),
+            datasets_client=DatasetsClient(**self._auth),  # ty: ignore[invalid-argument-type]
             storage_locations=storage_locations,
         )