90 lines
2.3 KiB
Markdown
90 lines
2.3 KiB
Markdown
# 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](https://click.palletsprojects.com/)
|
|
- HTTP via [Requests](https://requests.readthedocs.io/)
|
|
- 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:
|
|
|
|
```python
|
|
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
|
|
```
|