Option groups and subcommand help sections for pallets/click
Project description
cloup
cloup (click + group) extends pallets/click to add option groups and the possibility of organizing the subcommands of a Group in multiple help sections.
Currently, this package only affects how the command help is formatted, it doesn’t allow to specify constraints on option groups. Look at click-option-group if you want that. Nonetheless, constraints would be a very easy addition and may be added soon.
Installation
To install the last release:
pip install cloup
Versioning
cloup uses semantic versioning. I’ll release v1.0 when I’m satisfied with API and features but cloup is already usable, just make sure you specify a compatible version number in your list of requirements if you decide to use it, e.g.:
cloup==0.3.*
Patch releases are guaranteed to be backwards compatible (even before v1.0).
Option groups
You can define option groups in two ways or “styles”: I’ll call them “nested style” and “flat style”. The full code for the examples shown below can also be found in examples/option_groups_example.py.
Nested style (recommended)
In “nested style” you make use of the decorator option_group. This decorator is “overloaded” with two signatures:
@option_group(name, *options, help=None) # help as keyword argument
@option_group(name, help, *options) # help as 2nd positional argument
I introduced the 2nd signature because I think it looks and feels nicer when you have to provide a long help that takes multiple lines; also, it reflects how to help is actually formatted.
Here’s an example:
import cloup
from cloup import option_group, option
@cloup.command('clouptest')
@option_group('Input options',
"This is a very long description of the option group. I don't think this is "
"needed very often; still, if you want to provide it, you can pass it as 2nd "
"positional argument or as keyword argument 'help' after all options.",
option('-o', '--one', help='1st input option'),
option('--two', help='2nd input option'),
option('--three', help='3rd input option')
)
@option_group('Output options',
option('--four / --no-four', help='1st output option'),
option('--five', help='2nd output option'),
option('--six', help='3rd output option'),
# help='You can also pass the help as keyword argument after the options.'
)
@option('--seven', help='first uncategorized option', type=click.Choice('yes no ask'.split()))
@option('--height', help='second uncategorized option')
def cli(**kwargs):
""" A CLI that does nothing. """
print(kwargs)
The help will be:
Usage: clouptest [OPTIONS] A CLI that does nothing. Input options: This is a very long description of the option group. I don't think this is needed very often; still, if you want to provide it, you can pass it as 2nd positional argument or as keyword argument 'help' after all options. -o, --one TEXT 1st input option --two TEXT 2nd input option --three TEXT 3rd input option Output options: --four / --no-four 1st output option --five TEXT 2nd output option --six TEXT 3rd output option Other options: --seven [yes|no|ask] first uncategorized option --height TEXT second uncategorized option --help Show this message and exit.
As you can see, the columns of all option groups are aligned. If you want to format each option group independently, you can pass align_option_groups=False to @command().
Flat style
In “flat style”, you first define your option groups and then call the option() method on them. Don’t reuse OptionGroup objects in multiple commands.
input_grp = OptionGroup('Input options', help='This is a very useful description of the group')
output_grp = OptionGroup('Output options')
@cloup.command('clouptest', align_option_groups=True)
@input_grp.option('-o', '--one', help='1st input option')
@input_grp.option('--two', help='2nd input option')
@input_grp.option('--three', help='3rd input option')
@output_grp.option('--four / --no-four', help='1st output option')
@output_grp.option('--five', help='2nd output option')
@output_grp.option('--six', help='3rd output option')
@option('--seven', help='first uncategorized option', type=click.Choice('yes no ask'.split()))
@option('--height', help='second uncategorized option')
def cli_flat(**kwargs):
""" A CLI that does nothing. """
print(kwargs)
Subcommand sections
See the full example code here.
# {Definitions of subcommands are omitted}
@cloup.group('git')
def git():
return 0
"""
group.section() creates a new GroupSection object, adds it to "group" and returns it.
In the help, sections are shown in the same order they are added.
Commands in each sections are shown in the same order they are listed, unless
you pass the argument "sorted=True".
"""
git.section('Start a working area (see also: git help tutorial)',
git_clone,
git_init
)
git.section('Work on the current change (see also: git help everyday)',
git_rm,
git_sparse_checkout,
git_mv
)
# The following commands will be added to the "default section" (a sorted GroupSection)
git.add_command(cloup.command('fake-2', help='Fake command #2')(f))
git.add_command(cloup.command('fake-1', help='Fake command #1')(f))
The help will be:
Usage: git [OPTIONS] COMMAND [ARGS]... Options: --help Show this message and exit. Start a working area (see also: git help tutorial): clone Clone a repository into a new directory init Create an empty Git repository or reinitialize an... Work on the current change (see also: git help everyday): rm Remove files from the working tree and from the index sparse-checkout Initialize and modify the sparse-checkout mv Move or rename a file, a directory, or a symlink Other commands: fake-1 Fake command #1 fake-2 Fake command #2
Though I think using _.section() is the cleanest way to define sections, there are alternatives.
One is to pass a list of GroupSection objects to @cloup.group():
SECTIONS = [
GroupSection('Start a working area (see also: git help tutorial)',
git_clone, git_init),
GroupSection('Work on the current change (see also: git help everyday)',
git_rm, git_sparse_checkout, git_mv)
]
@cloup.group('git', sections=SECTIONS)
def git():
return 0
Others are:
git.add_section(section) to add an existing GroupSection object
git.add_command(cmd, name, section, ...); the section must NOT contain the command
@git.command(cmd, name, section, ...), specifying section.
Note: individual commands don’t know the section they belong to. Neither cloup.Command nor @cloup.command() accept a “section” argument.
Credits
For implementing option groups, I started from the idea of @chrisjsewell presented in this comment.
This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.
History
0.3.0 (2020-03-26)
Backward incompatible API changes
option_groups decorator now takes options as positional arguments *options;
Group.section decorator now takes sections as positional arguments *sections;
align_sections_help was renamed to align_sections;
GroupSection.__init__() sorted_ argument was renamed to sorted.
Additional signature for option_group: you can pass the help argument as 2nd positional argument.
Aligned option groups (option align_option_groups with default True).
More refactoring and testing.
0.2.0 (2020-03-11)
Rename CloupCommand and CloupGroup resp. to just Command and Group
[Feature] Add possibility of organizing subcommands of a cloup.Group in multiple help sections
Various code improvements
0.1.0 (2020-02-25)
First release on PyPI.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for cloup-0.3.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b6e276566362baa9ce792b68745f82a623787a2354472402fc40652f4ea9279c |
|
MD5 | cfa3da582ab86b42047e125a2434350c |
|
BLAKE2b-256 | f4ce828db4c74210d7fc2b4c1be285df30c28d499bbb33e63207977824d3a39f |