.. |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://codecov.io/github/janLuke/cloup?branch=master
.. |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/
.. |donate| image:: https://img.shields.io/badge/Donate-PayPal-green.svg :alt: Donate with PayPal :target: https://www.paypal.com/donate/?hosted_button_id=4GTN24HXPMNBJ
|pypi-release| |python-versions| |downloads| |tests-status| |coverage| |dev-docs| |donate|
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
mutually_exclusive, that can be applied to option groups
or to any group of parameters, even conditionally
subcommands sections, i.e. the possibility to organize the subcommands of a
Group in multiple help sections
a themeable HelpFormatter that:
suggestions like "did you mean ?" when you mistype a subcommand.
Moreover, Cloup improves on IDE support providing decorators with detailed
type hints and adding the static methods
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.
.. 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. def cmd(**kwargs): """This is the command description.""" pass if __name__ == '__main__': cmd(prog_name='invoked-command')
.. image:: https://raw.githubusercontent.com/janLuke/cloup/master/docs/_static/basic-example.png :alt: Basic example --help screenshot
If you don't provide
.. 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).
Designing, testing and documenting a library takes a lot of time. The most concrete way to show your appreciation and to support future development is by donating. Any amount is appreciated.
Apart from that, you can help the project by starring it on GitHub, reporting issues, proposing improvements and contributing with your code!
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
* - |JetBrainsLogo| - A big thank to `JetBrains <https://www.jetbrains.com/>`_ for providing me with a free license for their IDEs. If you're developing a non-commercial open-source project, you may consider applying for a free license too. You find all details at `this link <https://jb.gg/OpenSourceSupport>`_. Note that this license can be used only to develop non-commercial projects.
.. |JetBrainsLogo| image:: https://resources.jetbrains.com/storage/products/company/brand/logos/jb_beam.png :alt: JetBrains logo :width: 250