Support customizable short flags

[evanunderscore]

Currently defopt allows for no customization of the command line. There are some things that could be made more flexible without violating the spirit of defopt if implemented well.

Possibilities:

• Short flags, e.g. -c/--count
• "store_const" flags, e.g. --thing/--not-thing
• Others?

One potential solution is to parse this information out of RST comments so the generated documentation is not polluted.

def func(count=1, up=False):
    """Do something

    :param int count: desc
    :param bool up: desc

    .. count: -c/--count COUNT
    .. up: --up=True --down=False
    """

[evanunderscore]

These comments are valid for Google/Numpy docstrings but must be above the fields.

[evanunderscore]

Going to hold off on implementing anything until I have a better idea of potential use cases.

[evanunderscore]

One downside to doing this inside the docstring is that it introduces magic that doesn't exist outside defopt, which I've so far avoided. Perhaps it would be better to just pass something to defopt.run?

[flying-sheep]

i filed #12 for flags (called “store_const” in the original comment), this can be about customization.

my idea: provide a decorator after all. it would add metadata to the function object.

apart from custom flag/option names it would be cool to have a simple way to use dashes instead of underscores.

we’d have the decorator defopt.opts:

# Supports either arg_name='s', arg_name='long' or arg_name=('long', 's', 'alt-long', ...)
def opts(_use_dashes=False, **opt_names):
    final_opt_names = {}
    for arg_name, spec in opt_names.items():
        if isinstance(spec, str):
            spec = (spec,)
        assert isinstance(spec, tuple), 'spec must be str or tuple, not {}'.format(type(spec))
        assert not any(len(n) < 1 for n in spec), 'empty string found in spec {!r}'.format(spec)

        long = [n for n in spec if len(n) > 1]
        short = [n for n in spec if len(n) == 1]

        # default to python kwarg name if no long name is given
        # explicit long name trumps _use_dashes
        if not long:
            long = [arg_name.replace('_', '-') if use_dashes else arg_name]

        final_opt_names[arg_name] = {'short': short, 'long': long}

    def decorator(func):
        setattr(func, '__defopt_names', final_opt_names)
        return func

    return decorator

file my-cmd (shebang, no .py):

#!/usr/bin/env python
import defopt

@defopt.opts(True, long_opt='l', legend='g', custom=('individual', 'c'))
def my_cmd(long_opt=1, legend=True, custom='a'):
    print(long, legend, custom)

if __name__ == '__main__':
    defopt.run(my_cmd, use_dashes=True)

$ ./my-cmd --long-opt 5 -g -c foo
5 True foo
$ ./my-cmd --no-legend
1 False a

[evanunderscore]

On dashes versus underscores: I hadn't considered this originally, but I feel like this would be good for the default behavior. If someone actually wants underscores in their flags, it could probably be an argument to defopt.run.

For decorators, this sort of thing is already quite nicely covered by argh, and also by plac which I mentioned in the readme (I might put argh in there instead). Part of the reason I didn't want to include a decorator interface is that I don't want defopt to just become a less flexible equivalent of these existing parsers.

My thinking lately is that it would be nice to handle this in a similar way to parsers. In the same way the parsers argument to defopt.run maps types to parsers globally, this could map flag names to short flags globally. This is less flexible, but very simple and consistent.

The rough equivalent for your example:

def my_cmd(long_opt=1, legend=True, custom='a'):
    print(long_opt, legend, custom)

if __name__ == '__main__':
    defopt.run(my_cmd, short={'long_opt': 'l', 'legend': 'g', 'custom': 'c'})

How would you feel about something like this?

[evanunderscore]

I've renamed this issue so that this can focus on short flags and #12 can handle boolean flags.

[flying-sheep]

My thinking lately is that it would be nice to handle this in a similar way to parsers. In the same way the parsers argument to defopt.run maps types to parsers globally, this could map flag names to short flags globally. This is less flexible, but very simple and consistent.
[…]

defopt.run(my_cmd, short={'long_opt': 'l', 'legend': 'g', 'custom': 'c'})

i like it, but we should consider doing alternatives={'long_opt': ('l', 'long', 'long2'), 'legend': 'g'} instead. it’s a more flexible than short. the behavior would be to

1. only have a long opt (from arg name) per default
2. if (one or more) short opts are given, use the default long opt and them
3. if (one or more) long opts are given, replace the default long opt

[evanunderscore]

Can you give me an example of where you would want to rename a flag but not just change the name of the function parameter?

[flying-sheep]

e.g. a backwards compatible flag name change?

it doesn’t matter though, as adding this part later would still work (i.e. implementing like you propose and later add the ability to handle tuples)

[evanunderscore]

My preference would be to implement a simpler solution first and expand on it later if necessary. I'm open to implementing something like you proposed in the future if there's a demand for it.

[flying-sheep]

yeah, sure 😄

[evanunderscore]

Very simple implementation here: 9478299

Might have to change a bit once #12 is done. Thoughts?

[evanunderscore]

I've made the change from underscores to hyphens here: 75c8755

[flying-sheep]

cool! this is a breaking change though, so it’ll be released in 2.0, correct?

[evanunderscore]

Indeed, all of these changes will be in 2.0. The short flags could go separately into 1.x, but unless someone asks, I won't bother.

[evanunderscore]

Implemented in c44e398 taking into account the other changes that have happened.

[evanunderscore]

Going to close this since most of it has been addressed. If there's anything you want that the current solution doesn't cover, feel free to create a new issue.

[flying-sheep]

very cool, thank you!