Ansible Compat

Warnings

• breaking Version 26.0.0 introduced significant internal refactoring related to collection and role loading logic, specifically adapting to changes in `ansible-core` 2.15+. Code that relied on direct access to internal path attributes (e.g., `_ansible_collection_path`) may no longer work.
  Fix: Migrate to using public methods of the `AnsibleRuntime` class for robust path resolution and interaction with Ansible's loading mechanisms.
• gotcha Ansible Compat has tight Python version requirements, which can also be influenced by its `ansible-core` dependency. For `ansible-compat` 26.x, Python 3.10+ is required.
  Fix: Always ensure your Python environment meets the minimum version specified in the `ansible-compat` project's `pyproject.toml` or documentation, as well as the requirements of the `ansible-core` version you intend to use.
• gotcha `ansible-compat` is highly dependent on `ansible-core`. Using mismatched versions (e.g., `ansible-compat` expecting `ansible-core` 2.15+ but finding an older version) can lead to runtime errors or unexpected behavior.
  Fix: Refer to the `ansible-compat` documentation or its `pyproject.toml` for the supported range of `ansible-core` versions and install a compatible `ansible-core` release.
• gotcha When working in non-standard Ansible environments (e.g., custom `ansible.cfg` locations, unique collection paths, or isolated virtual environments), `AnsibleRuntime` and `AnsibleCompatConfig` might not automatically discover all desired settings by default.
  Fix: Explicitly pass relevant configuration paths or set standard Ansible environment variables (e.g., `ANSIBLE_CONFIG`, `ANSIBLE_COLLECTIONS_PATH`) before initializing `AnsibleCompatConfig` or `AnsibleRuntime` to ensure proper discovery.

Install

• pip install ansible-compat Install latest version

Imports

• AnsibleCompatConfig

  from ansible_compat.config import AnsibleCompatConfig

• AnsibleRuntime

  from ansible_compat.runtime import AnsibleRuntime

• AnsibleCollectionConfig

  from ansible_compat.primitives import AnsibleCollectionConfig

• AnsiblePath

  from ansible_compat.primitives import AnsiblePath

Quickstart

This quickstart demonstrates how to initialize `AnsibleCompatConfig` and `AnsibleRuntime` to access Ansible's configuration and runtime environment. It shows how to query the Ansible version, configuration file path, collection paths, and find a specific collection. It also includes an example of using the `AnsiblePath` primitive.

from ansible_compat.config import AnsibleCompatConfig
from ansible_compat.runtime import AnsibleRuntime
from ansible_compat.primitives import AnsiblePath
import os

# Initialize configuration (can be empty for defaults, or load from ansible.cfg)
config = AnsibleCompatConfig()

# Initialize runtime, which discovers Ansible paths and settings
runtime = AnsibleRuntime()

print(f"Ansible core version: {runtime.ansible_version}")
print(f"Ansible config file: {runtime.config_file or 'Not found'}")
print(f"Ansible collection paths: {runtime.ansible_collection_paths}")

# Example: Get path for a specific collection
collection_name = os.environ.get('ANSIBLE_TEST_COLLECTION', 'community.general')
collection_path = runtime.get_collection_path(collection_name)
if collection_path:
    print(f"Collection '{collection_name}' found at: {collection_path}")
else:
    print(f"Collection '{collection_name}' not found. Try setting it via ANSIBLE_TEST_COLLECTION.")

# Example: Using an AnsiblePath primitive
some_path = AnsiblePath("my_ansible_artifact.yml")
print(f"AnsiblePath object for 'my_ansible_artifact.yml': {some_path}")