Python Coding Standards

Relevant source files

The following files were used as context for generating this wiki page:

• dev/guidelines/python.md
• AGENTS.md
• pyproject.toml
• tasks.py
• dev/guidelines/git-workflow.md
• dev/guidelines/testing.md

Python Coding Standards define the development requirements for the nornir-infrahub project. These standards ensure consistency across the Nornir inventory and task plugins while maintaining strict compatibility with the Infrahub SDK. The project targets Python version >=3.10,<3.15.

Sources: dev/guidelines/python.md:4, AGENTS.md:7

Tooling and Automation

The project uses uv for dependency management and invoke for task automation. Developers must run formatting and linting tools before pushing code to ensure all CI gates pass.

Quality Control Commands

Command	Tool	Purpose
invoke format	Ruff, rumdl	Formats Python files and Markdown structure.
invoke lint	All linters	Executes the full suite of linting tools.
invoke lint-ruff	Ruff	Performs fast linting and import sorting.
invoke lint-pylint	Pylint	Performs deep static code analysis.
invoke lint-ty	ty	Validates Python type hints.
invoke lint-yaml	yamllint	Validates YAML file syntax.

Sources: tasks.py:16-70, dev/guidelines/python.md:8-16

Linting Pipeline Flow

The following diagram illustrates the sequence of checks performed during the standard linting workflow.

Code Style and Formatting

The repository enforces specific stylistic choices to maintain a clean codebase. Ruff serves as the primary formatter, configured for a 120-character line length and double-quoted strings.

Naming Conventions

• Classes: Use PascalCase.
• Functions and Variables: Use snake_case.
• Private Helpers: Prefix with a leading underscore (e.g., _resolve_mapping).

Sources: dev/guidelines/python.md:32-34, pyproject.toml:138-142

Documentation Requirements

Every public class and function must include a docstring. These docstrings are extracted by invoke generate-docs to build the official plugin reference. Docstrings must include:

• Args: section.
• Returns: section.
• Raises: section.
• Example: code block.

Sources: dev/guidelines/python.md:35-39, tasks.py:149-216

Typing and Data Validation

The project mandates type annotations for all public function signatures, parameters, and return values.

Type Checking and Pydantic

• Type Checker: The project uses ty (configured in pyproject.toml).
• Validation: Use Pydantic v2 for structured configuration objects.
• Models: Subclass BaseModel for complex structures or use pydantic.dataclasses for simple records.
• Rules: A few ty rules (e.g., unresolved-import) are relaxed specifically for the Infrahub SDK's dynamic types.

Sources: dev/guidelines/python.md:21-30, pyproject.toml:98-102

Execution Model and Patterns

The runtime code in nornir-infrahub is strictly synchronous.

Synchronous Constraints

Developers must not introduce async def patterns into plugin code. The inventory plugin utilizes InfrahubClientSync and InfrahubNodeSync. Nornir task plugins call SDK methods synchronously to ensure compatibility with the core Nornir framework.

Sources: dev/guidelines/python.md:46-50, AGENTS.md:92-93

Logging and Error Handling

• Logging: Use logging.getLogger(__name__). Do not use print() statements in library code.
• Error Handling: Raise RuntimeError for mapping or resolution failures. Use ValueError for invalid configurations.
• YAML: Use ruamel.yaml in safe mode (typ="safe") and always specify encoding="utf-8".

Sources: dev/guidelines/python.md:40-45, dev/guidelines/python.md:52-55

Testing Standards

Tests are divided into two distinct layers: Unit and Integration.

Testing Guidelines

• Unit Tests: These are the default and must hit no network. Mocks (using unittest.mock) are required for Infrahub interactions.
• Integration Tests: These use infrahub-testcontainers to spin up a live stack. They must inherit from NornirInfrahubIntegration.
• Credentials: Never hardcode tokens. Use PROJECT_ENV_VARIABLES["INFRAHUB_TESTING_INITIAL_ADMIN_TOKEN"] for integration testing.

Sources: dev/guidelines/testing.md:22-55, dev/guidelines/python.md:57-73

Git Workflow and Boundaries

The project follows a strict contribution model targeting the stable branch.

• Pre-commit: Fast checks (ruff, rumdl, whitespace) are wired into git via .pre-commit-config.yaml.
• Suppression: Do not disable lint rules globally. Use inline # noqa: <code> or # pylint: disable=<symbol> with justification if suppression is necessary.
• Dependencies: All dependencies must be pinned with both lower and upper bounds (e.g., infrahub-sdk>=1.20.1,<2).

Sources: dev/guidelines/git-workflow.md:10-30, AGENTS.md:99-100

Python Coding Standards in this project prioritize synchronous execution, robust type safety through Pydantic, and automated quality gates. Adherence to these standards ensures that the Nornir-Infrahub bridge remains maintainable and reliable.