✨ add create dirs option (#13)

* add create dirs option

* cli arguments should be positional

* clean up examples

* depend on typer-slim

* add verbose option

* add overwrite protection

* update readme

---------

Co-authored-by: Bryn Lloyd <12702862+dyollb@users.noreply.github.com>

Author: dyollb

README.md

@@ -14,6 +14,9 @@ Create [Typer](https://github.com/tiangolo/typer) command line interfaces from f
 - 🔄 Automatic file I/O handling for SimpleITK images and transforms
 - 🎯 Type-safe with full type annotation support
 - 🚀 Built on Typer for modern CLI experiences
+- 🐍 Pythonic CLI design using native `*,` syntax for keyword-only parameters
+- 📁 Auto-create output directories with optional overwrite protection
+- 📝 Optional verbose logging with Rich integration
 - 🐍 Python 3.11+ with modern syntax
 
 ## Installation
@@ -22,6 +25,13 @@ Create [Typer](https://github.com/tiangolo/typer) command line interfaces from f
 pip install sitk-cli
 ```
 
+**Optional dependencies:**
+
+```sh
+# For enhanced logging output with colors and formatting
+pip install sitk-cli[rich]
+```
+
 **Requirements:** Python 3.11 or higher
 
 ## Quick Start
@@ -58,49 +68,74 @@ if __name__ == "__main__":
 1. Calls your function with the loaded objects
 1. Saves returned images/transforms to the specified output file
 
-## Usage Examples
+## Advanced Features
+
+### Positional vs Named Arguments
 
-### Optional Arguments
+Use Python's native `*,` syntax to control whether CLI arguments are positional or named:
 
 ```python
 @register_command(app)
-def median_filter(input: sitk.Image, radius: int = 2) -> sitk.Image:
-    """Apply median filtering to an image."""
-    return sitk.Median(input, [radius] * input.GetDimension())
+def process(input: sitk.Image, *, mask: sitk.Image) -> sitk.Image:
+    """Mix positional and keyword-only arguments.
+
+    CLI: process INPUT OUTPUT --mask MASK
+    """
+    return input * mask
+```
+
+Behavior:
+
+- **Required** Image/Transform parameters → **positional** by default
+- Parameters **after `*,`** → **keyword-only** (named options)
+- **Optional** parameters (with defaults) → **named options**
+- Output → **positional** if any input is positional, otherwise **named**
+
+### Verbose Logging
+
+```python
+from sitk_cli import logger, register_command
+
+@register_command(app, verbose=True)
+def process_with_logging(input: sitk.Image) -> sitk.Image:
+    logger.info("Starting processing...")
+    result = sitk.Median(input, [2] * input.GetDimension())
+    logger.debug(f"Result size: {result.GetSize()}")
+    return result
 ```
 
 ```sh
-python script.py median-filter --input image.nii.gz --radius 3 --output filtered.nii.gz
+python script.py process-with-logging input.nii output.nii -v   # INFO level
+python script.py process-with-logging input.nii output.nii -vv  # DEBUG level
 ```
 
-### Multiple Inputs with Type Unions
+### Overwrite Protection
 
 ```python
-@register_command(app)
-def add_images(
-    input1: sitk.Image,
-    input2: sitk.Image | None = None
-) -> sitk.Image:
-    """Add two images together, or return first if second is not provided."""
-    if input2 is None:
-        return input1
-    return input1 + input2
+@register_command(app, overwrite=False)
+def protected_process(input: sitk.Image) -> sitk.Image:
+    """Prevent accidental overwrites."""
+    return sitk.Median(input, [2] * input.GetDimension())
 ```
 
-### Transform Registration
+```sh
+python script.py protected-process input.nii output.nii
+python script.py protected-process input.nii output.nii          # Error: file exists
+python script.py protected-process input.nii output.nii --force  # OK, overwrites
+```
+
+Modes: `overwrite=True` (default), `overwrite=False` (requires `--force`), `overwrite="prompt"` (asks user)
+
+Optional parameters with defaults automatically become named options:
 
 ```python
 @register_command(app)
-def register_images(
-    fixed: sitk.Image,
-    moving: sitk.Image,
-    init_transform: sitk.Transform | None = None
-) -> sitk.Transform:
-    """Register two images and return the computed transform."""
-    if init_transform is None:
-        init_transform = sitk.CenteredTransformInitializer(fixed, moving)
-    # ... registration code ...
-    return final_transform
+def median_filter(input: sitk.Image, radius: int = 2) -> sitk.Image:
+    """Apply median filtering to an image.
+
+    CLI: median-filter INPUT OUTPUT [--radius 3]
+    """
+    return sitk.Median(input, [radius] * input.GetDimension())
 ```
 
 ## Demo
@@ -116,7 +151,7 @@ git clone https://github.com/dyollb/sitk-cli.git
 cd sitk-cli
 python -m venv .venv
 source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows
-pip install -e '.[dev]'
+pip install -e '.[dev,rich]'
 ```
 
 ### Running Tests

examples/argument_patterns.py

@@ -0,0 +1,97 @@
+"""Comprehensive guide to argument patterns using Python's *, syntax.
+
+This example demonstrates all the ways to control whether CLI arguments
+are positional or named using native Python keyword-only parameter syntax.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import typer
+
+from sitk_cli import register_command
+
+if TYPE_CHECKING:
+    import SimpleITK as sitk
+
+app = typer.Typer()
+
+
+# Pattern 1: All positional (default for required Image/Transform parameters)
+@register_command(app)
+def all_positional(input: sitk.Image, mask: sitk.Image) -> sitk.Image:
+    """All required inputs are positional by default.
+
+    CLI: all-positional INPUT MASK OUTPUT
+    """
+    return input * mask
+
+
+# Pattern 2: Mixed positional and named using *, (Pythonic!)
+@register_command(app)
+def mixed_args(input: sitk.Image, *, mask: sitk.Image) -> sitk.Image:
+    """Use *, to make specific parameters keyword-only.
+
+    CLI: mixed-args INPUT OUTPUT --mask MASK
+
+    The *, separator makes everything after it keyword-only,
+    so 'mask' becomes a named option while 'input' stays positional.
+    This is the recommended Python pattern!
+    """
+    return input * mask
+
+
+# Pattern 3: All keyword-only
+@register_command(app)
+def all_named(*, input: sitk.Image, mask: sitk.Image) -> sitk.Image:
+    """Use *, at start to make ALL parameters keyword-only.
+
+    CLI: all-named --input INPUT --mask MASK --output OUTPUT
+
+    Note: Output is also named because there are no positional inputs.
+    """
+    return input * mask
+
+
+# Pattern 4: Optional parameters are always named
+@register_command(app)
+def optional_params(input: sitk.Image, mask: sitk.Image | None = None) -> sitk.Image:
+    """Optional Image parameters (with defaults) are always named.
+
+    CLI: optional-params INPUT OUTPUT [--mask MASK]
+
+    Even without *,, optional parameters become named options.
+    """
+    if mask is not None:
+        return input * mask
+    return input
+
+
+# Pattern 5: Complex mixing for maximum clarity
+@register_command(app)
+def segment_regions(
+    input: sitk.Image,
+    reference: sitk.Image,
+    *,
+    brain_mask: sitk.Image | None = None,
+    threshold: float = 0.5,
+) -> sitk.Image:
+    """Recommended pattern: positional for required, keyword-only for optional.
+
+    CLI: segment-regions INPUT REFERENCE OUTPUT \\
+         [--brain-mask MASK] [--threshold 0.7]
+
+    Benefits:
+    - Required inputs (input, reference): positional → concise
+    - Optional/configuration (brain_mask, threshold): keyword-only → explicit
+    - This is the most Pythonic and readable CLI pattern!
+    """
+    result = input + reference
+    if brain_mask is not None:
+        result = result * brain_mask
+    return result > threshold
+
+
+if __name__ == "__main__":
+    app()

examples/create_directories.py

@@ -0,0 +1,44 @@
+"""Demonstrates automatic directory creation for output files.
+
+By default, sitk-cli automatically creates parent directories for output
+files. This can be disabled with create_dirs=False.
+"""
+
+from __future__ import annotations
+
+import SimpleITK as sitk
+import typer
+
+from sitk_cli import register_command
+
+app = typer.Typer()
+
+
+@register_command(app)  # create_dirs=True by default
+def process_with_auto_dirs(width: int = 100, height: int = 100) -> sitk.Image:
+    """Process that auto-creates output directories.
+
+    CLI: process-with-auto-dirs OUTPUT --width 100 --height 100
+
+    You can specify nested paths like:
+        process-with-auto-dirs results/2024/output.nii --width 200
+
+    The directories 'results/2024/' will be created automatically.
+    """
+    return sitk.Image(width, height, sitk.sitkUInt8)
+
+
+@register_command(app, create_dirs=False)
+def process_no_auto_dirs(width: int = 100, height: int = 100) -> sitk.Image:
+    """Process that requires directories to exist.
+
+    CLI: process-no-auto-dirs OUTPUT --width 100 --height 100
+
+    If you specify a path with directories that don't exist, you'll get an error.
+    Useful when you want to ensure output paths are pre-validated.
+    """
+    return sitk.Image(width, height, sitk.sitkUInt8)
+
+
+if __name__ == "__main__":
+    app()

examples/generator_functions.py

@@ -0,0 +1,67 @@
+"""Demonstrates functions that generate images without input images.
+
+When a function has no Image/Transform inputs but returns an Image/Transform,
+the output parameter is positional by default (unless you use *, syntax).
+"""
+
+from __future__ import annotations
+
+import SimpleITK as sitk
+import typer
+
+from sitk_cli import register_command
+
+app = typer.Typer()
+
+
+@register_command(app)
+def create_blank() -> sitk.Image:
+    """Create a blank 100x100 image.
+
+    CLI: create-blank OUTPUT
+
+    Output is positional because there are no Image/Transform inputs.
+    """
+    return sitk.Image([100, 100], sitk.sitkUInt8)
+
+
+@register_command(app)
+def create_checkerboard(
+    size: int = 100,
+    square_size: int = 10,
+) -> sitk.Image:
+    """Create a checkerboard pattern.
+
+    CLI: create-checkerboard OUTPUT --size 200 --square-size 20
+
+    Output is positional, size/square_size are named options with defaults.
+    """
+    image = sitk.Image([size, size], sitk.sitkUInt8)
+    for y in range(size):
+        for x in range(size):
+            if (x // square_size + y // square_size) % 2 == 0:
+                image.SetPixel([x, y], 255)
+    return image
+
+
+@register_command(app)
+def create_gradient(
+    *,
+    width: int = 100,
+    height: int = 100,
+) -> sitk.Image:
+    """Create a horizontal gradient image.
+
+    CLI: create-gradient --output OUTPUT --width 200 --height 150
+
+    Using *, makes all parameters keyword-only, so output is also named.
+    """
+    image = sitk.Image([width, height], sitk.sitkUInt8)
+    for y in range(height):
+        for x in range(width):
+            image.SetPixel([x, y], int(255 * x / width))
+    return image
+
+
+if __name__ == "__main__":
+    app()