Changelog¶
Newer releases¶
Release notes are now only on GitHub: https://github.com/janluke/cloup/releases.
v1.0.1 (2022-09-22)¶
Show a helpful error message when some tries to use command decorators without parenthesis. #128
v1.0.0 (2022-07-17)¶
Drop support for Python 3.6. Python 3.6 ha reached end-of-life in Dec 2021 and it’s not officially supported by Click 8. From https://pypistats.org/packages/cloup, I can see that about 37% of people are still using Python 3.6. If you can’t upgrade, you should still be able to use Cloup by installing the
dataclasses
backport package and using a compatible version of Click.Drop support for Click 7.
Run tests on Python 3.10.
v0.15.1 (2022-06-26)¶
Bug fixes¶
Fix type of
type
argument of@option
and@argument
. Specifically, tuple types weren’t correctly described.Reimplement
@argument
and@option
without calling the corresponding Click methods (#124):make decorators returned by
@argument
reusable by not relying on bugged Click implementationremove unnecessary copy of
**attrs
in@option
.
v0.15.0 (2022-06-16)¶
New features and enhancements¶
v0.14.0 (2022-05-09)¶
New features and enhancements¶
You can show a “Positional arguments” help section by passing a non-empty
help
description for at least one of the arguments of a command/group. #113cloup.Group
now extendscloup.Command
and, as a consequence, supports option groups and constraints. #113GroupedOption
is now an alias ofcloup.Option
.Add the new
params
Click argument to@command
and@group
signatures. This argument is supported only for click >= 8.1.0. See https://github.com/pallets/click/pull/2203.
Breaking changes¶
BaseCommand
was removed. This shouldn’t cause any issue to anybody.cloup.Group
extendscloup.Command
, similarly asclick.Group
extendsclick.Command
.OptionGroupMixin.format_options
was renamed toformat_params
. This means you can’t just mix it withclick.Command
to print help sections for option groups, you have to overrideformat_help
and callformat_params
.The new
format_params
doesn’t callsuper().format_commands
asformat_options
did: that’s what Click does and Cloup (reluctantly) did. Now, instead,cloup.Command
callsformat_params
informat_help
and then, for multi-commands, callsformat_commands
directly.ConstraintMixin.format_help
was removed. This means you can’t just mix it with a click.Command to make it print the “Constraints” help section, you need to callformat_constraints
explicitly in your commandformat_help
.
v0.13.1 (2022-05-08)¶
Since version 8.1.0, Click does not normalize the command attributes
help
,short_help
andepilog
while Cloup assumed them to be normalized as in previous releases. This lead to Cloup printing non-normalized help and epilog text when using click >= 8.1.0.
v0.13.0 (2022-02-14)¶
Add shortcuts for
click.Path
types which usespathlib.Path
aspath_type
by default: -cloup.path
-cloup.dir_path
(file_okay=False
) -cloup.file_path
(dir_okay=False
)
v0.12.1 (2021-10-14)¶
Fix: when
OptionGroupMixin
is mixed withGroup
, subcommands weren’t shown.
v0.12.0 (2021-09-17)¶
Feature: when a subcommand is mistyped, show “did you mean <subcommand>?”.
Doc fixes.
v0.11.0 (2021-08-05)¶
No major changes in this release, just refinements.
Attributes of parametric constraints are now public. #82
Slightly changed the
repr()
ofRequireExactly(3)
: fromRequireExactly(n=3)
toRequireExactly(3)
.Minor code refactoring.
Docs fixes and improvements.
v0.10.0 (2021-07-14)¶
New features and enhancements¶
Command decorators: improvements to type hints and other changes (#67):
mypy can now infer the exact type of the instantiated command based on the
cls
argument. — Unfortunately, this required the use of@overload
to work around a mypy limitationin
@group
, allowcls
to be anyclick.Group
— previously it had to be a subclass ofcloup.Group
in
Group.command
andGroup.group
add type hints and make all arguments exceptname
keyword-only. Technically this is a (minor) incompatibility with theclick.Group
superclass, but it’s coherent with Cloup’s@command
and@group
add Cloup-specific arguments to the signature of
@command
; if the developer uses one of such arguments with acls
that doesn’t support them, Cloup augments the resultingTypeError
with extra information.
Export Click types from Cloup namespace for convenience. #72
In dark and light themes, the epilog is now left unstyled by default. #62
Bug fixes¶
Breaking changes¶
In
Group.command
andGroup.group
all arguments exceptname
are now keyword-only.The
name
parameter/attribute ofOptionGroup
was renamed totitle
.In
SectionMixin
(thus, inGroup
), added actx: Context
attribute to make_commands_help_section and format_subcommand_name to support theshow_subcommand_aliases
setting.
v0.9.1 (2021-07-03)¶
Fixed bug: shell completion breaking because of Cloup checking constraints despite
ctx.resilient_parsing=True
Added public attributes to
ConstraintMixin
:optgroup_constraints
,param_constraints
andall_constraints
.Cleaned up code and added other type hints (to internal code).
Docs fixes and improvements. Fixed dark theme styling.
v0.9.0 (2021-06-30)¶
Fixed bugs¶
New features and enhancements¶
Add detailed type hints for
@argument
,@option
,@command
and@group
. This should greatly improve IDE code completion. #47, #50You can now use constraints as decorators (or
@constrained_params
) to constrain a group of “contiguous” parameters without repeating their names (see Constraints as decorators). This is a breaking change (see section below). #8Added the
require_any
andrequire_one
constraints (as aliases). #57Simplify and improve the
error
argument ofRephraser
(see Rephrasing constraints). #54The formatter setting
row_sep
can now take aRowSepPolicy
that decides whether and which row separator to use for each definition list independently, e.g. based on the number of definitions taking multiple lines (see: Row separators). #37Added method
format_subcommand_name(name, cmd)
toSectionMixin
to facilitate it combination with other Click extensions that overrideformat_commands()
. #59@option_group
andSection
now show a better error message when one forgets to provide the name/title as first argument.Fixed/improved some type hints and added others.
Breaking changes¶
Calling a constraint – previously a shortcut to the
check()
method – now returns a decorator. Use the methodConstraint.check()
to check a constraint inside a function. #8The semantics of
row_sep
changed. Now, it defaults toNone
and must not end with\n
, since the formatter writes a newline automatically after it. So,row_sep=""
now corresponds to an empty line between rows. #41In
@command
and@group
make all arguments butname
keyword-only. #46In
Context.settings
andHelpFormatter.settings
, use aMISSING
constant instead ofNone
as a flag for “empty” arguments. #40Constraint.toggle_consistency_checks
was replaced with aContext
setting calledcheck_constraints_consistency
. #33ConstraintViolated
requires more parameters now. #54
Docs¶
Restyling to improve readability: increased font size and vertical spacing, decreased line width. Restyled the table of contents on the right side. Ecc.
Reorganized and rewrote several parts.
v0.8.1-2 (2021-05-25)¶
(I had to release v0.8.2 just after v0.8.1 to fix a docs issue)
Work around a minor Click 8.0.1 issue with boolean options which caused some Cloup tests to fail.
Cosmetic: use a nicer logo and add a GitHub “header” including it.
Slightly improved readme, docs and examples.
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.
New features and enhancements¶
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 belowformatter.col2_min_width
)it adds several attributes to fine-tune and customize the generated help:
col1_max_width
,col_spacing
androw_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 defaultadds 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 methodHelpFormatter.settings
to create such a dictionaryallows 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 acontext_settings
dictionary (you get the help of your IDE).
Added a base class
BaseCommand
forCommand
andGroup
that:extends
click.Command
back-ports Click 8.0 class attribute
context_class
and set it tocloup.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 sethidden=True
, all contained options will have theirhidden
attribute set toTrue
automatically.Adds the conditions
AllSet
andAnySet
.The
and
of two or moreIsSet
conditions returns anAllSet
condition.The
or
of two or moreIsSet
conditions returns anAnySet
condition.
Changed the error messages of
all_or_none
andaccept_none
.The following Click decorators are now exported by Cloup:
argument
,confirmation_option
,help_option
,pass_context
,pass_obj
,password_option
andversion_option
.
Breaking changes¶
These incompatible changes don’t affect the most “external” API used by most clients of this library.
Formatting methods of
OptionGroupMixin
andSectionMixin
now expects theformatter
to be acloup.HelpFormatter
. If you used a customclick.HelpFormatter
, you’ll need to change your code if you want to use this release. If you usedclick-help-colors
, keep in mind that the new formatter has built-in styling capabilities so you don’t needclick-help-colors
anymore.OptionGroupMixin.format_option_group
was removed.SectionMixin.format_section
was removed.The class
MultiCommand
was removed, being useless.The
OptionGroupMixin
attributealign_option_groups
is nowNone
by default. Functionally, nothing changes: option groups are aligned by default.The
SectionMixin
attributealign_sections
is nowNone
by default. Functionally, nothing changes: subcommand sections are aligned by default.The
ConstraintMixin
attributeshow_constraints
is nowNone
by default. Functionally, nothing changes: constraints are not shown by default.
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 givingAttributeError
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)¶
New features and enhancements¶
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.
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 bysetuptools-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)¶
New features and enhancements¶
Slightly improved return type (hint) of command decorators.
Minor refactoring of ConstraintMixin.
Improved the documentation.
Breaking changes¶
Removed the deprecated
GroupSection
as previously announced. Use the new name instead:Section
.In
Group.group()
andGroup.command
, the argumentsection
was moved after thecls
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) passedsection
andcls
as keyword arguments in your code, you don’t need to change anything.
v0.5.0 (2021-02-10)¶
Requirements¶
Drop support to Python 3.5.
New features and enhancements¶
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
.
Deprecated¶
GroupSection
was renamed asSection
.
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.
New features and enhancements¶
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)¶
Breaking 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 toalign_sections
;GroupSection.__init__() sorted_
argument was renamed tosorted
.
Other changes¶
Additional signature for
option_group
: you can pass thehelp
argument as 2nd positional argument.Aligned option groups (option
align_option_groups
with defaultTrue
).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
andCloupGroup
resp. to justCommand
andGroup
.
v0.1.0 (2020-02-25)¶
First release on PyPI.