AGENTS.md

Guidelines for AI coding agents working in this repository.

Project overview

A collection of Python CLI tools for working with OpenStreetMap data. Each tool is a standalone Python script using Click for the CLI interface and Requests for HTTP calls.

Repository layout

pyproject.toml              - Package metadata and build configuration
src/
  osm_geojson/
    __init__.py             - Top-level package marker
    pt/
      __init__.py           - Public transport subpackage
      core.py               - Data fetching and processing functions
      cli.py                - Click CLI commands
tests/
  fixtures/                 - Saved OSM API responses for offline testing
  test_osm_pt_geojson.py    - Test suite
README.md                   - User-facing documentation
AGENTS.md                   - This file

osm_geojson is the top-level namespace for all tools in this collection. Each tool lives in its own subpackage (e.g. osm_geojson.pt), with its CLI entry point registered in pyproject.toml under [project.scripts].

Code conventions

Python 3.11+
CLI via Click
HTTP via Requests
Parse XML with lxml if needed; prefer the OSM JSON API where possible
Errors go to stderr; data output goes to stdout
GeoJSON output uses ensure_ascii=False
All modules, functions, and test functions must have docstrings

OSM API

Tools fetch data from the public OSM API:

https://www.openstreetmap.org/api/0.6/

No authentication is required for read-only access. Include a descriptive User-Agent header in all requests.

Type checking

All code uses type hints. Run mypy in strict mode to check:

mypy --strict src/osm_geojson/

Testing

Run the test suite with:

pytest tests/

Tests use the responses library to mock HTTP calls and never hit the live OSM API. Fixture data is stored in tests/fixtures/ as saved API responses.

Example relations used during development

ID	Description
15083963	M11 Istanbul Metro (subway)
18892969	Bus A1: Bristol Airport → Bus Station

Dependencies

Use a virtual environment. Install the package and test dependencies with:

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

2.4 KiB Raw Blame History