mirror of
https://github.com/ansible/ansible.git
synced 2026-07-28 00:24:41 +02:00
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>
84 lines
3.1 KiB
Markdown
84 lines
3.1 KiB
Markdown
# 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](https://github.github.com/gfm/) (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.
|