1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
.. raw:: html
<p align="center">
<img
src="_static/logo-on-white.svg"
width="50%" />
</p>
<p align="center">
<i>
<a href="https://github.com/pallets/click">Click</a>
+ option groups + constraints + aliases + help themes + ...
</i>
</p>
<p align="center">
<a href="https://cloup.readthedocs.io/">https://cloup.readthedocs.io/</a>
</a>
----------
.. docs-index-start
.. |pypi-release| image:: https://img.shields.io/pypi/v/cloup.svg
:alt: Latest release on PyPI
:target: https://pypi.org/project/cloup/
.. |tests-status| image:: https://github.com/janLuke/cloup/workflows/Tests/badge.svg
:alt: Tests status
:target: https://github.com/janLuke/cloup/actions?query=workflow%3ATests
.. |coverage| image:: https://codecov.io/github/janLuke/cloup/coverage.svg?branch=master
:alt: Coverage Status
:target: https://app.codecov.io/github/janluke/cloup/tree/master
.. |python-versions| image:: https://img.shields.io/pypi/pyversions/cloup.svg
:alt: Supported versions
:target: https://pypi.org/project/cloup
.. |dev-docs| image:: https://readthedocs.org/projects/cloup/badge/?version=latest
:alt: Documentation Status (master branch)
:target: https://cloup.readthedocs.io/en/latest/
.. |release-docs| image:: https://readthedocs.org/projects/cloup/badge/?version=stable
:alt: Documentation Status (latest release)
:target: https://cloup.readthedocs.io/en/stable/
.. |downloads| image:: https://static.pepy.tech/personalized-badge/cloup?period=week&units=international_system&left_color=grey&right_color=blue&left_text=downloads%20/%20week
:alt: PyPI - Downloads
:target: https://pepy.tech/project/cloup
========
Overview
========
**Cloup** — originally from "**Cl**\ick + option gr\ **oup**\s" — enriches
`Click <https://github.com/pallets/click>`_ with several features that make it
more expressive and configurable:
- **option groups** and an (optional) help section for positional arguments
- **constraints**, like ``mutually_exclusive``, that can be applied to option groups
or to any group of parameters, even *conditionally*
- **subcommand aliases**
- **subcommands sections**, i.e. the possibility of organizing the subcommands of a
``Group`` in multiple help sections
- a **themeable HelpFormatter** that:
- has more parameters for adjusting widths and spacing, which can be provided
at the context and command level
- use a different layout when the terminal width is below a certain threshold
in order to improve readability
- suggestions like "did you mean <subcommand>?" when you mistype a subcommand.
Moreover, Cloup improves on **IDE support** providing decorators with *detailed*
type hints and adding the static methods ``Context.settings()`` and
``HelpFormatter.settings()`` for creating dictionaries of settings.
Cloup is **statically type-checked** with MyPy in strict mode and extensively **tested**
against multiple versions of Python with nearly 100% coverage.
A simple example
================
.. code-block:: python
from cloup import (
HelpFormatter, HelpTheme, Style,
command, option, option_group
)
from cloup.constraints import RequireAtLeast, mutually_exclusive
# Check the docs for all available arguments of HelpFormatter and HelpTheme.
formatter_settings = HelpFormatter.settings(
theme=HelpTheme(
invoked_command=Style(fg='bright_yellow'),
heading=Style(fg='bright_white', bold=True),
constraint=Style(fg='magenta'),
col1=Style(fg='bright_yellow'),
)
)
# In a multi-command app, you can pass formatter_settings as part
# of your context_settings so that they are propagated to subcommands.
@command(formatter_settings=formatter_settings)
@option_group(
"Cool options",
option('--foo', help='This text should describe the option --foo.'),
option('--bar', help='This text should describe the option --bar.'),
constraint=mutually_exclusive,
)
@option_group(
"Other cool options",
"This is the optional description of this option group.",
option('--pippo', help='This text should describe the option --pippo.'),
option('--pluto', help='This text should describe the option --pluto.'),
constraint=RequireAtLeast(1),
)
def cmd(**kwargs):
"""This is the command description."""
pass
if __name__ == '__main__':
cmd(prog_name='invoked-command')
.. image:: _static/basic-example.png
:alt: Basic example --help screenshot
If you don't provide ``--pippo`` or ``--pluto``:
.. code-block:: text
Usage: invoked-command [OPTIONS]
Try 'invoked-command --help' for help.
Error: at least 1 of the following parameters must be set:
--pippo
--pluto
This simple example just scratches the surface. Read more in the documentation
(links below).
.. docs-index-end
Links
=====
* Online Documentation (release_ | development_)
* `Changelog <pages/changelog.html>`_
* `GitHub repository <https://github.com/janLuke/cloup>`_
* `Q&A and discussions <https://github.com/janLuke/cloup/discussions>`_
.. _release: https://cloup.readthedocs.io/en/stable/#user-guide
.. _development: https://cloup.readthedocs.io/en/latest/#user-guide
|
