Metadata-Version: 2.4
Name: docopt-typed
Version: 0.1.1
Summary: A lightweight helper around docopt-ng adding automatic type conversion
Project-URL: Homepage, https://github.com/johnscillieri/docopt-typed
Project-URL: Repository, https://github.com/johnscillieri/docopt-typed
Project-URL: Issues, https://github.com/johnscillieri/os-normalizer/issues
Project-URL: Changelog, https://github.com/johnscillieri/docopt-typed
Author: John Scillieri
License: MIT License
        
        Copyright (c) 2025 OS Normalizer contributors
        
        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.
License-File: LICENSE
Keywords: argparse,argument,docopt,parsing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: docopt-ng>=0.9.0
Description-Content-Type: text/markdown

# docopt-typed

docopt-typed is a lightweight helper around [docopt-ng](https://pypi.org/project/docopt-ng/) that keeps the ergonomics of docstrings-as-interfaces while adding automatic type conversion. Annotate your usage text with the familiar `<type>` markers and receive a `ParsedOptions` object whose values already match those types.

## Features

- Works as a drop-in replacement for `docopt` while returning the same `ParsedOptions` object
- Converts values to Python types by reading `<type>` (or `<name:type>`) hints in the usage text
- Supports common primitives (`int`, `float`, `bool`, `str`, `path`) plus JSON-backed structures, complex numbers, and `none/null`
- Keeps raw strings when a conversion fails so you can decide how to handle edge cases
- Treats option and positional argument annotations the same, so flags and required arguments can both be typed

## Installation

```bash
pip install docopt-typed
```

or

```bash
uv add docopt-typed
```

## Usage

Import `docopt_typed` instead of `docopt` and describe your CLI exactly as you would with docopt-ng, adding type annotations inside angle brackets. The example below mirrors the runnable block at the bottom of `src/docopt_typed/docopt_typed.py` and shows both option and positional annotations:

```python
from docopt_typed import docopt_typed

__doc__ = """Usage:
  myprogram.py --speed=<int> INPUT_FILE [options]

Arguments:
  INPUT_FILE <path>       The path to read from

Options:
  -s, --speed=<int>       Speed in mph (integer)
  -v, --verbose=<bool>    Enable verbose logging (true/false) [default: false]
  -n, --name=<str>        Your name [default: Alice]
  -d, --debug             Enable debug mode (no value needed)
"""

args = docopt_typed(__doc__)
print(args.speed, type(args.speed))        # 60 <class 'int'>
print(args.verbose, type(args.verbose))    # True <class 'bool'>
print(args.name, type(args.name))          # Bob <class 'str'>
print(args.debug, type(args.debug))        # True <class 'bool'>
print(args.INPUT_FILE, type(args.INPUT_FILE))  # Positional argument converted to Path
```

Running the script as `python myprogram.py --speed=60 --verbose=true --name=Bob input.txt` produces an already-typed result. Positional arguments are annotated by placing the type marker alongside the name (e.g. `INPUT_FILE <path>` in the `Arguments` section), while options continue to use the `--flag=<type>` pattern.

## Supported type hints

The converter looks for the `<type>` token associated with each option or argument name and applies the matching callable:
- `int`, `float`, `complex`
- `bool`, `boolean` (accepts `true/false`, `1/0`, `yes/no`, `on/off` in any case)
- `str`, `string`, `text`
- `json`, `dict`, `list` (parsed with `json.loads`)
- `bytes` (UTF-8 encoding of the provided value)
- `path`, `file`, `filepath`, `dir`, `directory` (converted to `pathlib.Path`)
- `none`, `null` (converted to `None`)

Any pattern that cannot be converted cleanly is left untouched as the original string so you can handle validation yourself.

## Attribute access and testing

`docopt_typed` returns the same `ParsedOptions` object as docopt-ng, so you can access results via `args["--speed"]` or `args.speed`. The accompanying tests in `tests/test_docopt.py` demonstrate how to supply custom argument lists, assert on types, and verify behavior for short-form flags and various boolean spellings.

## Error handling

When a hint is missing, misspelled, or unsupported, the original string is preserved. This mirrors docopt's philosophy of trusting the usage documentation and keeps the wrapper safe as a drop-in replacement.
