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.
Free software: MIT license
Option groups
The following code
import click
import cloup
from cloup import option_group, option
@cloup.command('clouptest')
@click.argument('arg')
@option_group('Option group A', [
option('--a1', help='1st option of group A'),
option('--a2', help='2nd option of group A'),
option('--a3', help='3rd option of group A')],
help='This is a useful description of group A',
)
@option_group('Option group B', [
option('--b1', help='1st option of group B'),
option('--b2', help='2nd option of group B'),
option('--b3', help='3rd option of group B'),
])
@option('--opt1', help='an uncategorized option')
@option('--opt2', help='another uncategorized option')
def cli(**kwargs):
""" A CLI that does nothing. """
print(kwargs)… will print:
Usage: clouptest [OPTIONS] [ARG] A CLI that does nothing. Option group A: This is a useful description of group A --a1 TEXT 1st option of group A --a2 TEXT 2nd option of group A --a3 TEXT 3rd option of group A Option group B: --b1 TEXT 1st option of group B --b2 TEXT 2nd option of group B --b3 TEXT 3rd option of group B Other options: --opt1 TEXT an uncategorized option --opt2 TEXT another uncategorized option --help Show this message and exit.
cloup.Group sections
See the full example code here.
# {Definitions of subcommands are omitted}
"""
If "align_sections_help=True" (default), the help column of all sections will
be aligned; otherwise, each section will be formatted independently.
"""
@cloup.group('git', align_sections_help=True)
def git():
return 0
"""
git.section() creates a new GroupSection object, adds it to git 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))With align_sections_help=True, 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
With align_sections_help=False, the help will be:
Usage: git_sections.py [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 existing one 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
In alternative to git.section(), you could also use:
@cloup.group('git', sections=[<list of GroupSection objects]))
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, ...)
Individual commands don’t know the section they belong to. As a consequence, 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.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.
1 maintainer
Metadata
1 maintainer
Release files for cloup 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| cloup-0.2.0.tar.gz | 15.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| cloup-0.2.0-py2.py3-none-any.whl | Python 3, Python 2 | none | any | Details |
Total release size: 23.3 kB
Release files / cloup-0.2.0.tar.gz
| Download URL | cloup-0.2.0.tar.gz |
|---|---|
| Size | 15.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7a3161a17dafa2e4e0fb31075cb0dc0851185f904eab341bd42a867ad1684300
|
|
BLAKE2b-256 checksum How to use checksums |
2d4557ebc256bd1b322a0e48f7b812627fc6ed9ea0ec2fd73a25087b77f0dbd5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/46.0.0 requests-toolbelt/0.9.1 tqdm/4.43.0 CPython/3.8.0
|
Release files / cloup-0.2.0-py2.py3-none-any.whl
| Download URL | cloup-0.2.0-py2.py3-none-any.whl |
|---|---|
| Size | 8.1 kB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
105d7cca354037ed891d035a087444e4323bab005d8f796203af144c918139f5
|
|
BLAKE2b-256 checksum How to use checksums |
979c6daad955e91f00ff9a66a35dca829a3850db6eddac573e0ba2135c6e70b1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/46.0.0 requests-toolbelt/0.9.1 tqdm/4.43.0 CPython/3.8.0
|
