From 5d0c5be9dda386aa245d36024b9094ff37ea5e51 Mon Sep 17 00:00:00 2001 From: Zhiwei Liang Date: Fri, 31 Jul 2026 15:48:19 -0400 Subject: [PATCH] Add project guidelines and coding conventions to AGENTS.md --- AGENTS.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..63f49fb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,33 @@ +# Project Guidelines + +## Project Shape +- This is a Python package for the Linode Metadata Service. Runtime code lives in [linode_metadata](linode_metadata), unit tests in [test/unit](test/unit), Linode-backed integration tests in [test/integration](test/integration), and Sphinx docs in [docs](docs). +- Use [README.md](README.md) for installation, usage, and end-to-end testing details; use [CONTRIBUTING.md](CONTRIBUTING.md) for contribution expectations. +- Treat [build](build), [docs/_build](docs/_build), and [linode_metadata.egg-info](linode_metadata.egg-info) as generated artifacts unless the task explicitly concerns packaging output. + +## Architecture +- [linode_metadata/metadata_client.py](linode_metadata/metadata_client.py) owns the sync and async clients, shared HTTP request preparation, token generation/refresh, response parsing, and metadata endpoint methods. Keep `MetadataClient` and `AsyncMetadataClient` behavior in sync when changing client semantics. +- [linode_metadata/watcher.py](linode_metadata/watcher.py) mirrors sync generators and async generators for polling metadata. Watchers yield immediately, then only when `dataclasses.asdict()` differs from the previous response. +- [linode_metadata/objects](linode_metadata/objects) contains lightweight dataclass response wrappers. Classes usually inherit `ResponseBase` with `@dataclass(init=False)`; use `field(metadata={"json": "service_key"})` when the service key differs from the Python attribute. +- Public imports are re-exported from [linode_metadata/__init__.py](linode_metadata/__init__.py); update it only when the public surface changes. + +## Build And Test +- Install dev dependencies with `make dev-install`; this also regenerates [linode_metadata/version.py](linode_metadata/version.py) through the `create-version` target. +- Run fast local checks with `make unit-test` and `make lint`. Use `make format` to run Black, isort, and autoflake. +- Run `make build` for packaging checks. The package supports Python `>=3.9` and configures Black/isort line length at 80 in [pyproject.toml](pyproject.toml). +- Integration tests require the Metadata Service from inside a Linode or Ansible-provisioned test infrastructure. Do not run `make int-test`, `make int-test-local`, or `make test` unless the user asks for integration coverage and the required `LINODE_TOKEN`/environment is available. + +## Coding Conventions +- Preserve sync/async parity: new client endpoints, token behavior, errors, and watcher changes normally need both synchronous and asynchronous implementations plus matching tests. +- Prefer existing `ResponseBase` population behavior for new response objects instead of hand-parsing JSON. Add focused unit tests under [test/unit/objects](test/unit/objects) for object mapping changes. +- Keep request behavior centralized in `BaseMetadataClient` helpers where practical so headers, user agent, timeouts, error handling, and debug logging stay consistent. +- Update Sphinx `.rst` files under [docs/linode_metadata](docs/linode_metadata) when public classes, methods, or response objects change. + +## Test Notes +- Unit tests use pytest and mostly validate response object mapping without network access. +- Integration tests use session-scoped sync and async clients from [test/integration/conftest.py](test/integration/conftest.py), include an autouse 5-second delay to avoid 429s, and exercise real Metadata Service behavior. +- When changing integration assertions, reuse or extend helpers in [test/integration/helpers.py](test/integration/helpers.py) so sync and async tests keep consistent expectations. + +## Maintaining This File +- Keep this file factually accurate. If an agent finds a statement here that is demonstrably incorrect, or makes a code, configuration, or workflow change that invalidates it, update [AGENTS.md](AGENTS.md) in the same change. +- Limit maintenance edits to durable, repository-wide guidance affected by the discovery or change; do not add speculative rules or transient implementation details.