Development Environment & Invoke Tasks

Relevant source files

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

• pyproject.toml
• AGENTS.md
• dev/guidelines/python.md
• dev/guidelines/testing.md
• dev/guidelines/documentation.md
• tasks/docs.py
• dev/constitution.md

The opsmill.infrahub development environment provides a standardized toolset for managing dependencies, enforcing code quality, and executing multi-stage tests. It uses uv for Python package management and Invoke as the primary task runner to automate common developer workflows.

This environment ensures all contributors use consistent versions of tools like Ruff for linting and Docusaurus for documentation generation. The following diagram illustrates the high-level workflow for contributing to the collection.

The diagram shows the standard sequence of environment setup, quality checks, testing, and documentation generation required before submitting a pull request.
Sources: AGENTS.md:37-45, dev/guidelines/python.md:105-115

Dependency Management & Python Configuration

The project manages all dependencies and environment configurations through pyproject.toml and the uv tool. It targets Python versions >=3.11 and <3.15.

Tech Stack Overview

Component	Requirement
Python	>=3.11, <3.15
Ansible	ansible-core >=2.19.0
SDK	infrahub-sdk[all] >=1.19.0, <2.0
Tooling	uv, Invoke, Ruff, pytest

Sources: pyproject.toml:7-13, AGENTS.md:15-24

Dependency Groups

Developers use uv to install specific dependency groups defined in pyproject.toml.

• Default: Includes ansible-core, infrahub-sdk, and jinja2.
• dev: Contains linting and testing tools like ruff, mypy, pytest, and invoke.
• integration: Requires infrahub-testcontainers for live API testing.

To synchronize the environment, you run:

uv sync --group dev --group integration

Sources: pyproject.toml:20-50

Invoke Task Automation

The project uses Invoke to wrap complex commands into simple, memorable tasks. These tasks handle formatting, linting, testing, and documentation builds.

Core Development Tasks

Task	Description
invoke format	Auto-fixes code formatting issues using Ruff.
invoke lint	Runs autoflake, ruff, yamllint, and rumdl checks.
invoke generate-doc	Parses plugin docstrings and generates MDX reference files.
invoke docusaurus	Builds the static documentation site from docs/.
invoke galaxy-build	Packages the collection into a .tar.gz tarball for Galaxy.

Sources: AGENTS.md:27-35, tasks/docs.py:228-253

Documentation Pipeline

The generate-doc task (implemented in tasks/docs.py) extracts YAML data from Python docstrings to create consistent documentation.

This sequence illustrates how the tasks/docs.py module transforms Python source code into user-facing documentation artifacts.
Sources: tasks/docs.py:228-253, dev/guidelines/documentation.md:9-14

Code Quality & Linting

The environment enforces strict code quality standards through multiple linters configured in pyproject.toml.

1. Ruff: Acts as the primary linter and formatter. It uses a 120-character line length limit and double-quote string style.
2. Mypy: Performs static type checking. Note that invoke lint does not run mypy; you must execute uv run mypy . separately.
3. Rumdl: Validates Markdown structure and formatting.
4. Vale: Checks documentation prose style against the Infrahub brand guidelines.

Sources: dev/guidelines/python.md:5-15, pyproject.toml:104-120, AGENTS.md:47-50

Testing Infrastructure

All tests run inside Docker containers managed by docker-compose.yml to ensure environment parity across different machines.

Test Tiers

• Sanity Tests: Use ansible-test sanity to validate collection structure, imports, and documentation format.
• Unit Tests: Use pytest with mocked SDK clients to test individual function logic.
• Integration Tests: Execute Ansible playbooks against live Infrahub instances using testcontainers.

Execution via Invoke

You can run specific test suites using these commands:

invoke tests-sanity       # Validates Ansible standards
invoke tests-unit         # Runs pytest on unit tests
invoke tests-integration  # Runs end-to-end integration tests
invoke tests-all         # Runs the entire test suite

Sources: dev/guidelines/testing.md:5-20, AGENTS.md:27-35

Conclusion

The opsmill.infrahub development environment centralizes complex workflows into a unified set of Invoke tasks. By utilizing uv for dependencies and Docker for testing, the project provides a stable and reproducible environment for developing infrastructure automation modules. Effective use of these tools ensures that contributions meet the high standards for documentation accuracy and code quality defined in the project constitution.