| Name | helptext JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | |
| Summary | A documentation-generated argument parser. |
| upload_time | 2024-03-14 04:04:36 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3 |
| license | Copyright (C) 2024 by Rob Thralls <robert.thralls@pm.me> Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted. THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
| keywords |
argument
cli
command-line
docstring
getopt
help
helptext
interface
option
parser
text
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Help Text - a documentation-generated argument parser
### Stop wasting time on over-engineered nonsense.
> [PEP 257 – Docstring Conventions][1]
>
> The docstring of a script (a stand-alone program) should be usable as its
> “usage” message, [...] as well as a complete quick reference to all options
> and arguments for the sophisticated user.
### Which means your script can already do this:
```py
"""
Usage: hello [-ghv]
OPTIONS
-h, --help display this help text and exit
-v, --version display version information and exit
-g, --global print a familiar message
"""
__version__ = '1.2.3'
import sys
from helptext import parse
opts, _ = parse(sys.argv[1:], __doc__, __version__)
if opts['--global']['enabled']:
print('Hello, world!')
```
```console
$ hello -h
Usage: hello [-ghv]
OPTIONS
-h, --help display this help text and exit
-v, --version display version information and exit
-g, --global print a familiar message
$ hello --version
1.2.3
$ hello -g
Hello, world!
```
# Installation
```console
$ python3 -m pip install helptext
```
# API
Help Text provides a single `parse` function.
## parse
```py
from helptext import parse
opts, operands = parse(args, doc, version=None, posixly_correct=False)
```
### Arguments
- `args`: a list of command-line argument strings.
- `doc`: a docstring containing an _option list_.
- `version`: a version string.
- `posixly_correct`: a boolean to enable POSIX mode.
If `version` is not `None`, checks for `--help` and then `--version`. If
defined in `doc` and invoked in `args`, prints `doc` or `version` accordingly,
then raises `SystemExit(0)`.
If `posixly_correct` is `True`, support for GNU-style long options is disabled
and non-option operands terminate argument parsing.
### Return Values
- `opts`: a dictionary of option flags (e.g. `-h`, `--help`):
- `flags`: a list of flag aliases for this option.
- `argument`: a boolean for whether an argument is required or forbidden.
- `enabled`: an integer count of command-line invocations.
- `value`: an option-argument string, default is `None`.
- `operands`: a list of non-option operand strings.
# Docstring Format
```py
"""
-a --alpha this option takes no arguments
-b arg --beta this option requires an argument
-c, --gamma arg this option behaves the same
this line will be ignored
-d, --delta=arg attached notation works as well
"""
```
- Leading whitespace is ignored.
- Lines not beginning with a dash (`-`) are ignored.
- Flags and option-arguments are separated by whitespace or commas (`,`).
- All flags on a line are aliases to the same option.
- A single option-argument will also set the requirement for all aliases.
- Long option flags may attach option-arguments with an equals sign (`=`).
- Line parsing is terminated by two consecutive spaces (` `).
# Best Practices
Designing user interfaces is _hard_. Even simple text-based command-line
interfaces are difficult to execute cleanly. We do have some standards to
guide us (e.g. [POSIX][2], [GNU][3]), but we are contending with several
decades of legacy code and bad advice ([argparse][4]).
The features below are unsupported in favor of encouraging CLI best practices.
<table>
<thead>
<tr>
<th style="width:30%">Feature</th>
<th>Comment</th>
</tr>
</thead>
<tbody>
<tr>
<td><b>Required options</b></td>
<td>
A required option is an oxymoron. Set a reasonable default or use positional
arguments to accept input, otherwise subcommands can be used to change modes.
</td>
</tr>
<tr>
<td><b>Mutually-exclusive options</b></td>
<td>
Reduce command-line clutter by inverting your program logic. Use subcommands
or an option-argument to select a value from a list.
</td>
</tr>
<tr>
<td><b>Optional option-arguments</b></td>
<td>
Indicates an overloaded option. Can often be split into two options, one that
requires an option-argument and another that does not.
</td>
</tr>
<tr>
<td><b>Multiple option-arguments</b></td>
<td>
The standard approach is to use comma- or whitespace-separated values inside
a single (quoted or escaped) option-argument. Such values can even accept
arguments of their own by attaching them with an equals sign.
</td>
</tr>
</tbody>
</table>
[1]: https://peps.python.org/pep-0257
[2]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
[3]: https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html
[4]: https://docs.python.org/3/library/argparse.html
Raw data
{
"_id": null,
"home_page": "",
"name": "helptext",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": "Rob Thralls <robert.thralls@pm.me>",
"keywords": "argument,cli,command-line,docstring,getopt,help,helptext,interface,option,parser,text",
"author": "",
"author_email": "Rob Thralls <robert.thralls@pm.me>",
"download_url": "https://files.pythonhosted.org/packages/7c/b3/0e9d9f2b93b354516399b2ebc2f0578391a41871c09aacae6dbe5c3e900f/helptext-1.0.0.tar.gz",
"platform": null,
"description": "# Help Text - a documentation-generated argument parser\n\n### Stop wasting time on over-engineered nonsense.\n\n> [PEP 257 \u2013 Docstring Conventions][1]\n>\n> The docstring of a script (a stand-alone program) should be usable as its\n> \u201cusage\u201d message, [...] as well as a complete quick reference to all options\n> and arguments for the sophisticated user.\n\n### Which means your script can already do this:\n\n```py\n\"\"\"\nUsage: hello [-ghv]\n\nOPTIONS\n -h, --help display this help text and exit\n -v, --version display version information and exit\n -g, --global print a familiar message\n\"\"\"\n\n__version__ = '1.2.3'\n\nimport sys\nfrom helptext import parse\n\nopts, _ = parse(sys.argv[1:], __doc__, __version__)\nif opts['--global']['enabled']:\n print('Hello, world!')\n```\n\n```console\n$ hello -h\nUsage: hello [-ghv]\n\nOPTIONS\n -h, --help display this help text and exit\n -v, --version display version information and exit\n -g, --global print a familiar message\n$ hello --version\n1.2.3\n$ hello -g\nHello, world!\n```\n\n# Installation\n\n```console\n$ python3 -m pip install helptext\n```\n\n# API\n\nHelp Text provides a single `parse` function.\n\n## parse\n\n```py\nfrom helptext import parse\nopts, operands = parse(args, doc, version=None, posixly_correct=False)\n```\n\n### Arguments\n - `args`: a list of command-line argument strings.\n - `doc`: a docstring containing an _option list_.\n - `version`: a version string.\n - `posixly_correct`: a boolean to enable POSIX mode.\n\nIf `version` is not `None`, checks for `--help` and then `--version`. If\ndefined in `doc` and invoked in `args`, prints `doc` or `version` accordingly,\nthen raises `SystemExit(0)`.\n\nIf `posixly_correct` is `True`, support for GNU-style long options is disabled\nand non-option operands terminate argument parsing.\n\n### Return Values\n - `opts`: a dictionary of option flags (e.g. `-h`, `--help`):\n - `flags`: a list of flag aliases for this option.\n - `argument`: a boolean for whether an argument is required or forbidden.\n - `enabled`: an integer count of command-line invocations.\n - `value`: an option-argument string, default is `None`.\n - `operands`: a list of non-option operand strings.\n\n# Docstring Format\n\n```py\n\"\"\"\n -a --alpha this option takes no arguments\n -b arg --beta this option requires an argument\n -c, --gamma arg this option behaves the same\n this line will be ignored\n -d, --delta=arg attached notation works as well\n\"\"\"\n```\n\n- Leading whitespace is ignored.\n- Lines not beginning with a dash (`-`) are ignored.\n- Flags and option-arguments are separated by whitespace or commas (`,`).\n- All flags on a line are aliases to the same option.\n- A single option-argument will also set the requirement for all aliases.\n- Long option flags may attach option-arguments with an equals sign (`=`).\n- Line parsing is terminated by two consecutive spaces (` `).\n\n# Best Practices\n\nDesigning user interfaces is _hard_. Even simple text-based command-line\ninterfaces are difficult to execute cleanly. We do have some standards to\nguide us (e.g. [POSIX][2], [GNU][3]), but we are contending with several\ndecades of legacy code and bad advice ([argparse][4]).\n\nThe features below are unsupported in favor of encouraging CLI best practices.\n\n<table>\n <thead>\n <tr>\n <th style=\"width:30%\">Feature</th>\n <th>Comment</th>\n </tr>\n </thead>\n <tbody>\n <tr>\n <td><b>Required options</b></td>\n <td>\nA required option is an oxymoron. Set a reasonable default or use positional\narguments to accept input, otherwise subcommands can be used to change modes.\n </td>\n </tr>\n <tr>\n <td><b>Mutually-exclusive options</b></td>\n <td>\nReduce command-line clutter by inverting your program logic. Use subcommands\nor an option-argument to select a value from a list.\n </td>\n </tr>\n <tr>\n <td><b>Optional option-arguments</b></td>\n <td>\nIndicates an overloaded option. Can often be split into two options, one that\nrequires an option-argument and another that does not.\n </td>\n </tr>\n <tr>\n <td><b>Multiple option-arguments</b></td>\n <td>\nThe standard approach is to use comma- or whitespace-separated values inside\na single (quoted or escaped) option-argument. Such values can even accept\narguments of their own by attaching them with an equals sign.\n </td>\n </tr>\n </tbody>\n</table>\n\n[1]: https://peps.python.org/pep-0257\n[2]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html\n[3]: https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html\n[4]: https://docs.python.org/3/library/argparse.html\n\n",
"bugtrack_url": null,
"license": "Copyright (C) 2024 by Rob Thralls <robert.thralls@pm.me> Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted. THE SOFTWARE IS PROVIDED \"AS IS\" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. ",
"summary": "A documentation-generated argument parser.",
"version": "1.0.0",
"project_urls": {
"documentation": "https://gitlab.com/helptext/helptext",
"homepage": "https://gitlab.com/helptext/helptext",
"repository": "https://gitlab.com/helptext/helptext"
},
"split_keywords": [
"argument",
"cli",
"command-line",
"docstring",
"getopt",
"help",
"helptext",
"interface",
"option",
"parser",
"text"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "630c2832df14aa225d009cbb513ee0314596e5562ef45b731a0cf33b818e2722",
"md5": "6e74c009eec6d2edcad1ca4a7be80d0a",
"sha256": "5122a302da20deefb1392d32d2cbaf474138899bfa5dfa2e8de08497a3dd2b1d"
},
"downloads": -1,
"filename": "helptext-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6e74c009eec6d2edcad1ca4a7be80d0a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 5479,
"upload_time": "2024-03-14T04:04:34",
"upload_time_iso_8601": "2024-03-14T04:04:34.237256Z",
"url": "https://files.pythonhosted.org/packages/63/0c/2832df14aa225d009cbb513ee0314596e5562ef45b731a0cf33b818e2722/helptext-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7cb30e9d9f2b93b354516399b2ebc2f0578391a41871c09aacae6dbe5c3e900f",
"md5": "c21aa99db6eb1011c6a32f929eeeb8e8",
"sha256": "1311974f04af0dd9cc70b1bc27e07453a1454227d7cf3b59d939fcf664ece231"
},
"downloads": -1,
"filename": "helptext-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "c21aa99db6eb1011c6a32f929eeeb8e8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 5860,
"upload_time": "2024-03-14T04:04:36",
"upload_time_iso_8601": "2024-03-14T04:04:36.142729Z",
"url": "https://files.pythonhosted.org/packages/7c/b3/0e9d9f2b93b354516399b2ebc2f0578391a41871c09aacae6dbe5c3e900f/helptext-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-14 04:04:36",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "helptext",
"gitlab_project": "helptext",
"lcname": "helptext"
}
