| Name | ansible-argument-spec-generator JSON |
| Version |
1.0.0.post1
JSON |
| download |
| home_page | None |
| Summary | A comprehensive tool to generate argument_specs.yml files for Ansible collections and roles |
| upload_time | 2025-08-21 18:53:49 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.6 |
| license | MIT License
Copyright (c) 2025 David Danielsson
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
ansible
automation
argument-specs
validation
documentation
yaml
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Ansible Argument Specs Generator
[](https://github.com/djdanielsson/ansible_arg_spec_generator/actions/workflows/test.yml)
[](https://badge.fury.io/py/ansible-argument-spec-generator)
[](https://pypi.org/project/ansible-argument-spec-generator/)
[](https://opensource.org/licenses/MIT)
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**: Automatically detects variable types based on naming patterns and usage
- **Variable Discovery**: Extracts variables from tasks, defaults, vars, and conditional statements
- **Smart Filtering**: Excludes registered variables, private variables, and Ansible built-ins
- **Multiple Entry Points**: Supports roles with multiple task entry points
- **Version Tracking**: Automatically adds `version_added` fields for new variables
- **Clean Output**: Generates well-formatted YAML with alphabetical sorting
- **Validation**: Built-in validation of generated specs
## Installation
```bash
# 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-generator`
- `generate-argument-spec` (shorter alias)
## Quick Start
```bash
# 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:
```bash
# 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:
```bash
# 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
```bash
# Silent (default) - 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
```
## 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 |
| `-v, -vv, -vvv` | Verbosity levels (basic, detailed, debug) |
## How It Works
The tool analyzes your Ansible roles to automatically generate argument specifications:
1. **Discovers Variables**: Extracts variables from `defaults/main.yml`, `vars/main.yml`, and task files
2. **Infers Types**: Automatically detects variable types based on naming patterns and default values
3. **Detects Entry Points**: Identifies multiple task entry points (main.yml, install.yml, etc.)
4. **Filters Variables**: Excludes registered variables, private variables, and Ansible built-ins
5. **Generates Specs**: Creates clean, well-formatted `argument_specs.yml` files
## Configuration File Format
For complex scenarios, create a configuration file:
```yaml
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:
```yaml
---
argument_specs:
main:
short_description: "Auto-generated specs for webapp role"
options:
app_name:
description: "Application name"
type: str
default: myapp
app_enabled:
description: "Enable application"
type: bool
default: 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 and Vars**: `defaults/main.yml` and `vars/main.yml`
- **Task Files**: Variables used in Jinja2 templates, conditionals, and loops
- **Multiple Entry Points**: Supports roles with `main.yml`, `install.yml`, `configure.yml`, etc.
### Smart Type Inference
Variables are automatically typed based on naming patterns:
- `*_path`, `*_dir`, `*_file` → `type: path`
- `*_enabled`, `*_debug`, `force_*` → `type: bool`
- `*_port`, `*_timeout` → `type: int`
### Variable Filtering
Automatically excludes:
- Private variables (starting with `__`)
- Registered variables from tasks
- Ansible built-ins (`ansible_facts`, `inventory_hostname`, etc.)
## Validation
Validate existing specs:
```bash
# 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
```bash
# Process entire collection
cd /path/to/my_collection
ansible-argument-spec-generator
# Process single role in collection
ansible-argument-spec-generator --role webapp
# 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
1. **"Not a collection root"**: Ensure you're in a directory with `galaxy.yml` and `roles/`
2. **"No roles found"**: Check that `roles/` directory contains valid role structures
3. **YAML parsing errors**: The tool provides specific error messages for malformed files
4. **File encoding issues**: Ensure all files are UTF-8 encoded
### Debugging
Use verbosity flags for troubleshooting:
```bash
# 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
```
## License
MIT
Raw data
{
"_id": null,
"home_page": null,
"name": "ansible-argument-spec-generator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "ansible, automation, argument-specs, validation, documentation, yaml",
"author": null,
"author_email": "David Danielsson <djdanielsson@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/9a/b2/298d8ade4a707eb0c3655097b792deb18450f97ee99fbc0890b5baf778e8/ansible_argument_spec_generator-1.0.0.post1.tar.gz",
"platform": null,
"description": "# Ansible Argument Specs Generator\n\n[](https://github.com/djdanielsson/ansible_arg_spec_generator/actions/workflows/test.yml)\n[](https://badge.fury.io/py/ansible-argument-spec-generator)\n[](https://pypi.org/project/ansible-argument-spec-generator/)\n[](https://opensource.org/licenses/MIT)\n\nA 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.\n\n## Features\n\n- **Collection-Wide Processing**: Process all roles in a collection automatically\n- **Single Role Mode**: Generate specs for individual roles with interactive or automated modes\n- **Intelligent Type Inference**: Automatically detects variable types based on naming patterns and usage\n- **Variable Discovery**: Extracts variables from tasks, defaults, vars, and conditional statements\n- **Smart Filtering**: Excludes registered variables, private variables, and Ansible built-ins\n- **Multiple Entry Points**: Supports roles with multiple task entry points\n- **Version Tracking**: Automatically adds `version_added` fields for new variables\n- **Clean Output**: Generates well-formatted YAML with alphabetical sorting\n- **Validation**: Built-in validation of generated specs\n\n## Installation\n\n```bash\n# Install from PyPI\npip install ansible-argument-spec-generator\n\n# Or install from source\npip install -e .\n```\n\n**Requirements:**\n- Python 3.8+\n- PyYAML (automatically installed)\n- Ansible Core 2.11+ (for using the generated specs)\n\nAfter installation, you have access to these commands:\n- `ansible-argument-spec-generator`\n- `generate-argument-spec` (shorter alias)\n\n## Quick Start\n\n```bash\n# Process all roles in current collection\nansible-argument-spec-generator\n\n# Process a single role interactively \nansible-argument-spec-generator --single-role\n\n# Get help\nansible-argument-spec-generator --help\n```\n\n## Usage\n\n### Collection Mode (Default)\n\nProcess all roles in a collection:\n\n```bash\n# Process all roles in current collection\nansible-argument-spec-generator\n\n# Process specific collection path\nansible-argument-spec-generator --collection-path /path/to/collection\n\n# List roles in collection\nansible-argument-spec-generator --list-roles\n\n# Process specific role only\nansible-argument-spec-generator --role my_role\n```\n\n### Single Role Mode\n\nProcess individual roles:\n\n```bash\n# Interactive mode\nansible-argument-spec-generator --single-role\n\n# Generate from defaults file\nansible-argument-spec-generator --single-role --from-defaults defaults/main.yml\n\n# Generate from configuration file\nansible-argument-spec-generator --single-role --from-config config.yml\n```\n\n### Verbosity Control\n\n```bash\n# Silent (default) - summary only\nansible-argument-spec-generator\n\n# Basic info\nansible-argument-spec-generator -v\n\n# Detailed processing\nansible-argument-spec-generator -vv\n\n# Full debug output\nansible-argument-spec-generator -vvv\n```\n\n## Command Line Options\n\n| Option | Description |\n|--------|-------------|\n| `--single-role` | Process individual role instead of entire collection |\n| `--collection-path PATH` | Path to collection root (default: current directory) |\n| `--list-roles` | List all roles found in collection |\n| `--role NAME` | Process only the specified role |\n| `--from-defaults FILE` | Generate specs from defaults file |\n| `--from-config FILE` | Generate from configuration file |\n| `--output FILE` | Output file path (default: meta/argument_specs.yml) |\n| `--validate-only` | Validate existing specs without generating |\n| `-v, -vv, -vvv` | Verbosity levels (basic, detailed, debug) |\n\n## How It Works\n\nThe tool analyzes your Ansible roles to automatically generate argument specifications:\n\n1. **Discovers Variables**: Extracts variables from `defaults/main.yml`, `vars/main.yml`, and task files\n2. **Infers Types**: Automatically detects variable types based on naming patterns and default values\n3. **Detects Entry Points**: Identifies multiple task entry points (main.yml, install.yml, etc.)\n4. **Filters Variables**: Excludes registered variables, private variables, and Ansible built-ins\n5. **Generates Specs**: Creates clean, well-formatted `argument_specs.yml` files\n\n## Configuration File Format\n\nFor complex scenarios, create a configuration file:\n\n```yaml\nentry_points:\n main:\n short_description: \"Install and configure web application\"\n arguments:\n app_name:\n type: str\n required: true\n description: \"Name of the application\"\n \n state:\n type: str\n default: \"present\"\n choices: [\"present\", \"absent\", \"started\", \"stopped\"]\n description: \"Desired state\"\n \n app_port:\n type: int\n default: 8080\n description: \"Port number\"\n \n required_if:\n - [\"state\", \"present\", [\"app_name\"]]\n```\n\n## Generated Output\n\nThe tool creates standard `argument_specs.yml` files:\n\n```yaml\n---\nargument_specs:\n main:\n short_description: \"Auto-generated specs for webapp role\"\n options:\n app_name:\n description: \"Application name\"\n type: str\n default: myapp\n \n app_enabled:\n description: \"Enable application\"\n type: bool\n default: true\n \n config_path:\n description: \"Configuration file path\"\n type: path\n default: /etc/myapp/config.yml\n version_added: \"1.1.0\"\n...\n```\n\n## Variable Detection\n\nThe tool automatically extracts variables from multiple sources:\n\n- **Defaults and Vars**: `defaults/main.yml` and `vars/main.yml`\n- **Task Files**: Variables used in Jinja2 templates, conditionals, and loops\n- **Multiple Entry Points**: Supports roles with `main.yml`, `install.yml`, `configure.yml`, etc.\n\n### Smart Type Inference\n\nVariables are automatically typed based on naming patterns:\n- `*_path`, `*_dir`, `*_file` \u2192 `type: path`\n- `*_enabled`, `*_debug`, `force_*` \u2192 `type: bool`\n- `*_port`, `*_timeout` \u2192 `type: int`\n\n### Variable Filtering\n\nAutomatically excludes:\n- Private variables (starting with `__`)\n- Registered variables from tasks\n- Ansible built-ins (`ansible_facts`, `inventory_hostname`, etc.)\n\n## Validation\n\nValidate existing specs:\n\n```bash\n# Validate all roles\nansible-argument-spec-generator --validate-only\n\n# Validate single role\nansible-argument-spec-generator --single-role --validate-only\n```\n\n## Integration with Ansible\n\nGenerated specs provide:\n- **Documentation**: `ansible-doc --type role my_collection.my_role`\n- **Validation**: Automatic argument validation\n- **Error Messages**: Clear feedback for invalid inputs\n\n## Examples\n\n```bash\n# Process entire collection\ncd /path/to/my_collection\nansible-argument-spec-generator\n\n# Process single role in collection\nansible-argument-spec-generator --role webapp\n\n# Interactive single role mode\nansible-argument-spec-generator --single-role\n\n# Generate from defaults file\nansible-argument-spec-generator --single-role --from-defaults defaults/main.yml\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **\"Not a collection root\"**: Ensure you're in a directory with `galaxy.yml` and `roles/`\n2. **\"No roles found\"**: Check that `roles/` directory contains valid role structures\n3. **YAML parsing errors**: The tool provides specific error messages for malformed files\n4. **File encoding issues**: Ensure all files are UTF-8 encoded\n\n### Debugging\n\nUse verbosity flags for troubleshooting:\n\n```bash\n# List roles in collection\nansible-argument-spec-generator --list-roles\n\n# Validate existing specs\nansible-argument-spec-generator --validate-only\n\n# Debug with verbosity\nansible-argument-spec-generator -vvv --role myrole\n```\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 David Danielsson\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "A comprehensive tool to generate argument_specs.yml files for Ansible collections and roles",
"version": "1.0.0.post1",
"project_urls": {
"Bug Reports": "https://github.com/djdanielsson/ansible_arg_spec_generator/issues",
"Documentation": "https://github.com/djdanielsson/ansible_arg_spec_generator#readme",
"Homepage": "https://github.com/djdanielsson/ansible_arg_spec_generator",
"Source": "https://github.com/djdanielsson/ansible_arg_spec_generator"
},
"split_keywords": [
"ansible",
" automation",
" argument-specs",
" validation",
" documentation",
" yaml"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "550f95b06cadbd17e9683bea659a7f5f26941d9b2d3b395c705b967a16506553",
"md5": "175609e318d4c1489c7854a4aca19af6",
"sha256": "ef52b43e5d6b74295955f10120c7e0d01fa60ed0f221b043227a0342101302fd"
},
"downloads": -1,
"filename": "ansible_argument_spec_generator-1.0.0.post1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "175609e318d4c1489c7854a4aca19af6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 29346,
"upload_time": "2025-08-21T18:53:48",
"upload_time_iso_8601": "2025-08-21T18:53:48.395427Z",
"url": "https://files.pythonhosted.org/packages/55/0f/95b06cadbd17e9683bea659a7f5f26941d9b2d3b395c705b967a16506553/ansible_argument_spec_generator-1.0.0.post1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9ab2298d8ade4a707eb0c3655097b792deb18450f97ee99fbc0890b5baf778e8",
"md5": "51ba22973113cd53b4400b0c238157b6",
"sha256": "9867bc9d6e9646b4a25bee35e27b6bf723b0b91d5c8fd2ad1a3ba9ee2c2c7efc"
},
"downloads": -1,
"filename": "ansible_argument_spec_generator-1.0.0.post1.tar.gz",
"has_sig": false,
"md5_digest": "51ba22973113cd53b4400b0c238157b6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 36348,
"upload_time": "2025-08-21T18:53:49",
"upload_time_iso_8601": "2025-08-21T18:53:49.329351Z",
"url": "https://files.pythonhosted.org/packages/9a/b2/298d8ade4a707eb0c3655097b792deb18450f97ee99fbc0890b5baf778e8/ansible_argument_spec_generator-1.0.0.post1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-21 18:53:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "djdanielsson",
"github_project": "ansible_arg_spec_generator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ansible-argument-spec-generator"
}
