helptext 1.0.0

A documentation-generated argument parser.

Help Text - a documentation-generated argument parser

Stop wasting time on over-engineered nonsense.

PEP 257 – Docstring Conventions

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:

"""
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!')

$ 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

$ python3 -m pip install helptext

API

Help Text provides a single parse function.

parse

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

"""
  -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, GNU), but we are contending with several decades of legacy code and bad advice (argparse).

The features below are unsupported in favor of encouraging CLI best practices.

Feature	Comment
Required options	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.
Mutually-exclusive options	Reduce command-line clutter by inverting your program logic. Use subcommands or an option-argument to select a value from a list.
Optional option-arguments	Indicates an overloaded option. Can often be split into two options, one that requires an option-argument and another that does not.
Multiple option-arguments	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.