From c6faf13a0283426cf65e99be48b4fe17f6c86914 Mon Sep 17 00:00:00 2001 From: Hans-Martin von Gaudecker Date: Wed, 20 May 2026 09:56:20 +0200 Subject: [PATCH 1/3] Fix with_signature docstring: it does support type hints The caveat claimed type hints could not be set. They can: the dict form of args/kwargs maps names to type strings, and return_annotation sets the return type. Reword the caveat and parameter descriptions to reflect this; default values remain unsupported. --- src/dags/signature.py | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/src/dags/signature.py b/src/dags/signature.py index 7bea8e6..9b2413f 100644 --- a/src/dags/signature.py +++ b/src/dags/signature.py @@ -83,30 +83,34 @@ def with_signature( ) -> Callable[P, R] | Callable[[Callable[P, R]], Callable[P, R]]: """Add a signature to a function of type `f(*args, **kwargs)` (decorator). - The user-described view (parameter names, kinds, and any type strings - passed via `args` / `kwargs`) is written to the wrapper's - `__signature__`. The wrapper's `__annotations__` advertises the - `*args, **kwargs` forwarder shape instead — the wrapper genuinely + The user-described view (parameter names, kinds, and any type hints passed + via the dict form of `args` / `kwargs` or via `return_annotation`) is written + to the wrapper's `__signature__`. The wrapper's `__annotations__` advertises + the `*args, **kwargs` forwarder shape instead — the wrapper genuinely accepts anything at the Python level, and only the wrapped function expects the user-typed arguments. Runtime type checkers (beartype, typeguard) read `__annotations__` and therefore treat the wrapper as permissive; `dags.get_annotations` recovers the user view from `__signature__` via its built-in args/kwargs-mismatch fallback. - Caveats: The created signature only contains the names of arguments and whether - they are keyword-only. There is no way of setting default values or type hints. + The created signature carries argument names, whether each argument is + keyword-only, and—when the dict form of `args`/`kwargs` is used or + `return_annotation` is set—parameter and return type hints (written to + `__signature__`, as described above). Default values cannot be set. Args: func: The function to be decorated. Should take `*args` and `**kwargs` as only arguments. args: If a list, the names of positional or keyword arguments. If a dict, - the names of positional or keyword arguments and their types as strings. + the names of positional or keyword arguments mapped to their type hints + (as strings). kwargs: If a list, the names of keyword only arguments. If a dict, - the names of keyword only arguments and their types as strings. + the names of keyword only arguments mapped to their type hints (as + strings). enforce: Whether the signature should be enforced or just added to the function for introspection. This creates runtime overhead. - return_annotation: The return annotation. By default, the return annotation is + return_annotation: The return type hint. By default, the return annotation is `inspect.Parameter.empty`. Returns: From 11082b159a324ae09d7aa269574254f7c6ecc02f Mon Sep 17 00:00:00 2001 From: Hans-Martin von Gaudecker Date: Wed, 20 May 2026 10:11:37 +0200 Subject: [PATCH 2/3] Use "annotation" for the return_annotation param description The param holds an inspect-style annotation (it accepts the inspect.Parameter.empty sentinel, which is not a type hint) and is named return_annotation. "Type hint" stays in the caveat and the args/kwargs dict-form descriptions, where the claim is genuinely about expressing types. --- src/dags/signature.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/dags/signature.py b/src/dags/signature.py index 9b2413f..f85bfa1 100644 --- a/src/dags/signature.py +++ b/src/dags/signature.py @@ -110,7 +110,7 @@ def with_signature( enforce: Whether the signature should be enforced or just added to the function for introspection. This creates runtime overhead. - return_annotation: The return type hint. By default, the return annotation is + return_annotation: The return annotation. By default, it is `inspect.Parameter.empty`. Returns: From a88ca4bfc98be96b3a8c33a8e78c8c5258bf45d8 Mon Sep 17 00:00:00 2001 From: Hans-Martin von Gaudecker Date: Fri, 22 May 2026 19:26:44 +0200 Subject: [PATCH 3/3] Document with_signature type-hint support in api.md Mirrors the docstring correction: the dict form of `args`/`kwargs` and `return_annotation` set parameter and return type hints on the wrapper's `__signature__`; default values remain unsupported. Co-Authored-By: Claude Opus 4.7 --- docs/api.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/api.md b/docs/api.md index cbbd281..c1ce868 100644 --- a/docs/api.md +++ b/docs/api.md @@ -121,7 +121,9 @@ with_signature( ``` Add a signature to a function of type `f(*args, **kwargs)`. Can be used as a decorator -with or without arguments. +with or without arguments. The dict form of `args`/`kwargs` maps parameter names to +type-hint strings and `return_annotation` sets the return type — both written to the +wrapper's `__signature__`. Default values cannot be set. `dags.signature`