AGENTS.md

Guidance for coding agents working in qgis_osminfo.

1) Repository Overview

• Language: Python
• Project type: QGIS plugin (NextGIS OSMInfo)
• Domain: OpenStreetMap / Overpass / Nominatim integration in QGIS
• Package root: src/osminfo
• Build/tool entrypoint: setup.py (custom QGIS plugin builder)
• Lint/format/type config: pyproject.toml (ruff, pyright, pytest)
• Tests root: tests/
• Pre-commit config: .pre-commit-config.yaml

Key files:

• Plugin entry: src/osminfo/__init__.py
• Main plugin class: src/osminfo/osminfo.py
• Compatibility layer: src/osminfo/compat.py
• Logging: src/osminfo/logging.py
• Query builder: src/osminfo/overpass/query_builder/query_builder.py
• Wizard parser/compiler: src/osminfo/overpass/query_builder/wizard/
• Search UI/model: src/osminfo/search/
• Test harness and QGIS stubs: tests/conftest.py

2) Environment Expectations

• Runtime/plugin loading requires a Python environment where qgis imports work.
• Metadata declares qgisMinimumVersion=3.22, qgisMaximumVersion=4.99, supportsQt6=True.
• Compatibility target from pyproject.toml: Python 3.7.
• Many unit tests do not require a real QGIS runtime: tests/conftest.py injects lightweight qgis and qgis.PyQt stubs for wizard, query builder, and model tests.
• Commands related to resources and translations rely on Qt tooling in PATH, notably pyrcc5, lrelease, and pylupdate5.
• If Qt code must run headless, use QT_QPA_PLATFORM=offscreen.

3) Build / Bootstrap / Packaging

Primary help:

python setup.py --help

Supported top-level commands:

python setup.py bootstrap
python setup.py build
python setup.py install --qgis Vanilla --force
python setup.py uninstall --qgis Vanilla
python setup.py clean
python setup.py update_ts
python setup.py config vscode --qgis Vanilla

Bootstrap details:

python setup.py bootstrap
python setup.py bootstrap --qrc
python setup.py bootstrap --ts

Important bootstrap notes:

• bootstrap compiles resources and translations by default.
• bootstrap --ui exists in the CLI, but [tool.qgspb.forms] currently sets compile = false, so .ui files are shipped as raw UI files rather than generated Python modules.
• src/osminfo/resources.py is generated from src/osminfo/resources.qrc and should be regenerated, not hand-maintained.

Install/uninstall examples:

python setup.py install --qgis Vanilla --force
python setup.py install --qgis Vanilla --editable --force
python setup.py install --qgis VanillaFlatpak --force
python setup.py uninstall --qgis Vanilla --profile default

Notes:

• install and uninstall support --qgis {Vanilla,VanillaFlatpak}.
• install also supports --profile, --editable, and --force.
• config vscode generates local development helpers such as .vscode/tasks.json, .vscode/launch.json, and .env.
• python setup.py build creates build/osminfo-<version>.zip.

4) Lint / Format / Type Check

Preferred project command:

pre-commit run --all-files

Equivalent direct commands:

ruff check .
ruff check . --fix
ruff format .
pyright

Pre-commit currently runs:

• addlicense with assets/license-header.txt for Python files
• check-toml
• ruff --fix
• ruff-format

Notes:

• Keep line length at 79.
• Ruff target is py37.
• src/osminfo/resources.py is excluded from Ruff linting because it is generated.

5) Test Commands (Single-Test Focus)

Run full suite:

python -m pytest tests

Run a single file:

python -m pytest tests/test_query_builder.py
python -m pytest tests/wizard/test_parser.py

Run a single test function:

python -m pytest tests/test_query_builder.py::test_build_for_coords_accepts_qgs_point_xy
python -m pytest tests/wizard/test_parser.py::test_parse_regex_and_global_bounds

Useful selectors:

python -m pytest tests -k "query_builder"
python -m pytest tests -x -vv

Important test caveats:

• Current tests are mostly deterministic unit tests around query building, search completion, and wizard parsing/rendering.
• tests/conftest.py provides stubbed QGIS and Qt modules, so keep new tests at that level when possible.
• Avoid adding tests that depend on live Overpass or Nominatim endpoints unless explicitly required.

6) Cursor / Copilot Rules Check

Repository scan found:

• No .cursorrules
• No .cursor/rules/
• No .github/copilot-instructions.md

If these files appear later, treat them as high-priority constraints and update this document.

7) Code Style Guidelines

Imports

• Order imports as: stdlib -> third-party/QGIS/Qt -> local package imports.
• Prefer explicit imports over wildcard imports.
• Import Qt only from qgis.PyQt, never from PyQt5 directly.

Formatting

• Follow Ruff formatting and linting configuration from pyproject.toml.
• Respect the 79-character limit.
• Preserve existing file structure and avoid unrelated refactors.

Types and Annotations

• Add type hints for new or changed public APIs and non-trivial internals.
• Keep annotations compatible with Python 3.7.
• Use narrow pyright: ignore[...] comments only when needed for QGIS typing gaps.

Naming

• Functions, variables, modules: snake_case
• Classes, exceptions, enums: PascalCase
• Constants: UPPER_SNAKE_CASE
• When overriding Qt/QGIS APIs, preserve the expected camelCase method names.

Error Handling

• Prefer early returns for guard conditions.
• Keep user-facing messages short and actionable.
• Preserve exception causes with raise ... from error where helpful.

Logging

• Use the logging helpers from src/osminfo/logging.py.
• Prefer logger-based diagnostics over print() in plugin code.
• Use debug logging for operational detail and warnings/errors for user-impacting failures.

QGIS / Qt Compatibility

• Respect compatibility shims in src/osminfo/compat.py.
• Do not remove version guards without checking the QGIS 3.22 to 4.99 support range.
• Be careful with Qt5/Qt6 differences, especially around moved Qt classes.

UI / Resources / Translations

• Keep .ui files under ui subfolder unless there is a strong reason to move them.
• .ui files are packaged directly; do not assume generated Python UI modules exist.
• Regenerate resources and translations through setup.py instead of editing generated outputs manually.
• Keep metadata.txt, pyproject.toml, and packaged resource paths aligned.

Tests

• Prefer narrow regression tests near the affected subsystem.
• For wizard/query changes, add or update pure pytest tests before considering integration coverage.
• Keep tests isolated and deterministic.

8) Agent Workflow Checklist

• Make minimal, task-scoped changes.
• Check whether the target file is generated before editing it.
• Run focused tests first, then broader checks if the change warrants it.
• Run pre-commit run --all-files for substantial Python changes.
• Do not commit generated caches such as __pycache__, .pytest_cache, or .ruff_cache.
• Preserve existing public behavior unless the task explicitly requires changing it.