.. 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
.. |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
========
Overview
========
|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
- **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:: https://raw.githubusercontent.com/janLuke/cloup/master/docs/_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).
Supporting the project
======================
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.
|donate|
Apart from that, you can help the project by starring it on GitHub, reporting
issues, proposing improvements and contributing with your code!
.. docs-index-end
Links
=====
* Documentation (release_ | development_)
* `Changelog <https://cloup.readthedocs.io/en/stable/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
Raw data
{
"_id": null,
"home_page": "https://github.com/janLuke/cloup",
"name": "cloup",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "CLI,click,argument groups,option groups,constraints,help colors,help themes,help styles",
"author": "Gianluca Gippetto",
"author_email": "gianluca.gippetto@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/cf/71/608e4546208e5a421ef00b484f582e58ce0f17da05459b915c8ba22dfb78/cloup-3.0.5.tar.gz",
"platform": null,
"description": ".. docs-index-start\n\n.. |pypi-release| image:: https://img.shields.io/pypi/v/cloup.svg\n :alt: Latest release on PyPI\n :target: https://pypi.org/project/cloup/\n\n.. |tests-status| image:: https://github.com/janLuke/cloup/workflows/Tests/badge.svg\n :alt: Tests status\n :target: https://github.com/janLuke/cloup/actions?query=workflow%3ATests\n\n.. |coverage| image:: https://codecov.io/github/janLuke/cloup/coverage.svg?branch=master\n :alt: Coverage Status\n :target: https://app.codecov.io/github/janluke/cloup/tree/master\n\n.. |python-versions| image:: https://img.shields.io/pypi/pyversions/cloup.svg\n :alt: Supported versions\n :target: https://pypi.org/project/cloup\n\n.. |dev-docs| image:: https://readthedocs.org/projects/cloup/badge/?version=latest\n :alt: Documentation Status (master branch)\n :target: https://cloup.readthedocs.io/en/latest/\n\n.. |release-docs| image:: https://readthedocs.org/projects/cloup/badge/?version=stable\n :alt: Documentation Status (latest release)\n :target: https://cloup.readthedocs.io/en/stable/\n\n.. |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\n :alt: PyPI - Downloads\n :target: https://pepy.tech/project/cloup\n\n.. |donate| image:: https://img.shields.io/badge/Donate-PayPal-green.svg\n :alt: Donate with PayPal\n :target: https://www.paypal.com/donate/?hosted_button_id=4GTN24HXPMNBJ\n\n========\nOverview\n========\n|pypi-release| |python-versions| |downloads| |tests-status| |coverage| |dev-docs| |donate|\n\n**Cloup** \u2014 originally from \"**Cl**\\ick + option gr\\ **oup**\\s\" \u2014 enriches\n`Click <https://github.com/pallets/click>`_ with several features that make it\nmore expressive and configurable:\n\n- **option groups** and an (optional) help section for positional arguments\n\n- **constraints**, like ``mutually_exclusive``, that can be applied to option groups\n or to any group of parameters, even *conditionally*\n\n- **subcommand aliases**\n\n- **subcommands sections**, i.e. the possibility of organizing the subcommands of a\n ``Group`` in multiple help sections\n\n- a **themeable HelpFormatter** that:\n\n - has more parameters for adjusting widths and spacing, which can be provided\n at the context and command level\n - use a different layout when the terminal width is below a certain threshold\n in order to improve readability\n\n- suggestions like \"did you mean <subcommand>?\" when you mistype a subcommand.\n\nMoreover, Cloup improves on **IDE support** providing decorators with *detailed*\ntype hints and adding the static methods ``Context.settings()`` and\n``HelpFormatter.settings()`` for creating dictionaries of settings.\n\nCloup is **statically type-checked** with MyPy in strict mode and extensively **tested**\nagainst multiple versions of Python with nearly 100% coverage.\n\n\nA simple example\n================\n\n.. code-block:: python\n\n from cloup import (\n HelpFormatter, HelpTheme, Style,\n command, option, option_group\n )\n from cloup.constraints import RequireAtLeast, mutually_exclusive\n\n # Check the docs for all available arguments of HelpFormatter and HelpTheme.\n formatter_settings = HelpFormatter.settings(\n theme=HelpTheme(\n invoked_command=Style(fg='bright_yellow'),\n heading=Style(fg='bright_white', bold=True),\n constraint=Style(fg='magenta'),\n col1=Style(fg='bright_yellow'),\n )\n )\n\n # In a multi-command app, you can pass formatter_settings as part\n # of your context_settings so that they are propagated to subcommands.\n @command(formatter_settings=formatter_settings)\n @option_group(\n \"Cool options\",\n option('--foo', help='This text should describe the option --foo.'),\n option('--bar', help='This text should describe the option --bar.'),\n constraint=mutually_exclusive,\n )\n @option_group(\n \"Other cool options\",\n \"This is the optional description of this option group.\",\n option('--pippo', help='This text should describe the option --pippo.'),\n option('--pluto', help='This text should describe the option --pluto.'),\n constraint=RequireAtLeast(1),\n )\n def cmd(**kwargs):\n \"\"\"This is the command description.\"\"\"\n pass\n\n if __name__ == '__main__':\n cmd(prog_name='invoked-command')\n\n\n.. image:: https://raw.githubusercontent.com/janLuke/cloup/master/docs/_static/basic-example.png\n :alt: Basic example --help screenshot\n\nIf you don't provide ``--pippo`` or ``--pluto``:\n\n.. code-block:: text\n\n Usage: invoked-command [OPTIONS]\n Try 'invoked-command --help' for help.\n\n Error: at least 1 of the following parameters must be set:\n --pippo\n --pluto\n\nThis simple example just scratches the surface. Read more in the documentation\n(links below).\n\n\nSupporting the project\n======================\nDesigning, testing and documenting a library takes a lot of time. The most\nconcrete way to show your appreciation and to support future development is by\ndonating. Any amount is appreciated.\n\n|donate|\n\nApart from that, you can help the project by starring it on GitHub, reporting\nissues, proposing improvements and contributing with your code!\n\n.. docs-index-end\n\n\nLinks\n=====\n\n* Documentation (release_ | development_)\n* `Changelog <https://cloup.readthedocs.io/en/stable/pages/changelog.html>`_\n* `GitHub repository <https://github.com/janLuke/cloup>`_\n* `Q&A and discussions <https://github.com/janLuke/cloup/discussions>`_\n\n.. _release: https://cloup.readthedocs.io/en/stable/#user-guide\n.. _development: https://cloup.readthedocs.io/en/latest/#user-guide\n",
"bugtrack_url": null,
"license": "BSD 3-Clause",
"summary": "Adds features to Click: option groups, constraints, subcommand sections and help themes.",
"version": "3.0.5",
"project_urls": {
"Homepage": "https://github.com/janLuke/cloup"
},
"split_keywords": [
"cli",
"click",
"argument groups",
"option groups",
"constraints",
"help colors",
"help themes",
"help styles"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "961a5a2a4fbf6c95f11b079f02d7b191377ea4509f5e442887e4c7c026bc56d3",
"md5": "ffde8a4dd7c87dcd81566207777a8cb9",
"sha256": "bf122036066584eb0db113561167c29969cc015972b7b7ee03158d9bc7de87f8"
},
"downloads": -1,
"filename": "cloup-3.0.5-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "ffde8a4dd7c87dcd81566207777a8cb9",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.7",
"size": 54431,
"upload_time": "2024-03-04T12:36:55",
"upload_time_iso_8601": "2024-03-04T12:36:55.818158Z",
"url": "https://files.pythonhosted.org/packages/96/1a/5a2a4fbf6c95f11b079f02d7b191377ea4509f5e442887e4c7c026bc56d3/cloup-3.0.5-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cf71608e4546208e5a421ef00b484f582e58ce0f17da05459b915c8ba22dfb78",
"md5": "2cfc84a2aa28a4a2c71c912b511870bb",
"sha256": "c92b261c7bb7e13004930f3fb4b3edad8de2d1f12994dcddbe05bc21990443c5"
},
"downloads": -1,
"filename": "cloup-3.0.5.tar.gz",
"has_sig": false,
"md5_digest": "2cfc84a2aa28a4a2c71c912b511870bb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 225806,
"upload_time": "2024-03-04T12:36:57",
"upload_time_iso_8601": "2024-03-04T12:36:57.314087Z",
"url": "https://files.pythonhosted.org/packages/cf/71/608e4546208e5a421ef00b484f582e58ce0f17da05459b915c8ba22dfb78/cloup-3.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-04 12:36:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "janLuke",
"github_project": "cloup",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "cloup"
}
JSON
