docstringargs: Python module for setting up argparse

[Chris Angelico]

On Tue, Apr 21, 2015 at 1:44 PM, Paul Rubin <no.email at nospam.invalid> wrote:
> Chris Angelico <rosuav at gmail.com> writes:
>>> Does this conflict with type signature proposals
>> In the sense that you can't use both together, yes. But docstringargs
>> follows the rule of "if you're going to use annotations, also use a
>> decorator"; and the decorator removes all the annotations it uses.
>
> This makes me think the annotation system is too limited.  There should
> be a way to use multiple kinds of annotation at the same time, by using
> multiple decorators.  Maybe there could be a convention where the
> annotation is a dictionary whose entries correspond to decorators and
> are consumed by those decorators.

This has been hashed out in great detail on this and other lists in
the past. The biggest response is YAGNI. The cognitive and syntactic
burden of supporting multiple annotations is ridiculous compared to
the minuscule benefit. Compare:

# Exclusive annotations
@cmdline
def adduser(
        user: "Name of user to add",
        password: "Password for the new user"=""):
    """Add a new user"""

# Shared annotations
import typing
@cmdline
def adduser(
        user: {cmdline: "Name of user to add", typing: str},
        password: {cmdline: "Password for the new user", typing: str}=""):
    """Add a new user"""

This example actually isn't too bad... because the arguments coming
from the command line will always be strings, which is exactly what
makes the annotations useless. But it's worth noting that *every*
annotation would need this complex adornment system, repeating some
key for every single parameter, just for the unusual case where you
actually want to put two annotations onto something.

It's the job of a programming language to limit things. Here's
something I wrote up a while ago about a similar design question - I'd
built something that required one-line-per-action in a given file, and
my boss asked me to make it more flexible and able to handle
multi-line actions. (Point of interest: He overruled me, and since he
was paying the bills, I had to make it flexible... but from then until
I left the company some years later, there were exactly ZERO uses of
that system that had multi-line actions. Zero.) The same concepts
apply to game design, user interface design, API design, and pretty
much everything.

http://rosuav.blogspot.com/2011/09/we-dont-need-all-that-design-space.html

ChrisA