Clize 3.0b1: An argument parser that draws a CLI from your function sigature

[Yann Kaiser]

On Mon, 27 Apr 2015 at 17:04 Chris Angelico <rosuav at gmail.com> wrote:

> On Mon, Apr 27, 2015 at 7:02 PM, Yann Kaiser <kaiser.yann at gmail.com>
> wrote:
> > Hello everyone!
> >
> > After a few years in development, I am proud to say Clize is landing its
> > feet again and is now in beta for an upcoming release.
> >
> > You can try it out using    pip install --user clize=3.0b1    and you can
> > browse the docs at    https://clize.readthedocs.org/
> >
> > For those who'd like an explanation before clicking links, here's Clize's
> > 5-bullet point explanation:
> >
> > * Command-line interfaces are created by passing functions to
> `clize.run`.
> > * Parameter types are deduced from the functions' parameters.
> > * A ``--help`` message is generated from your docstrings. (Why does this
> > still need to be a bullet point?)
> > * Decorators can be used to reuse functionality across functions.
> > * Clize can be extended with new parameter behavior.
>
> Interesting. I've also been working on a simpler arg handling module;
> maybe we can work together. The goals for mine are:
>
> * Each function should be as independent as possible.
>

In Clize, commands are also just regular functions which have the desired
amount of keyword-only parameters and annotations. They can still be run
individually, be tested, and so forth.


> * Minimize repetition (of names, descriptions, etc)
>

I try to minimize repetition, but the reality of things is that a parameter
name could be repeated up to 4 times in Clize:

* In the function's parameter list
* In the function's docstring
* If named explicitly, in a @-kwoargs decorator (not needed with Py3)
* In an annotate decorator (again, not needed with Py2 compatibility isn't
desired)

Two of these wouldn't be relevant in a Python 3-only world (if it's just a
shell script replacement, you can probably pretend to be in one for a
moment), the remainder being normal things in a function. So I'm not doing
too badly there. Descriptions are of course only written in the description
:-)

In addition, I took up the goal of helping minimize repetition in client
code behavior through better support for decorators (which is really cool,
by the way!)


> * Keep everything in the function signature
>

I started taking this at heart with 3.0, after seeing the rather disgusting
constructs that had to be used in Clize 2.x for specifying aliases and
value converters. Now everything is annotations. Nothing in the docstring
specifies behavior, and it isn't even read at all until --help is
triggered. I intend to keep docstrings behavior-free because, well, they're
strictly for documentation IMO.

One of the last remains of the old "give parameters to Clize about what
your function's parameters does" stuff, a flag to pass the executable name
to the function that's being run, was in fact changed in 3.0b1 to be an
annotation instead, giving it more flexibility (you can annotate whichever
parameter you want rather than being forced to use the first one).

What I mean to say, is that I am definitely committed to keeping everything
in the function signature. Probably even more than you :-)


> * Simplify the basic and obvious usages
>

That's where Clize started and I intend to keep simple usages simple.
One could say having to use @autokwoargs for turning parameters with
default values into keyword-only parameters, but I feel it was necessary
for consistency with the presence of actual keyword-only parameters.

Overall we're agreed on all these goals.

I will add that I'm taking up extensibility as a goal as of Clize 3.0.
clize.parameters.argument_decorator[1] wasn't originally by idea and was
first implemented by someone else using the public API.

[1]
http://clize.readthedocs.org/en/latest/compositing.html#using-a-composed-function-to-process-arguments-to-a-parameter

What it's clearly lacking when compared to your parser is better
docstrings, haha :-) The parser docs alleviate that a bit, but the parser
can be hard to navigate at first.

https://github.com/Rosuav/docstringargs
> https://pypi.python.org/pypi/docstringargs/
>
> There's a demo file in the source repo, plus here are a couple of
> actual usage examples:
>
> https://github.com/Rosuav/LetMeKnow/blob/master/letmeknow.py
> https://github.com/MikeiLL/appension/blob/master/fore/database.py
>
> The latter is an existing module in an existing project, and it grew a
> command-line interface with minimal changes, eg:
>
> https://github.com/MikeiLL/appension/commit/566f195
>
> Can we merge our plans and make a single module that's more likely to
> be maintained long-term? No point over-duplicating!
>

Agreed. I'm open to have more maintainers and to take input, but I have to
admit that at this stage of development, I'm quite attached to Clize's
existing codebase and features (although I'm always open to refactoring,
and the test suite helps with that).


> ChrisA
> --
> https://mail.python.org/mailman/listinfo/python-list
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-list/attachments/20150428/626f6459/attachment.html>