Function Argument Wrapper for Enhanced Handling

1.0.1 · active · verified Mon Apr 13

func-args is a lightweight Python library (current version 1.0.1) designed for creating wrapper functions with enhanced argument handling. It addresses common challenges encountered with third-party APIs that have suboptimal interface designs, allowing developers to explicitly mark parameters as required or optional using special sentinel values (REQ and OPT). The library is actively maintained with a stable release cadence.

Warnings

gotcha The `OPT` sentinel value is distinct from `None`. When an optional parameter is not provided, its value will be the `OPT` object, not `None`. Always check `if my_param is not OPT:` if you need to differentiate an omitted argument from an explicit `None`.
Fix: Use `if my_param is not OPT:` to check if an optional argument was truly provided, rather than `if my_param is not None:` if `None` is a valid explicit value.
breaking Omitting a parameter marked with `REQ` will result in a `TypeError`, as the `delegator` decorator enforces its presence. This behavior ensures explicit argument handling and early error detection.
Fix: Ensure all parameters marked with `REQ` are always provided when calling the function. The `TypeError` message will indicate which required argument is missing.
gotcha While `func-args` provides a mechanism for explicit argument handling, it does not directly prevent the general Python 'mutable default argument' footgun. If you assign a mutable object (like a list or dictionary) as a default value to a parameter *not* using `OPT`, that object will be shared across all calls to the function.
Fix: For mutable default arguments, always initialize the mutable object inside the function if the argument is `OPT` (or `None` if `OPT` is not used), e.g., `if my_list is OPT: my_list = []`.

Install

pip install func-args Install func-args

Imports

delegator
```
from func_args import delegator
```
REQ
```
from func_args import REQ
```
OPT
```
from func_args import OPT
```

Quickstart

This example demonstrates how to define a function using the `@delegator` decorator and `REQ`/`OPT` sentinel values. `REQ` marks a parameter as mandatory, ensuring a `TypeError` is raised if it's not provided. `OPT` acts as a placeholder for optional parameters, allowing you to differentiate between an explicitly passed `None` and an omitted optional argument.

from func_args import REQ, OPT, delegator

@delegator
def my_function(required_param: REQ, optional_param: OPT = None):
    """An example function using REQ and OPT for argument handling."""
    print(f"Required: {required_param}")
    if optional_param is not OPT:
        print(f"Optional: {optional_param}")
    else:
        print("Optional parameter was not provided.")
    return {"required": required_param, "optional": optional_param}

# Example 1: Providing both required and optional
result1 = my_function(required_param="hello", optional_param="world")
print(f"Result 1: {result1}")

# Example 2: Providing only required, optional defaults to OPT sentinel
result2 = my_function(required_param=123)
print(f"Result 2: {result2}")

# Example 3: Missing a required argument (will raise TypeError)
try:
    my_function()
except TypeError as e:
    print(f"Error: {e}")

view raw JSON →