Return tabular output by default via a three-mode output setting.

Author: Nathaniel Henry

.claude/CLAUDE.md

@@ -1,8 +1,9 @@
 # closecity (Python SDK)
 
 Python client for the Close travel-time API (https://api.close.city). httpx-based,
-returns `geopandas` by default. Sphinx + Furo docs deploy to GitHub Pages; PyPI (via
-OIDC trusted publishing) is the eventual target. Public repo:
+returns tabular data by default (a `geopandas.GeoDataFrame` where geometry applies, a
+plain `pandas.DataFrame` otherwise). Sphinx + Furo docs deploy to GitHub Pages; PyPI
+(via OIDC trusted publishing) is the eventual target. Public repo:
 `henryspatialanalysis/closecity-python`. The R sibling is
 `henryspatialanalysis/closecity-r` -- keep the two SDKs behaviourally in step.
 
@@ -15,19 +16,31 @@ OIDC trusted publishing) is the eventual target. Public repo:
 - **Attribution:** copyright and funder is "Henry Spatial Analysis", never "Close".
   Author `Nathaniel Henry <nat@henryspatialanalysis.com>`.
 - **Code style:** line length 90, spaces around `=` even inside calls (Nat overrides
-  linters on this). `ruff` clean.
-- **API shape:** `Client` with one method per route; `Reply` / `Paginator`. Feature
-  methods convert to geopandas via `spatial.py` (`to_geopandas()` is also public).
-- **Spatial by default:** feature methods (POIs, catchments, areal blocks, isochrones)
-  return a `GeoDataFrame`. `Client(spatial=True)` is the default; `spatial=False` (on
-  the client or per call) returns the raw `Reply`. Catalog/places/summaries stay raw.
-- **Dependencies:** `geopandas>=0.14` is a hard dependency. `pygris` is the `[tiger]`
-  extra, used only to fetch block boundaries for the GEOID-only block routes
-  (`fetch=True`). Keep the runtime footprint minimal otherwise.
+  linters on this: `E251`/`E252` are ignored). `ruff check` clean with
+  `select = ["E","F","W","I","N","UP","B","C4","SIM"]`. **Never run `ruff format`** --
+  it strips the kwarg `=` spacing; lint only.
+- **API shape:** `Client` with one method per route; `Reply` / `Paginator`. Routes
+  with geometry convert via `spatial.py` (`to_geopandas()`), everything else via
+  `tabular.py` (`to_pandas()`); both are public. The `Client._deliver()` chokepoint
+  routes by the resolved output mode.
+- **Output modes (`output`, default `"spatial"`):** `"spatial"` returns a
+  `GeoDataFrame` where geometry applies (points, isochrone and block polygons) and a
+  plain `DataFrame` for catalog and summary routes; `"tabular"` returns a plain
+  `DataFrame` everywhere and never downloads block boundaries; `"raw"` returns the
+  `Reply` / `Paginator`. Set it on the client (`close.output = "raw"`) or per call
+  (`..., output = "tabular"`). `health`/`last_updated`/`isochrone_meta` are always raw;
+  a 304 is always raw. Metering + envelope ride on `df.attrs`. Keep the R SDK's
+  identical `output` vocabulary in step.
+- **Dependencies:** `pandas>=1.5` and `geopandas>=0.14` are hard dependencies. `pygris`
+  is the `[tiger]` extra, used only to fetch block boundaries for the GEOID-only block
+  routes in `spatial` mode. Keep the runtime footprint minimal otherwise.
 - **Tutorials (notebooks):** dead-simple and linear, **no helper functions**. Pull
   destination-type ids from the **free catalog** (`client.destination_types()`), never
-  hardcode numeric codes. Draw a **map at each stage**. **No token-cost talk.** After a
-  placeholder key, inline `# use your own key here`.
+  hardcode numeric codes. Draw a **map at each stage**. State the tutorial's **measured
+  token usage** in one italic line near the top ("Running this tutorial uses about N
+  tokens."); keep every tutorial **under 5,000 tokens** and do not publish a cheaper
+  variant on the same page. No other token-cost talk in the body except the dedicated
+  `docs/token_use.md` page. After a placeholder key, inline `# use your own key here`.
 - **Example cities:** Somerville MA (home search), Richmond VA (amenity basket),
   Providence RI (competitor walksheds). **No Seattle anywhere.**
 - **Docs execute live** at build time (see below), guarded on `CLOSECITY_KEY` so a

CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.1.0
+
+Tabular results by default, across every route.
+
+- New `output` mode replaces the `spatial` flag: `Client(output = "spatial")` (the
+  default) returns a `GeoDataFrame` where geometry applies and a plain
+  `pandas.DataFrame` for catalog and summary routes; `output = "tabular"` returns a
+  plain `DataFrame` everywhere and never downloads block boundaries (the cheap path
+  when you only want the numbers); `output = "raw"` returns the underlying `Reply` /
+  `Paginator`. Set it on the client or per call.
+- Catalog routes (`modes()`, `destination_types()`, `vintage()`, `places()`) and
+  the block and point summaries now return data frames instead of nested replies.
+  `block_summary()` / `point_summary()` broadcast the origin GEOID to a `geoid`
+  column. `isochrone(format = "blocks")` now converts too.
+- Metering and envelope metadata (`tokens_charged`, `tokens_remaining`, `etag`,
+  `block_geoid`, `assumptions`, ...) ride on `df.attrs`.
+- New `to_pandas()` module function and `Reply.to_pandas()` / `Paginator.to_pandas()`
+  methods, beside the existing geopandas ones. `pandas` is now a direct dependency.
+
 ## 1.0.0
 
 First public release of the `closecity` Python client for the Close API

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "closecity"
-version = "1.0.0"
+version = "1.1.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"
@@ -19,7 +19,7 @@ classifiers = [
     "Programming Language :: Python :: 3",
     "Topic :: Scientific/Engineering :: GIS",
 ]
-dependencies = ["httpx>=0.27", "geopandas>=0.14"]
+dependencies = ["httpx>=0.27", "pandas>=1.5", "geopandas>=0.14"]
 
 [project.urls]
 Homepage = "https://close.city"
@@ -42,7 +42,18 @@ where = ["src"]
 
 [tool.ruff]
 line-length = 90
+target-version = "py39"
 
 [tool.ruff.lint]
-# House style: spaces around '=' in keyword args and defaults.
+select = ["E", "F", "W", "I", "N", "UP", "B", "C4", "SIM"]
+# House style: spaces around '=' in keyword args and defaults (E251/E252). Do NOT
+# run `ruff format` here; it strips those spaces. Lint only with `ruff check`.
 ignore = ["E251", "E252"]
+
+[tool.ruff.lint.per-file-ignores]
+# `Point` is the shapely class passed around and called as a constructor; the
+# uppercase name is deliberate (like sklearn's X), so allow it here.
+"src/closecity/spatial.py" = ["N803", "N806"]
+
+[tool.ruff.format]
+quote-style = "double"

src/closecity/__init__.py

@@ -8,7 +8,6 @@
 """
 
 from .client import Client, Paginator, Reply
-from .spatial import to_geopandas
 from .errors import (
     AuthenticationError,
     BadRequestError,
@@ -20,14 +19,17 @@
     ServiceUnavailableError,
     TokensExhaustedError,
 )
+from .spatial import to_geopandas
+from .tabular import to_pandas
 
-__version__ = "1.0.0"
+__version__ = "1.1.0"
 
 __all__ = [
     "Client",
     "Paginator",
     "Reply",
     "to_geopandas",
+    "to_pandas",
     "CloseError",
     "CloseAPIError",
     "BadRequestError",