Merge branch 'tapify' into main

Author: swansonk14

README.md

@@ -22,9 +22,24 @@ Tap provides the following benefits:
 
 See [this poster](https://docs.google.com/presentation/d/1AirN6gpiq4P1L8K003EsXmobVxP3A4AVEIR2KOEQN7Y/edit?usp=sharing), which we presented at [PyCon 2020](https://us.pycon.org/2020/), for a presentation of some of the relevant concepts we used to guide the development of Tap. 
 
+As of version 1.8.0, Tap includes `tapify`, which runs functions or initializes classes with arguments parsed from the command line. We show an example below.
+
+```python
+# square.py
+from tap import tapify
+
+def square(num: float) -> float:
+    return num ** 2
+
+if __name__ == '__main__':
+    print(f'The square of your number is {tapify(square)}.')
+```
+
+Running `python square.py --num 2` will print `The square of your number is 4.0.`. Please see [tapify](#tapify) for more details.
+
 ## Installation
 
-Tap requires Python 3.6+
+Tap requires Python 3.7+
 
 To install Tap from PyPI run: 
 ```
@@ -46,31 +61,26 @@ pip install -e .
 * [Tap is Python-native](#tap-is-python-native)
 * [Tap features](#tap-features)
   + [Arguments](#arguments)
-  + [Help string](#help-string)
-  + [Flexibility of `configure`](#flexibility-of--configure-)
+  + [Tap help](#tap-help)
+  + [Configuring arguments](#configuring-arguments)
     - [Adding special argument behavior](#adding-special-argument-behavior)
     - [Adding subparsers](#adding-subparsers)
   + [Types](#types)
-    - [`str`, `int`, and `float`](#-str----int---and--float-)
-    - [`bool`](#-bool-)
-    - [`Optional`](#-optional-)
-    - [`List`](#-list-)
-    - [`Set`](#-set-)
-    - [`Tuple`](#-tuple-)
-    - [`Literal`](#-literal-)
-    - [`Union`](#-union-)
-    - [Complex Types](#complex-types)
-  + [Argument processing with `process_args`](#argument-processing-with--process-args-)
+  + [Argument processing](#argument-processing)
   + [Processing known args](#processing-known-args)
   + [Subclassing](#subclassing)
   + [Printing](#printing)
   + [Reproducibility](#reproducibility)
-    - [Reproducibility info](#reproducibility-info)
   + [Saving and loading arguments](#saving-and-loading-arguments)
-    - [Save](#save)
-    - [Load](#load)
-    - [Load from dict](#load-from-dict)
   + [Loading from configuration files](#loading-from-configuration-files)
+* [tapify](#tapify)
+  + [Examples](#examples)
+    - [Function](#function)
+    - [Class](#class)
+    - [Dataclass](#dataclass)
+  + [tapify help](#tapify-help)
+  + [Command line vs explicit arguments](#command-line-vs-explicit-arguments)
+  + [Known args](#known-args)
 
 ## Tap is Python-native
 
@@ -143,7 +153,7 @@ class MyTap(Tap):
     default_arg: str = 'default value'
 ```
 
-### Help string
+### Tap help
 
 Single line and/or multiline comments which appear after the argument are automatically parsed into the help string provided when running `python main.py -h`. The type and default values of arguments are also provided in the help string.
 
@@ -172,7 +182,7 @@ optional arguments:
   -h, --help  show this help message and exit
 ```
 
-### Flexibility of `configure`
+### Configuring arguments
 To specify behavior beyond what can be specified using arguments as class variables, override the `configure` method.
 `configure` provides access to advanced argument parsing features such as `add_argument` and `add_subparser`.
 Since Tap is a wrapper around argparse, Tap provides all of the same functionality.
@@ -329,7 +339,7 @@ print(f'{args.aged_person.name} is {args.aged_person.age}')  # Tapper is 27
 ```
 
 
-### Argument processing with `process_args`
+### Argument processing
 
 With complex argument parsing, arguments often end up having interdependencies. This means that it may be necessary to disallow certain combinations of arguments or to modify some arguments based on other arguments.
 
@@ -565,3 +575,150 @@ args = Args(config_files=['my_config_shlex.txt']).parse_args()
 to get the resulting `args = {'arg1': 21, 'arg2': 'two three four'}`
 
 The legacy parsing behavior of using standard string split can be re-enabled by passing `legacy_config_parsing=True` to `parse_args`.
+
+## tapify
+
+`tapify` makes it possible to run functions or initialize objects via command line arguments. This is inspired by Google's [Python Fire](https://github.com/google/python-fire), but `tapify` also automatically casts command line arguments to the appropriate types based on the type hints. Under the hood, `tapify` implicitly creates a Tap object and uses it to parse the command line arguments, which it then uses to run the function or initialize the class. We show a few examples below.
+
+### Examples
+
+#### Function
+
+```python
+# square_function.py
+from tap import tapify
+
+def square(num: float) -> float:
+    """Square a number.
+
+    :param num: The number to square.
+    """
+    return num ** 2
+
+if __name__ == '__main__':
+    squared = tapify(square)
+    print(f'The square of your number is {squared}.')
+```
+
+Running `python square_function.py --num 5` prints `The square of your number is 25.0.`.
+
+#### Class
+
+```python
+# square_class.py
+from tap import tapify
+
+class Squarer:
+    def __init__(self, num: float) -> None:
+        """Initialize the Squarer with a number to square.
+
+        :param  num: The number to square.
+        """
+        self.num = num
+
+    def get_square(self) -> float:
+        """Get the square of the number."""
+        return self.num ** 2
+
+if __name__ == '__main__':
+    squarer = tapify(Squarer)
+    print(f'The square of your number is {squarer.get_square()}.')
+```
+
+Running `python square_class.py --num 2` prints `The square of your number is 4.0.`.
+
+#### Dataclass
+
+```python
+# square_dataclass.py
+from dataclasses import dataclass
+
+from tap import tapify
+
+@dataclass
+class Squarer:
+    """Squarer with a number to square.
+
+     :param  num: The number to square.
+    """
+    num: float
+
+    def get_square(self) -> float:
+        """Get the square of the number."""
+        return self.num ** 2
+
+if __name__ == '__main__':
+    squarer = tapify(Squarer)
+    print(f'The square of your number is {squarer.get_square()}.')
+```
+
+Running `python square_dataclass.py --num -1` prints `The square of your number is 1.0.`.
+
+### tapify help
+
+The help string on the command line is set based on the docstring for the function or class. For example, running `python square_function.py -h` will print:
+
+```
+usage: square_function.py [-h] --num NUM
+
+Square a number.
+
+options:
+  -h, --help  show this help message and exit
+  --num NUM   (float, required) The number to square.
+```
+
+Note that for classes, if there is a docstring in the `__init__` method, then `tapify` sets the help string description to that docstring. Otherwise, it uses the docstring from the top of the class.
+
+### Command line vs explicit arguments
+
+`tapify` can simultaneously use both arguments passed from the command line and arguments passed in explicitly in the `tapify` call. Arguments provided in the `tapify` call override function defaults, and arguments provided via the command line override both arguments provided in the `tapify` call and function defaults. We show an example below.
+
+```python
+# add.py
+from tap import tapify
+
+def add(num_1: float, num_2: float = 0.0, num_3: float = 0.0) -> float:
+    """Add numbers.
+
+    :param num_1: The first number.
+    :param num_2: The second number.
+    :param num_3: The third number.
+    """
+    return num_1 + num_2 + num_3
+
+if __name__ == '__main__':
+    added = tapify(add, num_2=2.2, num_3=4.1)
+    print(f'The sum of your numbers is {added}.')
+```
+
+Running `python add.py --num_1 1.0 --num_2 0.9` prints `The sum of your numbers is 6.0.`. (Note that `add` took `num_1 = 1.0` and `num_2 = 0.9` from the command line and `num_3=4.1` from the `tapify` call due to the order of precedence.)
+
+### Known args
+
+Calling `tapify` with `known_only=True` allows `tapify` to ignore additional arguments from the command line that are not needed for the function or class. If `known_only=False` (the default), then `tapify` will raise an error when additional arguments are provided. We show an example below where `known_only=True` might be useful for running multiple `tapify` calls.
+
+```python
+# person.py
+from tap import tapify
+
+def print_name(name: str) -> None:
+    """Print a person's name.
+
+    :param name: A person's name.
+    """
+    print(f'My name is {name}.')
+
+def print_age(age: int) -> None:
+    """Print a person's age.
+
+    :param name: A person's age.
+    """
+    print(f'My age is {age}.')
+
+if __name__ == '__main__':
+    tapify(print_name, known_only=True)
+    tapify(print_age, known_only=True)
+```
+
+Running `python person.py --name Jesse --age 1` prints `My name is Jesse.` followed by `My age is 1.`. Without `known_only=True`, the `tapify` calls would raise an error due to the extra argument.

tap/tapify.py

@@ -11,14 +11,15 @@
 
 
 def tapify(class_or_function: Union[Callable[[InputType], OutputType], OutputType],
-           args: Optional[List[str]] = None,
            known_only: bool = False,
+           command_line_args: Optional[List[str]] = None,
            **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 command_line_args: A list of command line style arguments to parse (e.g., ['--arg', 'value']).
+                              If None, arguments are parsed from the command line (default behavior).
     :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.
@@ -38,7 +39,7 @@ def tapify(class_or_function: Union[Callable[[InputType], OutputType], OutputTyp
     # 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
+    # Create a Tap object with a description from the docstring of the function or class
     tap = Tap(description='\n'.join(filter(None, (docstring.short_description, docstring.long_description))))
 
     # Add arguments of class init or function to the Tap object
@@ -75,10 +76,10 @@ def tapify(class_or_function: Union[Callable[[InputType], OutputType], OutputTyp
         raise ValueError(f'Unknown keyword arguments: {func_kwargs}')
 
     # Parse command line arguments
-    args = tap.parse_args(
-        args=args,
+    command_line_args = tap.parse_args(
+        args=command_line_args,
         known_only=known_only
     )
 
     # Initialize the class or run the function with the parsed arguments
-    return class_or_function(**args.as_dict())
+    return class_or_function(**command_line_args.as_dict())