From 8910859fe175306c93bd62da6e5f70f82d13d2e1 Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Tue, 17 Nov 2026 23:43:51 -0800 Subject: [PATCH 1/5] fix(data_function): -> None declares no outputs; refuse a returned value and positional-only parameters (ITL-1257, ITL-1258) - extract_function_schemas reads get_type_hints' NoneType as -> None, so the existing branch runs: -> None with no output keys means no outputs (as no return annotation does); -> None with output keys is refused at construction (it gave an output column of type NoneType). - A function with no output keys that returns a value other than None raises NoOutputsDeclaredError (an OutputTypeError) at call time, sync and async, instead of the value being dropped. - A positional-only parameter is refused at construction, naming it, as variadic parameters are: a pod passes its inputs by name. Tests for PythonDataFunction, @function_pod and FunctionPod.from_fn, with live and string annotations, sync and async; docs, changelog fragment, design issue ITL-1257-NR1. Co-Authored-By: Claude Opus 5.5 --- changelog.d/ITL-1257.md | 16 ++ docs/concepts/function-pods.md | 12 +- docs/dev/design_issues/ITL-1257-NR1.md | 23 ++ src/orcapod/core/data_function.py | 25 +- src/orcapod/errors.py | 36 +++ src/orcapod/utils/schema_utils.py | 5 + .../string_annotated_functions.py | 22 ++ .../data_function/test_none_return.py | 247 ++++++++++++++++++ .../data_function/test_positional_only.py | 75 ++++++ 9 files changed, 458 insertions(+), 3 deletions(-) create mode 100644 changelog.d/ITL-1257.md create mode 100644 docs/dev/design_issues/ITL-1257-NR1.md create mode 100644 tests/test_core/data_function/string_annotated_functions.py create mode 100644 tests/test_core/data_function/test_none_return.py create mode 100644 tests/test_core/data_function/test_positional_only.py diff --git a/changelog.d/ITL-1257.md b/changelog.d/ITL-1257.md new file mode 100644 index 000000000..76019d5d6 --- /dev/null +++ b/changelog.d/ITL-1257.md @@ -0,0 +1,16 @@ +### Breaking changes and migration + +- A function with no `output_keys` that returns a value other than `None` raises + `NoOutputsDeclaredError` (an `OutputTypeError`) instead of having the value dropped + (ITL-1257). Add an output key for the value, or return nothing. + +### Fixed + +- A function annotated `-> None` with no `output_keys` is accepted as a function with no + outputs, like a function with no return annotation (ITL-1257). It was refused ("has a + return type annotation, but no return keys were specified") because `typing.get_type_hints` + reads `-> None` as `NoneType`. `-> None` with `output_keys` is now refused when the pod is + created; it was accepted and gave an output column of type `NoneType`. +- A function with a positional-only parameter is refused when the pod is created, naming + the parameter (ITL-1258). A pod passes its inputs by name, so every call of such a pod + failed with a `TypeError`. diff --git a/docs/concepts/function-pods.md b/docs/concepts/function-pods.md index b6e1f475b..184166639 100644 --- a/docs/concepts/function-pods.md +++ b/docs/concepts/function-pods.md @@ -23,7 +23,14 @@ def compute_bmi(weight: float, height: float) -> float: Key points: - **`output_keys`** names the output data column(s). A single string means one output - column; a list of strings means the function returns multiple values. + column; a list of strings means the function returns multiple values. A function with + no outputs (it only reads its inputs) is annotated `-> None`, or not annotated, and + takes no `output_keys`; its pod has no output columns. `-> None` together with + `output_keys` raises `ValueError` when the pod is created, and a value other than + `None` returned by a function with no outputs raises `NoOutputsDeclaredError` (an + `OutputTypeError`): add an output key for it, or return nothing. An output that may be + missing is not "no outputs": it is one output key typed `T | None`, and a returned + `None` is stored as a null. - **Function parameters** are matched to the input stream's data columns by name: one data column per parameter. A parameter with a default value may be left out of the stream, and the default is used. Data columns the function does not take are dropped when the pod is @@ -34,6 +41,9 @@ Key points: dataclass instance, raises `TypeError` when the pod is created, naming the parameter. Use a hashable default and build the object inside the function, or supply the value as an input column. See [Function values and parameter defaults](../reference/hashing.md#1d-function-values-and-parameter-defaults). +- **Inputs are passed by name.** A parameter may be keyword-only (after `*`), but a + positional-only parameter (before `/`) and `*args` / `**kwargs` raise `ValueError` + when the pod is created. - **Parameter types** are used to validate schema compatibility. Give each parameter a type annotation, or supply its type through the decorator's `input_schema` mapping. A parameter with neither raises `ValueError` when the pod is created. diff --git a/docs/dev/design_issues/ITL-1257-NR1.md b/docs/dev/design_issues/ITL-1257-NR1.md new file mode 100644 index 000000000..8819b3f66 --- /dev/null +++ b/docs/dev/design_issues/ITL-1257-NR1.md @@ -0,0 +1,23 @@ +## `src/orcapod/core/data_function.py` — returned values not checked against the declared type + +### NR1 — `-> None` with no output keys was refused; a value returned with no outputs was dropped +**Status:** resolved +**Severity:** medium +**Issue:** ITL-1257 (related: ITL-1258) + +`extract_function_schemas` (`utils/schema_utils.py`) has a branch for a function annotated +`-> None`: with no output keys it means no outputs, with output keys it is refused. The +branch was never reached, because `typing.get_type_hints` reads `-> None` as `NoneType`: +`-> None` with no output keys was refused ("has a return type annotation, but no return +keys were specified"), while `-> None` with one output key was accepted with an output +column of type `NoneType`. Separately, a function with no output keys that returned a +value had the value dropped silently (`parse_function_outputs`). + +**Fix:** `extract_function_schemas` reads `NoneType` as `-> None`, so `-> None` with no +output keys means no outputs (as no return annotation does) and `-> None` with output keys +is refused at construction. A function with no output keys that returns a value other +than `None` raises `NoOutputsDeclaredError`, an `OutputTypeError`, at call time, on the +sync and the async path (developer: "declared `-> None` (or lack of any return type) should +be treated as empty return"). Tests: `tests/test_core/data_function/test_none_return.py`. +In the same change, a positional-only parameter is refused at construction (ITL-1258; +`test_positional_only.py`). diff --git a/src/orcapod/core/data_function.py b/src/orcapod/core/data_function.py index 4c6213d74..7bbf0bfd2 100644 --- a/src/orcapod/core/data_function.py +++ b/src/orcapod/core/data_function.py @@ -21,7 +21,7 @@ get_function_components, ) from orcapod.core.result_cache import ResultCache -from orcapod.errors import OutputTypeError +from orcapod.errors import NoOutputsDeclaredError, OutputTypeError from orcapod.protocols.core_protocols import DataFunctionProtocol, DataProtocol from orcapod.protocols.core_protocols.executor import ( DataFunctionExecutorProtocol, @@ -80,7 +80,8 @@ def parse_function_outputs( Map raw function return values to a keyed output dict. Rules: - - ``output_keys = []``: return value is ignored; empty dict returned. + - ``output_keys = []``: empty dict returned. ``PythonDataFunction`` refuses a + returned value other than ``None`` before this is called (ITL-1257). - ``output_keys = ["result"]``: any value (including iterables) is stored as-is under the single key. - ``output_keys = ["a", "b", ...]``: ``values`` must be iterable and its length @@ -439,6 +440,20 @@ def __init__( f"parameters (*args / **kwargs). " f"Offending parameters: {_variadic!r}." ) + # A pod passes its inputs by name, so a positional-only parameter could never + # be given (ITL-1258). + _positional_only = [ + name + for name, param in _sig.parameters.items() + if param.kind is inspect.Parameter.POSITIONAL_ONLY + ] + if _positional_only: + raise ValueError( + f"PythonDataFunction does not support functions with positional-only " + f"parameters: a function pod passes its inputs by name. " + f"Offending parameters: {_positional_only!r}; remove the '/' from the " + f"signature." + ) if output_keys is None: output_keys = [] @@ -617,9 +632,15 @@ def _build_output_data(self, values: Any) -> DataProtocol: A Data containing the parsed outputs with source info. Raises: + NoOutputsDeclaredError: If the function declares no outputs and returned a + value other than ``None``. OutputTypeError: If a returned value does not conform to its declared type, or cannot be converted to it. """ + if not self._output_keys and values is not None: + # No output keys declare an empty return (ITL-1257): a returned value + # contradicts the declaration and is refused, never dropped. + raise NoOutputsDeclaredError(self.canonical_function_name, values) output_data = parse_function_outputs(self._output_keys, values) output_schema = self.output_data_schema for key, value in output_data.items(): diff --git a/src/orcapod/errors.py b/src/orcapod/errors.py index 1cced3d37..2017d6830 100644 --- a/src/orcapod/errors.py +++ b/src/orcapod/errors.py @@ -362,6 +362,42 @@ def __reduce__(self) -> tuple[object, ...]: ) +class NoOutputsDeclaredError(OutputTypeError): + """A function that declares no outputs returned a value (ITL-1257). + + A function with no ``output_keys``, annotated ``-> None`` or not annotated, declares + an empty return: the number of outputs is the number of output keys. A returned value + other than ``None`` contradicts the declaration, so it is refused rather than + dropped. It is an ``OutputTypeError``, so a pipeline treats it as one: a row failure + under ``error_policy``. + + Attributes: + function_name: Name of the function pod's function. + value: The value the function returned. + """ + + def __init__(self, function_name: str, value: object) -> None: + """Create the error for one call. + + Args: + function_name: Name of the function pod's function. + value: The value the function returned. + """ + self.function_name: str = function_name + self.value: object = value + # Types only, never the value (see ``OutputTypeError``). + TypeError.__init__( + self, + f"Function {function_name!r} declares no outputs (no output_keys) but " + + f"returned {type_text(type(value))}. Add an output key for the value, " + + "or return nothing.", + ) + + def __reduce__(self) -> tuple[object, ...]: + """Pickle with the constructor arguments (executors send errors across processes).""" + return (type(self), (self.function_name, self.value)) + + class UnboundSourceError(RuntimeError): """Raised when a data-producing method is called on an unbound SourceNode. diff --git a/src/orcapod/utils/schema_utils.py b/src/orcapod/utils/schema_utils.py index 3bd3ec5d4..241ce0919 100644 --- a/src/orcapod/utils/schema_utils.py +++ b/src/orcapod/utils/schema_utils.py @@ -259,6 +259,11 @@ def extract_function_schemas( # get_type_hints stores the return annotation under the key 'return' return_annot = resolved_hints.get("return", signature.return_annotation) + # get_type_hints turns ``-> None`` into ``NoneType``. ``-> None`` declares no + # outputs (ITL-1257), which is not an output whose value is None: the number of + # outputs is the number of output keys. + if return_annot is type(None): + return_annot = None inferred_output_types: Schema = {} if return_annot is not inspect.Signature.empty and return_annot is not None: output_item_types = [] diff --git a/tests/test_core/data_function/string_annotated_functions.py b/tests/test_core/data_function/string_annotated_functions.py new file mode 100644 index 000000000..3b0fc2229 --- /dev/null +++ b/tests/test_core/data_function/string_annotated_functions.py @@ -0,0 +1,22 @@ +"""Functions whose annotations are strings (``from __future__ import annotations``). + +Used by ``test_none_return.py`` (ITL-1257): ``-> None`` read through +``typing.get_type_hints`` from a string annotation. +""" + +from __future__ import annotations + + +def log_value(x: int) -> None: + """Declares no outputs.""" + del x + + +def log_value_unannotated(x: int): # no return annotation on purpose + """Declares no outputs by having no return annotation.""" + del x + + +def maybe(x: int) -> int | None: + """One output that may be null.""" + return None if x < 0 else x diff --git a/tests/test_core/data_function/test_none_return.py b/tests/test_core/data_function/test_none_return.py new file mode 100644 index 000000000..31989ed1e --- /dev/null +++ b/tests/test_core/data_function/test_none_return.py @@ -0,0 +1,247 @@ +"""A function annotated ``-> None`` declares no outputs (ITL-1257). + +``-> None`` with no output keys means no outputs, exactly like a function with no return +annotation and no keys: an empty output schema. ``-> None`` with output keys is refused +at construction. An output whose value is None is something else: one output key whose +type allows null (``-> int | None``). + +``typing.get_type_hints`` turns ``-> None`` into ``NoneType``; each case is tested with +live annotations (this module) and with string annotations +(``string_annotated_functions``, ``from __future__ import annotations``), for +``PythonDataFunction``, ``@function_pod`` and ``FunctionPod.from_fn``. +""" + +import asyncio +import pickle +from collections.abc import Callable +from typing import Any + +import pytest + +from orcapod import function_pod +from orcapod.core.data_function import PythonDataFunction +from orcapod.core.datagrams import Data +from orcapod.core.function_pod import FunctionPod +from orcapod.core.sources import DictSource +from orcapod.errors import NoOutputsDeclaredError, OutputTypeError + +from . import string_annotated_functions as strings + +REFUSAL = "return type annotation as None, but return keys" + + +def log_value(x: int) -> None: + """Declares no outputs.""" + del x + + +def log_value_unannotated(x: int): # no return annotation on purpose + """Declares no outputs by having no return annotation.""" + del x + + +def maybe(x: int) -> int | None: + """One output that may be null.""" + return None if x < 0 else x + + +async def log_value_async(x: int) -> None: + """Declares no outputs; async.""" + del x + + +NO_OUTPUTS = { + "live": log_value, + "string": strings.log_value, + "async": log_value_async, +} +UNANNOTATED = {"live": log_value_unannotated, "string": strings.log_value_unannotated} +MAYBE = {"live": maybe, "string": strings.maybe} + + +def _build(form: str, fn: Callable[..., Any], output_keys: Any) -> Any: + """The data function of a pod built in ``form``.""" + if form == "data_function": + if output_keys is None: + return PythonDataFunction(fn) + return PythonDataFunction(fn, output_keys=output_keys) + if form == "decorator": + if output_keys is None: + return function_pod()(fn).pod.data_function + return function_pod(output_keys=output_keys)(fn).pod.data_function + if form == "from_fn": + return FunctionPod.from_fn(fn, output_keys=output_keys or []).data_function + raise ValueError(form) + + +FORMS = ["data_function", "decorator", "from_fn"] + + +@pytest.mark.parametrize("form", FORMS) +@pytest.mark.parametrize("annotations", list(NO_OUTPUTS)) +@pytest.mark.parametrize("output_keys", [None, []], ids=["keys_omitted", "keys_empty"]) +def test_none_with_no_output_keys_declares_no_outputs( + form: str, annotations: str, output_keys: Any +) -> None: + data_function = _build(form, NO_OUTPUTS[annotations], output_keys) + assert dict(data_function.output_data_schema) == {} + assert dict(data_function.input_data_schema) == {"x": int} + + +@pytest.mark.parametrize("form", FORMS) +@pytest.mark.parametrize("annotations", list(UNANNOTATED)) +def test_none_and_no_annotation_are_one_output_schema( + form: str, annotations: str +) -> None: + """``-> None`` and no annotation: the same output schema, so the same uri part.""" + annotated = _build(form, NO_OUTPUTS[annotations], None) + unannotated = _build(form, UNANNOTATED[annotations], None) + assert annotated.output_data_schema == unannotated.output_data_schema + assert annotated.uri[1:] == unannotated.uri[1:] + + +@pytest.mark.parametrize("form", FORMS) +@pytest.mark.parametrize("annotations", list(NO_OUTPUTS)) +@pytest.mark.parametrize( + "output_keys", ["result", ["first", "second"]], ids=["one", "two"] +) +def test_none_with_output_keys_is_refused( + form: str, annotations: str, output_keys: Any +) -> None: + with pytest.raises(ValueError, match=REFUSAL): + _build(form, NO_OUTPUTS[annotations], output_keys) + + +@pytest.mark.parametrize("annotations", list(NO_OUTPUTS)) +def test_a_function_with_no_outputs_runs_and_gives_empty_data(annotations: str) -> None: + """Called per row, sync and async, with no output columns; tags pass through.""" + data_function = PythonDataFunction(NO_OUTPUTS[annotations]) + if data_function.is_async: + result = asyncio.run(data_function.async_call(Data({"x": 1}))) + else: + result = data_function.call(Data({"x": 1})) + assert result is not None + assert result.as_dict() == {} + + source = DictSource( + [{"k": "a", "j": 1, "x": 1}, {"k": "b", "j": 2, "x": 2}], + tag_columns=["k", "j"], + tag_only_columns=True, + source_id="s", + ) + stream = FunctionPod(data_function)(source) # pyright: ignore[reportArgumentType] # PythonDataFunction is not yet typed as matching DataFunctionProtocol; it works at runtime + tag_keys, data_keys = stream.keys() + assert tuple(tag_keys) == ("k", "j") + assert tuple(data_keys) == () + assert sorted(str(tag.as_dict()["k"]) for tag, _ in stream.iter_data()) == [ + "a", + "b", + ] + + +@pytest.mark.parametrize("form", FORMS) +@pytest.mark.parametrize("annotations", list(MAYBE)) +def test_one_output_whose_value_is_none_is_a_null_value( + form: str, annotations: str +) -> None: + """An output whose value is None is not "no outputs": a null of a nullable type.""" + data_function = _build(form, MAYBE[annotations], "value") + assert dict(data_function.output_data_schema) == {"value": int | None} + null = data_function.call(Data({"x": -1})) + present = data_function.call(Data({"x": 3})) + assert null is not None and present is not None + assert null.as_dict() == {"value": None} + assert present.as_dict() == {"value": 3} + + +# A function that declares no outputs but returns a value: refused (ITL-1257 decision). + + +def returns_status(x: int) -> None: + """Declares no outputs, but returns a value.""" + return x # pyright: ignore[reportReturnType] # the contradiction under test + + +def returns_status_unannotated(x: int): # no return annotation on purpose + """Declares no outputs by having no return annotation, but returns a value.""" + return x + + +async def returns_status_async(x: int) -> None: + """Declares no outputs, but returns a value; async.""" + return x # pyright: ignore[reportReturnType] # the contradiction under test + + +RETURNS_A_VALUE = { + "annotated": returns_status, + "unannotated": returns_status_unannotated, + "async": returns_status_async, +} + + +def _call(data_function: Any, x: int) -> Any: + if data_function.is_async: + return asyncio.run(data_function.async_call(Data({"x": x}))) + return data_function.call(Data({"x": x})) + + +@pytest.mark.parametrize("form", FORMS) +@pytest.mark.parametrize("declaration", list(RETURNS_A_VALUE)) +def test_a_value_returned_by_a_function_with_no_outputs_is_refused( + form: str, declaration: str +) -> None: + data_function = _build(form, RETURNS_A_VALUE[declaration], None) + with pytest.raises(NoOutputsDeclaredError) as raised: + _call(data_function, 7) + error = raised.value + assert isinstance(error, OutputTypeError) + assert error.function_name == RETURNS_A_VALUE[declaration].__name__ + assert error.value == 7 + message = str(error) + assert repr(RETURNS_A_VALUE[declaration].__name__) in message + assert "declares no outputs" in message + assert "Add an output key" in message and "return nothing" in message + # Types only, never the value. + assert "7" not in message + + +def explicit_none(x: int) -> None: + del x + return None # explicit on purpose + + +def bare_return(x: int) -> None: + del x + return # explicit on purpose + + +def falls_off_the_end(x: int): # no return annotation on purpose + del x + + +@pytest.mark.parametrize("fn", [explicit_none, bare_return, falls_off_the_end]) +def test_returning_none_is_returning_nothing(fn: Callable[..., Any]) -> None: + assert _call(PythonDataFunction(fn), 1).as_dict() == {} + + +def test_a_pod_over_a_stream_refuses_the_returned_value() -> None: + source = DictSource( + [{"k": "a", "j": 1, "x": 1}, {"k": "b", "j": 2, "x": 2}], + tag_columns=["k", "j"], + tag_only_columns=True, + source_id="s", + ) + stream = function_pod()(returns_status).pod(source) + with pytest.raises(NoOutputsDeclaredError): + list(stream.iter_data()) + + +def test_the_error_pickles_with_its_arguments() -> None: + error = NoOutputsDeclaredError("f", 3) + restored = pickle.loads(pickle.dumps(error)) + assert type(restored) is NoOutputsDeclaredError + assert (restored.function_name, restored.value, str(restored)) == ( + "f", + 3, + str(error), + ) diff --git a/tests/test_core/data_function/test_positional_only.py b/tests/test_core/data_function/test_positional_only.py new file mode 100644 index 000000000..4f8234787 --- /dev/null +++ b/tests/test_core/data_function/test_positional_only.py @@ -0,0 +1,75 @@ +"""A function with a positional-only parameter is refused at construction (ITL-1258). + +A function pod passes its inputs by name (``self._function(**inputs)``, sync and async), +so a positional-only parameter could never be given: every call would fail. It is refused +when the pod is created, as variadic parameters are, naming every such parameter. +""" + +from collections.abc import Callable +from typing import Any + +import pytest + +from orcapod import function_pod +from orcapod.core.data_function import PythonDataFunction +from orcapod.core.datagrams import Data +from orcapod.core.function_pod import FunctionPod + + +def one(x: int, /, y: int) -> int: + return x + y + + +def two(x: int, w: int, /, y: int) -> int: + return x + w + y + + +def mixed(x: int, /, y: int, *, z: int) -> int: + return x + y + z + + +async def one_async(x: int, /, y: int) -> int: + return x + y + + +def keyword_only(*, x: int, y: int) -> int: + return x * 10 + y + + +def _build(form: str, fn: Callable[..., Any]) -> Any: + if form == "data_function": + return PythonDataFunction(fn, output_keys="out") + if form == "decorator": + return function_pod(output_keys="out")(fn).pod.data_function + if form == "from_fn": + return FunctionPod.from_fn(fn, output_keys="out").data_function + raise ValueError(form) + + +FORMS = ["data_function", "decorator", "from_fn"] + + +@pytest.mark.parametrize("form", FORMS) +@pytest.mark.parametrize( + ("fn", "names"), + [(one, ["x"]), (two, ["x", "w"]), (mixed, ["x"]), (one_async, ["x"])], + ids=["one", "two", "mixed", "async"], +) +def test_a_positional_only_parameter_is_refused_at_construction( + form: str, fn: Callable[..., Any], names: list[str] +) -> None: + with pytest.raises(ValueError, match="positional-only") as raised: + _build(form, fn) + message = str(raised.value) + assert f"Offending parameters: {names!r}" in message + assert "passes its inputs by name" in message + + +@pytest.mark.parametrize("form", FORMS) +def test_keyword_only_parameters_keep_working(form: str) -> None: + data_function = _build(form, keyword_only) + # Two inputs, given in either order: matched by name. + for data in ({"x": 1, "y": 2}, {"y": 2, "x": 1}): + result = data_function.call(Data(data)) + assert result is not None + assert result.as_dict() == {"out": 12} From 1941515d66714493cccad1ea1549c03484df44b8 Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Wed, 18 Nov 2026 00:22:35 -0800 Subject: [PATCH 2/5] fix(data_function): keep OutputTypeError's attributes; read a postponed -> None; adjust the stored positional-only hash test (ITL-1257, ITL-1258) - NoOutputsDeclaredError sets every attribute OutputTypeError documents (output_key and declared_type None, detail None, hint the fix). - extract_function_schemas reads the text "None" as -> None too: it stays a string when get_type_hints fails on another (postponed) annotation. - test_function_default_hashing: f(a, /, b) has no stored signature hash any more (a data function refuses it); the value hash still tells it apart. This was the one CI failure. - Docs: no-output pods are limited (ITL-1260); use a SideEffectPod for an effect. Co-Authored-By: Claude Opus 5.5 --- docs/concepts/function-pods.md | 5 +++- src/orcapod/errors.py | 22 +++++++++++---- src/orcapod/utils/schema_utils.py | 9 ++++--- .../string_annotated_functions.py | 9 +++++++ .../data_function/test_none_return.py | 27 +++++++++++++++++++ .../test_function_default_hashing.py | 10 ++++++- 6 files changed, 71 insertions(+), 11 deletions(-) diff --git a/docs/concepts/function-pods.md b/docs/concepts/function-pods.md index 184166639..95fd36d0b 100644 --- a/docs/concepts/function-pods.md +++ b/docs/concepts/function-pods.md @@ -28,7 +28,10 @@ Key points: takes no `output_keys`; its pod has no output columns. `-> None` together with `output_keys` raises `ValueError` when the pod is created, and a value other than `None` returned by a function with no outputs raises `NoOutputsDeclaredError` (an - `OutputTypeError`): add an output key for it, or return nothing. An output that may be + `OutputTypeError`): add an output key for it, or return nothing. Such a pod is + limited for now: in a job its rows fail, over data-tags and before an operator it + raises (ITL-1260); for a function run for its effect, use a `SideEffectPod`. An + output that may be missing is not "no outputs": it is one output key typed `T | None`, and a returned `None` is stored as a null. - **Function parameters** are matched to the input stream's data columns by name: one data diff --git a/src/orcapod/errors.py b/src/orcapod/errors.py index 2017d6830..a3d7bc823 100644 --- a/src/orcapod/errors.py +++ b/src/orcapod/errors.py @@ -305,9 +305,14 @@ class OutputTypeError(TypeError, ValueError): Attributes: function_name: Name of the function pod's function. - output_key: Name of the output column. - declared_type: The declared type of that output. + output_key: Name of the output column; ``None`` for ``NoOutputsDeclaredError`` + (the function declares no output). + declared_type: The declared type of that output; ``None`` for + ``NoOutputsDeclaredError``. value: The value the function returned for that output. + detail: Where inside the value the mismatch is, when that is not the whole + value; ``None`` otherwise. + hint: What the function should return instead, when there is a specific fix. """ def __init__( @@ -332,7 +337,7 @@ def __init__( fix (``Return a float instead: 0.0 or float(value)``). """ self.function_name: str = function_name - self.output_key: str = output_key + self.output_key: str | None = output_key self.declared_type: object = declared_type self.value: object = value self.detail: str | None = detail @@ -371,6 +376,10 @@ class NoOutputsDeclaredError(OutputTypeError): dropped. It is an ``OutputTypeError``, so a pipeline treats it as one: a row failure under ``error_policy``. + It keeps the attributes of ``OutputTypeError``: ``output_key`` and + ``declared_type`` are ``None`` (there is no output), ``detail`` is ``None`` and + ``hint`` says how to fix it. + Attributes: function_name: Name of the function pod's function. value: The value the function returned. @@ -384,13 +393,16 @@ def __init__(self, function_name: str, value: object) -> None: value: The value the function returned. """ self.function_name: str = function_name + self.output_key: str | None = None + self.declared_type: object = None self.value: object = value + self.detail: str | None = None + self.hint: str | None = "Add an output key for the value, or return nothing" # Types only, never the value (see ``OutputTypeError``). TypeError.__init__( self, f"Function {function_name!r} declares no outputs (no output_keys) but " - + f"returned {type_text(type(value))}. Add an output key for the value, " - + "or return nothing.", + + f"returned {type_text(type(value))}. {self.hint}.", ) def __reduce__(self) -> tuple[object, ...]: diff --git a/src/orcapod/utils/schema_utils.py b/src/orcapod/utils/schema_utils.py index 241ce0919..5b64d6b98 100644 --- a/src/orcapod/utils/schema_utils.py +++ b/src/orcapod/utils/schema_utils.py @@ -259,10 +259,11 @@ def extract_function_schemas( # get_type_hints stores the return annotation under the key 'return' return_annot = resolved_hints.get("return", signature.return_annotation) - # get_type_hints turns ``-> None`` into ``NoneType``. ``-> None`` declares no - # outputs (ITL-1257), which is not an output whose value is None: the number of - # outputs is the number of output keys. - if return_annot is type(None): + # ``-> None`` declares no outputs (ITL-1257), which is not an output whose value is + # None: the number of outputs is the number of output keys. get_type_hints turns + # it into ``NoneType``; when get_type_hints fails on another annotation, a + # postponed annotation (``from __future__ import annotations``) is the text "None". + if return_annot is type(None) or return_annot == "None": return_annot = None inferred_output_types: Schema = {} if return_annot is not inspect.Signature.empty and return_annot is not None: diff --git a/tests/test_core/data_function/string_annotated_functions.py b/tests/test_core/data_function/string_annotated_functions.py index 3b0fc2229..e84abd1e4 100644 --- a/tests/test_core/data_function/string_annotated_functions.py +++ b/tests/test_core/data_function/string_annotated_functions.py @@ -20,3 +20,12 @@ def log_value_unannotated(x: int): # no return annotation on purpose def maybe(x: int) -> int | None: """One output that may be null.""" return None if x < 0 else x + + +def unresolvable_input(x: Missing) -> None: # noqa: F821 # pyright: ignore[reportUndefinedVariable] # unresolvable on purpose + """Declares no outputs; its parameter annotation cannot be resolved. + + ``typing.get_type_hints`` fails on it, so the return annotation stays the text + ``"None"``; the input type is supplied with ``input_schema``. + """ + del x diff --git a/tests/test_core/data_function/test_none_return.py b/tests/test_core/data_function/test_none_return.py index 31989ed1e..31c57b986 100644 --- a/tests/test_core/data_function/test_none_return.py +++ b/tests/test_core/data_function/test_none_return.py @@ -245,3 +245,30 @@ def test_the_error_pickles_with_its_arguments() -> None: 3, str(error), ) + + +def test_none_is_read_when_another_annotation_cannot_be_resolved() -> None: + """``get_type_hints`` fails on ``x: Missing``; the postponed ``-> None`` still counts. + + The input type comes from ``input_schema`` (Copilot, #447). + """ + data_function = PythonDataFunction( + strings.unresolvable_input, input_schema={"x": int} + ) + assert dict(data_function.output_data_schema) == {} + with pytest.raises(ValueError, match=REFUSAL): + PythonDataFunction( + strings.unresolvable_input, output_keys="out", input_schema={"x": int} + ) + + +def test_the_error_keeps_the_attributes_of_an_output_type_error() -> None: + """Every attribute ``OutputTypeError`` documents is present (Copilot, #447).""" + error = NoOutputsDeclaredError("f", 3) + for restored in (error, pickle.loads(pickle.dumps(error))): + assert restored.function_name == "f" + assert restored.value == 3 + assert restored.output_key is None + assert restored.declared_type is None + assert restored.detail is None + assert restored.hint == "Add an output key for the value, or return nothing" diff --git a/tests/test_hashing/test_function_default_hashing.py b/tests/test_hashing/test_function_default_hashing.py index edaa0445d..7535cde60 100644 --- a/tests/test_hashing/test_function_default_hashing.py +++ b/tests/test_hashing/test_function_default_hashing.py @@ -365,7 +365,11 @@ def kinds(a: int, *, b: int) -> int: # noqa: F811 (same name on purpose) assert site(plain) != site(kinds) def test_positional_only_marker(self, site: Callable[..., Any]): - """``f(a, /, b)`` differs from ``f(a, b)``.""" + """``f(a, /, b)`` differs from ``f(a, b)`` as a value. + + A data function refuses a positional-only parameter (ITL-1258: a pod passes its + inputs by name), so ``f(a, /, b)`` has no stored signature hash at all. + """ def kinds(a: int, b: int) -> int: return a @@ -375,6 +379,10 @@ def kinds(a: int, b: int) -> int: def kinds(a: int, /, b: int) -> int: # noqa: F811 (same name on purpose) return a + if site is _stored_signature_hash: + with pytest.raises(ValueError, match="positional-only"): + site(kinds) + return assert site(plain) != site(kinds) From f4a41d19c57978061ea70c37e7d388f2d7a0080b Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Wed, 18 Nov 2026 00:48:16 -0800 Subject: [PATCH 3/5] fix(data_function): copy output keys at construction; say the key needs a type; read a quoted postponed None (ITL-1257, ITL-1258) - PythonDataFunction keeps a tuple of its output keys, taken once: a later change to the caller's list changes nothing. - NoOutputsDeclaredError's hint, the docs and the changelog say a kept value needs an output key WITH its type (a return annotation or output_schema). - extract_function_schemas reads a postponed '-> "None"' (the text "'None'") as -> None too, through one helper, _declares_none. - The changelog and the design entry say a call that supplied a positional-only parameter failed, not every call. Co-Authored-By: Claude Opus 5.5 --- changelog.d/ITL-1257.md | 8 ++-- docs/concepts/function-pods.md | 3 +- docs/dev/design_issues/ITL-1257-NR1.md | 4 +- src/orcapod/core/data_function.py | 2 + src/orcapod/errors.py | 5 ++- src/orcapod/utils/schema_utils.py | 25 +++++++++-- .../string_annotated_functions.py | 8 ++++ .../data_function/test_data_function.py | 4 +- .../data_function/test_none_return.py | 42 ++++++++++++++----- 9 files changed, 78 insertions(+), 23 deletions(-) diff --git a/changelog.d/ITL-1257.md b/changelog.d/ITL-1257.md index 76019d5d6..27be57861 100644 --- a/changelog.d/ITL-1257.md +++ b/changelog.d/ITL-1257.md @@ -2,7 +2,8 @@ - A function with no `output_keys` that returns a value other than `None` raises `NoOutputsDeclaredError` (an `OutputTypeError`) instead of having the value dropped - (ITL-1257). Add an output key for the value, or return nothing. + (ITL-1257). To keep the value, declare an output key with its type (a return + annotation or `output_schema`); otherwise return nothing. ### Fixed @@ -12,5 +13,6 @@ reads `-> None` as `NoneType`. `-> None` with `output_keys` is now refused when the pod is created; it was accepted and gave an output column of type `NoneType`. - A function with a positional-only parameter is refused when the pod is created, naming - the parameter (ITL-1258). A pod passes its inputs by name, so every call of such a pod - failed with a `TypeError`. + the parameter (ITL-1258). A pod passes its inputs by name, so a call that supplied + such a parameter failed with a `TypeError` (one with a default worked only while the + input never held it, and the parameter could never be given). diff --git a/docs/concepts/function-pods.md b/docs/concepts/function-pods.md index 95fd36d0b..a234799e4 100644 --- a/docs/concepts/function-pods.md +++ b/docs/concepts/function-pods.md @@ -28,7 +28,8 @@ Key points: takes no `output_keys`; its pod has no output columns. `-> None` together with `output_keys` raises `ValueError` when the pod is created, and a value other than `None` returned by a function with no outputs raises `NoOutputsDeclaredError` (an - `OutputTypeError`): add an output key for it, or return nothing. Such a pod is + `OutputTypeError`): to keep the value, declare an output key with its type (a return + annotation or `output_schema`), or return nothing. Such a pod is limited for now: in a job its rows fail, over data-tags and before an operator it raises (ITL-1260); for a function run for its effect, use a `SideEffectPod`. An output that may be diff --git a/docs/dev/design_issues/ITL-1257-NR1.md b/docs/dev/design_issues/ITL-1257-NR1.md index 8819b3f66..a8d7fc9d7 100644 --- a/docs/dev/design_issues/ITL-1257-NR1.md +++ b/docs/dev/design_issues/ITL-1257-NR1.md @@ -19,5 +19,5 @@ is refused at construction. A function with no output keys that returns a value than `None` raises `NoOutputsDeclaredError`, an `OutputTypeError`, at call time, on the sync and the async path (developer: "declared `-> None` (or lack of any return type) should be treated as empty return"). Tests: `tests/test_core/data_function/test_none_return.py`. -In the same change, a positional-only parameter is refused at construction (ITL-1258; -`test_positional_only.py`). +In the same change, a positional-only parameter is refused at construction (ITL-1258: a +call that supplied it failed; `test_positional_only.py`). diff --git a/src/orcapod/core/data_function.py b/src/orcapod/core/data_function.py index 7bbf0bfd2..568f7ed45 100644 --- a/src/orcapod/core/data_function.py +++ b/src/orcapod/core/data_function.py @@ -459,6 +459,8 @@ def __init__( output_keys = [] if isinstance(output_keys, str): output_keys = [output_keys] + # A copy taken once: a later change to the caller's list changes nothing. + output_keys = tuple(output_keys) self._output_keys = output_keys if function_name is None: if hasattr(self._function, "__name__"): diff --git a/src/orcapod/errors.py b/src/orcapod/errors.py index a3d7bc823..f95ec06b7 100644 --- a/src/orcapod/errors.py +++ b/src/orcapod/errors.py @@ -397,7 +397,10 @@ def __init__(self, function_name: str, value: object) -> None: self.declared_type: object = None self.value: object = value self.detail: str | None = None - self.hint: str | None = "Add an output key for the value, or return nothing" + self.hint: str | None = ( + "Declare an output key with its type (a return " + "annotation or output_schema), or return nothing" + ) # Types only, never the value (see ``OutputTypeError``). TypeError.__init__( self, diff --git a/src/orcapod/utils/schema_utils.py b/src/orcapod/utils/schema_utils.py index 5b64d6b98..385d1d96e 100644 --- a/src/orcapod/utils/schema_utils.py +++ b/src/orcapod/utils/schema_utils.py @@ -134,6 +134,25 @@ def schema_incompatibility( return None +def _declares_none(annotation: object) -> bool: + """Whether a return annotation, as read, is ``-> None``. + + ``typing.get_type_hints`` turns ``-> None`` into ``NoneType``. When it fails on + another annotation, a postponed annotation (``from __future__ import annotations``) + is still text: ``"None"``, or ``"'None'"`` when it was written as a string + (``-> "None"``). + + Args: + annotation: The return annotation as ``get_type_hints`` or the signature gives it. + + Returns: + True when it is ``None`` written in one of those forms. + """ + if annotation is type(None): + return True + return isinstance(annotation, str) and annotation.strip("'\"") == "None" + + def extract_function_schemas( func: Callable, output_keys: Collection[str], @@ -260,10 +279,8 @@ def extract_function_schemas( # get_type_hints stores the return annotation under the key 'return' return_annot = resolved_hints.get("return", signature.return_annotation) # ``-> None`` declares no outputs (ITL-1257), which is not an output whose value is - # None: the number of outputs is the number of output keys. get_type_hints turns - # it into ``NoneType``; when get_type_hints fails on another annotation, a - # postponed annotation (``from __future__ import annotations``) is the text "None". - if return_annot is type(None) or return_annot == "None": + # None: the number of outputs is the number of output keys. + if _declares_none(return_annot): return_annot = None inferred_output_types: Schema = {} if return_annot is not inspect.Signature.empty and return_annot is not None: diff --git a/tests/test_core/data_function/string_annotated_functions.py b/tests/test_core/data_function/string_annotated_functions.py index e84abd1e4..3078ee2cb 100644 --- a/tests/test_core/data_function/string_annotated_functions.py +++ b/tests/test_core/data_function/string_annotated_functions.py @@ -29,3 +29,11 @@ def unresolvable_input(x: Missing) -> None: # noqa: F821 # pyright: ignore[rep ``"None"``; the input type is supplied with ``input_schema``. """ del x + + +def unresolvable_input_quoted(x: Missing) -> "None": # noqa: F821 # pyright: ignore[reportUndefinedVariable] # unresolvable on purpose + """As ``unresolvable_input``, with the return annotation written as a string. + + The postponed annotation is then the text ``"'None'"``. + """ + del x diff --git a/tests/test_core/data_function/test_data_function.py b/tests/test_core/data_function/test_data_function.py index bbc8ceb78..ff2fec60c 100644 --- a/tests/test_core/data_function/test_data_function.py +++ b/tests/test_core/data_function/test_data_function.py @@ -222,9 +222,9 @@ def test_output_data_schema_has_correct_types(self, add_pf): schema = add_pf.output_data_schema assert schema["result"] is int - def test_output_keys_string_normalised_to_list(self): + def test_output_keys_string_normalised_to_tuple(self): pf = PythonDataFunction(add, output_keys="result") - assert pf._output_keys == ["result"] + assert pf._output_keys == ("result",) def test_output_keys_collection_preserved(self): pf = PythonDataFunction(multi, output_keys=["sum", "product"]) diff --git a/tests/test_core/data_function/test_none_return.py b/tests/test_core/data_function/test_none_return.py index 31c57b986..88ec9ef24 100644 --- a/tests/test_core/data_function/test_none_return.py +++ b/tests/test_core/data_function/test_none_return.py @@ -200,7 +200,8 @@ def test_a_value_returned_by_a_function_with_no_outputs_is_refused( message = str(error) assert repr(RETURNS_A_VALUE[declaration].__name__) in message assert "declares no outputs" in message - assert "Add an output key" in message and "return nothing" in message + assert "Declare an output key with its type" in message + assert "return nothing" in message # Types only, never the value. assert "7" not in message @@ -247,19 +248,37 @@ def test_the_error_pickles_with_its_arguments() -> None: ) -def test_none_is_read_when_another_annotation_cannot_be_resolved() -> None: +@pytest.mark.parametrize( + "fn", + [strings.unresolvable_input, strings.unresolvable_input_quoted], + ids=["none", "quoted_none"], +) +def test_none_is_read_when_another_annotation_cannot_be_resolved( + fn: Callable[..., Any], +) -> None: """``get_type_hints`` fails on ``x: Missing``; the postponed ``-> None`` still counts. - The input type comes from ``input_schema`` (Copilot, #447). + Both spellings: ``-> None`` (the text ``"None"``) and ``-> "None"`` (the text + ``"'None'"``). The input type comes from ``input_schema`` (Copilot and CodeRabbit, + #447). """ - data_function = PythonDataFunction( - strings.unresolvable_input, input_schema={"x": int} - ) + data_function = PythonDataFunction(fn, input_schema={"x": int}) assert dict(data_function.output_data_schema) == {} with pytest.raises(ValueError, match=REFUSAL): - PythonDataFunction( - strings.unresolvable_input, output_keys="out", input_schema={"x": int} - ) + PythonDataFunction(fn, output_keys="out", input_schema={"x": int}) + + +def test_the_output_keys_are_copied_at_construction() -> None: + """A later change to the caller's list changes nothing (CodeRabbit, #447).""" + keys = ["value"] + data_function = PythonDataFunction(maybe, output_keys=keys) + keys.clear() + keys.append("other") + assert tuple(data_function.output_data_schema) == ("value",) + result = data_function.call(Data({"x": 3})) + assert result is not None + assert result.as_dict() == {"value": 3} + assert data_function.to_config()["config"]["output_keys"] == ["value"] def test_the_error_keeps_the_attributes_of_an_output_type_error() -> None: @@ -271,4 +290,7 @@ def test_the_error_keeps_the_attributes_of_an_output_type_error() -> None: assert restored.output_key is None assert restored.declared_type is None assert restored.detail is None - assert restored.hint == "Add an output key for the value, or return nothing" + assert restored.hint == ( + "Declare an output key with its type (a return " + "annotation or output_schema), or return nothing" + ) From c38f2e18d6d4e46b3a1510e0afc2166d37f05dbf Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Wed, 18 Nov 2026 01:56:58 -0800 Subject: [PATCH 4/5] fix(schema_utils): resolve the return annotation on its own when another one does not (ITL-1257) When typing.get_type_hints fails on an unrelated annotation (a postponed parameter annotation that cannot be resolved, its type supplied by input_schema), the return annotation is now evaluated on its own in the function's module namespace, a quoted one too, with Annotated[T, ...] read as T, as get_type_hints gives it. So -> None, -> "None", -> NoneType and -> Annotated[None, ...] all mean no outputs there, and a return such as -> int keeps its type. Tests for each spelling. Co-Authored-By: Claude Opus 5.5 --- src/orcapod/utils/schema_utils.py | 48 +++++++++++++++---- .../string_annotated_functions.py | 18 +++++++ .../data_function/test_none_return.py | 29 +++++++++-- 3 files changed, 81 insertions(+), 14 deletions(-) diff --git a/src/orcapod/utils/schema_utils.py b/src/orcapod/utils/schema_utils.py index 385d1d96e..832a01ab4 100644 --- a/src/orcapod/utils/schema_utils.py +++ b/src/orcapod/utils/schema_utils.py @@ -5,7 +5,7 @@ import sys from collections.abc import Callable, Collection, Iterable, Mapping, Sequence from types import UnionType -from typing import Any, Union, get_args, get_origin, get_type_hints +from typing import Annotated, Any, Union, get_args, get_origin, get_type_hints from orcapod.errors import InputValidationError from orcapod.types import Schema, SchemaLike @@ -134,21 +134,48 @@ def schema_incompatibility( return None +def _resolved_return_annotation(func: Callable[..., Any], annotation: Any) -> Any: + """The return annotation resolved on its own, as ``typing.get_type_hints`` would. + + Used when ``get_type_hints`` failed on another annotation of ``func``: a postponed + annotation (``from __future__ import annotations``) is still text then. The text is + evaluated in the function's module namespace, a string inside it as well + (``-> "None"``), and ``Annotated[T, ...]`` becomes ``T``, as ``get_type_hints`` + gives it. Text that cannot be evaluated is returned as it is. + + Args: + func: The function the annotation belongs to. + annotation: The return annotation as the signature gives it. + + Returns: + The resolved annotation, or ``annotation`` when it cannot be resolved. + """ + namespace = getattr(func, "__globals__", {}) + while isinstance(annotation, str): + try: + # Evaluated as typing.get_type_hints evaluates an annotation. + annotation = eval(annotation, namespace) + except Exception: + return annotation + if get_origin(annotation) is Annotated: + annotation = get_args(annotation)[0] + return annotation + + def _declares_none(annotation: object) -> bool: """Whether a return annotation, as read, is ``-> None``. - ``typing.get_type_hints`` turns ``-> None`` into ``NoneType``. When it fails on - another annotation, a postponed annotation (``from __future__ import annotations``) - is still text: ``"None"``, or ``"'None'"`` when it was written as a string - (``-> "None"``). + ``typing.get_type_hints`` turns ``-> None`` into ``NoneType``; an annotation it could + not resolve is resolved on its own first (``_resolved_return_annotation``). The text + ``"None"`` (or ``"'None'"``) also counts, should that fail. Args: - annotation: The return annotation as ``get_type_hints`` or the signature gives it. + annotation: The return annotation, resolved where it could be. Returns: - True when it is ``None`` written in one of those forms. + True when it is ``None``, ``NoneType`` or ``Annotated[None, ...]``. """ - if annotation is type(None): + if annotation is None or annotation is type(None): return True return isinstance(annotation, str) and annotation.strip("'\"") == "None" @@ -276,8 +303,11 @@ def extract_function_schemas( if param.default is not inspect.Parameter.empty: optional_params.add(name) - # get_type_hints stores the return annotation under the key 'return' + # get_type_hints stores the return annotation under the key 'return'; when it + # failed on another annotation, the return annotation is resolved on its own. return_annot = resolved_hints.get("return", signature.return_annotation) + if "return" not in resolved_hints: + return_annot = _resolved_return_annotation(func, return_annot) # ``-> None`` declares no outputs (ITL-1257), which is not an output whose value is # None: the number of outputs is the number of output keys. if _declares_none(return_annot): diff --git a/tests/test_core/data_function/string_annotated_functions.py b/tests/test_core/data_function/string_annotated_functions.py index 3078ee2cb..49ad9f3dc 100644 --- a/tests/test_core/data_function/string_annotated_functions.py +++ b/tests/test_core/data_function/string_annotated_functions.py @@ -6,6 +6,9 @@ from __future__ import annotations +from types import NoneType +from typing import Annotated + def log_value(x: int) -> None: """Declares no outputs.""" @@ -37,3 +40,18 @@ def unresolvable_input_quoted(x: Missing) -> "None": # noqa: F821 # pyright: i The postponed annotation is then the text ``"'None'"``. """ del x + + +def unresolvable_input_none_type(x: Missing) -> NoneType: # noqa: F821 # pyright: ignore[reportUndefinedVariable] # unresolvable on purpose + """As ``unresolvable_input``, with the return annotation written ``NoneType``.""" + del x + + +def unresolvable_input_annotated_none(x: Missing) -> Annotated[None, "no outputs"]: # noqa: F821 # pyright: ignore[reportUndefinedVariable] # unresolvable on purpose + """As ``unresolvable_input``, with the return annotation ``Annotated[None, ...]``.""" + del x + + +def unresolvable_input_returns_int(x: Missing) -> int: # noqa: F821 # pyright: ignore[reportUndefinedVariable] # unresolvable on purpose + """One ``int`` output; the return annotation resolves although ``x``'s does not.""" + return int(x) diff --git a/tests/test_core/data_function/test_none_return.py b/tests/test_core/data_function/test_none_return.py index 88ec9ef24..69e1d55f1 100644 --- a/tests/test_core/data_function/test_none_return.py +++ b/tests/test_core/data_function/test_none_return.py @@ -250,17 +250,23 @@ def test_the_error_pickles_with_its_arguments() -> None: @pytest.mark.parametrize( "fn", - [strings.unresolvable_input, strings.unresolvable_input_quoted], - ids=["none", "quoted_none"], + [ + strings.unresolvable_input, + strings.unresolvable_input_quoted, + strings.unresolvable_input_none_type, + strings.unresolvable_input_annotated_none, + ], + ids=["none", "quoted_none", "none_type", "annotated_none"], ) def test_none_is_read_when_another_annotation_cannot_be_resolved( fn: Callable[..., Any], ) -> None: """``get_type_hints`` fails on ``x: Missing``; the postponed ``-> None`` still counts. - Both spellings: ``-> None`` (the text ``"None"``) and ``-> "None"`` (the text - ``"'None'"``). The input type comes from ``input_schema`` (Copilot and CodeRabbit, - #447). + Every spelling of no outputs: ``-> None``, ``-> "None"``, ``-> NoneType`` and + ``-> Annotated[None, ...]`` (as ``get_type_hints`` gives it: ``Annotated`` is + dropped). The return annotation is resolved on its own; the input type comes from + ``input_schema`` (Copilot and CodeRabbit, #447). """ data_function = PythonDataFunction(fn, input_schema={"x": int}) assert dict(data_function.output_data_schema) == {} @@ -294,3 +300,16 @@ def test_the_error_keeps_the_attributes_of_an_output_type_error() -> None: "Declare an output key with its type (a return " "annotation or output_schema), or return nothing" ) + + +def test_a_return_annotation_resolves_when_another_annotation_does_not() -> None: + """``x: Missing`` cannot be resolved; ``-> int`` still gives an ``int`` output.""" + data_function = PythonDataFunction( + strings.unresolvable_input_returns_int, + output_keys="value", + input_schema={"x": int}, + ) + assert dict(data_function.output_data_schema) == {"value": int} + result = data_function.call(Data({"x": 4})) + assert result is not None + assert result.as_dict() == {"value": 4} From 25660cba00e3c31dd473a4b89f29a4ba7acc5084 Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Wed, 18 Nov 2026 02:09:53 -0800 Subject: [PATCH 5/5] Revert "fix(schema_utils): resolve the return annotation on its own when another one does not (ITL-1257)" This reverts commit c38f2e18d6d4e46b3a1510e0afc2166d37f05dbf. Resolving output annotations by evaluation reaches the function's identity and needs its own design: tracked in ITL-1262. Co-Authored-By: Claude Opus 5.5 --- src/orcapod/utils/schema_utils.py | 48 ++++--------------- .../string_annotated_functions.py | 18 ------- .../data_function/test_none_return.py | 29 ++--------- 3 files changed, 14 insertions(+), 81 deletions(-) diff --git a/src/orcapod/utils/schema_utils.py b/src/orcapod/utils/schema_utils.py index 832a01ab4..385d1d96e 100644 --- a/src/orcapod/utils/schema_utils.py +++ b/src/orcapod/utils/schema_utils.py @@ -5,7 +5,7 @@ import sys from collections.abc import Callable, Collection, Iterable, Mapping, Sequence from types import UnionType -from typing import Annotated, Any, Union, get_args, get_origin, get_type_hints +from typing import Any, Union, get_args, get_origin, get_type_hints from orcapod.errors import InputValidationError from orcapod.types import Schema, SchemaLike @@ -134,48 +134,21 @@ def schema_incompatibility( return None -def _resolved_return_annotation(func: Callable[..., Any], annotation: Any) -> Any: - """The return annotation resolved on its own, as ``typing.get_type_hints`` would. - - Used when ``get_type_hints`` failed on another annotation of ``func``: a postponed - annotation (``from __future__ import annotations``) is still text then. The text is - evaluated in the function's module namespace, a string inside it as well - (``-> "None"``), and ``Annotated[T, ...]`` becomes ``T``, as ``get_type_hints`` - gives it. Text that cannot be evaluated is returned as it is. - - Args: - func: The function the annotation belongs to. - annotation: The return annotation as the signature gives it. - - Returns: - The resolved annotation, or ``annotation`` when it cannot be resolved. - """ - namespace = getattr(func, "__globals__", {}) - while isinstance(annotation, str): - try: - # Evaluated as typing.get_type_hints evaluates an annotation. - annotation = eval(annotation, namespace) - except Exception: - return annotation - if get_origin(annotation) is Annotated: - annotation = get_args(annotation)[0] - return annotation - - def _declares_none(annotation: object) -> bool: """Whether a return annotation, as read, is ``-> None``. - ``typing.get_type_hints`` turns ``-> None`` into ``NoneType``; an annotation it could - not resolve is resolved on its own first (``_resolved_return_annotation``). The text - ``"None"`` (or ``"'None'"``) also counts, should that fail. + ``typing.get_type_hints`` turns ``-> None`` into ``NoneType``. When it fails on + another annotation, a postponed annotation (``from __future__ import annotations``) + is still text: ``"None"``, or ``"'None'"`` when it was written as a string + (``-> "None"``). Args: - annotation: The return annotation, resolved where it could be. + annotation: The return annotation as ``get_type_hints`` or the signature gives it. Returns: - True when it is ``None``, ``NoneType`` or ``Annotated[None, ...]``. + True when it is ``None`` written in one of those forms. """ - if annotation is None or annotation is type(None): + if annotation is type(None): return True return isinstance(annotation, str) and annotation.strip("'\"") == "None" @@ -303,11 +276,8 @@ def extract_function_schemas( if param.default is not inspect.Parameter.empty: optional_params.add(name) - # get_type_hints stores the return annotation under the key 'return'; when it - # failed on another annotation, the return annotation is resolved on its own. + # get_type_hints stores the return annotation under the key 'return' return_annot = resolved_hints.get("return", signature.return_annotation) - if "return" not in resolved_hints: - return_annot = _resolved_return_annotation(func, return_annot) # ``-> None`` declares no outputs (ITL-1257), which is not an output whose value is # None: the number of outputs is the number of output keys. if _declares_none(return_annot): diff --git a/tests/test_core/data_function/string_annotated_functions.py b/tests/test_core/data_function/string_annotated_functions.py index 49ad9f3dc..3078ee2cb 100644 --- a/tests/test_core/data_function/string_annotated_functions.py +++ b/tests/test_core/data_function/string_annotated_functions.py @@ -6,9 +6,6 @@ from __future__ import annotations -from types import NoneType -from typing import Annotated - def log_value(x: int) -> None: """Declares no outputs.""" @@ -40,18 +37,3 @@ def unresolvable_input_quoted(x: Missing) -> "None": # noqa: F821 # pyright: i The postponed annotation is then the text ``"'None'"``. """ del x - - -def unresolvable_input_none_type(x: Missing) -> NoneType: # noqa: F821 # pyright: ignore[reportUndefinedVariable] # unresolvable on purpose - """As ``unresolvable_input``, with the return annotation written ``NoneType``.""" - del x - - -def unresolvable_input_annotated_none(x: Missing) -> Annotated[None, "no outputs"]: # noqa: F821 # pyright: ignore[reportUndefinedVariable] # unresolvable on purpose - """As ``unresolvable_input``, with the return annotation ``Annotated[None, ...]``.""" - del x - - -def unresolvable_input_returns_int(x: Missing) -> int: # noqa: F821 # pyright: ignore[reportUndefinedVariable] # unresolvable on purpose - """One ``int`` output; the return annotation resolves although ``x``'s does not.""" - return int(x) diff --git a/tests/test_core/data_function/test_none_return.py b/tests/test_core/data_function/test_none_return.py index 69e1d55f1..88ec9ef24 100644 --- a/tests/test_core/data_function/test_none_return.py +++ b/tests/test_core/data_function/test_none_return.py @@ -250,23 +250,17 @@ def test_the_error_pickles_with_its_arguments() -> None: @pytest.mark.parametrize( "fn", - [ - strings.unresolvable_input, - strings.unresolvable_input_quoted, - strings.unresolvable_input_none_type, - strings.unresolvable_input_annotated_none, - ], - ids=["none", "quoted_none", "none_type", "annotated_none"], + [strings.unresolvable_input, strings.unresolvable_input_quoted], + ids=["none", "quoted_none"], ) def test_none_is_read_when_another_annotation_cannot_be_resolved( fn: Callable[..., Any], ) -> None: """``get_type_hints`` fails on ``x: Missing``; the postponed ``-> None`` still counts. - Every spelling of no outputs: ``-> None``, ``-> "None"``, ``-> NoneType`` and - ``-> Annotated[None, ...]`` (as ``get_type_hints`` gives it: ``Annotated`` is - dropped). The return annotation is resolved on its own; the input type comes from - ``input_schema`` (Copilot and CodeRabbit, #447). + Both spellings: ``-> None`` (the text ``"None"``) and ``-> "None"`` (the text + ``"'None'"``). The input type comes from ``input_schema`` (Copilot and CodeRabbit, + #447). """ data_function = PythonDataFunction(fn, input_schema={"x": int}) assert dict(data_function.output_data_schema) == {} @@ -300,16 +294,3 @@ def test_the_error_keeps_the_attributes_of_an_output_type_error() -> None: "Declare an output key with its type (a return " "annotation or output_schema), or return nothing" ) - - -def test_a_return_annotation_resolves_when_another_annotation_does_not() -> None: - """``x: Missing`` cannot be resolved; ``-> int`` still gives an ``int`` output.""" - data_function = PythonDataFunction( - strings.unresolvable_input_returns_int, - output_keys="value", - input_schema={"x": int}, - ) - assert dict(data_function.output_data_schema) == {"value": int} - result = data_function.call(Data({"x": 4})) - assert result is not None - assert result.as_dict() == {"value": 4}