README.md

argparse-ps1

Generate PowerShell wrapper scripts from Python argparse parsers

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

pip install argparse-ps1

Quick Start

Add wrapper generation to your Python script:

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:

python my_script.py --make-ps1
# Creates My-Script.ps1

Use the PowerShell wrapper:

.\My-Script.ps1 -Hello -Option "test"

Examples

See the examples/ directory for complete working examples:

• basic_example.py: Simple boolean flags
• example.py: String options with uv run
• example_uv_project.py: Using uv run --project
• 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)

generate_ps1_wrapper(parser, script_path=Path(__file__))
# Creates: & uv run script.py @args

Project Mode: uv run --project

generate_ps1_wrapper(
    parser,
    script_path=Path(__file__),
    command_name="my-command"  # Must exist in [project.scripts]
)
# Creates: & uv run --project <project-root> my-command @args

Custom Runner

Use alternative Python executables instead of uv:

# 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 for a complete working example.

API Reference

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 file for details.

Contributing

Contributions welcome! Please see DEVELOPMENT.md for setup instructions.