# 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` automatically generates the command line parameters from the function signature.
It 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)
```
And that's it! The program can now take parameters from the command line like so:
python example.py -d -i 1000 B
Running the script with `python example.py -h` will give you the following help message: :
```
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
```
Running the script with no parameters `python example.py` would print:
```
usage: example.py [-h] [-i 100] [-d] {A,B,C}
example.py: error: the following arguments are required: model
```
## 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
- <https://github.com/ialbert/plac>
Author: Michele Simionato, <michele.simionato@gmail.com>
Maintainer: Istvan Albert, <istvan.albert@gmail.com>
## Issues
- <https://github.com/ialbert/plac/issues>
## License
BSD License
Raw data
{
"_id": null,
"home_page": "https://github.com/ialbert/plac",
"name": "plac",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "command line arguments parser",
"author": "Michele Simionato",
"author_email": "michele.simionato@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f2/15/9c8b756afb87cd99f9d10ecc7b022276abf3f1ac46554bf864614885a635/plac-1.4.2.tar.gz",
"platform": "All",
"description": "# Plac: parsing the command line the easy way\n\n`plac` is a Python package that can generate command line parameters\nfrom function signatures.\n\n`plac` works on Python 2.6 through all versions of Python 3.\n\n`plac` has no dependencies beyond modules already present in the Python\nstandard library.\n\n`plac` implements most of its functionality in a single file that may be\nincluded in your source code.\n\n## Quickstart\n\n`plac` automatically generates the command line parameters from the function signature. \n \nIt offers three decorators to describe positional, option and flag type parameters:\n\n```python\nimport plac\n\n# Add decorators to the function\n@plac.pos('model', help=\"model name\", choices=['A', 'B', 'C'])\n@plac.opt('iter', help=\"iterations\", type=int)\n@plac.flg('debug', help=\"debug mode\")\ndef main(model, iter=100, debug=False):\n \"\"\"\n A script for machine learning\n \"\"\"\n print (model, iter, debug)\n\nif __name__ == '__main__':\n # Execute function via plac.call()\n plac.call(main)\n```\n\nAnd that's it! The program can now take parameters from the command line like so:\n\n python example.py -d -i 1000 B \n\nRunning the script with `python example.py -h` will give you the following help message: :\n\n```\nusage: example.py [-h] [-i 100] [-d] {A,B,C}\n\nA script for machine learning\n\npositional arguments:\n {A,B,C} model name\n\noptions:\n -h, --help show this help message and exit\n -i 100, --iter 100 iterations\n -d, --debug debug mode\n```\n\nRunning the script with no parameters `python example.py` would print:\n\n```\nusage: example.py [-h] [-i 100] [-d] {A,B,C}\nexample.py: error: the following arguments are required: model\n```\n\n## Decorator reference\n\nTo use `plac` all you need to know are the following three decorators:\n\n* `@plac.pos` - for positional parameters `model`\n* `@plac.opt` - for key value options `--iter 100`\n* `@plac.flg` - for flags `--debug`\n\nthat have the following signatures:\n\n```python\n# Positional parameters.\npos(arg, help=None, type=None, choices=None, metavar=None):\n\n# Option parameters.\nopt(arg, help=None, type=None, abbrev=None, choices=None, metavar=None):\n\n# Flag parameters.\nflg(arg, help=None, abbrev=None):\n```\n\n## Zero dependencies ... not even plac :-)\n\nNotably, the main functionality of `plac` is implemented in a single\nPython module called `plac_core.py` that, if necessary, may be included and\ndistributed with your source code thus reducing external dependencies in\nyour code.\n\nCopy `plac_core.py` to your package then use it like so:\n\n```python\nfrom mypackage import plac_core as plac\n```\n\n## Avoiding name clashes\n\nPython syntax, or your variable naming may impose constraints on what\nwords may be used as parameters. To circumvent that limitation append a\ntrailing underscore to the name. `plac` will strip that underscore from\nthe command line parameter name:\n\n```python\nimport plac\n\n@plac.flg('list_') # avoid clash with builtin\n@plac.flg('yield_') # avoid clash with keyword\n@plac.opt('sys_') # avoid clash with a very common name\ndef main(list_, yield_=False, sys_=100):\n print(list_)\n print(yield_)\n print(sys_)\n\nif __name__ == '__main__':\n plac.call(main)\n```\n\nproduces the usage:\n\n```\nusage: example13.py [-h] [-l] [-y] [-s 100]\n\noptional arguments:\n -h, --help show this help message and exit\n -l, --list\n -y, --yield [False]\n -s 100, --sys 100 [100]\n```\n\n## Variable arguments\n\n`plac` may accept multiple positional arguments and even additional key=value pairs:\n\n```python\nimport plac\n\n@plac.pos('args', help=\"words\")\n@plac.opt('kwds', help=\"key=value\", )\ndef main(*args, **kwds):\n print(args)\n print(kwds)\n\nif __name__ == '__main__':\n plac.call(main)\n```\n\nthe usage will be:\n\n```\nusage: example15.py [-h] [args ...] [kwds ...]\n\npositional arguments:\n args words\n kwds key=value\n\noptional arguments:\n -h, --help show this help message and exit\n```\n\nwhen running it as:\n\n python example15.py A B x=10 y=20\n\nthe program prints:\n\n ('A', 'B')\n {'x': '10', 'y': '20'}\n\n## Installation\n\n pip install plac\n\n## Testing\n\nRun\n\n python doc/test_plac.py\n\nYou will see several apparent errors, but this is right, since the tests\nare checking for several error conditions. The important thing is that\nyou get a line like\n\n`Executed XX tests OK`\n\n## Code\n\n- <https://github.com/ialbert/plac>\n\nAuthor: Michele Simionato, <michele.simionato@gmail.com>\n\nMaintainer: Istvan Albert, <istvan.albert@gmail.com>\n\n## Issues\n\n- <https://github.com/ialbert/plac/issues>\n\n## License\n\nBSD License\n",
"bugtrack_url": null,
"license": "BSD License",
"summary": "The smartest command line arguments parser in the world",
"version": "1.4.2",
"project_urls": {
"Homepage": "https://github.com/ialbert/plac"
},
"split_keywords": [
"command",
"line",
"arguments",
"parser"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "180e49691b3dc10bbf9071e5812b16b2ab566452f41d700df8a3f795402729ba",
"md5": "de2eb22f5f0cf77c5f705790b45ea077",
"sha256": "675b93468a3761e1fb657c2b2c80bd59f1fb884bcfcd5d4a53bcee8baada66a6"
},
"downloads": -1,
"filename": "plac-1.4.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "de2eb22f5f0cf77c5f705790b45ea077",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 22365,
"upload_time": "2023-12-09T14:18:27",
"upload_time_iso_8601": "2023-12-09T14:18:27.192466Z",
"url": "https://files.pythonhosted.org/packages/18/0e/49691b3dc10bbf9071e5812b16b2ab566452f41d700df8a3f795402729ba/plac-1.4.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f2159c8b756afb87cd99f9d10ecc7b022276abf3f1ac46554bf864614885a635",
"md5": "8699dbf7f9fbce244cc4af6579b8f731",
"sha256": "b0d04d9bc4875625df45982bc900e9d9826861c221850dbfda096eab82fe3330"
},
"downloads": -1,
"filename": "plac-1.4.2.tar.gz",
"has_sig": false,
"md5_digest": "8699dbf7f9fbce244cc4af6579b8f731",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 37595,
"upload_time": "2023-12-09T14:18:29",
"upload_time_iso_8601": "2023-12-09T14:18:29.227254Z",
"url": "https://files.pythonhosted.org/packages/f2/15/9c8b756afb87cd99f9d10ecc7b022276abf3f1ac46554bf864614885a635/plac-1.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-09 14:18:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ialbert",
"github_project": "plac",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"lcname": "plac"
}
JSON
