1378412a9e
* Deconstruct AGENTS.md to context dir * Split guidelines applicable to both humans and agents to top-level `context` dir. * Instruct agents to read all context files for now- piecemeal/just-in-time context ingestion has been spotty and problematic to date. Co-authored-by: Matt Clay <matt@mystile.com> Assisted-by: Claude * update package-data sanity to ignore context * markdown line length sanity * Ignore context dir in change detection * Remove core plugin deprecation instructions * Inconsistent with published docs and docsite behavior- resolve those first. --------- Co-authored-by: Matt Clay <matt@mystile.com>
3.1 KiB
Coding style and syntax
For new code and updates to existing code, including unit tests.
In general, prefer newer Python features as they become available. A feature is available when the minimum supported Python version for the code being written supports it, and it doesn't conflict with other supported versions.
Python version support
- Controller code: minimum version defined in
pyproject.toml(requires-python). - Modules/module_utils: minimum version in
lib/ansible/module_utils/basic.py(_PY_MIN). - Modules support a wider Python version range than controller code.
- Supported Python versions for testing are defined within
ansible-test.
Dependencies
- Prefer Python stdlib over external dependencies.
- Use existing code from within the Ansible project.
Markdown
Markdown files use GitHub Flavored Markdown (verified by the "pymarkdown" sanity test).
Use dashes (-) for unordered list items, not asterisks.
End list items with periods.
ASCII characters
- Use ASCII quotes (
'and") instead of Unicode smart quotes (verified by the "no-smart-quotes" sanity test). - Use ASCII dashes (
-or--) instead of em dashes.
Line length
The line limit is 160 characters.
Trailing whitespace
Don't leave trailing whitespace on lines.
Docstrings
Explain what the annotated code does, but don't create structured entries for parameters. Don't document parameter types in docstrings -- use type hints instead.
Anything considered a public API must have a docstring. Internal code should, and it often makes sense for unit tests, too.
Line breaks in source text
Try to stick to one sentence per line in text like docstrings, comments and changelog fragments.
Native type annotations
Use native type hints with from __future__ import annotations (verified by the "boilerplate" sanity test).
Include type annotations on function/method arguments and return types, unless the annotation becomes too complex (e.g. TypedDict).
The "mypy" sanity test only performs type checking on annotated functions/methods.
Prefer PEP 695 type parameter syntax over TypeVar and ParamSpec declarations.
For example, use def foo[T](x: T) -> T instead of declaring T = TypeVar('T') separately.
This does not apply to module_utils/ code, which must support older Python versions that lack the feature.
Format strings
Use f-strings instead of % strings or str.format, except for logging where formatting is deferred.
Quoting strings
Use the !r format qualifier to quote a value instead of manually quoting.
Example: f"A string with a {quoted!r} value."
Code formatting check/fix for internals
The black sanity test runs against all _internal packages, using default settings with an increased line length of 160 and no quote conversion.
Use ansible-test to automatically apply required formatting changes.
Example: ansible-test sanity --test black --fix
Import ordering in modules
The E402 pycodestyle rule (module level import not at top) is ignored.
In lib/ansible/modules/, imports must come after the DOCUMENTATION, EXAMPLES, and RETURN definitions.