# argparse-ps1
**Generate PowerShell wrapper scripts from Python argparse parsers**
[](https://badge.fury.io/py/argparse-ps1)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/shimarch/argparse-ps1/actions)
`argparse-ps1` automatically generates PowerShell (.ps1) wrapper scripts for Python scripts that use `argparse`. This provides native PowerShell tab completion and parameter binding for your Python scripts.
## Features
- 🚀 **Automatic Generation**: Creates PowerShell wrappers from `ArgumentParser` objects
- 🎯 **Type Mapping**: Maps Python types to PowerShell parameter types
- 📝 **Native Interface**: Provides PowerShell-style parameter names and help
- ⚙️ **Multiple Runners**: Supports `uv`, `python`, or custom runners
- 🔧 **Zero Dependencies**: Uses only Python standard library
## Installation
```bash
pip install argparse-ps1
```
## Quick Start
Add wrapper generation to your Python script:
```python
from argparse_ps1 import generate_ps1_wrapper
# Your existing argparse code
parser = argparse.ArgumentParser(description="My script")
parser.add_argument("--hello", action="store_true", help="Say hello")
parser.add_argument("--option", type=str, help="String option")
# Generate PowerShell wrapper
if "--make-ps1" in sys.argv:
output = generate_ps1_wrapper(parser, script_path=Path(__file__))
print(f"Generated: {output}")
sys.exit(0)
```
Generate the wrapper:
```bash
python my_script.py --make-ps1
# Creates My-Script.ps1
```
Use the PowerShell wrapper:
```powershell
.\My-Script.ps1 -Hello -Option "test"
```
## Examples
See the [examples/](examples/) directory for complete working examples:
- **[basic_example.py](examples/basic_example.py)**: Simple boolean flags
- **[example.py](examples/example.py)**: String options with `uv run`
- **[example_uv_project.py](examples/example_uv_project.py)**: Using `uv run --project`
- **[example_python.py](examples/example_python.py)**: Using `python` runner instead of `uv`
### Project Mode Requirements
For project mode examples (`example_uv_project.py`), you need:
1. **Proper pyproject.toml structure** with `[project.scripts]` entry
2. **Package structure** with `__init__.py` files
3. **Correct execution method**: Use `uv run python example_uv_project.py` instead of script entries
## Usage Modes
### Default: uv run (Direct Script)
```python
generate_ps1_wrapper(parser, script_path=Path(__file__))
# Creates: & uv run script.py @args
```
### Project Mode: uv run --project
```python
generate_ps1_wrapper(
parser,
script_path=Path(__file__),
project_root=Path(".."),
command_name="my-command" # Must exist in [project.scripts]
)
# Creates: & uv run --project .. my-command @args
```
### Custom Runner
Use alternative Python executables instead of `uv`:
```python
# System Python
generate_ps1_wrapper(
parser,
script_path=Path(__file__),
runner="python"
)
# Creates: & python script.py @args
# Virtual environment Python (relative path)
generate_ps1_wrapper(
parser,
script_path=Path(__file__),
runner=".venv/Scripts/python.exe" # Windows
# runner=".venv/bin/python" # Unix/macOS
)
# Creates: & .venv\Scripts\python.exe script.py @args
# Custom Python installation (absolute path)
generate_ps1_wrapper(
parser,
script_path=Path(__file__),
runner="C:/Python312/python.exe"
)
# Creates: & "C:/Python312/python.exe" script.py @args
```
**Note**: See [example_python.py](examples/example_python.py) for a complete working example.
## API Reference
```python
def generate_ps1_wrapper(
parser: argparse.ArgumentParser,
*,
script_path: Path,
output_path: Path | None = None,
output_dir: Path | None = None,
skip_dests: Iterable[str] | None = None,
runner: str = "uv",
command_name: str | None = None,
) -> Path
```
**Parameters:**
- `parser`: Your `ArgumentParser` instance
- `script_path`: Path to your Python script (absolute path required)
- `output_path`: Specific output file path (optional, overrides output_dir)
- `output_dir`: Output directory (default: current working directory)
- `skip_dests`: Argument destinations to exclude from wrapper
- `runner`: Command to run Python scripts (default: "uv", can be "python")
- `command_name`: Command name in `[project.scripts]` (enables project mode for uv)
## Type Mapping
| Python Type | PowerShell Type | Example |
| ------------ | --------------- | ---------------------- |
| `str` | `[string]` | `-Name "value"` |
| `int` | `[int]` | `-Count 42` |
| `float` | `[double]` | `-Rate 3.14` |
| `Path` | `[string]` | `-File "path/to/file"` |
| `store_true` | `[switch]` | `-Verbose` |
## Requirements
- Python 3.11+
- Windows PowerShell or PowerShell Core
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Contributing
Contributions welcome! Please see [DEVELOPMENT.md](DEVELOPMENT.md) for setup instructions.
Raw data
{
"_id": null,
"home_page": null,
"name": "argparse-ps1",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "cli, code-generation, powershell, uv, wrapper",
"author": "Shimarch",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/65/ef/22fe99168dfe22f46a9f6a947a7dd5206e13a49e97a21b262ef6d6c6a4d7/argparse_ps1-0.1.5.tar.gz",
"platform": null,
"description": "# argparse-ps1\n\n**Generate PowerShell wrapper scripts from Python argparse parsers**\n\n[](https://badge.fury.io/py/argparse-ps1)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/shimarch/argparse-ps1/actions)\n\n`argparse-ps1` automatically generates PowerShell (.ps1) wrapper scripts for Python scripts that use `argparse`. This provides native PowerShell tab completion and parameter binding for your Python scripts.\n\n## Features\n\n- \ud83d\ude80 **Automatic Generation**: Creates PowerShell wrappers from `ArgumentParser` objects\n- \ud83c\udfaf **Type Mapping**: Maps Python types to PowerShell parameter types\n- \ud83d\udcdd **Native Interface**: Provides PowerShell-style parameter names and help\n- \u2699\ufe0f **Multiple Runners**: Supports `uv`, `python`, or custom runners\n- \ud83d\udd27 **Zero Dependencies**: Uses only Python standard library\n\n## Installation\n\n```bash\npip install argparse-ps1\n```\n\n## Quick Start\n\nAdd wrapper generation to your Python script:\n\n```python\nfrom argparse_ps1 import generate_ps1_wrapper\n\n# Your existing argparse code\nparser = argparse.ArgumentParser(description=\"My script\")\nparser.add_argument(\"--hello\", action=\"store_true\", help=\"Say hello\")\nparser.add_argument(\"--option\", type=str, help=\"String option\")\n\n# Generate PowerShell wrapper\nif \"--make-ps1\" in sys.argv:\n output = generate_ps1_wrapper(parser, script_path=Path(__file__))\n print(f\"Generated: {output}\")\n sys.exit(0)\n```\n\nGenerate the wrapper:\n\n```bash\npython my_script.py --make-ps1\n# Creates My-Script.ps1\n```\n\nUse the PowerShell wrapper:\n\n```powershell\n.\\My-Script.ps1 -Hello -Option \"test\"\n```\n\n## Examples\n\nSee the [examples/](examples/) directory for complete working examples:\n\n- **[basic_example.py](examples/basic_example.py)**: Simple boolean flags\n- **[example.py](examples/example.py)**: String options with `uv run`\n- **[example_uv_project.py](examples/example_uv_project.py)**: Using `uv run --project`\n- **[example_python.py](examples/example_python.py)**: Using `python` runner instead of `uv`\n\n### Project Mode Requirements\n\nFor project mode examples (`example_uv_project.py`), you need:\n\n1. **Proper pyproject.toml structure** with `[project.scripts]` entry\n2. **Package structure** with `__init__.py` files\n3. **Correct execution method**: Use `uv run python example_uv_project.py` instead of script entries\n\n## Usage Modes\n\n### Default: uv run (Direct Script)\n\n```python\ngenerate_ps1_wrapper(parser, script_path=Path(__file__))\n# Creates: & uv run script.py @args\n```\n\n### Project Mode: uv run --project\n\n```python\ngenerate_ps1_wrapper(\n parser,\n script_path=Path(__file__),\n project_root=Path(\"..\"),\n command_name=\"my-command\" # Must exist in [project.scripts]\n)\n# Creates: & uv run --project .. my-command @args\n```\n\n### Custom Runner\n\nUse alternative Python executables instead of `uv`:\n\n```python\n# System Python\ngenerate_ps1_wrapper(\n parser,\n script_path=Path(__file__),\n runner=\"python\"\n)\n# Creates: & python script.py @args\n\n# Virtual environment Python (relative path)\ngenerate_ps1_wrapper(\n parser,\n script_path=Path(__file__),\n runner=\".venv/Scripts/python.exe\" # Windows\n # runner=\".venv/bin/python\" # Unix/macOS\n)\n# Creates: & .venv\\Scripts\\python.exe script.py @args\n\n# Custom Python installation (absolute path)\ngenerate_ps1_wrapper(\n parser,\n script_path=Path(__file__),\n runner=\"C:/Python312/python.exe\"\n)\n# Creates: & \"C:/Python312/python.exe\" script.py @args\n```\n\n**Note**: See [example_python.py](examples/example_python.py) for a complete working example.\n\n## API Reference\n\n```python\ndef generate_ps1_wrapper(\n parser: argparse.ArgumentParser,\n *,\n script_path: Path,\n output_path: Path | None = None,\n output_dir: Path | None = None,\n skip_dests: Iterable[str] | None = None,\n runner: str = \"uv\",\n command_name: str | None = None,\n) -> Path\n```\n\n**Parameters:**\n\n- `parser`: Your `ArgumentParser` instance\n- `script_path`: Path to your Python script (absolute path required)\n- `output_path`: Specific output file path (optional, overrides output_dir)\n- `output_dir`: Output directory (default: current working directory)\n- `skip_dests`: Argument destinations to exclude from wrapper\n- `runner`: Command to run Python scripts (default: \"uv\", can be \"python\")\n- `command_name`: Command name in `[project.scripts]` (enables project mode for uv)\n\n## Type Mapping\n\n| Python Type | PowerShell Type | Example |\n| ------------ | --------------- | ---------------------- |\n| `str` | `[string]` | `-Name \"value\"` |\n| `int` | `[int]` | `-Count 42` |\n| `float` | `[double]` | `-Rate 3.14` |\n| `Path` | `[string]` | `-File \"path/to/file\"` |\n| `store_true` | `[switch]` | `-Verbose` |\n\n## Requirements\n\n- Python 3.11+\n- Windows PowerShell or PowerShell Core\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nContributions welcome! Please see [DEVELOPMENT.md](DEVELOPMENT.md) for setup instructions.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate PowerShell wrapper scripts for Python scripts executed with uv",
"version": "0.1.5",
"project_urls": {
"Documentation": "https://github.com/shimarch/argparse-ps1#readme",
"Homepage": "https://github.com/shimarch/argparse-ps1",
"Issues": "https://github.com/shimarch/argparse-ps1/issues",
"Repository": "https://github.com/shimarch/argparse-ps1"
},
"split_keywords": [
"cli",
" code-generation",
" powershell",
" uv",
" wrapper"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c6d849517980c81f8a6a5317b891a0974971e931e9868763db49996aaff4a3bd",
"md5": "18143a775738f39d3ad7d0f7147ea2b1",
"sha256": "ab927e7658343e7e12ef667dd1b26eb6c32bc880b7da2fbfc72c15e3858622e2"
},
"downloads": -1,
"filename": "argparse_ps1-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "18143a775738f39d3ad7d0f7147ea2b1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 8884,
"upload_time": "2025-10-28T12:22:40",
"upload_time_iso_8601": "2025-10-28T12:22:40.780184Z",
"url": "https://files.pythonhosted.org/packages/c6/d8/49517980c81f8a6a5317b891a0974971e931e9868763db49996aaff4a3bd/argparse_ps1-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "65ef22fe99168dfe22f46a9f6a947a7dd5206e13a49e97a21b262ef6d6c6a4d7",
"md5": "59cde68000b1edc262207c0ec4b884da",
"sha256": "0fdea019aa5390628742fcf7c9f7685929ada37c2b58a1470f77e0f8fefe5d4a"
},
"downloads": -1,
"filename": "argparse_ps1-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "59cde68000b1edc262207c0ec4b884da",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 12104,
"upload_time": "2025-10-28T12:22:41",
"upload_time_iso_8601": "2025-10-28T12:22:41.850611Z",
"url": "https://files.pythonhosted.org/packages/65/ef/22fe99168dfe22f46a9f6a947a7dd5206e13a49e97a21b262ef6d6c6a4d7/argparse_ps1-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-28 12:22:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "shimarch",
"github_project": "argparse-ps1#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "argparse-ps1"
}
JSON
