Agent Guide

Source of Truth

This is the official synchronous Python SDK for the Linode API. Supported Python versions come from pyproject.toml (>=3.10); do not infer support from the older environment names still present in tox.ini.
Make changes only in canonical source trees such as linode_api4/, test/, docs/, examples/, and .github/. Do not edit generated copies or output in build/, dist/, docs/build/, docs/_build/, or linode_api4.egg-info/.
linode_api4/version.py is generated by make create-version and make build. Do not hand-edit it for ordinary feature work.
Use README.rst for setup and test details and CONTRIBUTING.md for contribution policy. Keep this file limited to guidance that is easy to miss while navigating the repository.

linode_api4/linode_client.py owns HTTP behavior and wires API groups onto LinodeClient; linode_api4/groups/ exposes operations; linode_api4/objects/ defines resource models; linode_api4/paginated_list.py handles collection pagination.
Follow the nearest existing group method, model, and unit test before adding a new pattern. Collection methods normally use client._get_and_filter(...); create/update/delete methods use the client's request helpers and return model objects where appropriate.
Models are lazy-loaded, and reading an unknown or stale property may issue an API request. Read docs/guides/core_concepts.rst before changing model properties, relationships, filtering, or pagination.
New public models must be exported from linode_api4/objects/__init__.py. New groups must be exported from linode_api4/groups/__init__.py and wired into LinodeClient. Preserve public API compatibility unless the task explicitly requires a breaking change.
Public behavior belongs in Sphinx-compatible docstrings and, when needed, the source files under docs/. Never edit rendered documentation.

Start with the narrowest relevant unit test, for example python -m pytest test/unit/objects/linode_test.py -k test_name. Run make test-unit for the full mocked unit suite.
Unit tests normally extend test.unit.base.ClientBaseCase. GET requests are resolved from JSON under test/fixtures/; use mock_post, mock_put, and mock_delete for other verbs and assert the captured URL, body, or headers.
Fixture names encode endpoint paths: a single underscore becomes /, while a doubled underscore becomes a literal _. Paginated fixtures containing results also provide per-ID responses automatically when items include an id field. See test/unit/fixtures.py before inventing custom request mocking.
make test-int and make test-smoke call the live Linode API, require LINODE_TOKEN, and may create or delete real resources. Run them only when the change requires live validation and the environment is intentionally configured.

Install development dependencies with make dev-install.
Formatting is Black + isort + autoflake with settings in pyproject.toml. make format rewrites all of linode_api4/ and test/, so review the worktree before and after using it for a focused change.
make lint is the broad CI-equivalent check: it builds distributions, checks formatting/imports, runs pylint, and validates package metadata. Prefer focused tests first because this target regenerates build artifacts and version metadata.

Target the dev branch unless the task specifies otherwise.
PR titles must use TPT-1234: Description; CI exempts only the labels documented in .github/workflows/ci.yml.
Keep changes focused, add tests for behavior changes, and use .github/pull_request_template.md when drafting the PR description.