Metadata-Version: 2.3
Name: typed-args
Version: 0.6.5
Summary: Parse command line arguments by defining dataclasses
Project-URL: Homepage, https://github.com/SunDoge/typed-args
Project-URL: Repository, https://github.com/SunDoge/typed-args
Author-email: SunDoge <triplez0@outlook.com>
License: BSD 3-Clause License
        
        Copyright (c) 2019, SunDoge
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        * Redistributions of source code must retain the above copyright notice, this
          list of conditions and the following disclaimer.
        
        * Redistributions in binary form must reproduce the above copyright notice,
          this list of conditions and the following disclaimer in the documentation
          and/or other materials provided with the distribution.
        
        * Neither the name of the copyright holder nor the names of its
          contributors may be used to endorse or promote products derived from
          this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: argparse,cli
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.6
Description-Content-Type: text/markdown

# typed-args

[![Github Actions](https://img.shields.io/github/actions/workflow/status/SunDoge/typed-args/python-package.yml?branch=master&style=for-the-badge)](https://github.com/SunDoge/typed-args/actions/workflows/python-package.yml)
[![Pypi](https://img.shields.io/pypi/v/typed-args?style=for-the-badge)](https://pypi.org/project/typed-args/)

This project is inspired by [TeXitoi/structopt](https://github.com/TeXitoi/structopt).

## Introduction

`typed-args` is a Python package for creating command line interfaces with type annotations. 
The program defines what arguments it requires, and `typed-args` will figure out how to parse them out of `sys.argv`. 
`typed-args` use standard python library `argparse` and `dataclasses` so no need to install any dependencies after Python 3.6. 
Its API is very similar to `argparse`. 


What does it look like? Here is an [example](https://docs.python.org/3/library/argparse.html#example) from `argparse` docs and is rewritten with `typed-args`:

```python
import typed_args as ta
from typing import List, Callable


@ta.argument_parser(
    description='Process some integers.'
)
class Args(ta.TypedArgs):
    integers: List[int] = ta.add_argument(
        metavar='N', type=int, nargs='+',
        help='an integer for the accumulator'
    )
    accumulate: Callable[[List[int]], int] = ta.add_argument(
        '--sum',
        action='store_const',
        const=sum, default=max,
        help='sum the integers (default: find the max)'
    )


args = Args.parse_args()
print(args.accumulate(args.integers))
```

Assuming the above Python code is saved into a file called `prog.py`, it can be run at the command line and it provides useful help messages:

```text
$ python prog.py -h
usage: prog.py [-h] [--sum] N [N ...]

Process some integers.

positional arguments:
  N           an integer for the accumulator

optional arguments:
  -h, --help  show this help message and exit
  --sum       sum the integers (default: find the max)
```

When run with the appropriate arguments, it prints either the sum or the max of the command-line integers:

```text
$ python prog.py 1 2 3 4
4

$ python prog.py 1 2 3 4 --sum
10
```

If invalid arguments are passed in, an error will be displayed:

```text
$ python prog.py a b c
usage: prog.py [-h] [--sum] N [N ...]
prog.py: error: argument N: invalid int value: 'a'
```



## Installation

From pypi

```bash
pip install typed-args
```

If you want to use it on python 3.5 and 3.6 please install `dataclasses`:

```bash
pip install dataclasses
```

## Core Functionality

Check [_test_v0_6.py](https://github.com/SunDoge/typed-args/blob/master/_test_v0_6.py) for `add_argument_group` and `add_subparsers`.


### Create a parser

`argparse`

```python
import argparse
parser = argparse.ArgumentParser(prog='ProgramName')
```

`typed-args`

```python
import typed_args as ta

@ta.argument_parser(prog='ProgramName')
class Args(ta.TypedArgs):
    pass
```

### Add arguments

`argparse`

```python
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('filename')           # positional argument
parser.add_argument('-c', '--count')      # option that takes a value
parser.add_argument('-v', '--verbose',
                    action='store_true')  # on/off flag
```

`typed-args`

```python
import typed_args as ta

@ta.argument_parser()
class Args(ta.TypedArgs):
    filename: str = ta.add_argument()                    # positional argument, use the attribute name automatically
    count: str = ta.add_argument('-c', '--count')        # option that takes a value, also can be annotated as Optional[str]
    verbose: bool = ta.add_argument('-v', '--verbose', 
                                    action='store_true') # on/off flag
```

### Parse args

`argparse`

```python
args = parser.parse_args()
print(args.filename, args.count, args.verbose)
```

`typed-args`

```python
args = Args.parse_args()
print(args.filename, args.count, args.verbose)
```


