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