Relocate functions to clarify API

[kotfu]

While working on the API documentation, I noticed that decorators.py contains two functions categorize() and set_parser_prog(). Shouldn't these functions be in utils.py instead? Is there a good reason why they are in decorators.py?

[kmvanbrunt]

They are related to decorated command functions. That's why I put them there initially. But they are not decorators, so utils could also be an appropriate location.

[kotfu]

categorize() is imported by __init__.py so it could reasonably be moved without breaking anything. However, set_parser_prog() is not, so if we move it it will break people's imports. Perhaps I'll rename this issue and keep a running list of functions that could potentially be relocated and we'll see how long the list is before deciding whether to move them or not.

[kotfu]

Functions/consts/classes to be relocated

Relocated means moved from one source file to another. In some cases this will break imports. This list tracks each proposed move, and whether it will break imports or not.

• set_parser_prog() : unlikely to be used, maybe rename to _set_parser_prog() and leave in decorators.py
• categorize() : decorators.py -> utils.py : imported by __init__.py so it shouldn't break anything downstream

[kmvanbrunt]

I recently wrote set_parser_prog() as a support function for the argparse decorators. I don't think anyone calls it directly.

[kotfu]

So maybe it shouldn't be included in the public API?

[kmvanbrunt]

I'd be ok prepending an underscore.

[kmvanbrunt]

set_parser_prog()'s purpose is to solve the problem of prog getting properly set on subcommand's subparsers. cmd2 doesn't require developers to set prog on parsers used in the argparse decorators since we set it to match the command's name for them. When you don't set prog, it defaults to sys.argv[0]. Each subparser you add inherits this name. Since our decorators were updating prog after all the subparsers had been added, they weren't picking up the change. Therefore usage text on subcommands would start with sys.argv[0]. The only way to fix this before was to set prog explicitly on the root parser. Most people didn't know this caveat.

To make things easier, I made the decorators do all the work by calling set_parser_prog().

[kmvanbrunt]

I say all that to mean I don't think set_parser_prog() has a general use case. Therefore prepending it with an underscore and leaving it in decorators.py is OK by me.

[tleonhardt]

This was closed by #895