feat: named environment option (production default, staging switch)

Adds environment="production"|"staging" to Client/AsyncClient with resolution
precedence base_url > environment > TOPOLAB_BASE_URL > TOPOLAB_ENV > production.
Production ships as the default; staging is one keyword away. +6 tests (30 pass).

Author: bbjansen

README.md

@@ -51,6 +51,19 @@ from topolab import Client
 tl = Client(api_key=os.environ["TOPOLAB_API_KEY"])
 ```
 
+## Staging vs production
+
+The client targets **production** (`https://api.topolab.nl`) by default. Point it
+at staging with the `environment` argument:
+
+```python
+tl = Client(api_key="tlb_staging_...", environment="staging")  # https://api-staging.topolab.nl
+```
+
+Or set `TOPOLAB_ENV=staging` in the environment. An explicit `base_url=` always
+wins (for self-hosting or tests). Precedence: `base_url` → `environment` →
+`TOPOLAB_BASE_URL` → `TOPOLAB_ENV` → production.
+
 ## What you can do
 
 ### Browse the catalog

src/topolab/async_client.py

@@ -5,7 +5,7 @@
 from .errors import ConfigurationError
 from ._transport import Transport
 from .models import DatasetSummary, DatasetPage
-from .client import DEFAULT_BASE_URL
+from .client import resolve_base_url
 
 
 def _clean(d):
@@ -75,13 +75,14 @@ async def list(self, *, page=None, limit=None, search=None, theme=None,
 
 class AsyncClient:
     def __init__(self, api_key: str | None = None, *, base_url: str | None = None,
-                 timeout: float = 60.0, max_retries: int = 3,
-                 proxy_url: str | None = None, user_agent: str | None = None):
+                 environment: str | None = None, timeout: float = 60.0,
+                 max_retries: int = 3, proxy_url: str | None = None,
+                 user_agent: str | None = None):
         key = api_key if api_key is not None else os.environ.get("TOPOLAB_API_KEY")
         if not key:
             raise ConfigurationError("No API key. Pass api_key= or set TOPOLAB_API_KEY.")
         self.api_key = key
-        self.base_url = base_url or os.environ.get("TOPOLAB_BASE_URL") or DEFAULT_BASE_URL
+        self.base_url = resolve_base_url(base_url, environment)
         self._t = Transport(api_key=key, base_url=self.base_url, timeout=timeout,
                             max_retries=max_retries, proxy_url=proxy_url, user_agent=user_agent)
         self.datasets = AsyncDatasetsNamespace(self._t)

src/topolab/client.py

@@ -6,18 +6,51 @@
 from .dataset import Dataset
 from .datasets import DatasetsNamespace
 
-DEFAULT_BASE_URL = "https://api.topolab.nl"
+# Named API environments. Production is the shipped default; staging is one
+# keyword away. Self-hosting / tests can still pass an explicit base_url.
+ENVIRONMENTS = {
+    "production": "https://api.topolab.nl",
+    "staging": "https://api-staging.topolab.nl",
+}
+DEFAULT_BASE_URL = ENVIRONMENTS["production"]
+
+
+def _environment_url(name: str) -> str:
+    try:
+        return ENVIRONMENTS[name.lower()]
+    except KeyError:
+        raise ConfigurationError(
+            f"Unknown environment {name!r}. Use one of {sorted(ENVIRONMENTS)}."
+        ) from None
+
+
+def resolve_base_url(base_url: str | None, environment: str | None) -> str:
+    """Resolve the API base URL. Precedence (most specific first):
+    explicit base_url > environment arg > TOPOLAB_BASE_URL > TOPOLAB_ENV > production.
+    """
+    if base_url:
+        return base_url.rstrip("/")
+    if environment:
+        return _environment_url(environment)
+    env_base = os.environ.get("TOPOLAB_BASE_URL")
+    if env_base:
+        return env_base.rstrip("/")
+    env_name = os.environ.get("TOPOLAB_ENV")
+    if env_name:
+        return _environment_url(env_name)
+    return DEFAULT_BASE_URL
 
 
 class Client:
     def __init__(self, api_key: str | None = None, *, base_url: str | None = None,
-                 timeout: float = 60.0, max_retries: int = 3,
-                 proxy_url: str | None = None, user_agent: str | None = None):
+                 environment: str | None = None, timeout: float = 60.0,
+                 max_retries: int = 3, proxy_url: str | None = None,
+                 user_agent: str | None = None):
         key = api_key if api_key is not None else os.environ.get("TOPOLAB_API_KEY")
         if not key:
             raise ConfigurationError("No API key. Pass api_key= or set TOPOLAB_API_KEY.")
         self.api_key = key
-        self.base_url = base_url or os.environ.get("TOPOLAB_BASE_URL") or DEFAULT_BASE_URL
+        self.base_url = resolve_base_url(base_url, environment)
         self._t = Transport(api_key=key, base_url=self.base_url, timeout=timeout,
                             max_retries=max_retries, proxy_url=proxy_url, user_agent=user_agent)
         self.datasets = DatasetsNamespace(self._t)

tests/test_client.py

@@ -25,3 +25,41 @@ def test_missing_key_raises(monkeypatch):
     monkeypatch.delenv("TOPOLAB_API_KEY", raising=False)
     with pytest.raises(ConfigurationError):
         Client(api_key=None, base_url=BASE)
+
+
+def test_default_environment_is_production(monkeypatch):
+    monkeypatch.delenv("TOPOLAB_BASE_URL", raising=False)
+    monkeypatch.delenv("TOPOLAB_ENV", raising=False)
+    assert Client(api_key="k").base_url == "https://api.topolab.nl"
+
+
+def test_environment_staging(monkeypatch):
+    monkeypatch.delenv("TOPOLAB_BASE_URL", raising=False)
+    monkeypatch.delenv("TOPOLAB_ENV", raising=False)
+    assert Client(api_key="k", environment="staging").base_url == "https://api-staging.topolab.nl"
+
+
+def test_unknown_environment_raises():
+    with pytest.raises(ConfigurationError):
+        Client(api_key="k", environment="dev")
+
+
+def test_topolab_env_var(monkeypatch):
+    monkeypatch.delenv("TOPOLAB_BASE_URL", raising=False)
+    monkeypatch.setenv("TOPOLAB_ENV", "staging")
+    assert Client(api_key="k").base_url == "https://api-staging.topolab.nl"
+
+
+def test_base_url_beats_environment(monkeypatch):
+    monkeypatch.delenv("TOPOLAB_BASE_URL", raising=False)
+    monkeypatch.delenv("TOPOLAB_ENV", raising=False)
+    # explicit base_url wins over environment
+    c = Client(api_key="k", base_url="https://self.example/api", environment="staging")
+    assert c.base_url == "https://self.example/api"
+
+
+def test_async_environment_staging(monkeypatch):
+    from topolab import AsyncClient
+    monkeypatch.delenv("TOPOLAB_BASE_URL", raising=False)
+    monkeypatch.delenv("TOPOLAB_ENV", raising=False)
+    assert AsyncClient(api_key="k", environment="staging").base_url == "https://api-staging.topolab.nl"