Merge pull request #96 from swansonk14/tapify

Tapify: run functions via command line arguments + Python 3.11

Author: swansonk14

.github/workflows/code-coverage.yml

@@ -6,13 +6,13 @@ jobs:
   run:
     runs-on: ubuntu-latest
     env:
-      PYTHON: '3.10'
+      PYTHON: '3.11'
     steps:
     - uses: actions/checkout@main
     - name: Setup Python
       uses: actions/setup-python@main
       with:
-        python-version: '3.10'
+        python-version: '3.11'
     - name: Generate coverage report
       run: |
         git config --global user.email "[email protected]"
@@ -24,7 +24,7 @@ jobs:
         python -m pip install pytest-cov
         pytest --cov=tap --cov-report=xml
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v1
+      uses: codecov/codecov-action@v3
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
         files: ./coverage.xml

.github/workflows/tests.yml

@@ -16,12 +16,12 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ['3.7', '3.8', '3.9', '3.10']
+        python-version: ['3.7', '3.8', '3.9', '3.10', '3.11']
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@main
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@main
       with:
         python-version: ${{ matrix.python-version }}
     - name: Set temp directories on Windows

setup.py

@@ -29,7 +29,8 @@
     package_data={'tap': ['py.typed']},
     install_requires=[
         'typing_extensions >= 3.7.4',
-        'typing-inspect >= 0.7.1'
+        'typing-inspect >= 0.7.1',
+        'docstring-parser >= 0.15'
     ],
     tests_require=['pytest'],
     classifiers=[
@@ -38,6 +39,7 @@
         'Programming Language :: Python :: 3.8',
         'Programming Language :: Python :: 3.9',
         'Programming Language :: Python :: 3.10',
+        'Programming Language :: Python :: 3.11',
         'License :: OSI Approved :: MIT License',
         'Operating System :: OS Independent',
         "Typing :: Typed"

tap/__init__.py

@@ -1,5 +1,6 @@
 from argparse import ArgumentError, ArgumentTypeError
 from tap._version import __version__
 from tap.tap import Tap
+from tap.tapify import tapify
 
-__all__ = ['ArgumentError', 'ArgumentTypeError', 'Tap', '__version__']
+__all__ = ['ArgumentError', 'ArgumentTypeError', 'Tap', 'tapify', '__version__']

tap/_version.py

@@ -1,7 +1,7 @@
 __all__ = ['__version__']
 
 # major, minor, patch
-version_info = 1, 7, 3
+version_info = 1, 8, 0
 
 # Nice string for the version
 __version__ = '.'.join(map(str, version_info))

tap/tap.py

@@ -1,13 +1,13 @@
+import json
+import sys
+import time
 from argparse import ArgumentParser, ArgumentTypeError
 from collections import OrderedDict
 from copy import deepcopy
 from functools import partial
-import json
 from pathlib import Path
 from pprint import pformat
 from shlex import quote, split
-import sys
-import time
 from types import MethodType
 from typing import Any, Callable, Dict, List, Optional, Sequence, Set, Tuple, TypeVar, Union, get_type_hints
 from typing_inspect import is_literal_type
@@ -226,23 +226,23 @@ def _add_argument(self, *name_or_flags, **kwargs) -> None:
                     loop = False
                     types = get_args(var_type)
 
-                    # Don't allow Tuple[()]
-                    if len(types) == 1 and types[0] == tuple():
-                        raise ArgumentTypeError('Empty Tuples (i.e. Tuple[()]) are not a valid Tap type '
-                                                'because they have no arguments.')
-
                     # Handle Tuple[type, ...]
                     if len(types) == 2 and types[1] == Ellipsis:
                         types = types[0:1]
                         loop = True
                         kwargs['nargs'] = '*'
+                    # Handle Tuple[()]
+                    elif len(types) == 1 and types[0] == tuple():
+                        types = [str]
+                        loop = True
+                        kwargs['nargs'] = '*'
                     else:
                         kwargs['nargs'] = len(types)
 
                     var_type = TupleTypeEnforcer(types=types, loop=loop)
 
                 if get_origin(var_type) in BOXED_TYPES:
-                    # If List or Set type, set nargs
+                    # If List or Set or Tuple type, set nargs
                     if (get_origin(var_type) in BOXED_COLLECTION_TYPES
                             and kwargs.get('action') not in {'append', 'append_const'}):
                         kwargs['nargs'] = kwargs.get('nargs', '*')
@@ -259,6 +259,7 @@ def _add_argument(self, *name_or_flags, **kwargs) -> None:
                     # Handle the cases of List[bool], Set[bool], Tuple[bool]
                     if var_type == bool:
                         var_type = boolean_type
+
                 # If bool then set action, otherwise set type
                 if var_type == bool:
                     if explicit_bool:
@@ -421,8 +422,8 @@ def parse_args(self: TapType,
 
         :param args: List of strings to parse. The default is taken from `sys.argv`.
         :param known_only: If true, ignores extra arguments and only parses known arguments.
-        Unparsed arguments are saved to self.extra_args.
-        :legacy_config_parsing: If true, config files are parsed using `str.split` instead of `shlex.split`.
+                           Unparsed arguments are saved to self.extra_args.
+        :param legacy_config_parsing: If true, config files are parsed using `str.split` instead of `shlex.split`.
         :return: self, which is a Tap instance containing all of the parsed args.
         """
         # Prevent double parsing

tap/tapify.py

@@ -0,0 +1,84 @@
+"""Tapify module, which can initialize a class or run a function by parsing arguments from the command line."""
+from inspect import signature, Parameter
+from typing import Any, Callable, List, Optional, TypeVar, Union
+
+from docstring_parser import parse
+
+from tap import Tap
+
+InputType = TypeVar('InputType')
+OutputType = TypeVar('OutputType')
+
+
+def tapify(class_or_function: Union[Callable[[InputType], OutputType], OutputType],
+           args: Optional[List[str]] = None,
+           known_only: bool = False,
+           **func_kwargs) -> OutputType:
+    """Tapify initializes a class or runs a function by parsing arguments from the command line.
+
+    :param class_or_function: The class or function to run with the provided arguments.
+    :param args: Arguments to parse. If None, arguments are parsed from the command line.
+    :param known_only: If true, ignores extra arguments and only parses known arguments.
+    :param func_kwargs: Additional keyword arguments for the function. These act as default values when
+                        parsing the command line arguments and overwrite the function defaults but
+                        are overwritten by the parsed command line arguments.
+    """
+    # Get signature from class or function
+    sig = signature(class_or_function)
+
+    # Parse class or function docstring in one line
+    if isinstance(class_or_function, type) and class_or_function.__init__.__doc__ is not None:
+        doc = class_or_function.__init__.__doc__
+    else:
+        doc = class_or_function.__doc__
+
+    # Parse docstring
+    docstring = parse(doc)
+
+    # Get the description of each argument in the class init or function
+    param_to_description = {param.arg_name: param.description for param in docstring.params}
+
+    # Create a Tap object
+    tap = Tap(description='\n'.join(filter(None, (docstring.short_description, docstring.long_description))))
+
+    # Add arguments of class init or function to the Tap object
+    for param_name, param in sig.parameters.items():
+        tap_kwargs = {}
+
+        # Get type of the argument
+        if param.annotation != Parameter.empty:
+            # Any type defaults to str (needed for dataclasses where all non-default attributes must have a type)
+            if param.annotation is Any:
+                tap._annotations[param.name] = str
+            # Otherwise, get the type of the argument
+            else:
+                tap._annotations[param.name] = param.annotation
+
+        # Get the default or required of the argument
+        if param.name in func_kwargs:
+            tap_kwargs['default'] = func_kwargs[param.name]
+            del func_kwargs[param.name]
+        elif param.default != Parameter.empty:
+            tap_kwargs['default'] = param.default
+        else:
+            tap_kwargs['required'] = True
+
+        # Get the help string of the argument
+        if param.name in param_to_description:
+            tap.class_variables[param.name] = {'comment': param_to_description[param.name]}
+
+        # Add the argument to the Tap object
+        tap._add_argument(f'--{param_name}', **tap_kwargs)
+
+    # If any func_kwargs remain, they are not used in the function, so raise an error
+    if func_kwargs and not known_only:
+        raise ValueError(f'Unknown keyword arguments: {func_kwargs}')
+
+    # Parse command line arguments
+    args = tap.parse_args(
+        args=args,
+        known_only=known_only
+    )
+
+    # Initialize the class or run the function with the parsed arguments
+    return class_or_function(**args.as_dict())

tests/test_actions.py

@@ -220,7 +220,7 @@ def configure(self):
 
         help_regex = r'.*positional arguments:\n.*arg\s*\(str, required\).*'
         help_text = PositionalDefault().format_help()
-        self.assertRegexpMatches(help_text, help_regex)
+        self.assertRegex(help_text, help_regex)
 
 
 if __name__ == '__main__':