Metadata-Version: 2.1
Name: cloup
Version: 0.8.0
Summary: Option groups and subcommand help sections for pallets/click
Home-page: https://github.com/janLuke/cloup
Author: Gianluca Gippetto
Author-email: gianluca.gippetto@gmail.com
License: BSD 3-Clause
Keywords: cloup click option
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
Requires-Dist: click (<9.0,>=7.1)
Requires-Dist: dataclasses ; python_version <= "3.6"

.. |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://codecov.io/github/janLuke/cloup?branch=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/

.. |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
========

====================  ==========================================================
**Development**       |tests-status| |coverage| |dev-docs| |donate|
--------------------  ----------------------------------------------------------
**Latest release**    |pypi-release| |python-versions| |release-docs|
====================  ==========================================================

**Cloup** [originally from: **Cl**\ick + option gr\ **oup**\s] is a library that
extends `Click <https://github.com/pallets/click>`_ with several features
-- most notably, option groups -- sharing the common goal of improving the
readability and customizability of the command ``--help``.

Features
========

- **Option groups:** use the ``@option_group`` decorator to define option groups..

- **Group constraints:** apply constraints (even *conditionally*) to option groups
  or to any group of parameters (including positional arguments).
  Available constraints include: ``mutually_exclusive``, ``RequireAtLeast(n)``,
  ``AcceptAtMost(n)`` etc.

- **Help sections for subcommands:** organize the subcommands of a ``Group`` in
  multiple help sections.

- **A themeable HelpFormatter** that:

  - allows you to style several elements of the ``--help`` according to a theme
  - has more parameters that you can change per-context and per-command
  - switches to a different layout when the terminal width is small for the
    standard 2-column layout, so that the ``--help`` is readable in all circumstances.


Moreover, Cloup is:

- **type-annotated** and provides additional methods so that you can always be
  assisted by your IDE (e.g. ``Context.settings()`` for creating a
  ``context_settings`` dict leveraging auto-completion)
- **extensively tested** with multiple versions of Python and Click (see
  `Tests <https://github.com/janLuke/cloup/actions>`_)
- **well-documented**.

Basic example
=============

.. code-block:: python

    from cloup import Context, HelpFormatter, HelpTheme, command, option, option_group
    from cloup.constraints import RequireAtLeast, mutually_exclusive

    SETTINGS = Context.settings(
        formatter_settings=HelpFormatter.settings(
            theme=HelpTheme.dark()
        )
    )

    @command(context_settings=SETTINGS, no_args_is_help=True)
    @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://www.dropbox.com/s/ev9lljp2v3ndonu/basic-example.png?raw=1
    :alt: Basic example --help screenshot


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-home-end


Documentation
=============

* `Latest stable release <https://cloup.readthedocs.io/en/stable/>`_
* `Development version <https://cloup.readthedocs.io/en/latest/>`_


=========
Changelog
=========

..  v0.X.X (in development)
    =======================
    Incompatible changes
    --------------------
    Deprecated
    ----------
    Compatible changes
    ------------------


v0.8.0 (2021-05-19)
===================

Project changes
---------------

- Cloup license changed from MIT to 3-clause BSD, the one used by Click.
- Added a donation button.

Incompatible changes
--------------------

These incompatible changes don't affect the most "external" API used by most
clients of this library.

- Formatting methods of ``OptionGroupMixin`` and ``SectionMixin`` now expects
  the ``formatter`` to be a ``cloup.HelpFormatter``.
  If you used a custom ``click.HelpFormatter``, you'll need to change your code
  if you want to use this release. If you used ``click-help-colors``, keep in
  mind that the new formatter has built-in styling capabilities so you don't
  need ``click-help-colors`` anymore.

- ``OptionGroupMixin.format_option_group`` was removed.

- ``SectionMixin.format_section`` was removed.

- The class ``MultiCommand`` was removed, being useless.

- The ``OptionGroupMixin`` attribute ``align_option_groups`` is now ``None`` by default.
  Functionally, nothing changes: option groups are aligned by default.

- The ``SectionMixin`` attribute ``align_sections`` is now ``None`` by default.
  Functionally, nothing changes: subcommand sections are aligned by default.

- The ``ConstraintMixin`` attribute ``show_constraints`` is now ``None`` by default.
  Functionally, nothing changes: constraints are **not** shown by default.


Compatible changes
------------------

- Cloup now uses its own ``HelpFormatter``:

  * it supports alignment of multiple definition lists, so Cloup doesn't have to
    rely on a hack (padding) to align option groups and alike

  * it adds theming of the help page, i.e. styling of several elements of the
    help page

  * it has an additional way to format definition lists (implemented with the
    method ``write_linear_dl``) that kicks in when the available width for the
    standard 2-column format is not enough (precisely, when the width available
    for the 2nd column is below ``formatter.col2_min_width``)

  * it adds several attributes to fine-tune and customize the generated help:
    ``col1_max_width``, ``col_spacing`` and ``row_sep``

  * it fixes a couple of Click minor bugs and decides the column width of
    definition lists in a slightly smarter way that makes a better use of the
    available space.

- Added a custom ``Context`` that:

  * uses ``cloup.HelpFormatter`` as formatter class by default
  * adds a ``formatter_settings`` attributes that allows to set the default
    formatter keyword arguments (the same argument can be given to a command to
    override these defaults). You can use the static method
    ``HelpFormatter.settings`` to create such a dictionary
  * allows to set the default value for the following ``Command``/``Group`` args:

    * ``align_option_groups``,
    * ``align_sections``
    * ``show_constraints``

  * has a ``Context.setting`` static method that facilitates the creation of a
    ``context_settings`` dictionary (you get the help of your IDE).

- Added a base class ``BaseCommand`` for ``Command`` and ``Group`` that:

  - extends ``click.Command``
  - back-ports Click 8.0 class attribute ``context_class`` and set it to ``cloup.Context``
  - adds the ``formatter_settings`` argument

- Hidden option groups. An option group is hidden either if you pass
  ``hidden=True`` when you define it or if all its contained options are hidden.
  If you set ``hidden=True``, all contained options will have their ``hidden``
  attribute set to ``True`` automatically.

- Adds the conditions ``AllSet`` and ``AnySet``.

  * The ``and`` of two or more ``IsSet`` conditions returns an ``AllSet`` condition.
  * The ``or`` of two or more ``IsSet`` conditions returns an ``AnySet`` condition.

- Changed the error messages of ``all_or_none`` and ``accept_none``.

- The following Click decorators are now exported by Cloup: ``argument``,
  ``confirmation_option``, ``help_option``, ``pass_context``, ``pass_obj``,
  ``password_option`` and ``version_option``.

Docs
----
- Switch theme to ``furo``.
- Added section "Help formatting and theming".
- Improved all sections.

--------------------------------------------------------------------------------

v0.7.1 (2021-05-02)
===================
- Fixed a bug with ``&`` and ``|`` ``Predicate`` operators giving ``AttributeError``
  when used.
- Fixed the error message of ``accept_none`` which didn't include ``{param_list}``.
- Improved ``all_or_none`` error message.
- Minor docs fixes.


v0.7.0 (2021-03-24)
===================
Compatible changes
------------------

- In constraint errors, the way the parameter list is formatted has changed.
  Instead of printing a comma-separated list of single labels:

  * each parameter is printed on a 2-space indented line and
  * both the short and long name of options are printed.

  See the relevant `commit <https://github.com/janLuke/cloup/commit/0280323e481bcca2b941a49c9133b06685e4bbe1>`_.

- Minor improvements to code and docs.

--------------------------------------------------------------------------------

v0.6.1 (2021-03-01)
===================
This patch release fixes some problems in the management and releasing of
the package.

- Add a ``py.typed`` file to ship the package with type hints (PEP 561).
- Use ``setuptools-scm`` to automatically manage the version of the package
  *and* the content of the source distribution based on the git repository:

  * the source distribution now matches the git repository, with the only
    exception of ``_version.py``, which is not tracked by git; it's generated by
    ``setuptools-scm`` and included in the package;

  * tox.ini and Makefile were updated to account for the fact that ``_version.py``
    doesn't exist in the repository before installing the package.

- The new attribute ``cloup.__version_tuple__`` stores the version as a tuple
  (of *at least* 3 elements).


v0.6.0 (2021-02-28)
===================
Incompatible changes
--------------------

- Removed the deprecated ``GroupSection`` as previously announced.
  Use the new name instead: ``Section``.
- In ``Group.group()`` and ``Group.command``, the argument ``section`` was moved
  after the ``cls`` argument so that the signatures are now fully compatible with
  those of the parent class (the Liskov substitution principle is now satisfied).
  If you (wisely) passed ``section`` and ``cls`` as keyword arguments in your
  code, you don't need to change anything.

Compatible changes
------------------

- Slightly improved return type (hint) of command decorators.
- Minor refactoring of ConstraintMixin.
- Improved the documentation.

--------------------------------------------------------------------------------

v0.5.0 (2021-02-10)
===================
Requirements
------------

- Drop support to Python 3.5.

Deprecated
----------

- ``GroupSection`` was renamed as ``Section``.

Compatible changes
------------------

- Added a subpackage for defining **constraints** on parameters groups
  (including ``OptionGroup``'s).
- The code for adding support to option groups was extracted to ``OptionGroupMixin``.
- Most of the code for adding support to subcommand sections was extracted to
  ``SectionMixin``.

Project changes
---------------

- Migrated from TravisCI to GitHub Actions.

--------------------------------------------------------------------------------

v0.4.0 (2021-01-10)
===================

Requirements
------------

- This is the last release officially supporting Python 3.5.

Compatible changes
------------------

- Changed the internal (non-public) structure of the package.
- Minor code improvements.

Project changes
---------------

- New documentation (hosted by ReadTheDocs)
- Tox, TravisCI, Makefile completely rewritten.

--------------------------------------------------------------------------------

v0.3.0 (2020-03-26)
===================
Incompatible 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``.

Other changes
-------------
- 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.

--------------------------------------------------------------------------------

v0.2.0 (2020-03-11)
===================
- [Feature] Add possibility of organizing subcommands of a cloup.Group in
  multiple help sections.
- Various code improvements.
- Backward incompatible change:
    - rename ``CloupCommand`` and ``CloupGroup`` resp. to just ``Command`` and ``Group``.

--------------------------------------------------------------------------------

v0.1.0 (2020-02-25)
===================
- First release on PyPI.


