pyd3js-geo

Python port of d3-geo.

Tracked upstream version: upstream_lock.json (d3-geo 3.1.1).

What is d3-geo?

d3-geo is D3’s geographic module: spherical geometry (distance, area, bounds), GeoJSON streaming, graticules, and cartographic projections. This package brings the same public API names and workflows to Python using plain GeoJSON-shaped dict / list objects.

What you get

• Upstream export parity for the pinned d3-geo@3.1.1 index.js: see the compatibility matrix below (nothing marked [missing]).
• Always-on tests: smoke tests, README / user guide examples, and export-matrix consistency checks.
• Ported upstream JS tests under package_tests/test_upstream_*.py, opt-in via PYD3JS_GEO_FULL_UPSTREAM=1 (see Testing).

Install

From PyPI:

pip install pyd3js-geo

This repo is a uv workspace monorepo. For local development:

uv sync --group dev

Usage

from pyd3js_geo import geoDistance, geoMercator, geoPath

print(f"{geoDistance([0, 0], [90, 0]):.12f}")

projection = geoMercator().translate([0, 0]).scale(1)
path = geoPath(projection)
line = {"type": "LineString", "coordinates": [[0, 0], [1, 0]]}
print(path(line))

1.570796326795
M0,0L0.017,0

Projection factories return configurable objects (center, scale, clip, fit helpers, etc.), mirroring d3-geo’s chaining style in Python.

Stability & intentional differences

• Python vs JavaScript: no browser canvas; upstream PNG raster snapshots are not ported (see test_upstream_snapshot.py for deterministic path-context checks instead).
• Numerical parity: with PYD3JS_GEO_FULL_UPSTREAM=1, the ported d3-geo pytest suite is the parity harness (including composite geoAlbersUsa and fit* cases exercised there).
• Typing: the workspace applies targeted ty overrides for dynamic projection objects (mirroring JS patterns).

Compatibility matrix

Pinned upstream inventory: docs/UPSTREAM_API.md (d3-geo@3.1.1).

Legend:

• [implemented]: exported from pyd3js_geo and tracked in this matrix (default tests and/or doc examples; deeper parity via opt-in upstream suite).

Upstream exports (d3-geo@3.1.1)

• geoArea — [implemented]
• geoBounds — [implemented]
• geoCentroid — [implemented]
• geoCircle — [implemented]
• geoClipAntimeridian — [implemented]
• geoClipCircle — [implemented]
• geoClipExtent — [implemented]
• geoClipRectangle — [implemented]
• geoContains — [implemented]
• geoDistance — [implemented]
• geoGraticule — [implemented]
• geoGraticule10 — [implemented]
• geoInterpolate — [implemented]
• geoLength — [implemented]
• geoPath — [implemented]
• geoAlbers — [implemented]
• geoAlbersUsa — [implemented]
• geoAzimuthalEqualArea — [implemented]
• geoAzimuthalEqualAreaRaw — [implemented]
• geoAzimuthalEquidistant — [implemented]
• geoAzimuthalEquidistantRaw — [implemented]
• geoConicConformal — [implemented]
• geoConicConformalRaw — [implemented]
• geoConicEqualArea — [implemented]
• geoConicEqualAreaRaw — [implemented]
• geoConicEquidistant — [implemented]
• geoConicEquidistantRaw — [implemented]
• geoEqualEarth — [implemented]
• geoEqualEarthRaw — [implemented]
• geoEquirectangular — [implemented]
• geoEquirectangularRaw — [implemented]
• geoGnomonic — [implemented]
• geoGnomonicRaw — [implemented]
• geoIdentity — [implemented]
• geoProjection — [implemented]
• geoProjectionMutator — [implemented]
• geoMercator — [implemented]
• geoMercatorRaw — [implemented]
• geoNaturalEarth1 — [implemented]
• geoNaturalEarth1Raw — [implemented]
• geoOrthographic — [implemented]
• geoOrthographicRaw — [implemented]
• geoStereographic — [implemented]
• geoStereographicRaw — [implemented]
• geoTransverseMercator — [implemented]
• geoTransverseMercatorRaw — [implemented]
• geoRotation — [implemented]
• geoStream — [implemented]
• geoTransform — [implemented]

Testing

Run this package’s tests:

uv run pytest packages/pyd3js-geo/package_tests -q

Coverage (Python)

uv run pytest packages/pyd3js-geo/package_tests --cov=pyd3js_geo --cov-report=term-missing

Ported d3-geo JS tests (opt-in)

Tests under package_tests/test_upstream_*.py are ported from d3-geo test/ (v3.1.x). They are skipped by default unless PYD3JS_GEO_FULL_UPSTREAM=1 is set (keeps default CI fast).

PYD3JS_GEO_FULL_UPSTREAM=1 uv run pytest packages/pyd3js-geo/package_tests -q

100% line coverage (excluding `pragma: no cover` tails) is enforced with:

`PYD3JS_GEO_FULL_UPSTREAM=1 uv run pytest packages/pyd3js-geo/package_tests --cov=pyd3js_geo --cov-fail-under=100 --cov-report=term-missing:skip-covered -q`

Fixtures (gzip) live in package_tests/fixtures/ (ny.json.gz, us_land.geojson.gz, world_land_50m.geojson.gz, …). PNG raster snapshots are not ported; test_upstream_snapshot.py exercises the same canvas-style command stream as d3’s path context tests.

Lint / types

uv run ruff check packages/pyd3js-geo
uv run ty check .

Build (release artifact)

uv build packages/pyd3js-geo

Wheels and sdists are written to the workspace dist/ directory.

Releasing (PyPI)

0.1.0 checklist (before upload): version = 0.1.0 in pyproject.toml and pyd3js_geo.__version__; docs/CHANGELOG.md entry for the release; uv build packages/pyd3js-geo produces dist/pyd3js_geo-0.1.0-*; default tests + (recommended) PYD3JS_GEO_FULL_UPSTREAM=1 with --cov-fail-under=100; ruff check / ruff format, ty check packages/pyd3js-geo.

1. Publish pyd3js-array ≥ 0.1.0 first (runtime dependency).
2. Align version in pyproject.toml with __version__ in src/pyd3js_geo/__init__.py, and record changes in docs/CHANGELOG.md (dated section per release).
3. Confirm uv run pytest packages/pyd3js-geo/package_tests, ruff check, ruff format, and ty check packages/pyd3js-geo pass; for parity/coverage gate use commands under Testing.
4. From the monorepo root:

uv build packages/pyd3js-geo

Upload dist/pyd3js_geo-*.whl and dist/pyd3js_geo-*.tar.gz (for example uv publish or twine upload).

Documentation

• Guides (topics): docs/guides/README.md
• User guide (runnable examples): docs/USER_GUIDE.md
• Changelog: docs/CHANGELOG.md
• Roadmap / parity notes: docs/ROADMAP.md