Three small modules every later lesson imports.

1 Coordinate reference systems — core/crs.py

Two constants and two helpers. The constants name the CRSs the package will use everywhere; the helpers reproject a GeoDataFrame in or out:

WORKING_CRS = "EPSG:2230"   # CA State Plane Zone 6 (NAD83), US survey feet
WEB_CRS     = "EPSG:4326"   # WGS84 lon/lat for web maps

def to_working(gdf): ...    # reproject to WORKING_CRS
def to_web(gdf):     ...    # reproject to WEB_CRS

The helpers refuse to operate on a GeoDataFrame with no CRS — coordinates without a CRS are ambiguous and any operation on them is unreliable. Better to fail fast with a clear message than to silently produce wrong distances.

If you’re adapting the package for a different region, change WORKING_CRS to the appropriate projected CRS for your area — epsg.io is the canonical lookup. WGS84 stays at EPSG:4326 universally.

2 DuckDB session — core/duckdb_session.py

DuckDB is the package’s compute engine: serverless, runs in-process, reads parquet straight off disk. The spatial extension adds ST_* functions and geometry types so we can do spatial work in SQL when that’s the fastest path.

connect() opens a connection, tries LOAD spatial first (fast if the extension is already installed), and falls back to INSTALL spatial; LOAD spatial on first use. After this lesson, anything that needs DuckDB calls connect() and gets a session that’s ready for spatial SQL.

from opentrash.core.duckdb_session import connect

con = connect()
row = con.execute("SELECT ST_AsText(ST_Point(1.0, 2.0))").fetchone()
# -> ('POINT (1.0 2.0)',)

3 Parcels — prep/parcels.py

A parcel is a property lot with a boundary polygon. In waste operations parcels are how we reason about what should be served. Three functions:

• load_parcels(path) — read a vector file (GeoParquet, GeoPackage, etc.), ensure it’s in WORKING_CRS, return a GeoDataFrame. Refuses files with no CRS.
• bbox_filter(gdf, minx, miny, maxx, maxy) — the fast first pass. GeoPandas’s spatial-index-backed cx indexer narrows to parcels that intersect a bounding box without doing exact-geometry math. Use this before expensive intersects/within operations on the much smaller result.
• bbox_from_geometry(geom, buffer=0) — produce a bounding-box tuple from a geometry, optionally padded by a buffer (feet, in the working CRS). Pair this with bbox_filter for “parcels within N feet of this route.”

The bbox prefilter is the core performance pattern that will repeat across the package — for routes (Lesson 3), for the GPS-to-parcel join (Lesson 8), for everything that needs “narrow down before doing expensive work.”

4 Tests with synthetic data

One test file per module, all using small synthetic geometries (a few boxes in San Diego, no real data needed):

• tests/test_crs.py — constants are correct; reprojection round-trips; no-CRS input raises.
• tests/test_duckdb_session.py — connect() works; spatial functions are available. (These skip cleanly in environments where the extension can’t be downloaded.)
• tests/test_parcels.py — load round-trips; bbox_filter narrows correctly; no-CRS file raises; bbox_from_geometry math is right.

pip install -e ".[dev]"
ruff check .
pytest -q

5 Commit and push

git add .
git commit -m "Lesson 2: core/crs, core/duckdb_session, prep/parcels"
git push origin main

CI runs ruff + pytest on the push. Green check means the foundation is solid.