tessl/pypi-ansible-runner

Consistent Ansible Python API and CLI with container and process isolation runtime capabilities

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Plugin and Role Management

Name: tessl/pypi-ansible-runner
Author: tessl

Discover, document, and manage Ansible plugins and roles programmatically. Provides access to plugin documentation, role specifications, inventory operations, and Ansible configuration management through a consistent programmatic interface.

Capabilities

Plugin Documentation

Retrieve documentation for Ansible plugins including modules, lookup plugins, filter plugins, and other plugin types.

def get_plugin_docs(
    plugin_names: list,
    plugin_type: str = None,
    response_format: str = None,
    snippet: bool = False,
    playbook_dir: str = None,
    module_path: str = None,
    private_data_dir: str = None,
    artifact_dir: str = None,
    ident: str = None,
    rotate_artifacts: int = 0,
    timeout: int = None,
    process_isolation: bool = False,
    process_isolation_executable: str = None,
    container_image: str = None,
    envvars: dict = None,
    **kwargs
) -> Runner

Parameters:

plugin_names (list): List of plugin names to get documentation for
plugin_type (str): Type of plugin ('module', 'lookup', 'filter', 'test', etc.)
response_format (str): Output format ('json', 'yaml', 'text')
snippet (bool): Return only brief documentation snippets
playbook_dir (str): Directory containing playbooks and collections
module_path (str): Additional paths to search for modules

Usage examples:

import ansible_runner

# Get documentation for specific modules
result = ansible_runner.get_plugin_docs(
    plugin_names=['copy', 'template', 'service'],
    plugin_type='module',
    response_format='json'
)

# Get brief snippets for quick reference
result = ansible_runner.get_plugin_docs(
    plugin_names=['file', 'lineinfile'],
    plugin_type='module',
    snippet=True,
    response_format='text'
)

# Get lookup plugin documentation
result = ansible_runner.get_plugin_docs(
    plugin_names=['env', 'file', 'template'],
    plugin_type='lookup',
    response_format='yaml'
)

Asynchronous Plugin Documentation

def get_plugin_docs_async(
    plugin_names: list,
    plugin_type: str = None,
    response_format: str = None,
    snippet: bool = False,
    playbook_dir: str = None,
    module_path: str = None,
    private_data_dir: str = None,
    artifact_dir: str = None,
    ident: str = None,
    rotate_artifacts: int = 0,
    timeout: int = None,
    process_isolation: bool = False,
    process_isolation_executable: str = None,
    container_image: str = None,
    envvars: dict = None,
    **kwargs
) -> Runner

Usage example:

# Async plugin documentation retrieval
runner = ansible_runner.get_plugin_docs_async(
    plugin_names=['yum', 'apt', 'package'],
    plugin_type='module',
    response_format='json'
)

# Wait for completion
while runner.status in ['pending', 'running']:
    time.sleep(0.5)

if runner.status == 'successful':
    print("Plugin documentation retrieved successfully")

Plugin Listing

List available Ansible plugins by type or search criteria.

def get_plugin_list(
    list_files: str = None,
    response_format: str = None,
    plugin_type: str = None,
    playbook_dir: str = None,
    module_path: str = None,
    private_data_dir: str = None,
    artifact_dir: str = None,
    ident: str = None,
    rotate_artifacts: int = 0,
    timeout: int = None,
    process_isolation: bool = False,
    process_isolation_executable: str = None,
    container_image: str = None,
    envvars: dict = None,
    **kwargs
) -> Runner

Parameters:

list_files (str): File containing list of plugins to query
plugin_type (str): Type of plugins to list ('module', 'lookup', 'filter', etc.)
response_format (str): Output format ('json', 'yaml', 'text')

Usage examples:

# List all available modules
result = ansible_runner.get_plugin_list(
    plugin_type='module',
    response_format='json'
)

# List lookup plugins
result = ansible_runner.get_plugin_list(
    plugin_type='lookup',
    response_format='text'
)

# List all plugin types
result = ansible_runner.get_plugin_list(
    response_format='yaml'
)

Role Listing

List available Ansible roles from collections or local directories.

def get_role_list(
    collection: str = None,
    playbook_dir: str = None,
    private_data_dir: str = None,
    artifact_dir: str = None,
    ident: str = None,
    rotate_artifacts: int = 0,
    timeout: int = None,
    process_isolation: bool = False,
    process_isolation_executable: str = None,
    container_image: str = None,
    envvars: dict = None,
    **kwargs
) -> Runner

Parameters:

collection (str): Specific collection to list roles from
playbook_dir (str): Directory containing roles and collections

Usage examples:

# List all available roles
result = ansible_runner.get_role_list()

# List roles from specific collection
result = ansible_runner.get_role_list(
    collection='community.general'
)

# List roles from specific directory
result = ansible_runner.get_role_list(
    playbook_dir='/path/to/ansible/project'
)

Role Argument Specification

Get detailed argument specifications for Ansible roles.

def get_role_argspec(
    role: str,
    collection: str = None,
    playbook_dir: str = None,
    private_data_dir: str = None,
    artifact_dir: str = None,
    ident: str = None,
    rotate_artifacts: int = 0,
    timeout: int = None,
    process_isolation: bool = False,
    process_isolation_executable: str = None,
    container_image: str = None,
    envvars: dict = None,
    **kwargs
) -> Runner

Parameters:

role (str): Name of the role to get argument specification for
collection (str): Collection containing the role
playbook_dir (str): Directory containing the role

Usage examples:

# Get argument spec for a role
result = ansible_runner.get_role_argspec(
    role='nginx'
)

# Get argument spec for role in collection
result = ansible_runner.get_role_argspec(
    role='apache',
    collection='community.general'
)

# Get argument spec with custom playbook directory
result = ansible_runner.get_role_argspec(
    role='custom_app',
    playbook_dir='/path/to/roles'
)

Inventory Operations

Execute ansible-inventory commands for inventory management and inspection.

def get_inventory(
    action: str,
    inventories: list,
    response_format: str = None,
    host: str = None,
    playbook_dir: str = None,
    private_data_dir: str = None,
    artifact_dir: str = None,
    ident: str = None,
    rotate_artifacts: int = 0,
    timeout: int = None,
    process_isolation: bool = False,
    process_isolation_executable: str = None,
    container_image: str = None,
    envvars: dict = None,
    **kwargs
) -> Runner

Parameters:

action (str): Inventory action ('list', 'host', 'graph')
inventories (list): List of inventory files or directories
response_format (str): Output format ('json', 'yaml', 'text')
host (str): Specific host to query (for 'host' action)

Usage examples:

# List entire inventory
result = ansible_runner.get_inventory(
    action='list',
    inventories=['inventory/hosts'],
    response_format='json'
)

# Get information for specific host
result = ansible_runner.get_inventory(
    action='host',
    inventories=['inventory/hosts'],
    host='web01',
    response_format='json'
)

# Generate inventory graph
result = ansible_runner.get_inventory(
    action='graph',
    inventories=['inventory/hosts', 'inventory/groups'],
    response_format='text'
)

Ansible Configuration

Get and manage Ansible configuration settings.

def get_ansible_config(
    action: str,
    config_file: str = None,
    only_changed: bool = None,
    private_data_dir: str = None,
    artifact_dir: str = None,
    ident: str = None,
    rotate_artifacts: int = 0,
    timeout: int = None,
    process_isolation: bool = False,
    process_isolation_executable: str = None,
    container_image: str = None,
    envvars: dict = None,
    **kwargs
) -> Runner

Parameters:

action (str): Configuration action ('list', 'dump', 'view')
config_file (str): Specific configuration file to use
only_changed (bool): Show only changed configuration values

Usage examples:

# View current configuration
result = ansible_runner.get_ansible_config(
    action='view'
)

# Dump all configuration settings
result = ansible_runner.get_ansible_config(
    action='dump'
)

# List all available configuration options
result = ansible_runner.get_ansible_config(
    action='list'
)

# Show only changed settings
result = ansible_runner.get_ansible_config(
    action='dump',
    only_changed=True
)

Common Patterns

Plugin Discovery Workflow

import ansible_runner

# 1. List available modules
modules_result = ansible_runner.get_plugin_list(
    plugin_type='module',
    response_format='json'
)

# 2. Get documentation for specific modules
if modules_result.status == 'successful':
    docs_result = ansible_runner.get_plugin_docs(
        plugin_names=['file', 'copy', 'template'],
        plugin_type='module',
        response_format='json'
    )

# 3. Get brief snippets for quick reference
snippets_result = ansible_runner.get_plugin_docs(
    plugin_names=['file', 'copy'],
    plugin_type='module',
    snippet=True,
    response_format='text'
)

Role Management Workflow

# 1. List all available roles
roles_result = ansible_runner.get_role_list()

# 2. Get argument specification for specific role
if roles_result.status == 'successful':
    argspec_result = ansible_runner.get_role_argspec(
        role='nginx',
        collection='community.general'
    )

# 3. Validate role arguments
if argspec_result.status == 'successful':
    print("Role arguments validated successfully")

Inventory Analysis

# 1. Get complete inventory listing
inventory_result = ansible_runner.get_inventory(
    action='list',
    inventories=['production/hosts'],
    response_format='json'
)

# 2. Analyze specific hosts
for host in ['web01', 'db01', 'app01']:
    host_result = ansible_runner.get_inventory(
        action='host',
        inventories=['production/hosts'],
        host=host,
        response_format='json'
    )
    if host_result.status == 'successful':
        print(f"Host {host} configuration retrieved")

# 3. Generate inventory visualization
graph_result = ansible_runner.get_inventory(
    action='graph',
    inventories=['production/hosts'],
    response_format='text'
)

Install with Tessl CLI