func-args

library1.0.2pypypi✓ verified 23d ago

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.

serialization

pip install func-args

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · FUNC-ARGS

func-args

serializationpythonv1.0.2

Install

1.5s avg

Import

56ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.060s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.052s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

arg

✓ from func_args import arg

✗ from func_args import delegator

exc

✓ from func_args import exc

resolve_kwargs

✓ from func_args import resolve_kwargs

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}")

Debug

Known issues

gotchaThe `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.

affects: All versions

breakingOmitting 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.

affects: All versions

gotchaWhile `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 = []`.

affects: All versions

Upgrade

Version history

1.0.2latest on PyPI · released Apr 28, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/MacHu-GWU/func_args-project ↗

packagehttps://pypi.org/project/func-args/ ↗

docshttps://func-args.readthedocs.io/en/latest/ ↗

changeloghttps://github.com/MacHu-GWU/func_args-project/blob/main/release-history.rst ↗