Is it possible to break long lines in the "usages:" section?

[Mistake of copy and paste of the code, show the third message for a correct presentation of the problem, sorry.]

Hi,

Thanks for this usefull module.

When I have seen this page https://github.com/docopt/docopt/blob/master/examples/git/git.py, I thought it was possible to break long lines in the “usages:” section, but I have some problems.

The code:

    # The second usage  is written on 3 lines.
    help_message = """
    Usage:
      check_snmp storage (-h | --help)
      check_snmp storage -w <warning> -c <critical>
          -H <host-address> -t <timeout>
          (--v2c -C <community> | -l <login> -x <passwd> -X <privpass> -L <protocols>)
    Options:
      -h, --help
            Show this help message and exit.
      -H <host-address>, --host=<host-address>
            Set the address of the host.
      -t <timeout>, --timeout=<timeout>
            Set the timeout, in seconds, of the SNMP request.
      --v2c
            Use SNMP V2c instead of SNMP V3.
      -C <community>, --community=<community>
            Set the community password for SNMP V2c.
      -l <login>, --login=<login>
            Set the login for SNMP V3.
      -x <passwd>, --passwd=<passwd>
            Set the auth password for SNMP V3.
      -X <privpass>, --privpass=<privpass>
            Set the priv password for SNMP V3.
      -L <protocols>, --protocols=<protocols>
            Set the auth and priv protocols for SNMP V3. The authorised
            values are: "md5,des" "md5,aes" "sha,des" and "sha,aes".
      -w <warning>, --warning=<warning>
            With -w 80, the ckeck raises a warning if one local
            files system at least is full at more than 80%.
      -c <critical>, --critical=<critical>
            With -c 90, the ckeck raises a critical if one local
            files system at least is full at more than 90%.
    """

    from docopt import docopt

    if __name__ == '__main__':
        args = docopt(help_message, options_first=False)
        print(args) 

The call:

    $ ./check_snmp storage -w 80 -c 90 -H host -t 6 --v2c -C xxxxx
    Traceback (most recent call last):
      File "./check_snmp_lib/check_storage.py", line 46, in <module>
        args = docopt(help_message, options_first=False)
      File "/usr/local/lib/python2.6/dist-packages/docopt.py", line 560, in docopt
        pattern = parse_pattern(formal_usage(DocoptExit.usage), options)
      File "/usr/local/lib/python2.6/dist-packages/docopt.py", line 373, in parse_pattern
        result = parse_expr(tokens, options)
      File "/usr/local/lib/python2.6/dist-packages/docopt.py", line 387, in parse_expr
        seq = parse_seq(tokens, options)
      File "/usr/local/lib/python2.6/dist-packages/docopt.py", line 396, in parse_seq
        atom = parse_atom(tokens, options)
      File "/usr/local/lib/python2.6/dist-packages/docopt.py", line 413, in parse_atom
        result = pattern(*parse_expr(tokens, options))
      File "/usr/local/lib/python2.6/dist-packages/docopt.py", line 381, in parse_expr
        seq = parse_seq(tokens, options)
      File "/usr/local/lib/python2.6/dist-packages/docopt.py", line 396, in parse_seq
        atom = parse_atom(tokens, options)
      File "/usr/local/lib/python2.6/dist-packages/docopt.py", line 423, in parse_atom
        return parse_shorts(tokens, options)
      File "/usr/local/lib/python2.6/dist-packages/docopt.py", line 346, in parse_shorts
        (short, len(similar)))
    docopt.DocoptLanguageError: -t is specified ambiguously 2 times 

If I don’t break the long lines in the “usages:” section as below, I have no problem with the same call:

# The second usage  is written on 1 and long line.
help_message = """
Usage:
  check_snmp storage (-h | --help)
  check_snmp storage -w <warning> -c <critical> -H <host-address> -t <timeout> (--v2c -C <community> | -l <login> -x <passwd> -X <privpass> -L <protocols>)
Options:

# etc. The rest is just the same...

Is it normal?

Thanks.

PS: I use Debian Squeeze and Python 2.6.6 with docopt 0.6.1

[flaf]

Ok, thank you for your answer and the explanations. That’s very clear. I think I will keep myself to use the 0.6.1 version and make sure none of lines start with dash.😉

I tested the current master version in git and I had problems. If this can help, here is an example:

[with the current master]

#!/usr/bin/python
# -*- coding: utf-8 -*-

help_message = """ 
Usage:
  test.py (-h | --help)
  test.py -w <warning> -c <critical> -H <host-address>
      (--v2c -C <community> | -l <login> -x <passwd>)

Options:
  -h, --help                                 Blabla blabla.
  -H <host-address>, --host=<host-address>   Blabla blabla.
  --v2c                                      Blabla blabla.
  -C <community>, --community=<community>    Blabla blabla.
  -l <login>, --login=<login>                Blabla blabla.
  -x <passwd>, --passwd=<passwd>             Blabla blabla.
  -w <warning>, --warning=<warning>          Blabla blabla.
  -c <critical>, --critical=<critical>       Blabla blabla.
"""

from docopt import docopt

if __name__ == '__main__':
    args = docopt(help_message, options_first=False)
    print(args)

And:

$ ./test.py -w 80 -c 90 -H 192.168.0.30 --v2c -C community
{'--help': False,
 '--v2c': True,
 '-C': True,
 '-H': True,
 '-c': True,
 '-h': False,
 '-l': False,
 '-w': True,
 '-x': False,
 '<community>': 'community',
 '<critical>': '90',
 '<host-address>': '192.168.0.30',
 '<login>': None,
 '<passwd>': None,
 '<warning>': '80'}

I have just the short options in the dictionary (why not, perhaps a change as regards the 0.6.1 version) but for the “help” option, I have ‘-h’ the short option and ‘–help’ the long option in the dictionary. I had found this curious and a little unconsistent. But this is a detail.

And below, my call is not accepted and I don’t know why:

$ ./test.py -w 80 -c 90 -H 192.168.0.30 --v2c --community community
Usage:
  test.py (-h | --help)
  test.py -w <warning> -c <critical> -H <host-address>
      (--v2c -C <community> | -l <login> -x <passwd>)

But perhaps I hadn’t respected a new syntax.

[Pierre-Sassoulas]

I had this problem in conjunction with a strict line length rule applied by continuous integration. I think starting the line with a dash is what makes the most sense in order to not separate an argument and its name. But as a quick fix maybe an error message like “cannot start usage line with a dash” would be helpful.