docopt-ng

Changed

• BREAKING: Remove magic stuff.

  When using docopt(): Now you must supply docstring explicitly, and the more_magic option is removed.

  The magic() and magic_docopt() functions are also removed.

  I had several reasons for removing this:

  1. It's not needed. In 99% of cases you can just supply doc.
  2. It is implicit and too magical, encouraging code that is hard to reason about.
  3. It's brittle. See https://github.com/jazzband/docopt-ng/issues/49
  4. It is different from the spec outlined on docopt.org. I want them to be more aligned, because it isn't obvious to users that these two might be out of sync. (no one seems to have control of that documentation site)
  5. It fills in args in the calling scope???! We just returned the parsed result, just set it manually!
  6. It should be easy to migrate to this new version, and I don't think I've broken many people.
  7. It is out of scope. This library does one thing really well, and that is parsing the docstring. You can use the old code as an example if you want to re-create the magic.

• Tweak a few things to restore compatibility with docopt (the original repo) 0.6.2 See PR https://github.com/jazzband/docopt-ng/pull/36 for more info

  1. BREAKING: Restore what constitutes an "option": Now the important rule to follow is any line starting with - or -- is treated as an option. This means that some things that did NOT used to be treated as options, now ARE treated as options:

     1. lines before `usage:`
     2. non-indented --options
     3. lines not inside the options: section
     

     However, we also keep one part of the old behavior of this fork where in the line header that ends with the keyword options: --foo, --foo is still treated as an option because the start of a line up to options: is ignored.

  2. BREAKING: Error messages are tweaked a little bit. Unlikely that you relied on them, but just in case.

  3. NONBREAKING: Now allow for blank lines between options. As described in https://github.com/jazzband/docopt-ng/issues/33

  4. NONBREAKING: Fix an unlikely edge case of how options are parsed: Here, --foo was interpreted to take "Enable" as an argument

     options:
        --foo
      Enable the foo behaviour. (One space before "Enable")
     

     Whereas here, Enable was interpreted as part of the description.

     options:
        --foo
       Enable the foo behaviour. (2 space before "Enable".)
     

     Now, both of these examples are treated more intuitively, where Enable is treated as the description

• (for devs) Switch to PDM as project manager