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

osm-pt-geojson  - Fetch a public transport route relation, list stops, export GeoJSON
README.md       - User-facing documentation
AGENTS.md       - This file

New tools are added as individual scripts at the repo root.

Code conventions

Python 3, shebang #!/usr/bin/python3
CLI via Click
HTTP via Requests
Parse XML with lxml if needed; prefer the OSM JSON API where possible
Scripts have no .py extension and are executable
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 scripts use type hints. Run mypy in strict mode to check:

mypy --strict osm-pt-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.

Because tool scripts have hyphens in their names and no .py extension, they cannot be imported with the normal importlib.util.spec_from_file_location. Use importlib.machinery.SourceFileLoader instead:

import importlib.machinery
import importlib.util

_loader = importlib.machinery.SourceFileLoader("osm_pt_geojson", "osm-pt-geojson")
_spec = importlib.util.spec_from_loader("osm_pt_geojson", _loader)
assert _spec
osm = importlib.util.module_from_spec(_spec)
_loader.exec_module(osm)

Example relations used during development

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

Dependencies

Install with pip:

pip install click requests

2.3 KiB Raw Blame History