Ansible Argument Specs Generator
A Python tool that automatically generates argument_specs.yml files for Ansible collections and roles. It analyzes your role's variables, tasks, and defaults to create comprehensive argument specifications that provide documentation and validation for your Ansible roles.
Features
- Collection-Wide Processing: Process all roles in a collection automatically
- Single Role Mode: Generate specs for individual roles with interactive or automated modes
- Intelligent Type Inference: Detects types from default values (and path-like names/values)
- Variable Discovery: Extracts variables from
defaults/*.yml, tasks, and templates (vars/via--include-vars) - Secret Handling: Sets
no_log: truefor password/token/secret-like names - Smart Filtering: Excludes registered variables, private (
_-prefixed) variables, and Ansible built-ins - Multiple Entry Points: Supports roles with multiple task entry points
- Spec Preservation: Keeps curated types, choices, conditionals, and
no_logon regenerate - Safe Writes: Timestamped
.bakbackups before overwrite (disable with--no-backup) - Version Tracking: Automatically adds
version_addedfor newly discovered variables - Validation: Checks types, required/default conflicts, choices, elements, and conditionals
Installation
# Install from PyPI
pip install ansible-argument-spec-generator
# Or install from source
pip install -e .
Requirements:
- Python 3.8+
- PyYAML (automatically installed)
- Ansible Core 2.11+ (for using the generated specs)
After installation, you have access to these commands:
ansible-argument-spec-generatorgenerate-argument-spec(shorter alias)
Quick Start
# Process all roles in current collection
ansible-argument-spec-generator
# Process a single role interactively
ansible-argument-spec-generator --single-role
# Get help
ansible-argument-spec-generator --help
Usage
Collection Mode (Default)
Process all roles in a collection:
# Process all roles in current collection
ansible-argument-spec-generator
# Process specific collection path
ansible-argument-spec-generator --collection-path /path/to/collection
# List roles in collection
ansible-argument-spec-generator --list-roles
# Process specific role only
ansible-argument-spec-generator --role my_role
Single Role Mode
Process individual roles:
# Interactive mode
ansible-argument-spec-generator --single-role
# Generate from defaults file
ansible-argument-spec-generator --single-role --from-defaults defaults/main.yml
# Generate from configuration file
ansible-argument-spec-generator --single-role --from-config config.yml
Verbosity Control
# Default - final summary only
ansible-argument-spec-generator
# Basic info
ansible-argument-spec-generator -v
# Detailed processing
ansible-argument-spec-generator -vv
# Full debug output
ansible-argument-spec-generator -vvv
# Suppress all output (including summaries)
ansible-argument-spec-generator --quiet
Command Line Options
| Option | Description |
|---|---|
--single-role |
Process individual role instead of entire collection |
--collection-path PATH |
Path to collection root (default: current directory) |
--list-roles |
List all roles found in collection |
--role NAME |
Process only the specified role |
--from-defaults FILE |
Generate specs from defaults file |
--from-config FILE |
Generate from configuration file |
--output FILE |
Output file path (default: meta/argument_specs.yml) |
--validate-only |
Validate existing specs without generating |
--include-vars |
Include variables from vars/ as options (off by default) |
--no-backup |
Skip timestamped .bak backup before overwrite |
--dry-run |
Preview output without writing files |
-q, --quiet |
Suppress all output including summaries |
-v, -vv, -vvv |
Verbosity levels (basic, detailed, debug) |
How It Works
The tool analyzes your Ansible roles to automatically generate argument specifications:
- Discovers Variables: Extracts variables from
defaults/*.yml, task files, and templates (vars/only with--include-vars) - Infers Types: Automatically detects variable types based on naming patterns and default values
- Marks Secrets: Sets
no_log: truefor password/token/secret-like variable names - Detects Entry Points: Identifies multiple task entry points (main.yml, install.yml, etc.)
- Filters Variables: Excludes registered variables, private variables, and Ansible built-ins
- Preserves Curated Specs: Keeps existing types, choices, conditionals, and
no_logon regenerate - Generates Specs: Creates clean
argument_specs.ymlfiles (with timestamped backups by default)
Configuration File Format
For complex scenarios, create a configuration file:
entry_points:
main:
short_description: "Install and configure web application"
arguments:
app_name:
type: str
required: true
description: "Name of the application"
state:
type: str
default: "present"
choices: ["present", "absent", "started", "stopped"]
description: "Desired state"
app_port:
type: int
default: 8080
description: "Port number"
required_if:
- ["state", "present", ["app_name"]]
Generated Output
The tool creates standard argument_specs.yml files:
---
argument_specs:
main:
short_description: "Auto-generated specs for webapp role"
options:
app_enabled:
description: "Enable application"
type: bool
default: true
app_password:
description: "Password for authentication"
type: str
default: changeme
no_log: true
config_path:
description: "Configuration file path"
type: path
default: /etc/myapp/config.yml
version_added: "1.1.0"
...
Variable Detection
The tool automatically extracts variables from multiple sources:
- Defaults: all
defaults/*.yml/defaults/*.yaml(merged;main.ymlfirst) - Vars (optional): all
vars/*.ymlwhen--include-varsis set - Task Files: Jinja2 usages, conditionals, loops, asserts, environment, tags
- Templates: Jinja2 variables under
templates/ - Multiple Entry Points: standalone task files not included by others (plus
main)
Vars values may still be used for type inference when a variable appears in tasks/templates, even if --include-vars is off.
Smart Type Inference
Types come primarily from default values:
- Python
bool/int/float/list/dict→ matching Ansible types - Path-like names (
*_path,*_dir, …) with path-like values →type: path - List element types are inferred from list contents (
boolchecked beforeint) - Secret-like names (
password,token,secret, …) →no_log: true
Variable Filtering
Automatically excludes:
- Private variables (names starting with
_) - Registered variables and
set_factnames from tasks - Ansible built-ins (
ansible_*, and exact names likeitem,loop,hostvars,inventory_hostname, …)
Validation
Validate existing specs:
# Validate all roles
ansible-argument-spec-generator --validate-only
# Validate single role
ansible-argument-spec-generator --single-role --validate-only
Integration with Ansible
Generated specs provide:
- Documentation:
ansible-doc --type role my_collection.my_role - Validation: Automatic argument validation
- Error Messages: Clear feedback for invalid inputs
Examples
# Process entire collection
cd /path/to/my_collection
ansible-argument-spec-generator
# Process single role in collection
ansible-argument-spec-generator --role webapp
# Include vars/ as options and skip backups
ansible-argument-spec-generator --include-vars --no-backup
# Preview without writing files
ansible-argument-spec-generator --dry-run
# Interactive single role mode
ansible-argument-spec-generator --single-role
# Generate from defaults file
ansible-argument-spec-generator --single-role --from-defaults defaults/main.yml
Troubleshooting
Common Issues
- "Not a collection root": Ensure you're in a directory with
galaxy.ymlandroles/ - "No roles found": Check that
roles/directory contains valid role structures - YAML parsing errors: The tool provides specific error messages for malformed files
- File encoding issues: Ensure all files are UTF-8 encoded
Debugging
Use verbosity flags for troubleshooting:
# List roles in collection
ansible-argument-spec-generator --list-roles
# Validate existing specs
ansible-argument-spec-generator --validate-only
# Debug with verbosity
ansible-argument-spec-generator -vvv --role myrole
Contributing
We welcome contributions! Here's how you can help improve the Ansible Argument Specs Generator:
Development Setup
-
Clone the repository:
git clone https://github.com/djdanielsson/ansible_arg_spec_generator.git cd ansible_arg_spec_generator
-
Set up development environment:
# Install Python 3.8+ python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -e ".[dev]"
-
Run tests:
# Run all tests pytest # Run with coverage pytest --cov=generate_argument_specs --cov-report=html # Run specific test categories pytest -k "test_basic"
-
Code formatting:
# Format code with Black black . # Check formatting black --check .
Development Guidelines
- Code Style: Follow PEP 8 guidelines
- Formatting: Use Black for consistent formatting
- Testing: Write tests for new features and bug fixes
- Documentation: Update README and docstrings for changes
- Commits: Use clear, descriptive commit messages
Testing
The project includes comprehensive tests covering:
- Core functionality
- Edge cases
- Integration tests
- CI/CD workflows
Run the full test suite:
pytest tests/ -v
Pull Requests
- Fork the repository
- Create a feature branch:
git checkout -b feature/your-feature - Make your changes and add tests
- Ensure all tests pass:
pytest - Format code:
black . - Commit your changes:
git commit -m "Add your feature" - Push to your fork:
git push origin feature/your-feature - Create a Pull Request
Bug Reports and Feature Requests
- Bug Reports: Use GitHub Issues with detailed reproduction steps
- Feature Requests: Describe the proposed feature and its use case
- Questions: Check existing issues or create a discussion
Code of Conduct
This project follows a code of conduct to ensure a welcoming environment for all contributors.
License
MIT
Metadata
Release files for ansible-argument-spec-generator 1.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ansible_argument_spec_generator-1.2.0.tar.gz | 39.8 kB | With provenance | Details for ansible_argument_spec_generator-1.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ansible_argument_spec_generator-1.2.0-py3-none-any.whl | Python 3 | none | any | Details for ansible_argument_spec_generator-1.2.0-py3-none-any.whl |
Total release size: 74.5 kB
Release files / ansible_argument_spec_generator-1.2.0.tar.gz
| Download URL | ansible_argument_spec_generator-1.2.0.tar.gz |
|---|---|
| Size | 39.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b50adf87c10c6c4d9150403a0efba383884ec8941d640019d0215be7250c3f77
|
|
BLAKE2b-256 checksum How to use checksums |
3a8cd3c8c75c624aa0f9599d666462788dc3aadac4524d5841bf318d7464bc1a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 13, 2026.
Transparency logRelease files / ansible_argument_spec_generator-1.2.0-py3-none-any.whl
| Download URL | ansible_argument_spec_generator-1.2.0-py3-none-any.whl |
|---|---|
| Size | 34.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e4632e6f9d150c8824fa1938d88079d8f1f55ee3310fec2a9518b30b16be49fa
|
|
BLAKE2b-256 checksum How to use checksums |
c10431d1a2675e592fc361d7b91f41570ed7dff5af5fd9463de2688bc0959dce
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 13, 2026.
Transparency logSecurity for ansible-argument-spec-generator 1.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for ansible_argument_spec_generator-1.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.