Add a way to pass custom help formatter to call; add a multi-line HelpFormatter

[plazer1]

The custom improved help formatter implemented in this PR allows putting linebreaks into option descriptions as illustrated below, as well as using multi-line string literals with indented text contents (the indentation will be automatically removed). To activate this new formatter, pass formatter_class=plac.MultilineFormatter to call().

(This PR also adds __pycache__ to .gitignore.)

Code:

import plac

def main(
    foo:
      (r'''
        Lorem ipsum dolor *sit amet* -- consectetur adipiscing elit!
        Maecenas hendrerit quam nisl (vitae lacinia dui ullamcorper vulputate).
      ''', 'option', 'f', str)
      = 'bar'
):
  ...

if __name__ == '__main__':
  plac.call(main, formatter_class=plac.MultilineFormatter)

---

Current output with RawDescriptionHelpFormatter:

usage: a.py [-h] [-f bar]

options:
  -h, --help     show this help message and exit
  -f, --foo bar  Lorem ipsum dolor *sit amet* -- consectetur adipiscing elit! Maecenas hendrerit quam nisl (vitae lacinia dui ullamcorper vulputate).

Output with the proposed changes:

usage: a.py [-h] [-f bar]

options:
  -h, --help     show this help message and exit
  -f, --foo bar  Lorem ipsum dolor *sit amet* -- consectetur adipiscing elit!
                 Maecenas hendrerit quam nisl (vitae lacinia dui ullamcorper vulputate).

---

For reference, here is the output with RawTextHelpFormatter -- it does not strip and de-dent the description text:

usage: a.py [-h] [-f bar]

options:
  -h, --help     show this help message and exit
  -f, --foo bar
                         Lorem ipsum dolor *sit amet* -- consectetur adipiscing elit!
                         Maecenas hendrerit quam nisl (vitae lacinia dui ullamcorper vulputate).

[ialbert]

The problem is Hyrum’s Law - we really don't want to alter how plac works, we don't know what might break down the line:

With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody.”

https://www.hyrumslaw.com/

[plazer1]

I would be happy if I could pass my custom formatter to call, which is currently impossible. I'll adjust my PR to keep the default formatter and allow using a custom one. Better yet – if you're not opposed – I'd also like to add the custom formatter implementation to plac so that users don't have to implement it themselves (I'll also add a mention of this new formatter to the readme).

[ialbert]

yes, that might work,

that being said we have to keep backward and python 2.7(!) compatibility

[plazer1]

that being said we have to keep backward and python 2.7(!) compatibility

Hmmm.... According to the readme the lowest supported version is 2.6; however, according to the source code it's actually 2.3. So which is it: 2.3, 2.6 or 2.7?