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