Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ialbert/plac
Plac: Parsing the Command Line the Easy Way
https://github.com/ialbert/plac
Last synced: about 2 months ago
JSON representation
Plac: Parsing the Command Line the Easy Way
- Host: GitHub
- URL: https://github.com/ialbert/plac
- Owner: ialbert
- License: bsd-2-clause
- Created: 2015-03-15T14:10:23.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2024-08-09T23:08:11.000Z (4 months ago)
- Last Synced: 2024-08-10T00:24:24.548Z (4 months ago)
- Language: Python
- Homepage:
- Size: 3.8 MB
- Stars: 295
- Watchers: 8
- Forks: 29
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
- License: LICENSE.txt
Awesome Lists containing this project
- awesome-cli-frameworks - Plac
README
# Plac: parsing the command line the easy way
`plac` is a Python package that can generate command line parameters
from function signatures.
`plac` works on Python 2.6 through all versions of Python 3.
`plac` has no dependencies beyond modules already present in the Python
standard library.
`plac` implements most of its functionality in a single file that may be
included in your source code.
## Quickstart
`plac` can automatically generate command line parameters from a function signature.
```python
import plac
def main(model, iter=100, debug=False):
"""
A script for machine learning
"""
print (model, iter, debug)
if __name__ == '__main__':
# Execute function via plac.call()
plac.call(main)
```
The program above can now take parameters from the command line like so:
python example.py A 1000
Running the script with no parameters as `python example.py` would print:
```
usage: example.py [-h] model [iter] [debug]
example.py: error: the following arguments are required: model
```
In addition, the program can also generate a help message:
```python
python example.py -h
```
Produces the following output:
```
usage: example.py [-h] model [iter] [debug]
A script for machine learning
positional arguments:
model
iter [100]
debug [False]
options:
-h, --help show this help message and exit
```
When you need more control `plac` offers three decorators to describe positional, option and flag type parameters:
```python
import plac
# Add decorators to the function
@plac.pos('model', help="model name", choices=['A', 'B', 'C'])
@plac.opt('iter', help="iterations", type=int)
@plac.flg('debug', help="debug mode")
def main(model, iter=100, debug=False):
"""
A script for machine learning
"""
print (model, iter, debug)
if __name__ == '__main__':
# Execute function via plac.call().
plac.call(main)
```
That will produce the following help:
```
usage: example.py [-h] [-i 100] [-d] {A,B,C}
A script for machine learning
positional arguments:
{A,B,C} model name
options:
-h, --help show this help message and exit
-i 100, --iter 100 iterations
-d, --debug debug mode
```
## Decorator reference
To use `plac` all you need to know are the following three decorators:
* `@plac.pos` - for positional parameters `model`
* `@plac.opt` - for key value options `--iter 100`
* `@plac.flg` - for flags `--debug`
that have the following signatures:
```python
# Positional parameters.
pos(arg, help=None, type=None, choices=None, metavar=None):
# Option parameters.
opt(arg, help=None, type=None, abbrev=None, choices=None, metavar=None):
# Flag parameters.
flg(arg, help=None, abbrev=None):
```
## Zero dependencies ... not even plac :-)
Notably, the main functionality of `plac` is implemented in a single
Python module called `plac_core.py` that, if necessary, may be included and
distributed with your source code thus reducing external dependencies in
your code.
Copy `plac_core.py` to your package then use it like so:
```python
from mypackage import plac_core as plac
```
## Avoiding name clashes
Python syntax, or your variable naming may impose constraints on what
words may be used as parameters. To circumvent that limitation append a
trailing underscore to the name. `plac` will strip that underscore from
the command line parameter name:
```python
import plac
@plac.flg('list_') # avoid clash with builtin
@plac.flg('yield_') # avoid clash with keyword
@plac.opt('sys_') # avoid clash with a very common name
def main(list_, yield_=False, sys_=100):
print(list_)
print(yield_)
print(sys_)
if __name__ == '__main__':
plac.call(main)
```
produces the usage:
```
usage: example13.py [-h] [-l] [-y] [-s 100]
optional arguments:
-h, --help show this help message and exit
-l, --list
-y, --yield [False]
-s 100, --sys 100 [100]
```
## Variable arguments
`plac` may accept multiple positional arguments and even additional key=value pairs:
```python
import plac
@plac.pos('args', help="words")
@plac.opt('kwds', help="key=value", )
def main(*args, **kwds):
print(args)
print(kwds)
if __name__ == '__main__':
plac.call(main)
```
the usage will be:
```
usage: example15.py [-h] [args ...] [kwds ...]
positional arguments:
args words
kwds key=value
optional arguments:
-h, --help show this help message and exit
```
when running it as:
python example15.py A B x=10 y=20
the program prints:
('A', 'B')
{'x': '10', 'y': '20'}
## Installation
pip install plac
## Testing
Run
python doc/test_plac.py
You will see several apparent errors, but this is right, since the tests
are checking for several error conditions. The important thing is that
you get a line like
`Executed XX tests OK`
## Code
-
Author: Michele Simionato,
Maintainer: Istvan Albert,
## Issues
-
## License
BSD License