argparse tab autocompleter

[anselor]

I'm working on a tab completion implementation that automatically generates completions based on an argparse definition. Creating this issue to enable discussions.

[tleonhardt]

If we move to the state where we have a 2nd file as part of the cmd2 module instead of just the single cmd2.py file, then we should change the directory structure to create a cmd2 directory in which all of the source code lives and make cmd2 a proper Python package by including a dunder init.py and such.

Hopefully this should be a small change, but it will likely require small tweaks in all of the following areas:

• packaging for distribution to PyPI
• Sphinx documentation - where it looks for the cmd2 source when using autodoc features
• unit testing - where it looks for the cmd2 source and what it does to install before running tests

[tleonhardt]

When you create a PR for this, make sure you update setup.py to add a dependency on colorama if you use that module. I'm fine with that - it is a very common library which I always end up using anyways.

For a long time I've been considering adding a dependency on colorama and retrofitting cmd2's existing colorizing code to use colorama so that it will work on Windows as well as the POSIX OSes.

[tleonhardt]

From the limited experimentation I have done playing with this feature on the autocompleter branch, I think it rocks socks. It is a very slick feature which makes tab completing everything related to argparse arguments quite simple. And the way it provides a hint specifically for the argument you are attempting to complete is very helpful.

[tleonhardt]

@anselor
I love this feature. It combines so synergistically with the existing argparse decorators and existing tab-completion functionality that it goes a long way to make it just so damn easy to provide awesome tab-completion that end users will love pretty much "out-of-the-box".

I recommend that you work in conjunction with @kmvanbrunt to update the "front-page" code example in README.md to use this feature as well as the argument and/or index based tab completion and make that part of the PR that merges this feature in. Keep it as simple as possible, but make it readily obvious that these features exist.

Basically I want to make these powerful tab-completion capabilities very discoverable for new cmd2 users as I believe they are something which really set cmd2 apart from competing alternatives.

[anselor]

@tleonhardt

Instead of updating the example in README,md, I'm thinking I'll change how cmd2 handles all with_argparse commands such that if a complete_COMMAND function isn't provided cmd2 will automatically create an AutoCompleter. Users can still optionally implement the complete_CCOMMAND function to do whatever they want.

[tleonhardt]

@anselor
I like your idea much better ;-)

If you just make it so the two argparse-based decorators automatically create an AutoCompleter that sounds like the best possible scenario! This should provide a great out-of-the-box experience for end users with very little work required on their part, at least for basic cases.

[tleonhardt]

@anselor
We currently don't have macOS CI testing enabled because it is a bit unreliable on TravisCI (sometimes it gets badly backed up). I did a little manual testing on your branch on my Mac and got a bunch of failures when running with Python 3.6, but everything worked fine when running with Python 3.5.

When I had problems, it was apparently entirely within the test_acargparse.py unit test file.

Errors tended to look like the following:

========================================================= ERRORS =========================================================
_____________________________________ ERROR collecting tests/test_autocompletion.py ______________________________________
tests/test_autocompletion.py:20: in <module>
    from examples.tab_autocompletion import TabCompleteExample
examples/tab_autocompletion.py:13: in <module>
    class TabCompleteExample(cmd2.Cmd):
examples/tab_autocompletion.py:94: in TabCompleteExample
    suggest_parser = AutoCompleter.ACArgumentParser()
cmd2/AutoCompleter.py:717: in __init__
    super().__init__(**params)
E   TypeError: __init__() got an unexpected keyword argument 'allow_abbrev'

So I would strongly advise you borrow a Mac for some testing before you merge this in.

[anselor]

The allow_abbrev constructor parameter was added in python 3.5. I'm suspicious about what version of python is executing on your system. I think it would only be unrecognized if you were running 3.4 or 2.7.

That being said, I changed the way I pass through constructor parameters so it shouldn't show up again. This also reduces the maintenance overhead of having to match the parent constructor's parameters.