Frequently asked questions¶
Drafts! These docs are all new and the FAQ is almost empty! Help me improve this dire situation by contacting me with your questions!
Table of contents
What versions of Python are supported?¶
Clize is tested to run successfully on Python 3.6 through 3.10.
For other Python versions:
Python version |
Last compatible version of Clize |
---|---|
Python 2.6 |
|
Python 2.7 |
|
Python 3.3 |
|
Python 3.4 |
|
Python 3.5 |
What libraries are required for Clize to run?¶
Using pip
to install Clize from PyPI as in Installation will
automatically install the right dependencies for you.
If you still need the list, Clize always requires:
sigtools: Utilities to help manipulate function signatures.
od: Shorthand for OrderedDict.
attrs: Classes without boilerplate.
docutils: To parse docstrings.
If you wish to use clize.converters.datetime
, you need:
python-dateutil: For parsing dates.
pip
will install dateutil
if you specify to install Clize with the
datetime
option, i.e. pip install "clize[datetime]"
.
I just installed Clize using pip
and I still get ImportErrors
¶
Old versions of pip
do not read Python-version dependent requirements and
therefore do not install funcsigs
or ordereddict
. To remedy this, you can:
Upgrade
pip
and install Clize again. (Use the-U
flag ofpip install
to force a reinstall.)Install the dependencies manually.
What is sigtools
and why is it a separate library?¶
sigtools
is used in many of the examples throughout this documentation, and
it is maintained by the same person as Clize, thus the above question.
Clize’s purpose is twofold:
Convert the idioms of a function signature into those of a CLI,
Parse the input that CLI arguments are.
It turns out that just asking for the function signature from
inspect.signature
is not good enough:
Python 2 syntax, which was supported at the time, cannot be used to express keyword-only parameters.
inspect.signature
cannot process decorators that return a function with slightly altered parameters.
For the first point, Clize could have accepted an argument that said “do as if that parameter was keyword-only and make it a named parameter on the CLI” (and in fact it used to), but that would have Clize behave according to a signature and a bunch of things around it, which is a concept it tries to steer away from.
For the second, some tooling would be necessary to specify how exactly a decorator affected a wrapped function’s parameters.
Modifying and making signatures more useful was both complex and independent
from command-line argument parsing, so it was made a separate library as
sigtools
.
So there you have it, sigtools
helps you add keyword-only parameters on
Python 2, and helps decorators specify how they alter parameters on decorated
functions. All Clize sees is the finished accurate signature from which it
infers a CLI.
What other libraries can be used for argument parsing?¶
How can I write mutually exclusive flags?¶
Mutually exclusive flags refer to when a user can use one flag A (--flag-a
)
or the other (--flag-b
), but not both at the same time.
It is a feature that is difficult to express in a function signature as well as
on the --help
screen for the user (other than in the full usage form).
It is therefore recommended to use a positional parameter or option that
accepts one of specific values. one_of
can help you do
that.
If you still think mutually exclusive parameters are your best option, you can
check for the condition in your function and raise clize.ArgumentError
, as in
the Arbitrary requirements part of the tutorial.
Where can I find more help?¶
You can get help by contacting me directly, writing in the dedicated Gitter chatroom, using the #clize #python hashtags on Twitter, or by posting in the Clize Google+ community.