dataclass-args 1.2.0__tar.gz → 1.3.0__tar.gz

{dataclass_args-1.2.0 → dataclass_args-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dataclass-args
-Version: 1.2.0
+Version: 1.3.0
 Summary: Zero-boilerplate CLI generation from Python dataclasses with advanced type support and file loading
 Author-email: Martin Bartlett <martin.j.bartlett@gmail.com>
 License: MIT
@@ -52,7 +52,8 @@ Dynamic: license-file
 Generate command-line interfaces from Python dataclasses.
 
 [![Tests](https://github.com/bassmanitram/dataclass-args/actions/workflows/test.yml/badge.svg)](https://github.com/bassmanitram/dataclass-args/actions/workflows/test.yml)
-[![Code Quality](https://github.com/bassmanitram/dataclass-args/actions/workflows/lint.yml/badge.svg)](https://github.com/bassmanitram/dataclass-args/actions/workflows/lint.yml)
+[![Lint](https://github.com/bassmanitram/dataclass-args/actions/workflows/lint.yml/badge.svg)](https://github.com/bassmanitram/dataclass-args/actions/workflows/lint.yml)
+[![Code Quality](https://github.com/bassmanitram/dataclass-args/actions/workflows/quality.yml/badge.svg)](https://github.com/bassmanitram/dataclass-args/actions/workflows/quality.yml)
 [![Examples](https://github.com/bassmanitram/dataclass-args/actions/workflows/examples.yml/badge.svg)](https://github.com/bassmanitram/dataclass-args/actions/workflows/examples.yml)
 [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
 [![PyPI version](https://img.shields.io/pypi/v/dataclass-args.svg)](https://pypi.org/project/dataclass-args/)
@@ -66,6 +67,7 @@ Generate command-line interfaces from Python dataclasses.
 - **[Short Options](#short-options)** - Concise `-n` flags in addition to `--name`
 - **[Boolean Flags](#boolean-flags)** - Proper `--flag` and `--no-flag` boolean handling
 - **[Value Validation](#value-choices)** - Restrict values with `cli_choices()`
+- **[Repeatable Options](#repeatable-options)** - Allow options to be specified multiple times with `cli_append()`
 - **[File Loading](#file-loadable-parameters)** - Load parameters from files using `@filename` syntax
 - **[Config Merging](#configuration-merging)** - Combine configuration sources with hierarchical overrides
 - **[Flexible Types](#type-support)** - Support for `List`, `Dict`, `Optional`, and custom types
@@ -209,6 +211,108 @@ error: argument --environment: invalid choice: 'invalid' (choose from 'dev', 'st
 
 
 
+### Repeatable Options
+
+Use `cli_append()` to allow an option to be specified multiple times, with each occurrence collecting its own arguments:
+
+```python
+from dataclass_args import cli_append
+
+@dataclass
+class Config:
+    # Simple tags: each -t adds one value
+    tags: List[str] = combine_annotations(
+        cli_short('t'),
+        cli_append(),
+        cli_help("Add a tag"),
+        default_factory=list
+    )
+```
+
+```bash
+# Each -t occurrence accumulates
+$ python app.py -t python -t cli -t tool
+# Result: ['python', 'cli', 'tool']
+```
+
+#### Repeatable with Multiple Arguments
+
+Each occurrence can take multiple arguments using `nargs`:
+
+```python
+@dataclass
+class DockerConfig:
+    # Each -p takes exactly 2 arguments (HOST CONTAINER)
+    ports: List[List[str]] = combine_annotations(
+        cli_short('p'),
+        cli_append(nargs=2),
+        cli_help("Port mapping (HOST CONTAINER)"),
+        default_factory=list
+    )
+
+    # Each -v takes exactly 2 arguments (SOURCE TARGET)
+    volumes: List[List[str]] = combine_annotations(
+        cli_short('v'),
+        cli_append(nargs=2),
+        cli_help("Volume mount (SOURCE TARGET)"),
+        default_factory=list
+    )
+```
+
+```bash
+$ python docker.py -p 8080 80 -p 8443 443 -v /host/data /container/data
+```
+
+#### Variable Arguments with Validation
+
+Use `min_args` and `max_args` for flexible argument counts with automatic validation:
+
+```python
+@dataclass
+class UploadConfig:
+    files: List[List[str]] = combine_annotations(
+        cli_short('f'),
+        cli_append(min_args=1, max_args=2, metavar="FILE [MIMETYPE]"),
+        cli_help("File with optional MIME type"),
+        default_factory=list
+    )
+    # No __post_init__ needed - validation is automatic!
+```
+
+```bash
+# Mix files with and without MIME types
+$ python upload.py -f doc.pdf application/pdf -f image.png -f video.mp4 video/mp4
+# Result: [['doc.pdf', 'application/pdf'], ['image.png'], ['video.mp4', 'video/mp4']]
+
+# Validation catches errors automatically
+$ python upload.py -f file1 arg2 arg3 arg4
+# Error: Expected at most 2 argument(s), got 4
+```
+
+**Clean help display:**
+```
+-f FILE [MIMETYPE], --files FILE [MIMETYPE]
+    File with optional MIME type (can be repeated, 1-2 args each)
+```
+
+**Parameters:**
+- `min_args`: Minimum arguments per occurrence
+- `max_args`: Maximum arguments per occurrence
+- Must be used together (both or neither)
+- Mutually exclusive with `nargs`
+
+**nargs Options:**
+- `None` - One value per occurrence → `List[T]`
+- `int` (e.g., `2`) - Exact count per occurrence → `List[List[T]]`
+- `'+'` - One or more per occurrence → `List[List[T]]`
+- `'*'` - Zero or more per occurrence → `List[List[T]]`
+
+**Use Cases:**
+- Docker-style options: `-p 8080:80 -p 8443:443 -v /host:/container -e KEY=value`
+- File operations: `-f file1 type1 -f file2 -f file3 type3`
+- Server pools: `-s host1 port1 -s host2 port2`
+- Build systems: `-I dir1 -I dir2 --define KEY VAL`
+
 ### Positional Arguments
 
 Add positional arguments that don't require `--` prefixes:

{dataclass_args-1.2.0 → dataclass_args-1.3.0}/README.md

@@ -3,7 +3,8 @@
 Generate command-line interfaces from Python dataclasses.
 
 [![Tests](https://github.com/bassmanitram/dataclass-args/actions/workflows/test.yml/badge.svg)](https://github.com/bassmanitram/dataclass-args/actions/workflows/test.yml)
-[![Code Quality](https://github.com/bassmanitram/dataclass-args/actions/workflows/lint.yml/badge.svg)](https://github.com/bassmanitram/dataclass-args/actions/workflows/lint.yml)
+[![Lint](https://github.com/bassmanitram/dataclass-args/actions/workflows/lint.yml/badge.svg)](https://github.com/bassmanitram/dataclass-args/actions/workflows/lint.yml)
+[![Code Quality](https://github.com/bassmanitram/dataclass-args/actions/workflows/quality.yml/badge.svg)](https://github.com/bassmanitram/dataclass-args/actions/workflows/quality.yml)
 [![Examples](https://github.com/bassmanitram/dataclass-args/actions/workflows/examples.yml/badge.svg)](https://github.com/bassmanitram/dataclass-args/actions/workflows/examples.yml)
 [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
 [![PyPI version](https://img.shields.io/pypi/v/dataclass-args.svg)](https://pypi.org/project/dataclass-args/)
@@ -17,6 +18,7 @@ Generate command-line interfaces from Python dataclasses.
 - **[Short Options](#short-options)** - Concise `-n` flags in addition to `--name`
 - **[Boolean Flags](#boolean-flags)** - Proper `--flag` and `--no-flag` boolean handling
 - **[Value Validation](#value-choices)** - Restrict values with `cli_choices()`
+- **[Repeatable Options](#repeatable-options)** - Allow options to be specified multiple times with `cli_append()`
 - **[File Loading](#file-loadable-parameters)** - Load parameters from files using `@filename` syntax
 - **[Config Merging](#configuration-merging)** - Combine configuration sources with hierarchical overrides
 - **[Flexible Types](#type-support)** - Support for `List`, `Dict`, `Optional`, and custom types
@@ -160,6 +162,108 @@ error: argument --environment: invalid choice: 'invalid' (choose from 'dev', 'st
 
 
 
+### Repeatable Options
+
+Use `cli_append()` to allow an option to be specified multiple times, with each occurrence collecting its own arguments:
+
+```python
+from dataclass_args import cli_append
+
+@dataclass
+class Config:
+    # Simple tags: each -t adds one value
+    tags: List[str] = combine_annotations(
+        cli_short('t'),
+        cli_append(),
+        cli_help("Add a tag"),
+        default_factory=list
+    )
+```
+
+```bash
+# Each -t occurrence accumulates
+$ python app.py -t python -t cli -t tool
+# Result: ['python', 'cli', 'tool']
+```
+
+#### Repeatable with Multiple Arguments
+
+Each occurrence can take multiple arguments using `nargs`:
+
+```python
+@dataclass
+class DockerConfig:
+    # Each -p takes exactly 2 arguments (HOST CONTAINER)
+    ports: List[List[str]] = combine_annotations(
+        cli_short('p'),
+        cli_append(nargs=2),
+        cli_help("Port mapping (HOST CONTAINER)"),
+        default_factory=list
+    )
+
+    # Each -v takes exactly 2 arguments (SOURCE TARGET)
+    volumes: List[List[str]] = combine_annotations(
+        cli_short('v'),
+        cli_append(nargs=2),
+        cli_help("Volume mount (SOURCE TARGET)"),
+        default_factory=list
+    )
+```
+
+```bash
+$ python docker.py -p 8080 80 -p 8443 443 -v /host/data /container/data
+```
+
+#### Variable Arguments with Validation
+
+Use `min_args` and `max_args` for flexible argument counts with automatic validation:
+
+```python
+@dataclass
+class UploadConfig:
+    files: List[List[str]] = combine_annotations(
+        cli_short('f'),
+        cli_append(min_args=1, max_args=2, metavar="FILE [MIMETYPE]"),
+        cli_help("File with optional MIME type"),
+        default_factory=list
+    )
+    # No __post_init__ needed - validation is automatic!
+```
+
+```bash
+# Mix files with and without MIME types
+$ python upload.py -f doc.pdf application/pdf -f image.png -f video.mp4 video/mp4
+# Result: [['doc.pdf', 'application/pdf'], ['image.png'], ['video.mp4', 'video/mp4']]
+
+# Validation catches errors automatically
+$ python upload.py -f file1 arg2 arg3 arg4
+# Error: Expected at most 2 argument(s), got 4
+```
+
+**Clean help display:**
+```
+-f FILE [MIMETYPE], --files FILE [MIMETYPE]
+    File with optional MIME type (can be repeated, 1-2 args each)
+```
+
+**Parameters:**
+- `min_args`: Minimum arguments per occurrence
+- `max_args`: Maximum arguments per occurrence
+- Must be used together (both or neither)
+- Mutually exclusive with `nargs`
+
+**nargs Options:**
+- `None` - One value per occurrence → `List[T]`
+- `int` (e.g., `2`) - Exact count per occurrence → `List[List[T]]`
+- `'+'` - One or more per occurrence → `List[List[T]]`
+- `'*'` - Zero or more per occurrence → `List[List[T]]`
+
+**Use Cases:**
+- Docker-style options: `-p 8080:80 -p 8443:443 -v /host:/container -e KEY=value`
+- File operations: `-f file1 type1 -f file2 -f file3 type3`
+- Server pools: `-s host1 port1 -s host2 port2`
+- Build systems: `-I dir1 -I dir2 --define KEY VAL`
+
 ### Positional Arguments
 
 Add positional arguments that don't require `--` prefixes:

{dataclass_args-1.2.0 → dataclass_args-1.3.0}/dataclass_args/__init__.py

@@ -43,6 +43,7 @@ Advanced Usage:
 """
 
 from .annotations import (
+    cli_append,
     cli_choices,
     cli_exclude,
     cli_file_loadable,
@@ -51,10 +52,15 @@ from .annotations import (
     cli_positional,
     cli_short,
     combine_annotations,
+    get_cli_append_max_args,
+    get_cli_append_metavar,
+    get_cli_append_min_args,
+    get_cli_append_nargs,
     get_cli_choices,
     get_cli_positional_metavar,
     get_cli_positional_nargs,
     get_cli_short,
+    is_cli_append,
     is_cli_excluded,
     is_cli_file_loadable,
     is_cli_included,
@@ -65,7 +71,7 @@ from .exceptions import ConfigBuilderError, ConfigurationError, FileLoadingError
 from .file_loading import is_file_loadable_value, load_file_content
 from .utils import load_structured_file
 
-__version__ = "1.2.0"
+__version__ = "1.3.0"
 
 __all__ = [
     # Main API
@@ -80,15 +86,21 @@ __all__ = [
     "cli_include",
     "cli_file_loadable",
     "cli_positional",
+    "cli_append",
     "combine_annotations",
     "get_cli_short",
     "get_cli_choices",
     "get_cli_positional_nargs",
     "get_cli_positional_metavar",
+    "get_cli_append_nargs",
+    "get_cli_append_metavar",
+    "get_cli_append_min_args",
+    "get_cli_append_max_args",
     "is_cli_file_loadable",
     "is_cli_excluded",
     "is_cli_included",
     "is_cli_positional",
+    "is_cli_append",
     # File loading
     "load_file_content",
     "is_file_loadable_value",

{dataclass_args-1.2.0 → dataclass_args-1.3.0}/dataclass_args/annotations.py

@@ -219,6 +219,143 @@ def cli_file_loadable(**kwargs) -> Any:
     return field(**field_kwargs)
 
 
+def cli_append(
+    nargs: Optional[Any] = None,
+    min_args: Optional[int] = None,
+    max_args: Optional[int] = None,
+    metavar: Optional[str] = None,
+    **kwargs,
+) -> Any:
+    """
+    Mark a field for append action - allows repeating the option multiple times.
+
+    Each occurrence of the option collects its arguments into a sub-list,
+    and all sub-lists are collected into the final list.
+
+    Args:
+        nargs: Number of arguments per option occurrence (traditional argparse style)
+               None = exactly one (each -f takes 1 arg)
+               '?' = zero or one
+               '*' = zero or more
+               '+' = one or more
+               int = exact count (e.g., 2 for pairs)
+               Mutually exclusive with min_args/max_args
+        min_args: Minimum arguments per occurrence (e.g., 1 for "at least 1")
+                  Must be used together with max_args
+                  Mutually exclusive with nargs
+        max_args: Maximum arguments per occurrence (e.g., 2 for "at most 2")
+                  Must be used together with min_args
+                  Mutually exclusive with nargs
+        metavar: Name for display in help text (e.g., "FILE [MIMETYPE]")
+        **kwargs: Additional field parameters (default_factory, etc.)
+
+    Returns:
+        Field object with append metadata
+
+    Examples:
+        Basic append with single values:
+
+        >>> @dataclass
+        ... class Config:
+        ...     tags: List[str] = cli_append()
+
+        CLI: -t python -t cli -t dataclass
+        Result: ['python', 'cli', 'dataclass']
+
+        Append with pairs (nargs=2):
+
+        >>> @dataclass
+        ... class Config:
+        ...     files: List[List[str]] = cli_append(nargs=2)
+
+        CLI: -f file1.txt text/plain -f file2.jpg image/jpeg
+        Result: [['file1.txt', 'text/plain'], ['file2.jpg', 'image/jpeg']]
+
+        Append with variable args (nargs='+'):
+
+        >>> @dataclass
+        ... class Config:
+        ...     groups: List[List[str]] = cli_append(nargs='+')
+
+        CLI: -g file1 file2 -g file3 -g file4 file5 file6
+        Result: [['file1', 'file2'], ['file3'], ['file4', 'file5', 'file6']]
+
+        Combined with other annotations:
+
+        >>> @dataclass
+        ... class Config:
+        ...     files: List[List[str]] = combine_annotations(
+        ...         cli_short('f'),
+        ...         cli_append(nargs='+'),
+        ...         cli_help("File with optional MIME type"),
+        ...         default_factory=list
+        ...     )
+
+        CLI: -f doc.pdf application/pdf -f image.png -f video.mp4 video/mp4
+        Result: [['doc.pdf', 'application/pdf'], ['image.png'], ['video.mp4', 'video/mp4']]
+
+        With metavar for better help text:
+
+        >>> @dataclass
+        ... class Config:
+        ...     files: List[List[str]] = combine_annotations(
+        ...         cli_short('f'),
+        ...         cli_append(nargs='+', metavar="FILE [MIMETYPE]"),
+        ...         cli_help("File with optional MIME type"),
+        ...         default_factory=list
+        ...     )
+
+    Note:
+        - Field type should be List[T] for nargs=None, or List[List[T]] for nargs with multiple values
+        - Always use default_factory=list for append fields
+        - Cannot be combined with cli_positional()
+    """
+    # Validate mutually exclusive parameters
+    if nargs is not None and (min_args is not None or max_args is not None):
+        raise ValueError(
+            "cli_append: 'nargs' and 'min_args'/'max_args' are mutually exclusive. "
+            "Use either nargs for standard argparse behavior, or min_args/max_args for range validation."
+        )
+
+    # Validate min_args/max_args must be used together
+    if (min_args is not None) != (max_args is not None):
+        raise ValueError(
+            "cli_append: 'min_args' and 'max_args' must be used together. "
+            f"Got min_args={min_args}, max_args={max_args}"
+        )
+
+    # Validate range constraints
+    if min_args is not None and max_args is not None:
+        if min_args < 1:
+            raise ValueError(f"cli_append: 'min_args' must be >= 1, got {min_args}")
+        if max_args < min_args:
+            raise ValueError(
+                f"cli_append: 'max_args' ({max_args}) must be >= min_args ({min_args})"
+            )
+
+    field_kwargs = kwargs.copy()
+    metadata = field_kwargs.pop("metadata", {})
+    metadata["cli_append"] = True
+
+    if nargs is not None:
+        metadata["cli_append_nargs"] = nargs
+
+    if metavar is not None:
+        metadata["cli_append_metavar"] = metavar
+
+    if min_args is not None:
+        metadata["cli_append_min_args"] = min_args
+
+    if max_args is not None:
+        metadata["cli_append_max_args"] = max_args
+    # Move 'help' to metadata if present (dataclass field() doesn't accept it)
+    if "help" in field_kwargs:
+        metadata["cli_help"] = field_kwargs.pop("help")
+
+    field_kwargs["metadata"] = metadata
+    return field(**field_kwargs)
+
+
 def combine_annotations(*annotations, **field_kwargs) -> Any:
     """
     Combine multiple CLI annotations into a single field.
@@ -316,6 +453,22 @@ def is_cli_file_loadable(field_info: Dict[str, Any]) -> bool:
     return False
 
 
+def is_cli_append(field_info: Dict[str, Any]) -> bool:
+    """
+    Check if a field uses append action for repeated options.
+
+    Args:
+        field_info: Field information dictionary from GenericConfigBuilder
+
+    Returns:
+        True if field uses append action
+    """
+    field_obj = field_info.get("field_obj")
+    if field_obj and hasattr(field_obj, "metadata"):
+        return field_obj.metadata.get("cli_append", False)
+    return False
+
+
 def get_cli_short(field_info: Dict[str, Any]) -> Optional[str]:
     """
     Get short option character for a CLI argument.
@@ -348,6 +501,38 @@ def get_cli_choices(field_info: Dict[str, Any]) -> Optional[List[Any]]:
     return None
 
 
+def get_cli_append_nargs(field_info: Dict[str, Any]) -> Optional[Any]:
+    """
+    Get nargs value for an append CLI argument.
+
+    Args:
+        field_info: Field information dictionary from GenericConfigBuilder
+
+    Returns:
+        nargs value if specified, otherwise None (meaning exactly one per occurrence)
+    """
+    field_obj = field_info.get("field_obj")
+    if field_obj and hasattr(field_obj, "metadata"):
+        return field_obj.metadata.get("cli_append_nargs")
+    return None
+
+
+def get_cli_append_metavar(field_info: Dict[str, Any]) -> Optional[str]:
+    """
+    Get metavar for an append CLI argument.
+
+    Args:
+        field_info: Field information dictionary from GenericConfigBuilder
+
+    Returns:
+        Metavar string if specified, otherwise None
+    """
+    field_obj = field_info.get("field_obj")
+    if field_obj and hasattr(field_obj, "metadata"):
+        return field_obj.metadata.get("cli_append_metavar")
+    return None
+
+
 def get_cli_help(field_info: Dict[str, Any]) -> str:
     """
     Get custom help text for a CLI argument.
@@ -521,3 +706,35 @@ def get_cli_positional_metavar(field_info: Dict[str, Any]) -> Optional[str]:
     if field_obj and hasattr(field_obj, "metadata"):
         return field_obj.metadata.get("cli_positional_metavar")
     return None
+
+
+def get_cli_append_min_args(field_info: Dict[str, Any]) -> Optional[int]:
+    """
+    Get minimum arguments for an append CLI argument.
+
+    Args:
+        field_info: Field information dictionary from GenericConfigBuilder
+
+    Returns:
+        Minimum argument count if specified, otherwise None
+    """
+    field_obj = field_info.get("field_obj")
+    if field_obj and hasattr(field_obj, "metadata"):
+        return field_obj.metadata.get("cli_append_min_args")
+    return None
+
+
+def get_cli_append_max_args(field_info: Dict[str, Any]) -> Optional[int]:
+    """
+    Get maximum arguments for an append CLI argument.
+
+    Args:
+        field_info: Field information dictionary from GenericConfigBuilder
+
+    Returns:
+        Maximum argument count if specified, otherwise None
+    """
+    field_obj = field_info.get("field_obj")
+    if field_obj and hasattr(field_obj, "metadata"):
+        return field_obj.metadata.get("cli_append_max_args")
+    return None

dataclass_args-1.3.0/dataclass_args/append_action.py

@@ -0,0 +1,48 @@
+"""Custom argparse action for range-validated append arguments."""
+
+import argparse
+from typing import Any, Optional, Sequence, Union
+
+
+class RangeAppendAction(argparse._AppendAction):  # type: ignore[misc]
+    """
+    Append action for fields with min/max argument validation.
+
+    Works with RangeAppendHelpFormatter to display metavar cleanly without repetition.
+
+    Standard: -f X Y [X Y ...]
+    With this: -f X Y
+    """
+
+    def __init__(
+        self,
+        option_strings: Sequence[str],
+        dest: str,
+        nargs: Optional[Union[int, str]] = None,
+        const: Any = None,
+        default: Any = None,
+        type: Any = None,
+        choices: Optional[Sequence[Any]] = None,
+        required: bool = False,
+        help: Optional[str] = None,
+        metavar: Optional[str] = None,
+        **kwargs: Any,
+    ):
+        """Initialize with custom metavar storage."""
+        # Store metavar for custom formatter to use
+        self._custom_metavar = metavar
+
+        # Call parent without metavar to avoid argparse's automatic handling
+        super().__init__(
+            option_strings=option_strings,
+            dest=dest,
+            nargs=nargs,
+            const=const,
+            default=default,
+            type=type,
+            choices=choices,
+            required=required,
+            help=help,
+            metavar=None,  # Don't pass to parent
+            **kwargs,
+        )