Update to pop-tree 12.1.1 with optimizations and option enumeration

Summary

This MR introduces an enhancement to the pop-doc subcommand. Now, when you run pop-doc or idem doc it will list the "choices" for parameters that use Python's typing.Literal or Enum. This feature aids developers in understanding the allowed values for specific parameters and follows the pattern established by argparse.

Details

Before:

Running pop-doc on a function ref would provide basic information about parameters but would not detail the allowed values for Literal or Enum types.

After:

The pop-doc command will explicitly list "choices" for Literal and Enum types. This aligns with Python 3.8+ typing features and offers a more comprehensive overview.

Example:

Function Signature

from typing import Literal
from enum import Enum

class Choice(Enum):
    A = 1
    B = 2

def my_function(hub, param1: Literal['choice1', 'choice2'], param2: Choice):
    pass

pop-doc Output before changes:

{
        'contracts': {'call': [], 'post': [], 'pre': []},
        'doc': '',
        'end_line_number': 27,
        'file': '.../pop-tree/tests/tpath/tree_plugin/tree/choice.py',
        'parameters': {'hub': {'choices': None},
                       'param1': {'annotation': "typing.Literal['choice1', 'choice2']"},
                       'param2': {'annotation': "<enum 'Choice'>"}},
        'ref': 'tree.choice.my_function',
        'start_line_number': 25
}

pop-doc Output after changes:

{
        'contracts': {'call': [], 'post': [], 'pre': []},
        'doc': '',
        'end_line_number': 27,
        'file': '.../pop-tree/tests/tpath/tree_plugin/tree/choice.py',
        'parameters': {'hub': {'choices': None},
                       'param1': {'annotation': "<class 'str'>",
                                  'choices': ['choice1', 'choice2']},
                       'param2': {'annotation': "<enum 'Choice'>", 'choices': [1, 2]}},
        'ref': 'tree.choice.my_function',
        'start_line_number': 25
}

Reasoning

• Aligns with argparse's usage of "choices" to indicate allowable inputs.
• Utilizes Python 3.8+ typing.Literal for improved type safety and documentation.

How to Test

1. Update your local installation of pop-tree and idem.
2. Run idem doc <hub_reference> for a function that uses Literal or Enum.
3. Verify that the "choices" are displayed as expected.

vmware/pop/pop-tree!19 (merged)