Upgrading from older releases¶
This document will instruct you in porting applications using older clize versions to the newest version.
Upgrading from clize 1 and 2¶
Clize 3 now only treats keyword-only parameters on the function as named
parameters and does not convert any parameter from keyword to positional or
vice-versa, much like when using the use_kwoargs
parameter in Clize 2.
Aliases, and other parameter-related information is now communicated
exclusively through parameter annotations. Decorators from sigtools.modifiers
are the recommended way to set these up in a way compatible with Python 2.
However, clize.clize
is provided: it imitates the old behaviour but adds a deprecation warning when used.
Porting code using the @clize
decorator with no arguments¶
Consider this code made to work with Clize 1 or 2:
from clize import clize, run
@clize
def func(positional, option=3):
pass # ...
if __name__ == '__main__':
run(func)
Here, you can drop the @clize
line completely, but you have to convert option
to a keyword-only parameter. You can use sigtools.modifiers.autokwoargs`
to do so:
from sigtools.modifiers import autokwoargs
from clize import run
@autokwoargs
def func(positional, option=3):
pass # ...
if __name__ == '__main__':
run(func)
Decorating the function with @autokwoargs
will still let you call it
normally, except that any parameter with a default value(here just option
)
will only be accepted as a named argument.
force_positional
¶
force_positional
used to let you specify parameters with defaults that you don’t want as named options:
from clize import clize, run
@clize(force_positional=['positional_with_default'])
def func(positional, positional_with_default=3, option=6):
pass # ...
if __name__ == '__main__':
run(func)
The exceptions
parameter of autokwoargs
has the same purpose here:
from sigtools.modifiers import autokwoargs
from clize import run
@autokwoargs(exceptions=['positional_with_default'])
def func(positional, positional_with_default=3, option=6):
pass # ...
if __name__ == '__main__':
run(func)
Porting code that used alias
or coerce
¶
The alias
and coerce
were used in order to specify alternate names for options and functions to convert the value of arguments, respectively:
from clize import clize, run
@clize(
alias={'two': ['second'], 'three': ['third']},
coerce={'one': int, 'three': int})
def func(one, two=2, three=None):
pass # ...
if __name__ == '__main__':
run(func)
You now pass these as annotations on the corresponding parameter. To keep compatibility with Python 2, we use sigtools.modifiers.annotate
:
from sigtools.modifiers import annotate, autokwoargs
from clize import run
@autokwoargs
@annotate(one=int, two='second', three=('third', int)):
pass # ...
if __name__ == '__main__':
run(func)
require_excess
¶
Indicating that an *args
-like parameter is required is now done by annotating the parameter with Parameter.REQUIRED
or Parameter.R
for short:
from sigtools.modifiers import annotate
from clize import run, Parameter
@annotate(args=Parameter.R)
def func(*args):
pass # ...
if __name__ == '__main__':
run(func)
extra
and make_flag
¶
Alternate actions as shown in Clize 2’s tutorial are now done by passing the
function directly to run
as shown in the tutorial.
Unlike previously, the alternate command function is passed to the clizer just
like the main one.
For other use cases, you should find the appropriate parameter class from
clize.parser
or subclass one, instantiate it and pass it in a sequence as the
extra
parameter of Clize
or run
. If the parameter matches one
actually present on the source function, annotate that parameter with your
Parameter
instance instead of passing it to extra
.