Release notes¶
5.0.1 (2023-07-06)¶
Fixed
run(..., alt={...})
not working correctly with dicts
5.0.0 (2022-10-13)¶
Breaking changes:
bytes
annotation (converter) now re-encodes the corresponding parameter back to bytes
Deprecations:
The
convert_default
argument tovalue_converter
is now deprecated.Parameter.cli_default
is the recommended replacement. To help transition, a newconvert_default_filter
option has been added tovalue_converter
, which allows converter authors to filter which values are selected for default conversion, thereby not incurring a deprecation warning for the user.
Updated compatibility:
Dropped support for Python 2.7, Python 3.5.
Verified support for Python 3.10+
Compatibility with Docutils 0.21+
Improved path support for Windows
Improvements:
Automatically group identical subcommands as aliases
Evaluate deferred annotations from PEP 563
Basic support for
typing.Annotated
Parameter.cli_default
allows script writers to specify a default value that will be converted like an argument passed in from the CLI, but not supplied when the function is called from Python.
Process updates:
Updated Continuous Integration and Delivery to speed up releases and move off of deprecated CI platform.
4.2.1 (2021-11-13)¶
Fixed build dependencies for documentation generation
4.2.0 (2021-06-29)¶
Dropped support for Python 3.4.
Upgrade to attrs 21
4.1.2 (2021-11-13)¶
Fixed build dependencies for documentation generation
4.1.1 (2019-10-17)¶
Fix project description not appearing on PyPI.
4.1.0 (2019-10-17)¶
Dropped support for Python 3.3.
Allow custom capitalization for named parameter aliases.
pathlib.Path
is now automatically discovered as a value converter.Fixed crash when using a Clize program across Windows drives.
4.0.4 (2021-11-13)¶
Fixed build dependencies for documentation generation
4.0.3 (2018-02-01)¶
Requires attrs >17.4.0 to fix a crash in the parser.
4.0.2 (2017-11-18)¶
Fixed converted default arguments always overriding provided arguments.
4.0.1 (2017-04-2017)¶
Fixed code blocks not displaying correctly in Sphinx docstrings.
4.0 (2017-04-19)¶
Clize now parses Sphinx-style docstrings. It becomes the recommended way of documenting functions, as it is interoperable and not specific to Clize.
Value converters can now convert the default value for their parameter. Specify
convert_default=True
when decorating withvalue_converter
.-
you can use it without parenthesis now:
def func(infile:converters.file):
it now converts the default parameter:
infile:converters.file='-'
gives a file opener for stdin if no value was provided by the user
parameters.mapped
: Raises an error when two identical values are given.Improved error messages for incorrect annotations.
Parameter converters must have a name. You can now specify one using the
name=
keyword argument toparameter_converter
.Clize now shows a hint if a subcommand is misspelled.
Dropped Python 2.6 support. Use Clize 3.1 if you need to support it.
Fix wrong docstring being used for header/footer text when the intended function had no (visible) parameters.
Extension API changes:
parser.CliBoundArguments
now uses theattrs
package. Instead of parsing arguments on instantiation, it has a process_arguments method for this. This is a breaking change if you were instantiating it directly rather than useparser.CliSignature.read_arguments
Separate the value setting logic in
ParameterWithValue
to aset_value
method. Most parameter types don’t need to overrideread_argument
anymore.Separated the help CLI from documentation generation and display. Also comes with more
attrs
. This API is now documented.
3.1 (2016-10-03)¶
Support for sigtools’ automatic signature discovery. This is reflected in the function composition tutorial: In most cases you no longer have to specify how your decorators use
*args
and**kwargs
exactlySuggestions are provided when named parameters are misspelled. (Contributed by Karan Parikh.)
You can supply ‘alternative actions’ (i.e. –version) even when using multiple commands.
Improve hackability of argument parsing: named parameters are now sourced from the bound arguments instance, so a parameter could modify it duing parsing without changing the original signature.
Various documentation improvements.
3.0 (2015-05-13)¶
Version 3.0 packs a full rewrite. While it retains backwards-compatibility, the old interface is deprecated. See Upgrading from clize 1 and 2.
The argument parsing logic has been split between a loop over the parameters and parameter classes. New parameter classes can be made to implement cusom kinds of parameters.
The CLI inference is now based on
sigtools.specifiers.signature
rather thaninspect.getfullargspec
. This enables a common interface for the function signature to be manipulated prior to being passed to Clize. Namely, the__signature__
attribute can be overridden orsigtools
’s lazyforger_function
method can be employed.The
@clize
decorator is deprecated in favor of directly passing functions torun
, thus leaving the original function intact.Named parameters are now obtained exclusively through keyword-only parameters. Other information about each parameter is communicated through parameter annotations.
sigtools.modifiers
provides backwards-compatibility for Python 2.As a result of implementing the function signature-based abstraction, there are ways to set up decorators that work with Clize.
The help system now accepts subsection headers for named parameters.
Coercion functions have been renamed to value converters. Except for a few notable exceptions, they must be tagged with a decorator. This also applies to the type of supplied default values.
Alternate actions (for instance
--version
) can be supplied directly to run.Several Parameter converter annotations have been added, including parameters with a limited choice of values, repeatable parameters, parameters that always supply the same value, and more.
2.0 (2012-10-07)¶
This release and earlier were documented post-release.
Version 2.0 adds subcommands and support for function annotations and keyword-only parameters.
1.0 (2011-04-04)¶
Initial release.