Default value for argument gets assigned to option #36

shabbyrobe opened this Issue Jun 26, 2012 · 14 comments


None yet

5 participants

docopt member
Usage: [--opt num] [ARG]

    --opt num   An option with a value

    ARG         An arg with a default [default: A]

from docopt import docopt
arguments = docopt(__doc__)
print arguments

I expect this to show:

{'--opt': None, 'ARG': 'A'}

What actually happens:

{'--opt': 'A', 'ARG': None}

I'll take a look into a fix tomorrow if I can.


There isn't actually any Argument default support. Even the Options header is ignored, they are parsed from every line starting with a -.

For a quick fix to the bug, the regex on line 177 could be stopped at a blank line:

matched = re.findall('\[default: (.*)\]', re.split('\n\s*\n', description, 1)[0], flags=re.I)

Or a solution with only parses the first line of a description:

matched = re.findall('\s*.*\[default: (.*)\]', description, flags=re.I)

Neither actually affects Argument default support though.

docopt member

I think introduction of arguments' defaults is the right way to solve this.


If an Arguments section is added, should it require the Arguments: header? This would be clearer but introduce a discrepancy with the options, since it could be parsed in every non-usage line.

Although, I think the options are parsed from the usage lines too. That seems like a potential issue if someone needs multiple lines for one subcommand.

docopt member

I think headers make it less flexible (you might want several headers for both options and arguments). I think usage-pattern should be taken out of parsing option/arguments description/defaults.

@Met48 Met48 added a commit to Met48/docopt that referenced this issue Jul 1, 2012
@Met48 Met48 Add support for argument defaults. Fix issue #36.
This introduces a backwards-incompatible change.
Multi-line descriptions are now recognized through
additional indentation in the following lines.
This is required to correctly identify argument
defaults, but the change affects options as well.

I've implemented support for argument defaults, as well as fixed this bug. The behaviour for parsing multi-line argument defaults is a bit difficult, since it can't split on line prefix characters like with options. I chose to make it look for higher indentation levels instead:

usage: prog

    <arg1>  Arg1's description
    [default: Not arg1's default]
    <arg2>  Arg2's description
        [default: Arg2's default]

This decision adds the same requirement to option descriptions. The examples work with it, but one test had to be updated. @halst, is this change ok?

Edit: Another small difference, though backwards-compatible: tab characters can be used for indentation and separation.

docopt member

I think being dependent on indentation is very subtle in this case. Why not:

  • If line starts with {word starting with < and ending with >, or an upper case word}, which follows with 2 spaces, then it's argument's description, which can have [default: ...].


  • If line starts with a name of an argument from usage pattern, which follows with 2 spaces, then it's argument's description, which can have [default: ...]
docopt member

@Met48, I can see that you are a very active contributor to docopt—that is very appreciated. You know, it can be frustrating if your hard work is not pulled into the main repo, huh? :-) If you want to avoid that, we can do this: talk through API or DSL extension and then together decide how it should look. I will tag those issues that have unambiguous decision on API/DSL extension, as TODO, and then you can be sure that if you implement that, it will get pulled almost certainly.

Thanks again for sending patches! #27 looks very promising.

You can reach me on skype as halst.—I think chatting in skype has a better throughput than comments on github.


Thanks! I've added you on skype as well, though the 6 hour difference might make it hard to chat live.

I'll implement a variation on the second option - splitting every line and checking for arguments, no indentation checks.

@Met48 Met48 added a commit to Met48/docopt that referenced this issue Jul 6, 2012
@Met48 Met48 Revise argument defaults. See issue #36.
Argument defaults will now match on any
line starting with <.*> or [A-Z]+
Multi-line argument and option descriptions
are supported as long as the additional lines
never match one of the above patterns.
@Met48 Met48 added a commit to Met48/docopt that referenced this issue Jul 6, 2012
@Met48 Met48 Add support for argument defaults, fix issue #36.
Argument defaults will match on any non-usage line
that starts with  <.*>  or  [A-Z]+

Supports multi-line descriptions.
docopt member

Support upcoming, see #37

@keleshev keleshev closed this Dec 10, 2012

So what happened? Are there arguments defaults? I can't get it to work and I haven't found anything in the documentation.

docopt member

no, not yet


Is it likely to show up soon?

docopt member

I'm afraid not. Not until #104 is implemented. But that is because it's so easy to get around. You can still put [default: foo] in your documentation, but in code use args['<arg>'] or 'foo' instead of args['<arg>'].

@keleshev keleshev reopened this Jun 17, 2013

Hey, what's the status on this? I would really like to be able to set a default for an optional positional argument.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment