Read the API key from CLOSECITY_KEY, ship the py.typed marker, and cut 1.2.0

Author: Nathaniel Henry

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.2.0
+
+- `Client()` reads the `CLOSECITY_KEY` environment variable when no `api_key` is
+  passed, so scripts and agents can authenticate without hardcoding the key. A
+  401 with no key set now carries an actionable hint pointing at `CLOSECITY_KEY`
+  and the free-signup page (`err.hint`).
+- Ship the PEP 561 `py.typed` marker so downstream type checkers (mypy, pyright)
+  see the inline type hints.
+- Document that the client does not retry: on `RateLimitedError` /
+  `ServiceUnavailableError`, wait `err.retry_after` seconds and retry yourself.
+
 ## 1.1.0
 
 Tabular results by default, across every route.

README.md

@@ -25,7 +25,9 @@ GeoDataFrames, so you can map them right away.
 ```python
 from closecity import Client
 
-# The key (ck_live_) comes from https://account.close.city
+# The key (ck_live_) comes from https://account.close.city (5,000 free tokens
+# on signup, no card). You can also set the CLOSECITY_KEY environment variable
+# and call Client() with no argument.
 close = Client("ck_live_your_key")   # use your own key here
 
 # Grocery stores within a 1.5 km walk of a point, as points:
@@ -88,6 +90,10 @@ except CloseAPIError as err:
     print(err.status, err.slug)
 ```
 
+The client does not retry automatically. On a `RateLimitedError` or
+`ServiceUnavailableError`, wait `err.retry_after` seconds (from the
+`Retry-After` header) and retry the request yourself.
+
 ## Reference
 
 - Documentation: https://henryspatialanalysis.github.io/closecity-python/

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "closecity"
-version = "1.1.0"
+version = "1.2.0"
 description = "Python client for the Close API (api.close.city). Travel times to points of interest for every US census block."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -40,6 +40,10 @@ docs = ["sphinx>=7", "furo", "sphinx-copybutton", "myst-nb", "jupytext",
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+# Ship the PEP 561 marker so downstream mypy/pyright see the inline type hints.
+closecity = ["py.typed"]
+
 [tool.ruff]
 line-length = 90
 target-version = "py39"

src/closecity/client.py

@@ -8,6 +8,7 @@
 
 from __future__ import annotations
 
+import os
 from collections.abc import Iterator, Sequence
 from dataclasses import dataclass, field
 from typing import Any
@@ -166,7 +167,9 @@ class Client:
 
     ``api_key`` is optional (the catalog and health routes are free), but every
     data route needs one (a ``ck_live_`` key), created at
-    https://account.close.city. Usable as a context manager.
+    https://account.close.city (5,000 free tokens on signup, no card). When
+    ``api_key`` is not given, the ``CLOSECITY_KEY`` environment variable is used
+    if set. Usable as a context manager.
 
     ``output`` sets how results come back, and defaults to ``"spatial"``:
 
@@ -192,6 +195,9 @@ def __init__(
         http_client: httpx.Client | None = None,
         transport: httpx.BaseTransport | None = None,
     ):
+        if api_key is None:
+            api_key = os.getenv("CLOSECITY_KEY") or None
+        self._has_key = bool(api_key)
         self.output = _check_output(output)
         headers = {"Accept": "application/json"}
         if api_key:
@@ -257,9 +263,16 @@ def _request(
             body = resp.json() if resp.content else {}
             if not isinstance(body, dict):
                 body = {"title": str(body)}
+            hint = None
+            if resp.status_code == 401 and not self._has_key:
+                hint = (
+                    "No API key set. Pass Client(api_key=...) or set the "
+                    "CLOSECITY_KEY environment variable. Create a free key "
+                    "(5,000 tokens, no card) at https://account.close.city."
+                )
             raise errors.error_from_problem(
                 resp.status_code, body, request_id,
-                _retry_after(resp.headers.get("Retry-After")),
+                _retry_after(resp.headers.get("Retry-After")), hint,
             )
         return Reply(
             data = resp.json() if resp.content else None,

src/closecity/errors.py

@@ -21,8 +21,9 @@ class CloseAPIError(CloseError):
 
     Attributes mirror the problem document: ``slug`` (the stable machine key),
     ``title``, ``status``, ``detail``, plus ``request_id`` (from ``X-Request-Id``,
-    quote it in support requests), ``retry_after`` when present, and ``extras``
-    for any additional problem members (e.g. validation ``errors``).
+    quote it in support requests), ``retry_after`` when present, ``extras`` for
+    any additional problem members (e.g. validation ``errors``), and ``hint``, a
+    client-side note appended to the message (e.g. "set CLOSECITY_KEY").
     """
 
     def __init__(
@@ -35,6 +36,7 @@ def __init__(
         request_id: str | None = None,
         retry_after: float | None = None,
         extras: dict[str, Any] | None = None,
+        hint: str | None = None,
     ):
         self.status = status
         self.slug = slug
@@ -43,9 +45,12 @@ def __init__(
         self.request_id = request_id
         self.retry_after = retry_after
         self.extras = extras or {}
+        self.hint = hint
         message = f"{status} {slug}: {title}"
         if detail:
             message += f": {detail}"
+        if hint:
+            message += f" — {hint}"
         if request_id:
             message += f" (request {request_id})"
         super().__init__(message)
@@ -103,6 +108,7 @@ def error_from_problem(
     body: dict[str, Any],
     request_id: str | None,
     retry_after: float | None,
+    hint: str | None = None,
 ) -> CloseAPIError:
     """Build the most specific exception for a problem+json body."""
 
@@ -121,4 +127,5 @@ def error_from_problem(
         request_id = request_id,
         retry_after = retry_after,
         extras = extras,
+        hint = hint,
     )

src/closecity/py.typed

@@ -234,3 +234,57 @@ def handler(request):
     make_client(handler).isochrone(block = "410390020001010",
                                    contours = [15, 30, 45])
     assert seen["contours"] == "15,30,45"
+
+
+# -- api key sourcing --------------------------------------------------------
+
+def test_api_key_read_from_environment(monkeypatch):
+    monkeypatch.setenv("CLOSECITY_KEY", "ck_live_env")
+    seen = {}
+
+    def handler(request):
+        seen["auth"] = request.headers.get("authorization")
+        return httpx.Response(200, json = {"modes": []})
+
+    Client(base_url = "https://api.close.city", output = "raw",
+           transport = httpx.MockTransport(handler)).modes()
+    assert seen["auth"] == "Bearer ck_live_env"
+
+
+def test_explicit_key_overrides_environment(monkeypatch):
+    monkeypatch.setenv("CLOSECITY_KEY", "ck_live_env")
+    seen = {}
+
+    def handler(request):
+        seen["auth"] = request.headers.get("authorization")
+        return httpx.Response(200, json = {"modes": []})
+
+    Client("ck_live_explicit", base_url = "https://api.close.city",
+           output = "raw", transport = httpx.MockTransport(handler)).modes()
+    assert seen["auth"] == "Bearer ck_live_explicit"
+
+
+def test_missing_key_401_adds_actionable_hint(monkeypatch):
+    monkeypatch.delenv("CLOSECITY_KEY", raising = False)
+
+    def handler(request):
+        return problem(401, "missing-key", "Provide an API key.")
+
+    client = Client(base_url = "https://api.close.city", output = "raw",
+                    transport = httpx.MockTransport(handler))
+    with pytest.raises(AuthenticationError) as ei:
+        client.block_summary("410390020001010")
+    assert ei.value.hint is not None
+    assert "CLOSECITY_KEY" in ei.value.hint
+    assert "CLOSECITY_KEY" in str(ei.value)
+
+
+def test_invalid_key_401_has_no_missing_key_hint():
+    # A key IS set (make_client passes one), so the "you forgot your key" hint
+    # must not fire on an invalid-key 401.
+    def handler(request):
+        return problem(401, "invalid-key", "Unknown or revoked API key.")
+
+    with pytest.raises(AuthenticationError) as ei:
+        make_client(handler).block_summary("410390020001010")
+    assert ei.value.hint is None