Metadata-Version: 2.1
Name: arger
Version: 1.0.5
Summary: Create argparser automatically from functions
Home-page: https://pypi.org/project/arger
License: MIT
Author: Noortheen Raja
Author-email: jnoortheen@gmail.com
Requires-Python: >=3.6,<4.0
Classifier: Development Status :: 1 - Planning
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Freely Distributable
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
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.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Project-URL: Documentation, https://arger.readthedocs.io
Project-URL: Repository, https://github.com/jnoortheen/arger
Description-Content-Type: text/markdown

# Overview

A wrapper around argparser to help build CLIs from functions. Uses type-hints extensively :snake:.

[![PyPi Version](https://img.shields.io/pypi/v/arger.svg?style=flat)](https://pypi.python.org/pypi/arger)
[![Python Version](https://img.shields.io/pypi/pyversions/arger.svg)](https://pypi.org/project/arger/)
![](https://github.com/jnoortheen/arger/workflows/test-and-publish/badge.svg)
[![PyPI License](https://img.shields.io/pypi/l/arger.svg)](https://pypi.org/project/arger)

# Setup

## :gear: Installation

Install it directly into an activated virtual environment:

``` text
$ pip install arger
```

or add it to your [Poetry](https://poetry.eustace.io/) project:

``` text
$ poetry add arger
```

# :books: Usage

* create a python file called test.py

``` python
from arger import Arger

def main(param1: int, param2: str, kw1=None, kw2=False):
    """Example function with types documented in the docstring.

    :param param1: The first parameter.
    :param param2: The second parameter.
    """
    print(locals())

if __name__ == '__main__':
    Arger(main).run()
```

* run this normally with

``` sh
python test.py 100 param2
```

* Checkout [examples](docs/examples) folder and documentation to see more of `arger` in action.

# Features

- Uses docstring to parse help comment for arguments. Supports
    + [google](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)
    + [numpy](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html#example-numpy)
    + [rst](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)
- Flags will be generated from parameter-name. 
  If needed you could declare it inside docstring like `:param arg1: -a --arg this is the document`.
  Also one can use `def main(arg1:int=Option('-a', '--arg')): ...`
- The decorated functions can be composed to form nested sub-commands of any level.
- No external lib dependency
- Standard types supported. 
  Please see [examples](docs/examples/supported_options.py) for more supported types with examples.
- All argument to `ArgumentParser.add_argument` is supported. 
  It can be updated with `arger.Argument` or `arger.Option` classes.
- `*args` supported but no `**kwargs` support yet.
- all optional arguments that start with underscore is not passed to `Parser`. 
  They are considered private to the function implementation.
  One can use `_namespace_` to get the output from the `ArgumentParser.parse_args()`
  

# Similar Projects

## [argh](https://argh.readthedocs.io/en/latest/tutorial.html)

 - has similar goals as to ease up using argparser.
 - doesn't support type hints.
 - No recent releases.

## [typer](https://github.com/tiangolo/typer)

 - if you are using `click` , I highly recommend you to check this library.
 - it is neat and many features are drawn from it.
 - doesn't support loading help text for arguments from docstrings.

## [invoke](http://www.pyinvoke.org/)

 - doesn't support type hints.

## [cliche](https://github.com/kootenpv/cliche)

 - has similar goals.
 - doesn't cover much use cases as `arger` .

## [cliar](https://moigagoo.github.io/cliar/)

 - no docstring support for help argument.

# Recommended Alternatives

    Projects that I didn't know while creating this project. I highly recommend you to checkout them.

1.  [clize](https://github.com/epsy/clize)
2.  [nuclear](https://github.com/igrek51/nuclear)
3.  [defopt](https://github.com/anntzer/defopt)

This project was generated with [cookiecutter](https://github.com/audreyr/cookiecutter) using [jacebrowning/template-python](https://github.com/jacebrowning/template-python).


# Argparser enhancements

* web-ui : https://github.com/nirizr/argparseweb
* extra actions : https://github.com/kadimisetty/action-hero
* automatic shell completions using [argcomplete](https://github.com/kislyuk/argcomplete)


