Polish the docs: cut AI-tell writing, lead with the SDK line, fix the default-output wording, and install from GitHub until PyPI.

Author: Nathaniel Henry

README.md

@@ -1,16 +1,20 @@
 # closecity
 
-Python client for the Close API. Get travel times from every US census block to
-nearby places, on foot, by bike, and by public transit. This is the data behind
-[close.city](https://close.city), read over the [Close API](https://api.close.city).
+This is the Python software development kit for the Close.City API. It returns
+travel times from every US census block to nearby places, on foot, by bike, and by
+public transit. The data behind [close.city](https://close.city) is served over the
+[Close API](https://api.close.city).
 
 **Documentation:** https://henryspatialanalysis.github.io/closecity-python/
 
 ## Install
 
+Will soon be on PyPI; install from GitHub until then:
+
 ```bash
-pip install closecity
-pip install "closecity[tiger]"   # to auto-download census-block boundaries
+pip install git+https://github.com/henryspatialanalysis/closecity-python.git
+# add the census-block boundary downloader:
+pip install "closecity[tiger] @ git+https://github.com/henryspatialanalysis/closecity-python.git"
 ```
 
 This pulls in `httpx`, `pandas`, and `geopandas`, so results come back as data
@@ -55,7 +59,7 @@ A few terms come up throughout the API:
 - **Isochrone** or **catchment**: the area you can reach starting from a point
   within a time limit, by a selected travel mode.
 
-## Choosing an output
+## Choose an output
 
 Set `output` on the client, or per call:
 

docs/getting_started.md

@@ -32,7 +32,7 @@ close = Client(os.environ.get("CLOSECITY_KEY"))
 A few terms come up throughout:
 
 - **Census block.** The smallest area the Census Bureau publishes. Each one has a
-  15-digit id, its **GEOID**. Block GEOIDs come from the census — look them up with
+  15-digit id, its **GEOID**. Block GEOIDs come from the census. Look them up with
   `pygris` or the Census Bureau geocoder/API, or read them straight off Close's
   block routes (`blocks_query`, `place_blocks`).
 - **Destination type.** A category of place, such as grocery stores or libraries.
@@ -89,7 +89,7 @@ point instead of a GEOID.
 ## Make a call and map it
 
 Routes with geometry return a GeoDataFrame. `close_map()` draws it on an interactive
-basemap in one line — bright, hoverable points here, with the city boundary behind
+basemap in one line: bright, hoverable points here, with the city boundary behind
 them and the view zoomed to fit.
 
 ```{code-cell} python
@@ -135,34 +135,34 @@ full signatures.
 
 Catalog and lookups (free, no key):
 
-- {py:meth}`~closecity.Client.modes` — the travel modes: walk, bike, transit.
-- {py:meth}`~closecity.Client.destination_types` — the catalog of amenity categories and their numeric ids.
-- {py:meth}`~closecity.Client.places` — a city name to its GEOID and centre point.
-- {py:meth}`~closecity.Client.place_boundary` — the boundary polygon of a census place.
-- {py:meth}`~closecity.Client.vintage` — the data vintage.
-- {py:meth}`~closecity.Client.last_updated` — when the data was last refreshed.
-- {py:meth}`~closecity.Client.isochrone_meta` — isochrone modes, directions, and assumptions.
-- {py:meth}`~closecity.Client.health` — a service health check.
+- {py:meth}`~closecity.Client.modes`: the travel modes (walk, bike, transit).
+- {py:meth}`~closecity.Client.destination_types`: the catalog of amenity categories and their numeric ids.
+- {py:meth}`~closecity.Client.places`: a city name to its GEOID and centre point.
+- {py:meth}`~closecity.Client.place_boundary`: the boundary polygon of a census place.
+- {py:meth}`~closecity.Client.vintage`: the data vintage.
+- {py:meth}`~closecity.Client.last_updated`: when the data was last refreshed.
+- {py:meth}`~closecity.Client.isochrone_meta`: isochrone modes, directions, and assumptions.
+- {py:meth}`~closecity.Client.health`: a service health check.
 
 Travel times from a block or a point:
 
-- {py:meth}`~closecity.Client.block_summary` — walk/bike/transit time from a block to each amenity type.
-- {py:meth}`~closecity.Client.point_summary` — the same, from a `lat`/`lon` point.
-- {py:meth}`~closecity.Client.block_pois` — the individual POIs reachable from a block, each with its travel time.
-- {py:meth}`~closecity.Client.point_pois` — the same, from a `lat`/`lon` point.
+- {py:meth}`~closecity.Client.block_summary`: walk/bike/transit time from a block to each amenity type.
+- {py:meth}`~closecity.Client.point_summary`: the same, from a `lat`/`lon` point.
+- {py:meth}`~closecity.Client.block_pois`: the individual POIs reachable from a block, each with its travel time.
+- {py:meth}`~closecity.Client.point_pois`: the same, from a `lat`/`lon` point.
 
 Points of interest:
 
-- {py:meth}`~closecity.Client.pois_search` — search POIs by radius or bounding box.
-- {py:meth}`~closecity.Client.poi` — the details of one POI.
-- {py:meth}`~closecity.Client.poi_catchment` — the blocks that can walk to a POI (its catchment).
+- {py:meth}`~closecity.Client.pois_search`: search POIs by radius or bounding box.
+- {py:meth}`~closecity.Client.poi`: the details of one POI.
+- {py:meth}`~closecity.Client.poi_catchment`: the blocks that can walk to a POI (its catchment).
 
 Whole areas:
 
-- {py:meth}`~closecity.Client.blocks_query` — per-block travel times for a polygon, or a centre and radius.
-- {py:meth}`~closecity.Client.place_blocks` — per-block travel times for every block in a place.
-- {py:meth}`~closecity.Client.place_pois` — every POI within a place's boundary.
-- {py:meth}`~closecity.Client.isochrone` — travel-time contours from a block or a point.
+- {py:meth}`~closecity.Client.blocks_query`: per-block travel times for a polygon, or a centre and radius.
+- {py:meth}`~closecity.Client.place_blocks`: per-block travel times for every block in a place.
+- {py:meth}`~closecity.Client.place_pois`: every POI within a place's boundary.
+- {py:meth}`~closecity.Client.isochrone`: travel-time contours from a block or a point.
 
 ## Handling errors
 

docs/index.rst

@@ -1,9 +1,10 @@
 closecity
 =========
 
-Python client for the Close API (`api.close.city <https://api.close.city>`_). Get
+This is the Python software development kit for the Close.City API. It returns
 travel times from every US census block to nearby places, on foot, by bike, and by
-public transit. This is the data behind `close.city <https://close.city>`_.
+public transit. The data behind `close.city <https://close.city>`_ is served over
+`api.close.city <https://api.close.city>`_.
 
 .. code-block:: python
 
@@ -16,10 +17,10 @@ public transit. This is the data behind `close.city <https://close.city>`_.
    supermarkets = close.pois_search(lat = 41.823, lon = -71.412, radius_m = 1500, type = 30)
    close_map(supermarkets, color = "#e8590c")   # interactive map, bright hoverable points
 
-Results are tabular by default: a GeoDataFrame where geometry applies, a plain
-DataFrame otherwise. Install with ``pip install closecity``. The catalog and
-lookup routes are free; the data routes need a key from
-`account.close.city <https://account.close.city>`_.
+By default, results come back as a GeoDataFrame where geometry applies (points,
+isochrones, and block polygons) and a plain DataFrame otherwise. Install it from GitHub for now (see
+:doc:`installation`); PyPI is coming. The catalog and lookup routes are free; the
+data routes need a key from `account.close.city <https://account.close.city>`_.
 
 .. toctree::
    :maxdepth: 2

docs/installation.rst

@@ -1,11 +1,14 @@
 Installation
 ============
 
+The package will soon be published to PyPI. Until then, install it from GitHub:
+
 .. code-block:: bash
 
-   pip install closecity
+   pip install git+https://github.com/henryspatialanalysis/closecity-python.git
 
-This pulls in `httpx <https://www.python-httpx.org/>`_ and
+Once it lands on PyPI, ``pip install closecity`` will work. Either way, this pulls
+in `httpx <https://www.python-httpx.org/>`_ and
 `geopandas <https://geopandas.org/>`_, so feature methods return GeoDataFrames out of
 the box.
 
@@ -18,7 +21,7 @@ download the boundaries for you, add the ``tiger`` extra:
 
 .. code-block:: bash
 
-   pip install "closecity[tiger]"
+   pip install "closecity[tiger] @ git+https://github.com/henryspatialanalysis/closecity-python.git"
 
 You do not need it for ``output="tabular"``, which returns the same rows without
 geometry.

docs/tutorials/amenity_basket.md

@@ -99,7 +99,7 @@ for a in basket["amenity"]:
 ```
 
 Parks and restaurants tend to be everywhere; supermarkets and libraries are usually
-the hardest to reach. Map the library coverage — every block shown, the covered ones
+the hardest to reach. Map the library coverage: every block shown, the covered ones
 highlighted, the library locations as points, the city boundary behind.
 
 ```{code-cell} python
@@ -148,7 +148,7 @@ for a in basket["amenity"]:
 
 ## Who is one or two amenities away
 
-The residents worth targeting first are the ones *almost* there — a block with five
+The residents worth targeting first are the ones *almost* there: a block with five
 of the six is a much easier win than one with none. Count how many amenities each
 block is missing, and for the blocks short by just one or two, break down which
 amenities are the gap.

docs/tutorials/competitor_walksheds.md

@@ -76,7 +76,7 @@ close_map(
 
 Now split the walkshed by block. A single `block_pois` call takes the whole list of
 walkshed blocks and returns, for every block, each cafe its residents can walk to
-within 10 minutes — the real routed answer, not a straight-line guess, and one
+within 10 minutes: the real routed answer, not a straight-line guess, and one
 request rather than one per block. Passing a list of GEOIDs tags every row with its
 origin `geoid`, so grouping by it reads two things per block: how many cafes are in
 reach, and which one is closest by walk time.
@@ -98,17 +98,25 @@ our_shed["closest_cafe"] = our_shed["geoid"].map(winners["dest_id"])
 ## How many cafes each block can reach
 
 Shade every block in the walkshed by the number of cafes within a 10-minute walk;
-blue marks the blocks with the most choice.
+blue marks the blocks with the most choice, and the cafes those blocks can reach are
+drawn on top as points.
 
 ```{code-cell} python
-close_map(our_shed, fill = "n_cafes", reverse = True, boundary = city_boundary)
+reachable = cafes[cafes["dest_id"].isin(reach["dest_id"].unique())]
+close_map(
+    our_shed,
+    fill = "n_cafes",
+    reverse = True,
+    points = reachable,
+    boundary = city_boundary,
+)
 ```
 
 ## Which cafe is closest
 
 Give each cafe that wins at least one block a colour, then paint every block with the
 colour of its closest cafe. The cafe points share those colours. The result is the
-contested ground — where our shop's catchment gives way to a competitor's.
+contested ground: where our shop's catchment gives way to a competitor's.
 
 ```{code-cell} python
 closest = [int(c) for c in our_shed["closest_cafe"].dropna().unique()]

docs/tutorials/first_map.md

@@ -49,7 +49,7 @@ start_lat = providence_ri["lat"]
 
 ## Read travel times from a starting point
 
-Pick a starting point — here the centre of Providence — and ask how long it takes to
+Pick a starting point, here the centre of Providence, and ask how long it takes to
 walk to each kind of amenity. `point_summary()` takes a `lat`/`lon` instead of a block
 GEOID. Join the catalog's readable `name` and sort by time, so the nearest things are
 on top.
@@ -67,7 +67,7 @@ walk_times.sort_values("travel_time")[["name", "travel_time"]]
 
 A 30-minute walk is a travel-time question, not a distance one, so let the routing
 answer it directly: `point_pois` returns every POI reachable from the starting point
-within `max_minutes`, each carrying its walk time — no isochrone to overlay.
+within `max_minutes`, each carrying its walk time, with no isochrone to overlay.
 `close_map()` draws them in one line, shaded by that walk time (blue = closest),
 with the starting point marked by an X and the city boundary behind for context.
 
@@ -110,7 +110,7 @@ close_map(rings, fill = "contour")
 
 ## Walk versus transit
 
-The same starting point and the same 30-minute budget, on foot and by bus — the
+The same starting point and the same 30-minute budget, on foot and by bus: the
 clearest way to see what transit buys you.
 
 ```{code-cell} python

docs/tutorials/home_search.md

@@ -59,7 +59,7 @@ city_boundary = close.place_boundary(geoid = city["geoid"])
 ## See what is around
 
 Look at the raw ingredients first: every supermarket, restaurant, and frequent-transit
-stop **within Somerville**, from `place_pois` — the city boundary, not a guessed
+stop **within Somerville**, from `place_pois`. The city boundary, not a guessed
 radius, is the edge. Give each category a colour and map them together.
 
 ```{code-cell} python
@@ -84,10 +84,10 @@ close_map(
 ## Find the blocks that qualify
 
 Somerville is a census place, so one call by place GEOID pulls the per-block walk
-times for every block in the city — `place_blocks` reads every page and returns one
+times for every block in the city. `place_blocks` reads every page and returns one
 row per (block, category); block boundaries come from `pygris`, downloaded once and
 cached. (To search an arbitrary area instead, use `blocks_query` with a centre and
-radius or a polygon — we do that with a radius in the other tutorials only to keep
+radius or a polygon. We do that with a radius in the other tutorials only to keep
 their token cost low; a place GEOID pulls the whole city.)
 
 ```{code-cell} python
@@ -165,7 +165,7 @@ close_map(
 ```
 
 Keep the qualifying blocks that also sit inside both commutes. The final map shows
-those winning blocks, with the shortlist — inside both commutes — highlighted, over
+those winning blocks, with the shortlist (inside both commutes) highlighted, over
 the two commute walksheds.
 
 ```{code-cell} python

src/closecity/client.py

@@ -52,8 +52,8 @@ def _as_list(value: Any) -> Any:
 def _point_origins(points: Any) -> list[dict[str, float]]:
     """Normalise a batch of point origins to ``[{"lon": .., "lat": ..}, ...]``.
 
-    Each item is either a ``(lat, lon)`` pair — matching the ``(lat, lon)``
-    argument order of the single-point calls — or a ``{"lat": .., "lon": ..}``
+    Each item is either a ``(lat, lon)`` pair (matching the ``(lat, lon)``
+    argument order of the single-point calls) or a ``{"lat": .., "lon": ..}``
     mapping.
     """
     out: list[dict[str, float]] = []
@@ -403,8 +403,8 @@ def point_summary(
         The resolved block GEOID is echoed as `resolved_block` and broadcast to a
         `geoid` column. A DataFrame, or a raw `Reply`.
 
-        Pass a **list of points** as the first argument — each a `(lat, lon)` pair
-        or a `{"lat": .., "lon": ..}` mapping — to query many points in one call.
+        Pass a **list of points** as the first argument (each a `(lat, lon)` pair
+        or a `{"lat": .., "lon": ..}` mapping) to query many points in one call.
         Each row is tagged with its `origin_lat` / `origin_lon`; resolved blocks,
         `errors`, and `truncated` ride on `df.attrs`."""
         if isinstance(lat, (list, tuple)):
@@ -433,8 +433,8 @@ def point_pois(
         GeoDataFrame of points (a plain DataFrame under `output="tabular"`, a
         `Paginator` under `output="raw"`).
 
-        Pass a **list of points** as the first argument — each a `(lat, lon)` pair
-        or a `{"lat": .., "lon": ..}` mapping — to query many points in one call.
+        Pass a **list of points** as the first argument (each a `(lat, lon)` pair
+        or a `{"lat": .., "lon": ..}` mapping) to query many points in one call.
         Each row is tagged with its `origin_lat` / `origin_lon`. The batch form is
         not paginated (`limit` is ignored)."""
         if isinstance(lat, (list, tuple)):
@@ -544,8 +544,8 @@ def place_pois(
         output: str | None = None,
     ):
         """Every point of interest within a census place (city or town), by
-        place GEOID. The place analog of `pois_search`; pass `type` to get,
-        e.g., all supermarkets in a city. Spatial only — no travel times. A
+        place GEOID. The place analogue of `pois_search`; pass `type` to get,
+        e.g., all supermarkets in a city. Spatial only, no travel times. A
         GeoDataFrame of points (a plain DataFrame under `output="tabular"`, a
         `Paginator` under `output="raw"`)."""
         return self._deliver(Paginator(

src/closecity/errors.py

@@ -50,7 +50,8 @@ def __init__(
         if detail:
             message += f": {detail}"
         if hint:
-            message += f" — {hint}"
+            sep = "" if message.endswith((".", "!", "?")) else "."
+            message += f"{sep} {hint}"
         if request_id:
             message += f" (request {request_id})"
         super().__init__(message)