diff --git a/changelog.d/ITL-953.md b/changelog.d/ITL-953.md new file mode 100644 index 000000000..fa8da2c67 --- /dev/null +++ b/changelog.d/ITL-953.md @@ -0,0 +1,40 @@ +### Breaking changes and migration + +#### Function hashes: structured signature, default values through the semantic hasher (ITL-953) + +A function's signature is now hashed from one structured description: each parameter's name, +kind, annotation and default value, in declared order. Before, the parameters were one line of +text in which a default appeared as `repr(value)`. + +| | Before | Now | +|---|---|---| +| Default values | `repr(value)`: a `frozenset` or `dict` default hashed differently per process (`PYTHONHASHSEED`) or per insertion order, an `object()` default embedded a memory address, and two values with one `repr()` shared a hash | the semantic hasher's hash of the value, like every other hashed value | +| Parameter kind | not hashed: `f(a, *, b)`, `f(a, /, b)` and `f(a, b)` shared a hash | hashed | +| Stored `function_signature_hash` | hash of a separate signature text | the hash of the function as a value: one description of a signature | + +**What moves.** The hash of every function used as a value, and every newly written value of +the stored column `__pf_var_function_signature_hash`. Nothing reads that column, and stored +rows are not changed. A function pod's identity does not use this hash: no `uri`, +`pipeline_hash()`, `content_hash()` or table path moves. + +**A default value the hasher cannot hash is now an error.** A function pod whose function has +a default of a type with no hash rule fails when it is created (`@function_pod`, +`FunctionPod.from_fn`, `PythonDataFunction`), with a `TypeError` naming the parameter and the +function. There is no fallback to `repr()` or to the type name, which would let two different +defaults share a hash. Hashable defaults: `None`, `bool`, `int`, `float`, `str`, `bytes`, +`uuid.UUID`, lists, tuples, sets and dicts of hashable values, functions, types, +`numpy.ndarray`, `pandas` objects, `File`, `Directory`. Not hashable today: a plain +`enum.Enum` member, a dataclass or pydantic instance, `pathlib.Path`, `datetime`, `date`, +`Decimal`, numpy scalars other than `numpy.float64`. Giving these a hash rule (a pod +parameter's default hashed as the column value it would be) is the follow-up ITL-971. + +**Migration.** Use a default the hasher can hash (for example a `str` or `None`, building the +object inside the function), remove the default and supply the value as an input column, or +register a `PythonTypeHandlerProtocol` for the type. A custom `FunctionInfoExtractorProtocol` +that wants its defaults hashed returns `parameters` entries whose `default` is a +`ParameterDefault`. + +### Fixed + +- `get_function_signature(include_defaults=False)` no longer cuts a parameter at the first + `=`, which truncated an annotation such as `Literal["a=b"]` (ITL-953). diff --git a/design_issues/ITL-953-FD1.md b/design_issues/ITL-953-FD1.md new file mode 100644 index 000000000..87b055a3c --- /dev/null +++ b/design_issues/ITL-953-FD1.md @@ -0,0 +1,31 @@ +## `src/orcapod/hashing/semantic_hashing/function_info_extractors.py` — function signature hash (ITL-953) + +### FD1 — Function defaults entered the function hash as `repr()`; parameter kind was not hashed +**Status:** resolved +**Severity:** medium +**Issue:** ITL-953 + +Finding L2 of the ITL-938 hash-site audit (Appendix A.9). +`FunctionSignatureExtractor` wrote a function's parameters as one line of text in which a +default value appeared as `repr(value)`. A `frozenset` default therefore hashed differently +under every `PYTHONHASHSEED`, a `dict` default by insertion order, an `object()` default +embedded a memory address, and two values with the same `repr()` shared a hash. The text +also dropped the parameter kind, so `f(a, *, b)`, `f(a, /, b)` and `f(a, b)` shared a hash. +A second, parallel description (the text of `hash_utils.get_function_signature`) fed the +stored `__pf_var_function_signature_hash` column with the same defects. + +**Fix:** One structured description (developer decision, November 11, 2026): `parameters` is +a list of entries `{name, kind, annotation, default}` in declared order; `annotation` and +`default` are absent when the parameter has none. The extractor reports a default as a +`ParameterDefault`; `FunctionHandler` replaces it with the semantic hasher's hash of the value +(`hash_default_value`, the one place that decides how a default is hashed) and wraps the +hasher's `TypeError` with the parameter and function names. A default the hasher cannot hash +raises: no fallback to `repr()` or the type name. The stored signature hash is now +`hash_object(function)`. Moves: every function-value hash and every newly written stored +signature hash; no pod identity, path or stored schema. + +Decided (developer, November 11, 2026): `Path`, `Enum`, `datetime` / `date`, `Decimal` and +numpy scalar defaults keep raising in v0.3. A data value of those types is hashed through the +type converter and the Arrow hasher, never through the structure hasher, which is why it has +no handler for them. The follow-up, ITL-971, is to hash a pod parameter's default as the +column value it would be; `hash_default_value` is where that goes. diff --git a/docs/concepts/function-pods.md b/docs/concepts/function-pods.md index c78c78ee6..438856f3e 100644 --- a/docs/concepts/function-pods.md +++ b/docs/concepts/function-pods.md @@ -27,6 +27,12 @@ Key points: - **Function parameters** must match the input stream's data columns exactly: one data column per parameter, with the same names. A parameter with a default value may be left out of the stream, and the default is used. See [Input columns must match exactly](#input-columns-must-match-exactly). +- **Default values** are part of the function's signature hash, so a default must be a value + Orcapod can hash: `None`, numbers, strings, `bytes`, and lists, tuples, sets and dicts of + them. A default of another type, such as a `Path`, an `Enum` member, a `datetime` or a + 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). - **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/reference/hashing.md b/docs/reference/hashing.md index 6bc54b6a4..e44efefd0 100644 --- a/docs/reference/hashing.md +++ b/docs/reference/hashing.md @@ -421,6 +421,63 @@ definition. Consequences: The canonical trees of a corpus of expressions are pinned in `tests/test_hashing/test_polars_expr_hashing.py`, and their hashes in the golden suite. +### 1d. Function values and parameter defaults + +A function used as a value (inside an identity structure, or passed to +`semantic_hasher.hash_object`) is hashed from one structured description of its signature: + +```text +{"module": , "name": , + "parameters": [{"name": ..., "kind": ..., "annotation": ..., "default": ...}, ...], + "returns": } +``` + +| Member of a parameter entry | Value | Absent when | +|---|---|---| +| `name` | the parameter name | never | +| `kind` | `POSITIONAL_ONLY`, `POSITIONAL_OR_KEYWORD`, `VAR_POSITIONAL`, `KEYWORD_ONLY` or `VAR_KEYWORD` | never | +| `annotation` | the canonical text of the annotation (union members sorted, logical types by their identifier) | the parameter has no annotation | +| `default` | the semantic hasher's hash of the default value, as a nested hash | the parameter has no default | + +Parameters are listed in declared order. The function body is not part of this hash. + +**A default value is hashed like every other hashed value** (ITL-953): by the semantic +hasher, never by its `repr()`. Equal defaults give equal hashes in every process and under +every `PYTHONHASHSEED`; a default of `None` differs from having no default; and because a +default enters as a nested hash, no literal default can spell out another default's entry. +Before v0.3 the default entered as `repr(value)`, so a `frozenset` default hashed differently +per process and an `object()` default embedded a memory address. Before v0.3 the parameter +kind was also not hashed: `f(a, *, b)`, `f(a, /, b)` and `f(a, b)` shared a hash. + +**A default the hasher cannot hash is an error.** There is no fallback to `repr()` or to the +type name, either of which would let two different defaults share a hash. Hashing the +function raises `TypeError` naming the parameter and the function. Since a data function +computes its signature hash when it is built, **a function pod whose function has such a +default fails at construction** (`@function_pod`, `FunctionPod.from_fn`, +`PythonDataFunction`). + +| Default value | Hashed as | +|---|---| +| `None`, `bool`, `int`, `float`, `str` | the JSON primitive (a subclass such as an `IntEnum` member or `numpy.float64` hashes as the number it is) | +| `list`, `tuple`, `set`, `frozenset`, `dict`, namedtuple | the container forms of [the algorithm above](#algorithm-semanticawarepythonhasher) | +| `bytes`, `uuid.UUID`, a function, a type, `numpy.ndarray`, `pandas` objects, `File`, `Directory`, any object with `identity_structure()` | its registered handler | +| a plain `enum.Enum` member, a dataclass or pydantic instance, `pathlib.Path`, `datetime`, `date`, `Decimal`, `complex`, a numpy scalar other than `numpy.float64`, any other object | **not hashable: `TypeError`** | + +Remedies: use a default the hasher can hash (for example a `str` or `None`, building the +object inside the function); remove the default and supply the value as an input column; +or register a `PythonTypeHandlerProtocol` for the type in the data context's handler +registry. Raising is the v0.3 behaviour (developer decision, November 11, 2026); hashing a +pod parameter's default as the column value it would be, which would cover `Path`, +`datetime`, `date` and numpy scalars, is the follow-up ITL-971. + +**Where the hash is used.** As the hash of a function that appears as a value, and as the +`function_signature_hash` stored with every result row (the +`__pf_var_function_signature_hash` column), which is this same hash of the pod's function. A +function pod's identity does **not** use it: the pod's `uri`, its `pipeline_hash()`, its +`content_hash()` and its table paths depend on the function's name, version and output +schema (see [Data Function URI Hash](#5-data-function-uri-hash)), so changing a default +moves no path. + --- ## 2. Source Provenance & System Tags diff --git a/src/orcapod/core/data_function.py b/src/orcapod/core/data_function.py index 13a97817f..c340086cc 100644 --- a/src/orcapod/core/data_function.py +++ b/src/orcapod/core/data_function.py @@ -19,7 +19,6 @@ from orcapod.core.datagrams import Datagram, Data from orcapod.hashing.hash_utils import ( get_function_components, - get_function_signature, ) from orcapod.core.result_cache import ResultCache from orcapod.protocols.core_protocols import DataFunctionProtocol, DataProtocol @@ -518,8 +517,12 @@ def __init__( self._git_hash = git_hash semantic_hasher = self.data_context.semantic_hasher + # The signature hash is the hash of the function used as a value: one + # structured description of the signature (module, name, each parameter's + # name, kind, annotation and default, return annotation), with every default + # hashed by the semantic hasher (ITL-953). self._function_signature_hash = semantic_hasher.hash_object( - get_function_signature(function) + function ).to_prefixed_digest() self._function_content_hash = semantic_hasher.hash_object( get_function_components(self._function) diff --git a/src/orcapod/hashing/hash_utils.py b/src/orcapod/hashing/hash_utils.py index efec59d9b..856a93c5b 100644 --- a/src/orcapod/hashing/hash_utils.py +++ b/src/orcapod/hashing/hash_utils.py @@ -236,6 +236,10 @@ def get_function_signature( param_strs = [] for name, param in sig.parameters.items(): + if not include_defaults: + # Drop the default from the parameter itself; cutting the formatted text + # at "=" would truncate an annotation such as Literal["a=b"]. + param = param.replace(default=inspect.Parameter.empty) annotation = typing.cast(object, param.annotation) param_str = stabilize_type_names(str(param), annotation) if annotation is not inspect.Parameter.empty and is_union_annotation( @@ -248,8 +252,6 @@ def get_function_signature( # Replace ": " with ": " (first occurrence only). # The ": " prefix distinguishes the annotation from the default value. param_str = param_str.replace(f": {old_ann}", f": {new_ann}", 1) - if not include_defaults and "=" in param_str: - param_str = param_str.split("=")[0].strip() param_strs.append(param_str) parts["params"] = f"({', '.join(param_strs)})" diff --git a/src/orcapod/hashing/semantic_hashing/builtin_handlers.py b/src/orcapod/hashing/semantic_hashing/builtin_handlers.py index 8ca0fe7d8..89c8de483 100644 --- a/src/orcapod/hashing/semantic_hashing/builtin_handlers.py +++ b/src/orcapod/hashing/semantic_hashing/builtin_handlers.py @@ -28,6 +28,7 @@ from uuid import UUID from orcapod.hashing.semantic_hashing.encoded import Encoded +from orcapod.hashing.semantic_hashing.function_info_extractors import ParameterDefault from orcapod.logical_types.identifier import logical_type_identifier from orcapod.types import ContentHash, Schema from orcapod.utils.canonical_type_names import canonical_type_name @@ -61,6 +62,25 @@ def handle(self, obj: Any, hasher: "SemanticHasherProtocol") -> Any: raise TypeError(f"BytesHandler: expected bytes or bytearray, got {type(obj)!r}") +def hash_default_value(value: Any, hasher: "SemanticHasherProtocol") -> ContentHash: + """Hash one parameter default. + + The single place that decides how a default value is hashed: like every other + hashed value, by the semantic hasher, never by its ``repr()``. + + Args: + value: The default value. + hasher: The semantic hasher hashing the function. + + Returns: + The hash of the value. + + Raises: + TypeError: If the hasher has no way to hash the value. + """ + return hasher.hash_object(value) + + class FunctionHandler: """Hasher for Python functions/callables with a ``__code__`` attribute. @@ -80,7 +100,51 @@ def handle(self, obj: Any, hasher: "SemanticHasherProtocol") -> Any: func_name = getattr(obj, "__name__", repr(obj)) logger.debug("FunctionHandler: extracting info for function %r", func_name) info: dict[str, Any] = self.function_info_extractor.extract_function_info(obj) - return info + parameters = info.get("parameters") + if not parameters: + return info + return { + **info, + "parameters": [ + self._with_hashed_default(entry, obj, hasher) for entry in parameters + ], + } + + @staticmethod + def _with_hashed_default( + entry: dict[str, Any], func: Any, hasher: "SemanticHasherProtocol" + ) -> dict[str, Any]: + """Return a parameter entry with its default replaced by the default's hash. + + Args: + entry: One parameter entry of the extracted function description. + func: The function the parameter belongs to. + hasher: The semantic hasher hashing the function. + + Returns: + ``entry`` unchanged when it has no ``ParameterDefault``; otherwise a + copy whose ``"default"`` is the hash of the default value. + + Raises: + TypeError: If the default value cannot be hashed. The message names the + parameter and the function; the hasher's error is its cause. + """ + default = entry.get("default") + if not isinstance(default, ParameterDefault): + return entry + try: + default_hash = hash_default_value(default.value, hasher) + except TypeError as exc: + module = getattr(func, "__module__", None) + qualname = getattr(func, "__qualname__", None) or repr(func) + function_name = f"{module}.{qualname}" if module else qualname + raise TypeError( + f"Cannot hash the default value of parameter {entry['name']!r} of " + f"function {function_name}: {exc} A default value is part of the " + "function's hash: use a default the hasher can hash, or remove the " + "default and supply the value as an input." + ) from exc + return {**entry, "default": default_hash} class TypeObjectHandler: diff --git a/src/orcapod/hashing/semantic_hashing/function_info_extractors.py b/src/orcapod/hashing/semantic_hashing/function_info_extractors.py index b2b5f137f..d0d9a82ae 100644 --- a/src/orcapod/hashing/semantic_hashing/function_info_extractors.py +++ b/src/orcapod/hashing/semantic_hashing/function_info_extractors.py @@ -1,5 +1,6 @@ import inspect from collections.abc import Callable +from dataclasses import dataclass from typing import TYPE_CHECKING, Any, Literal from orcapod.hashing.hash_utils import canonical_annotation_str @@ -10,60 +11,50 @@ from orcapod.protocols.semantic_types_protocols import TypeConverterProtocol -def _format_param( - param: inspect.Parameter, - canonical_annotation: str | None, - include_defaults: bool, -) -> str: - """Reconstruct a parameter string from its structured components. +@dataclass(frozen=True) +class ParameterDefault: + """A parameter's default value, not yet hashed. - Produces output identical to ``str(inspect.Parameter)`` for normal inputs, - but substitutes ``canonical_annotation`` for the raw annotation string without - any string search/replace. This avoids two failure modes of the substitution - approach: + ``FunctionSignatureExtractor`` has no hasher, so it reports each default wrapped + in this class and ``FunctionHandler`` replaces it with the semantic hasher's hash + of the value. The structure hasher has no handler for this class: a description + whose defaults were not replaced is refused instead of being hashed with a raw + value in it. - 1. Accidentally matching the annotation string inside a complex default - value's ``repr`` (e.g. a dataclass whose repr embeds the type name). - 2. Truncating annotations that contain ``=`` (e.g. ``Literal["a=b"]``) when - stripping defaults via ``str.split("=")``. + Args: + value: The default value as written in the function's signature. + """ - The format follows CPython's ``inspect.Parameter.__str__`` exactly: + value: Any - - With annotation and default: ``name: type = repr(default)`` - - With annotation, no default: ``name: type`` - - No annotation, with default: ``name=repr(default)`` (no spaces around ``=``) - - No annotation, no default: ``name`` - - ``*args`` / ``**kwargs`` get the corresponding prefix. + +def _parameter_entry( + param: inspect.Parameter, + canonical_annotation: str | None, + include_default: bool, +) -> dict[str, Any]: + """Describe one parameter as a structured entry. Args: - param: The parameter to format. - canonical_annotation: Canonical string for the annotation, or ``None`` - when the parameter carries no annotation. - include_defaults: Whether to include the default value. + param: The parameter to describe. + canonical_annotation: Canonical text of the annotation, or ``None`` when the + parameter carries no annotation. + include_default: Whether to report the default value. Returns: - A formatted parameter string. + ``{"name", "kind"}`` plus ``"annotation"`` when the parameter is annotated + and ``"default"`` (a ``ParameterDefault``) when it has a default and + ``include_default`` is true. ``kind`` is the name of the parameter's + ``inspect`` kind (``"POSITIONAL_ONLY"``, ``"POSITIONAL_OR_KEYWORD"``, + ``"VAR_POSITIONAL"``, ``"KEYWORD_ONLY"`` or ``"VAR_KEYWORD"``). An absent key + is different from any value: a default of ``None`` is not "no default". """ - if param.kind == inspect.Parameter.VAR_POSITIONAL: - prefix = "*" - elif param.kind == inspect.Parameter.VAR_KEYWORD: - prefix = "**" - else: - prefix = "" - - base = f"{prefix}{param.name}" - has_default = include_defaults and param.default is not inspect.Parameter.empty - + entry: dict[str, Any] = {"name": param.name, "kind": param.kind.name} if canonical_annotation is not None: - # "name: type" or "name: type = default" - if has_default: - return f"{base}: {canonical_annotation} = {repr(param.default)}" - return f"{base}: {canonical_annotation}" - else: - # "name" or "name=default" (CPython omits spaces around = without annotation) - if has_default: - return f"{base}={repr(param.default)}" - return base + entry["annotation"] = canonical_annotation + if include_default and param.default is not inspect.Parameter.empty: + entry["default"] = ParameterDefault(param.default) + return entry class FunctionNameExtractor: @@ -93,9 +84,11 @@ class FunctionSignatureExtractor: reorganisations therefore do not invalidate cached function-pod signatures; a change of the type's identifier does. - For **parameter** annotations each parameter string is reconstructed from - its structured components (name, kind, canonical annotation, default) via - ``_format_param``, avoiding any string search/replace. + Each **parameter** is one structured entry (see ``_parameter_entry``): its + name, its kind, the canonical text of its annotation and its default value. A + default is reported as a ``ParameterDefault``; ``FunctionHandler`` replaces it + with the semantic hasher's hash of the value, so a default never enters the + hash as its ``repr()`` (ITL-953). For **return** annotations the raw annotation object is stored unchanged. Canonicalisation happens at hash time: ``TypeObjectHandler`` (wired with the @@ -146,23 +139,22 @@ def extract_function_info( tc = self._type_converter - # Build each parameter string from structured components. - # Using _format_param instead of str(param) + string substitution avoids - # accidentally matching the annotation text inside a default value's repr, - # and correctly handles annotations that contain '=' (e.g. Literal["a=b"]). - param_strs = [] - for _, param in sig.parameters.items(): + # One structured entry per parameter, in declared order: name, kind, + # canonical annotation and default. Nothing is formatted into text, so a + # default's value can never be confused with part of an annotation. + parameters = [] + for param in sig.parameters.values(): annotation = param.annotation canonical_ann = ( canonical_annotation_str(annotation, tc) if annotation is not inspect.Parameter.empty else None ) - param_strs.append( - _format_param(param, canonical_ann, self.include_defaults) + parameters.append( + _parameter_entry(param, canonical_ann, self.include_defaults) ) - parts["params"] = ", ".join(param_strs) + parts["parameters"] = parameters # Add return annotation if present. # The raw annotation object is stored here and hashed by the type diff --git a/src/orcapod/protocols/hashing_protocols.py b/src/orcapod/protocols/hashing_protocols.py index 71e20342b..311f0717d 100644 --- a/src/orcapod/protocols/hashing_protocols.py +++ b/src/orcapod/protocols/hashing_protocols.py @@ -207,7 +207,26 @@ def extract_function_info( output_typespec: Schema | None = None, exclude_function_signature: bool = False, exclude_function_body: bool = False, - ) -> dict[str, Any]: ... + ) -> dict[str, Any]: + """Describe a function as a structure the semantic hasher can hash. + + An extractor that reports parameters returns them under ``"parameters"`` + as a list of entries, one per parameter. An entry's ``"default"`` that is a + ``ParameterDefault`` is replaced by ``FunctionHandler`` with the semantic + hasher's hash of the default value; the extractor itself has no hasher. + + Args: + func: The function to describe. + function_name: Name to use in place of the function's own name. + input_typespec: Input schema of the function, when known. + output_typespec: Output schema of the function, when known. + exclude_function_signature: Whether to leave the signature out. + exclude_function_body: Whether to leave the body out. + + Returns: + The function's description. + """ + ... class SemanticTypeHasherProtocol(Protocol): diff --git a/superpowers/plans/2026-11-11-itl-953-function-defaults-semantic-hash.md b/superpowers/plans/2026-11-11-itl-953-function-defaults-semantic-hash.md new file mode 100644 index 000000000..f4d0e19cb --- /dev/null +++ b/superpowers/plans/2026-11-11-itl-953-function-defaults-semantic-hash.md @@ -0,0 +1,290 @@ +# Function Defaults Through the Semantic Hasher (ITL-953) Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use sensei:subagent-driven-development (recommended) or sensei:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** A function's default values enter its hashes as the semantic hasher's hash of each +value instead of `repr(value)`; a default the hasher cannot hash raises, naming the parameter +and the function. + +**Architecture:** The signature text stops carrying defaults. Defaults become a separate member +of the hashed description: a list of `[parameter name, hash of the default]` in declared order, +present only when the function has defaults. One helper hashes the defaults and wraps the +hasher's `TypeError` with the parameter and function names; both hash sites call it. + +**Tech Stack:** Python 3.11-3.13, pytest via `uv run`. + +**Linear:** ITL-953 (In Progress). Branch `eywalker/itl-953-function-default-values-enter-the-function`, +to be created FROM `origin/eywalker/itl-967-v03-hash-step-combine-the-hash-changing` once the +coordinator says the six merges are in. PR against `main`, "Stacked on the ITL-967 pull request". + +**Status (November 12, 2026):** complete, PR opened against `main`, stacked on ITL-967. +Merged ITL-967 at `c4b1e4a7` (all six hash-step branches, main with #316, its golden +regeneration). Relative to `c4b1e4a7`: + +- golden files `tests/test_hashing/golden/data`: 0 changed, 0 removed, 5 added + (`semantic:function.value.{plain,defaults,kinds}`, + `semantic:function.stored_signature.{ratio,scaled}`); a regeneration on the merged head + gives no diff; +- re-pinned by hand: `test_canonical_type_names.py` + (`test_function_object_hash`, `test_function_signature_hash`) and the two + builtin-annotation functions in `hash_samples/type_annotation_golden.json` (a deliberate + pre-fix snapshot, so not regenerated wholesale); +- checks on the merged head: `uv run pytest tests/` 8608 passed, 101 skipped, 18 xfailed, + 0 failed (3.12; 3.11 and 3.13 were green at the previous merge, 8593 passed each); ruff + check and format clean; basedpyright exit 0; changelog fragments OK. + +**Round 1 (PR #323, CodeRabbit review 5871552520 on `3ed0d418`):** 30 findings, all in the +review body. Two were on this PR's files (missing docstrings in +`test_function_default_hashing.py` and `test_function_info_extractors.py`): fixed. The other +28 are on ITL-967 files and were routed to the coordinator. Then merged ITL-967 at `9743004d` +(main with #317): golden data still differs from that tip by the same 5 added entries only; +3.12 suite 8696 passed, 0 failed; ruff clean; basedpyright exit 0. + +**Left:** CI and CodeRabbit on the pushed head, the signed top-level comment, `worker_done`. + +**Decisions that supersede the text further down:** + +- **D1 = (b)** (developer): one structured description. `parameters` is a list of + `{name, kind, annotation, default}` entries in declared order; `annotation` / `default` + absent when there is none. Fixes finding X (parameter kind). Every function-value hash moves. +- **Stored column = `hash_object(function)`** (coordinator, supersedes D2/S2): one description + of a signature. Every newly written `__pf_var_function_signature_hash` value moves. + `get_function_signature` is no longer used by `src` (kept public, with the Y fix). +- **D3 = raise** for v0.3 (developer, November 11, 2026); follow-up ITL-971, named in the + docs, changelog fragment, design-issue file and PR body. `hash_default_value` (in + `builtin_handlers.py`) is the one function that decides how a default is hashed, so "hash a + pod parameter's default as the data value it would be in a column" can be added there later. + Not built. +- **D4** as proposed. With one site left there is no shared helper: `FunctionHandler` hashes + each `ParameterDefault` the extractor reports and wraps the hasher's `TypeError`. + +--- + +## Step 1 findings (read on `origin/eywalker/itl-967-…` at `c1949b24`, Python 3.12) + +### Where the signature is hashed: TWO code paths, not one + +The issue says `FunctionSignatureExtractor` feeds both hashes. It feeds only one. + +| Hash | Code path | Carries defaults as | +|---|---|---| +| A function used as a **value** (`semantic_hasher.hash_object(fn)`; any function inside an identity structure) | `FunctionHandler.handle` → `FunctionSignatureExtractor.extract_function_info` (`hashing/semantic_hashing/function_info_extractors.py`), registered in `contexts/data/v1.json` for `types.FunctionType`, `BuiltinFunctionType`, `MethodType` | `repr(default)` inside the `params` string (`_format_param`) | +| Stored variation value `function_signature_hash` → column `__pf_var_function_signature_hash` | `PythonDataFunction.__init__` (`core/data_function.py:519`): `semantic_hasher.hash_object(get_function_signature(function))`, where `get_function_signature` is the string builder in `hashing/hash_utils.py` | `repr(default)` inside `str(inspect.Parameter)` | + +- `FunctionSignatureExtractor` is referenced only by `v1.json` (component + `function_semantic_hasher`), by `register_builtin_handlers` (the fallback default) and by + `FunctionInfoExtractorFactory`. Its only consumer is `FunctionHandler`. +- `__pf_var_function_signature_hash` is written with every result row and read by nothing + (`grep signature_hash src`: only `data_function.py`). +- A function pod's identity does not use either: the uri is + `(function name, output-schema hash, major version, type id)`, and paths derive from the uri + and the pipeline hash. Confirmed by the passing pins in the new test file once added (Task 4). +- `function_content_hash` (`get_function_components`) hashes the source text, where a default + appears as written; it never calls `repr()` on a value. Not touched. + +### How default values hash under the context's strict semantic hasher + +| Default | Result | +|---|---| +| `None`, `bool`, `int`, `float`, `str` | hashed as the JSON primitive. `None` differs from "no default" (the entry is absent) | +| `tuple` | tagged `tuple`, order kept; differs from the equal `list` | +| `set` / `frozenset` | tagged `set`, items sorted (by canonical JSON once ITL-942 is merged): seed-independent | +| `dict` | keys sorted; insertion order irrelevant | +| `bytes`, `uuid.UUID`, a function or lambda, a type, `numpy.ndarray` (content hash, `NumpyArrayHandler`), pandas objects, anything with `identity_structure()` | hashed by its handler | +| `IntEnum` member, `str`-mixin enum member, `numpy.float64` | hashed as the `int` / `str` / `float` it subclasses: `IntEnum.A` (value 1) and `1` are one default. Existing hasher behaviour for primitive subclasses, not changed here | +| plain `enum.Enum` member | **raises** | +| dataclass instance | **raises** (the dataclass *type* is a logical type; its *values* have no structure-hasher handler) | +| `pathlib.Path` | **raises** (same: logical type, no value handler) | +| `numpy.int64`, `numpy.float32`, `numpy.bool_` | **raises** | +| `datetime`, `date`, `Decimal`, `complex`, `range`, `...`, `object()` | **raises** | + +### Which defaults in the repo would now raise + +- `src/`, `docs/`, `README.md`, `examples/`, `notebooks/`, `workshop/` and the tutorial branch + (PR #274): an AST scan finds no pod-decorated function with any default. +- Test suite and executed docs samples: see "Probe" below. + +**Probe.** A pytest plugin recorded every default that reaches either hash site during the full +suite (8325 passed; includes the executed docs samples in `tests/test_docs`) and tried the +strict hasher on it. Seven defaults reach a hash site, all `int` or `str`, all hashable: + +- stored signature hash: `func_with_default(y: int = …)` in + `tests/test_core/data_function/test_data_function.py`, `add_with_default(y: int = …)` (two + tests) in `tests/test_core/function_pod/test_simple_function_pod.py`; +- function value: four local functions in `tests/test_hashing/test_function_info_extractors.py` + (direct extractor calls). + +**Nothing in the repo, its tests, the docs samples, the workshop tool or the tutorial branch +would raise.** No test or sample hashes a function as a value except by calling the extractor +or the hasher directly. + +### Golden files and stored values + +- No golden entry pins a function with a default or a signature hash + (`tests/test_hashing/golden/data/*.json`); golden fixtures `golden_ratio`, `golden_adjust` + have no defaults. Expected: 0 changed; entries added to pin the new behaviour. +- `contexts/data/v1.json` is not edited (same class, same config), so its pinned sha256 in + `released_manifests.json` stands. + +### Out-of-scope findings (for worker_done) + +1. Both signature builders drop the parameter kind: `f(a, *, b)` and `f(a, b)`, and + `f(a, /, b)` and `f(a, b)`, share a function-value hash and a stored signature hash. +2. `get_function_signature(include_defaults=False)` cuts at the first `=`, truncating an + annotation such as `Literal["a=b"]` (the extractor already avoids this). +3. There are two parallel signature descriptions (the string in `hash_utils`, the dict in the + extractor). +4. On `c1949b24` four tests fail without any change of mine (ITL-967 is mid-merge): + `tests/test_core/sources/test_spiraldb_table_source_fake.py::TestSourceId::test_unrecorded_table_hashes_are_unchanged` + and `tests/test_core/sources/test_stream_builder.py::TestUnhashableColumnTypes::{test_fixed_size_list_column_is_named,test_map_column_is_named,test_every_unhashable_column_is_named}`. + +--- + +## Decisions sent to the coordinator + +**D1. Shape (recommended).** `params` keeps today's text minus the defaults; a new member +`defaults` = `[[name, ], …]` in declared order, only when the function has defaults. A +function without defaults keeps its hash. The hash is embedded as a `ContentHash`, so after +ITL-945 it is the tagged `{"__type__": "hash", "digest": …}` and cannot be spelled by a literal +default; a default is never embedded raw, so no literal can collide with it either way. +Alternative: a fully structured parameter list (name, kind, annotation, default), which also +fixes out-of-scope finding 1 but moves every function-value hash. + +**D2. Stored column.** (S2, recommended) same rule on the existing string path: no defaults → +`hash_object(signature_text)` as today (value unchanged); with defaults → +`hash_object({"signature": text without defaults, "defaults": [[name, hash], …]})`. Only +functions with defaults move. (S1) store `hash_object(function)`: one description, but every +newly written value of the column moves, and the pinned value in +`test_canonical_type_names.py::TestFunctionPodGolden::test_function_signature_hash` changes. + +**D3. Path / Enum / dataclass defaults raise.** Per the issue (no fallback). Adding value +handlers for them is scope growth; not planned unless asked. + +**D4. Error type.** `TypeError` (what the hasher raises), chained from the hasher's error, +message: parameter name, function `module.qualname`, the hasher's text, and the remedy. + +--- + +### Coordinator's answers (November 11, 2026) + +- D2: **S2 approved.** D4: **approved.** Finding Y: fix as part of S2, with a test. +- D1 and D3: with the developer (D1 presented as (a) against (b) together with finding X; + D3 as raise against value handlers for Path / Enum / datetime). **Pending.** +- No branch until the coordinator says the six merges are in. +- Tests extended meanwhile (74 tests: 18 fail, 56 pass on `c1949b24`): + `TestDefaultsOfCommonTypes` holds under either D3 answer (refused, or hashed by value); + `TestParameterKind` covers X and stays only if D1 is (b), otherwise it is removed and X is + reported; `TestSignatureTextWithoutDefaults` covers Y. + +## File structure + +| File | Change | +|---|---| +| `src/orcapod/hashing/semantic_hashing/function_info_extractors.py` | `_format_param` loses the default; new `parameter_defaults(func)` and `hash_parameter_defaults(func, hasher)`; extractor reports `defaults` when `include_defaults` | +| `src/orcapod/hashing/semantic_hashing/builtin_handlers.py` | `FunctionHandler.handle` replaces the reported defaults by their hashes | +| `src/orcapod/hashing/hash_utils.py` | `get_function_signature` builds parameters without `repr()` of defaults when `include_defaults=False` (structured, no `split("=")`) | +| `src/orcapod/core/data_function.py` | stored signature hash per D2 | +| `src/orcapod/protocols/hashing_protocols.py` | docstring of `extract_function_info`: the `defaults` member | +| `tests/test_hashing/test_function_default_hashing.py` | new (written, failing) | +| `tests/test_hashing/test_function_info_extractors.py` | update the two `include_defaults` assertions | +| `tests/test_hashing/golden/cases.py`, `golden/data/semantic.json` | add entries for functions with defaults (additions only) | +| `docs/reference/hashing.md`, `docs/concepts/function-pods.md` | the rule, the consequence, the remedy | +| `changelog.d/ITL-953.md`, `design_issues/ITL-953-FD1.md` | fragment and entry | + +## Tasks (ORIGINAL draft for D1 (a) / S2; kept as the Step 1 record, superseded by the decisions at the top) + +### Task 1: branch and commit the failing tests + +- [ ] `git checkout -b eywalker/itl-953-function-default-values-enter-the-function origin/eywalker/itl-967-v03-hash-step-combine-the-hash-changing` +- [ ] `uv run pytest tests/test_hashing/test_function_default_hashing.py -q` → expect 11 failed, + 34 passed (dict order ×2, seeds, same-repr ×2, six "raises" tests). +- [ ] Commit `test(hashing): failing tests for function defaults through the semantic hasher (ITL-953)` with this plan; push. + +### Task 2: function-value hash + +- [ ] In `function_info_extractors.py`: + +```python +def parameter_defaults(func: Callable[..., Any]) -> list[tuple[str, Any]]: + """Return ``(name, default)`` for each parameter of ``func`` that has a default, in declared order.""" + return [ + (name, param.default) + for name, param in inspect.signature(func).parameters.items() + if param.default is not inspect.Parameter.empty + ] + + +def hash_parameter_defaults( + func: Callable[..., Any], hasher: "SemanticHasherProtocol" +) -> list[list[Any]]: + """Return ``[name, hash]`` for each default of ``func``, hashed by ``hasher``. + + Raises: + TypeError: If ``hasher`` cannot hash a default; names the parameter and the function. + """ + hashed: list[list[Any]] = [] + for name, default in parameter_defaults(func): + try: + hashed.append([name, hasher.hash_object(default)]) + except TypeError as exc: + where = f"{getattr(func, '__module__', '?')}.{getattr(func, '__qualname__', repr(func))}" + raise TypeError( + f"Cannot hash the default value of parameter {name!r} of function " + f"{where}: {exc} A default value is part of the function's hash. Register " + "a handler for its type, or remove the default and supply the value as " + "an input." + ) from exc + return hashed +``` + +- [ ] `_format_param(param, canonical_annotation)` drops `include_defaults` and never formats a + default. `FunctionSignatureExtractor.extract_function_info` (which has no hasher) reports + the raw defaults when `include_defaults` is true and the function has any: + `parts["defaults"] = parameter_defaults(func)`. `FunctionHandler.handle` (which has the + hasher) replaces that member: `if "defaults" in info: info["defaults"] = hash_parameter_defaults(obj, hasher)`. + The `defaults` member is documented on `FunctionInfoExtractorProtocol.extract_function_info`. +- [ ] Run the `value` tests → pass; `uv run pytest tests/test_hashing -q` → only the two + `include_defaults` extractor assertions need updating; golden suite unchanged. +- [ ] Commit `fix(hashing): function defaults enter the function-value hash through the semantic hasher (ITL-953)`. + +### Task 3: stored signature hash (per D2 answer) + +- [ ] `get_function_signature(include_defaults=False)` formats each parameter from its parts + (name, kind prefix, canonical annotation); `include_defaults=True` output unchanged. +- [ ] `PythonDataFunction.__init__`: + +```python +signature_text = get_function_signature(function, include_defaults=False) +defaults = hash_parameter_defaults(function, semantic_hasher) +signature: Any = ( + {"signature": signature_text, "defaults": defaults} if defaults else signature_text +) +self._function_signature_hash = semantic_hasher.hash_object(signature).to_prefixed_digest() +``` + +- [ ] Run the `stored` tests and `tests/test_core/data_function` → pass, the pinned value in + `test_canonical_type_names.py` unchanged. +- [ ] Commit `fix(data_function): stored signature hash takes defaults through the semantic hasher (ITL-953)`. + +### Task 4: pins, golden additions, identity unaffected + +- [ ] Add tests: a pod's `uri`, `pipeline_hash()` and `content_hash()` are equal for two + functions that differ only in a default; a no-default function's value hash and stored + hash equal the values computed on the ITL-967 branch before the change (literals). +- [ ] Add golden cases `semantic:function_defaults.*` (primitives, tuple, frozenset, dict, + nested function, no default); regenerate; `git diff --stat` on the golden data must show + additions only. List every entry in the PR. + +### Task 5: docs, changelog fragment, design issue + +- [ ] `docs/reference/hashing.md`: "Function values and default values" (rule, table of what + hashes and what raises, remedy). `docs/concepts/function-pods.md`: one paragraph at the + default-parameter text: a default of an unregistered type fails at construction. +- [ ] `changelog.d/ITL-953.md` (`### Breaking changes and migration`, `### Fixed`); + `uv run python scripts/assemble_changelog.py --check`. +- [ ] `design_issues/ITL-953-FD1.md`. + +### Task 6: verify and deliver + +- [ ] `uv run --with ruff ruff check .`, `ruff format --check .`, `uv run --with basedpyright basedpyright` (exit code), `uv run pytest tests/`. +- [ ] Merge `origin/main` if it moved; push once; PR per the brief; CodeRabbit round; `worker_done`. diff --git a/tests/test_hashing/golden/cases.py b/tests/test_hashing/golden/cases.py index 9384e25ac..5f212392f 100644 --- a/tests/test_hashing/golden/cases.py +++ b/tests/test_hashing/golden/cases.py @@ -366,6 +366,64 @@ def semantic_values() -> dict[str, Any]: return {k: hasher.hash_object(v).to_string() for k, v in SEMANTIC_VALUES.items()} +def golden_fn_plain(a: int, b: str) -> float: + """Function hashed as a value by the semantic group (ITL-953). DO NOT MOVE.""" + return float(a) + + +def golden_fn_defaults( + a: int, + b: str = "x", + c: int | None = None, + d: tuple[int, ...] = (1, 2), + e: frozenset[str] = frozenset({"p", "q", "r"}), + f: dict[str, list[int]] = {"k": [1, 2], "j": []}, # noqa: B006 (never mutated) +) -> float: + """Function with default values, hashed as a value (ITL-953). DO NOT MOVE.""" + return float(a) + + +def golden_fn_kinds(a: int, /, b: int, *, c: int = 0) -> int: + """Function with every parameter kind, hashed as a value (ITL-953). DO NOT MOVE.""" + return a + b + c + + +def golden_scaled(age: int, factor: float = 2.0) -> float: + """Data function with a default, pinned by its stored signature hash. DO NOT MOVE.""" + return age * factor + + +@case("semantic", "function") +def semantic_functions() -> dict[str, Any]: + """Pin the hash of a function used as a value and the stored signature hash. + + A default value enters as the semantic hasher's hash of the value and each + parameter carries its kind (ITL-953). + + Returns: + The function-value hashes, and the ``function_signature_hash`` a data + function stores with every result row. + """ + from orcapod.core.data_function import PythonDataFunction + + hasher = _ctx().semantic_hasher + out: dict[str, Any] = { + "value.plain": hasher.hash_object(golden_fn_plain).to_string(), + "value.defaults": hasher.hash_object(golden_fn_defaults).to_string(), + "value.kinds": hasher.hash_object(golden_fn_kinds).to_string(), + } + data_functions = { + "ratio": golden_ratio.pod.data_function, + "scaled": PythonDataFunction(golden_scaled, output_keys="scaled"), + } + for name, data_function in data_functions.items(): + variation = data_function.get_function_variation_data() + out[f"stored_signature.{name}"] = _bytes_text( + variation["function_signature_hash"] + ) + return out + + def _semantic_types() -> dict[str, Any]: return { "int": int, diff --git a/tests/test_hashing/golden/data/semantic.json b/tests/test_hashing/golden/data/semantic.json index a166e3323..4020e77a9 100644 --- a/tests/test_hashing/golden/data/semantic.json +++ b/tests/test_hashing/golden/data/semantic.json @@ -1,4 +1,9 @@ { + "function.stored_signature.ratio": "semantic_v1:7804cfbf8935f990b4d7941be5dae40aa9b2ff0bc94a3eb81d97a6db4b0dce77", + "function.stored_signature.scaled": "semantic_v1:143251902c84387a1acb97e0076d00a3d17c0b4671c3a3449271750c8c38866e", + "function.value.defaults": "semantic_v1:a55248ece1fc5e1a3c19860c390217a2325b843a0469982749706f38175d4366", + "function.value.kinds": "semantic_v1:1dc69aa0a124034e0ed4a42eaff8b53eaf417f37fdf992b578851b576624825b", + "function.value.plain": "semantic_v1:9a1060e257ae4ed91e08cd674ab7504d267df5f6a444a6b63bf7c334817950fc", "polars_expr.and_two_columns": "polars_expr_v1:f8d1228cb5a4f9ca281f2918acc70ac9067052301c4784ec205ed71d6648afd7", "polars_expr.eq_string": "polars_expr_v1:64fbdf549ede833eed74ee19dd1884292576534c215bfdb2521ce16df514132a", "polars_expr.gt_datetime_utc": "polars_expr_v1:b791db9b35617d6296304cc8eda154da2fe7049565b9d0e209c9a39ac731b603", diff --git a/tests/test_hashing/hash_samples/type_annotation_golden.json b/tests/test_hashing/hash_samples/type_annotation_golden.json index 13abffa41..2f9e9c28d 100644 --- a/tests/test_hashing/hash_samples/type_annotation_golden.json +++ b/tests/test_hashing/hash_samples/type_annotation_golden.json @@ -17,8 +17,8 @@ "Optional[op.File]": "semantic_v1:7816cc078cf2984dd36907c954daf1faff0272a8f7b66faa1ca5443e0552d8f9" }, "function_info_hashes": { - "fn_no_annotations": "semantic_v1:45aaeae8585a01d32864c5bc9b6419cec10c58ac6a4edab012f37fde0125f300", - "fn_builtin_param": "semantic_v1:4188e21fba6bb2e56a2f3b5d18b3b61e7c08044bbcfa2188a0a6b2cb13a0526a", + "fn_no_annotations": "semantic_v1:cd869089f120616e2030978c623e0f2ed3175fec799837eb3d546a06e3d20784", + "fn_builtin_param": "semantic_v1:450ffccf13fe5018da5393a701dcbc31f2e299bc152925a67547f09277ceece1", "fn_orcapod_param": "semantic_v1:f6d172eb51f2e924ef5955fca69d873ce35a7a454d7be20903295cb2dd4cfcc5", "fn_orcapod_return": "semantic_v1:2ec283815474854f4f869f7f426b9b7d1836baa8179a62958f24298a4628e2a2", "fn_generic_orcapod": "semantic_v1:bf9bf058a6b7570e5c9a55a788008d7f12ed310fb4d0e3a433f6ac7a635b5f9b", @@ -26,8 +26,8 @@ "fn_mixed": "semantic_v1:cd311a2c94580a0b176784daa422445497a9e305c1bf580b340a71b1b8c3b974" }, "function_object_hashes": { - "fn_no_annotations": "semantic_v1:45aaeae8585a01d32864c5bc9b6419cec10c58ac6a4edab012f37fde0125f300", - "fn_builtin_param": "semantic_v1:32a86b953b01e9b9b7c0a77a8fe1001b4d2f0a024d24200664eadd1158d4c25f", + "fn_no_annotations": "semantic_v1:cd869089f120616e2030978c623e0f2ed3175fec799837eb3d546a06e3d20784", + "fn_builtin_param": "semantic_v1:450ffccf13fe5018da5393a701dcbc31f2e299bc152925a67547f09277ceece1", "fn_orcapod_param": "semantic_v1:f6d172eb51f2e924ef5955fca69d873ce35a7a454d7be20903295cb2dd4cfcc5", "fn_orcapod_return": "semantic_v1:2ec283815474854f4f869f7f426b9b7d1836baa8179a62958f24298a4628e2a2", "fn_generic_orcapod": "semantic_v1:bf9bf058a6b7570e5c9a55a788008d7f12ed310fb4d0e3a433f6ac7a635b5f9b", diff --git a/tests/test_hashing/test_canonical_type_names.py b/tests/test_hashing/test_canonical_type_names.py index 72ffeffbc..df9663036 100644 --- a/tests/test_hashing/test_canonical_type_names.py +++ b/tests/test_hashing/test_canonical_type_names.py @@ -290,15 +290,18 @@ def test_components_annotations_line( def test_extractor_without_converter(self): info = FunctionSignatureExtractor().extract_function_info(golden_fn) - assert info["params"] == ( - "a: pathlib.Path, b: pathlib.Path | str, c: list[pathlib.Path], " - "d: dict[str, pathlib.Path], e: datetime.datetime" - ) + assert [(p["name"], p["annotation"]) for p in info["parameters"]] == [ + ("a", "pathlib.Path"), + ("b", "pathlib.Path | str"), + ("c", "list[pathlib.Path]"), + ("d", "dict[str, pathlib.Path]"), + ("e", "datetime.datetime"), + ] def test_function_object_hash(self): hasher = get_default_context().semantic_hasher assert hasher.hash_object(golden_fn).to_string() == ( - "semantic_v1:79e6590be1c9177a9b564559bd9dea14dd09968593da57174daae80dcfbfb4d0" + "semantic_v1:a55cef45f6b09c6d4189f958f97153bcfe1b510ea620695098e9b6c44695868b" ) @@ -312,8 +315,7 @@ def data_function(self) -> PythonDataFunction: def test_function_signature_hash(self, data_function: PythonDataFunction): variation = data_function.get_function_variation_data() assert variation["function_signature_hash"] == ( - b"semantic_v1:\x1cT\x97A$\x9d%\xac\x1e\xd4t\xa0#7\xe3Q\x1f*\xa5{" - b"\xa8\xfa\xee\xe2E\xf6\xa5\xf7\x80\x8d\xd7\x8b" + b"semantic_v1:\x0bHO\x1c\xc0K\xb9qp\x9cf\xcd\xb3\x15\x90T2fS<\xd4\xe5.\xcf\x05\x88\n\xdf*\x1d&\x9e" ) def test_function_content_hash(self, data_function: PythonDataFunction): diff --git a/tests/test_hashing/test_function_default_hashing.py b/tests/test_hashing/test_function_default_hashing.py new file mode 100644 index 000000000..05c77d43d --- /dev/null +++ b/tests/test_hashing/test_function_default_hashing.py @@ -0,0 +1,442 @@ +"""A function's default values enter its hashes through the semantic hasher (ITL-953). + +Finding L2 of the hash-site audit (Appendix A.9 of the ITL-938 design): a default value +used to enter the function's hashed description as ``repr(value)``, so a ``frozenset`` +default hashed differently under every hash seed and a default such as ``object()`` +embedded a memory address. Two hashes take a function's signature: + +* the hash of a function used as a value (``semantic_hasher.hash_object(fn)``), and +* the stored variation value ``function_signature_hash`` of a data function (the + ``__pf_var_function_signature_hash`` column). + +Every test drives both through the public interface. +""" + +from __future__ import annotations + +import dataclasses +import datetime +import enum +import os +import subprocess +import sys +import textwrap +from collections.abc import Callable +from decimal import Decimal +from pathlib import Path +from typing import Any, Literal + +import pytest + +from orcapod import FunctionPod, function_pod +from orcapod.contexts import resolve_context +from orcapod.core.data_function import PythonDataFunction +from orcapod.sources import DictSource + + +def _value_hash(fn: Callable[..., Any]) -> str: + """Hash of ``fn`` used as a value, by the default data context's semantic hasher.""" + return resolve_context(None).semantic_hasher.hash_object(fn).to_string() + + +def _stored_signature_hash(fn: Callable[..., Any]) -> bytes: + """The ``function_signature_hash`` a data function stores with every result row.""" + data_function = PythonDataFunction(fn, output_keys="out") + return data_function.get_function_variation_data()["function_signature_hash"] + + +HASH_SITES = pytest.mark.parametrize( + "site", [_value_hash, _stored_signature_hash], ids=["value", "stored"] +) + + +def _with_default(default: Any) -> Callable[..., Any]: + """A function ``f(x: int, option=) -> int``; only the default varies.""" + + def f(x: int, option: Any = default) -> int: + return x + + return f + + +def _without_default() -> Callable[..., Any]: + """The same function as ``_with_default`` builds, with no default on ``option``.""" + + def f(x: int, option: Any) -> int: + return x + + return f + + +class _Unregistered: + """A class the semantic hasher has no handler for.""" + + +# --------------------------------------------------------------------------- +# Equal defaults hash equally +# --------------------------------------------------------------------------- + + +@HASH_SITES +class TestEqualDefaultsHashEqually: + """Defaults that are equal as values give one hash, however they were built.""" + + def test_dict_default_ignores_insertion_order(self, site: Callable[..., Any]): + """``{"a": 1, "b": 2}`` and ``{"b": 2, "a": 1}`` are one default.""" + assert site(_with_default({"a": 1, "b": 2})) == site( + _with_default({"b": 2, "a": 1}) + ) + + def test_set_default_ignores_construction_order(self, site: Callable[..., Any]): + """Two equal frozensets built in different orders are one default.""" + forward = frozenset(["w", "x", "y", "z", "alpha", "beta"]) + backward = frozenset(["beta", "alpha", "z", "y", "x", "w"]) + assert site(_with_default(forward)) == site(_with_default(backward)) + + def test_same_default_twice(self, site: Callable[..., Any]): + """Two functions that differ in nothing hash equally.""" + assert site(_with_default((1, "a", None))) == site( + _with_default((1, "a", None)) + ) + + +_SEED_SCRIPT = """ + from typing import Any + + from orcapod.contexts import resolve_context + from orcapod.core.data_function import PythonDataFunction + + def f(x: int, option: Any = frozenset({"w", "x", "y", "z", "alpha", "beta"}), + *, table: Any = {"b": {1, 2, 3}, "a": ("p", "q")}) -> int: + return x + + value = resolve_context(None).semantic_hasher.hash_object(f).to_string() + stored = PythonDataFunction(f, output_keys="out").get_function_variation_data()[ + "function_signature_hash" + ] + print(value, stored.hex()) +""" + + +def _run_with_seed(script: str, seed: str) -> str: + """Run ``script`` in a fresh interpreter under ``PYTHONHASHSEED=seed``; return stdout.""" + env = os.environ.copy() + env["PYTHONHASHSEED"] = seed + result = subprocess.run( + [sys.executable, "-c", textwrap.dedent(script)], + capture_output=True, + text=True, + env=env, + check=False, # the assertion below reports stderr on failure + ) + assert result.returncode == 0, result.stderr + return result.stdout.strip() + + +class TestAcrossProcessesAndHashSeeds: + """Both hashes of a function are the same in every process and hash seed.""" + + def test_set_and_dict_defaults_hash_equally_under_every_seed(self): + """Both hashes of one function are the same in every process and hash seed.""" + outputs = {seed: _run_with_seed(_SEED_SCRIPT, seed) for seed in "01234567"} + assert len(set(outputs.values())) == 1, outputs + + +# --------------------------------------------------------------------------- +# Different defaults hash differently +# --------------------------------------------------------------------------- + + +@HASH_SITES +class TestDifferentDefaultsHashDifferently: + """Defaults that differ as values never share a hash.""" + + @pytest.mark.parametrize( + ("left", "right"), + [ + (1, 2), + (1, "1"), + (1, 1.5), + (None, "None"), + (None, 0), + (False, 0), + ((1, 2), [1, 2]), + ((1, 2), (2, 1)), + (frozenset({1, 2}), (1, 2)), + ({"a": 1}, {"a": 2}), + ("a", b"a"), + ], + ) + def test_distinct_values(self, site: Callable[..., Any], left: Any, right: Any): + """Two functions that differ only in the default's value hash differently.""" + assert site(_with_default(left)) != site(_with_default(right)) + + def test_default_none_differs_from_no_default(self, site: Callable[..., Any]): + """``option=None`` and a required ``option`` are different signatures.""" + assert site(_with_default(None)) != site(_without_default()) + + def test_default_cannot_spell_the_hash_of_another_default( + self, site: Callable[..., Any] + ): + """A string default equal to another default's hash text is still its own value.""" + hasher = resolve_context(None).semantic_hasher + hash_of_one = hasher.hash_object(1) + for spelling in (hash_of_one.to_string(), hash_of_one.to_hex()): + assert site(_with_default(spelling)) != site(_with_default(1)) + + def test_default_cannot_spell_the_hashers_encoding(self, site: Callable[..., Any]): + """A dict default that spells a tagged encoding is not the value it spells.""" + forged = {"__type__": "tuple", "items": [1, 2]} + assert site(_with_default(forged)) != site(_with_default((1, 2))) + + def test_the_parameter_a_default_belongs_to_matters(self, site: Callable[..., Any]): + """``a=1, b=2`` and ``a=2, b=1`` are different signatures.""" + + def swapped_ab(x: int, a: int = 1, b: int = 2) -> int: + return x + + first = swapped_ab + + def swapped_ab(x: int, a: int = 2, b: int = 1) -> int: # noqa: F811 (same name on purpose) + return x + + assert site(first) != site(swapped_ab) + + def test_same_repr_different_value(self, site: Callable[..., Any]): + """Two defaults that print alike are still told apart by their value.""" + + class Text(str): + """A string whose ``repr()`` is that of the integer 1.""" + + def __repr__(self) -> str: + return "1" + + assert repr(Text("one")) == repr(1) + assert site(_with_default(Text("one"))) != site(_with_default(1)) + + +# --------------------------------------------------------------------------- +# A default the hasher cannot hash raises +# --------------------------------------------------------------------------- + + +class TestUnhashableDefaultRaises: + """A default the semantic hasher cannot hash is an error, never a fallback.""" + + def test_function_value_names_parameter_and_function(self): + """Hashing the function names the parameter, the function and the type.""" + fn = _with_default(_Unregistered()) + with pytest.raises(TypeError) as excinfo: + _value_hash(fn) + message = str(excinfo.value) + assert "'option'" in message + assert fn.__qualname__ in message + assert "_Unregistered" in message + + def test_data_function_fails_at_construction(self): + """A data function with such a default cannot be built.""" + fn = _with_default(object()) + with pytest.raises(TypeError) as excinfo: + PythonDataFunction(fn, output_keys="out") + message = str(excinfo.value) + assert "'option'" in message + assert fn.__qualname__ in message + + def test_function_pod_decorator_fails_at_decoration(self): + """``@function_pod`` raises when it is applied, naming the parameter.""" + with pytest.raises(TypeError, match="'marker'"): + + @function_pod(output_keys="out") + def uses_marker(x: int, marker: Any = _Unregistered()) -> int: + return x + + def test_unhashable_member_of_a_container_default_raises(self): + """No fallback to ``repr()`` for a value nested inside a hashable container.""" + with pytest.raises(TypeError, match="'option'"): + _value_hash(_with_default((1, _Unregistered()))) + + def test_error_keeps_the_hashers_error_as_its_cause(self): + """The hasher's own ``TypeError`` is chained as the cause.""" + with pytest.raises(TypeError) as excinfo: + _value_hash(_with_default(_Unregistered())) + assert isinstance(excinfo.value.__cause__, TypeError) + + def test_error_states_the_remedy(self): + """The message says the default is the problem and how to register a handler.""" + with pytest.raises(TypeError) as excinfo: + _value_hash(_with_default(_Unregistered())) + message = str(excinfo.value) + assert "PythonTypeHandlerProtocol" in message or "handler" in message + assert "default" in message + + +# --------------------------------------------------------------------------- +# Defaults of common non-primitive types (decision D3: raise, or a value handler) +# --------------------------------------------------------------------------- + + +class _Colour(enum.Enum): + """A plain enum, which the semantic hasher has no handler for.""" + + RED = 1 + BLUE = 2 + + +@dataclasses.dataclass(frozen=True) +class _Window: + """A dataclass whose instances the semantic hasher has no handler for.""" + + start: int + stop: int + + +def _hash_or_error(site: Callable[..., Any], default: Any) -> Any: + """The site's hash for a function with ``default``, or ``TypeError`` if it refuses.""" + try: + return site(_with_default(default)) + except TypeError: + return TypeError + + +_COMMON_TYPE_PAIRS = [ + pytest.param(lambda: _Colour.RED, lambda: _Colour.BLUE, id="enum"), + pytest.param(lambda: Path("/data/a"), lambda: Path("/data/b"), id="path"), + pytest.param(lambda: _Window(0, 10), lambda: _Window(0, 20), id="dataclass"), + pytest.param( + lambda: datetime.datetime(2026, 1, 1), + lambda: datetime.datetime(2026, 1, 2), + id="datetime", + ), + pytest.param( + lambda: datetime.date(2026, 1, 1), lambda: datetime.date(2026, 1, 2), id="date" + ), + pytest.param(lambda: Decimal("1.5"), lambda: Decimal("1.50"), id="decimal"), +] + + +@HASH_SITES +@pytest.mark.parametrize(("make_left", "make_right"), _COMMON_TYPE_PAIRS) +class TestDefaultsOfCommonTypes: + """Hold whichever way D3 is decided: such a default is refused or hashed by value.""" + + def test_two_values_never_share_a_hash( + self, + site: Callable[..., Any], + make_left: Callable[[], Any], + make_right: Callable[[], Any], + ): + """Two different values are refused or get different hashes.""" + left, right = ( + _hash_or_error(site, make_left()), + _hash_or_error(site, make_right()), + ) + assert left is TypeError or right is TypeError or left != right + + def test_equal_values_agree( + self, + site: Callable[..., Any], + make_left: Callable[[], Any], + make_right: Callable[[], Any], + ): + """The same value built twice is refused both times or hashed alike.""" + assert _hash_or_error(site, make_left()) == _hash_or_error(site, make_left()) + + +# --------------------------------------------------------------------------- +# Parameter kind (out-of-scope finding X; in scope only if D1 is decided as (b)) +# --------------------------------------------------------------------------- + + +@HASH_SITES +class TestParameterKind: + """``f(a, *, b)``, ``f(a, /, b)`` and ``f(a, b)`` are three signatures.""" + + def test_keyword_only_marker(self, site: Callable[..., Any]): + """``f(a, *, b)`` differs from ``f(a, b)``.""" + + def kinds(a: int, b: int) -> int: + return a + + plain = kinds + + def kinds(a: int, *, b: int) -> int: # noqa: F811 (same name on purpose) + return a + + assert site(plain) != site(kinds) + + def test_positional_only_marker(self, site: Callable[..., Any]): + """``f(a, /, b)`` differs from ``f(a, b)``.""" + + def kinds(a: int, b: int) -> int: + return a + + plain = kinds + + def kinds(a: int, /, b: int) -> int: # noqa: F811 (same name on purpose) + return a + + assert site(plain) != site(kinds) + + +# --------------------------------------------------------------------------- +# Finding Y: an annotation containing "=" survives when defaults are left out +# --------------------------------------------------------------------------- + + +class TestSignatureTextWithoutDefaults: + """``get_function_signature(include_defaults=False)`` keeps the whole annotation.""" + + def test_annotation_containing_equals_is_kept(self): + # get_function_signature is the public helper the stored hash is built from. + """``Literal["a=b", "c"]`` survives and both defaults are left out.""" + from orcapod.hashing.hash_utils import get_function_signature + + def fn(mode: Literal["a=b", "c"] = "c", n: int = 3) -> int: + return n + + text = get_function_signature(fn, include_defaults=False) + assert "Literal['a=b', 'c']" in text + assert "n: int" in text + assert "= 3" not in text and "= 'c'" not in text + + +# --------------------------------------------------------------------------- +# A function pod's identity does not use the signature hash +# --------------------------------------------------------------------------- + + +class TestPodIdentityIgnoresDefaults: + """Changing a default moves the signature hash and nothing a path is built from.""" + + @staticmethod + def _pod_output(factor: float) -> tuple[FunctionPod, Any]: + def scale(x: int, factor: float = factor) -> float: + return x * factor + + pod = FunctionPod.from_fn(scale, output_keys="scaled") + source = DictSource( + data=[{"k": "a", "x": 1}, {"k": "b", "x": 2}], + tag_columns=["k"], + source_id="defaults_source", + ) + return pod, pod(source) + + def test_uri_pipeline_hash_and_content_hash_are_unchanged(self): + """Two pods that differ only in a default share uri and both hashes.""" + pod_two, out_two = self._pod_output(2.0) + pod_three, out_three = self._pod_output(3.0) + + assert pod_two.uri == pod_three.uri + assert out_two.pipeline_hash() == out_three.pipeline_hash() + assert out_two.content_hash() == out_three.content_hash() + + def test_stored_signature_hash_differs(self): + """The same two pods store different signature hashes.""" + pod_two, _ = self._pod_output(2.0) + pod_three, _ = self._pod_output(3.0) + + def signature_hash(pod: FunctionPod) -> bytes: + variation = pod.data_function.get_function_variation_data() + return variation["function_signature_hash"] + + assert signature_hash(pod_two) != signature_hash(pod_three) diff --git a/tests/test_hashing/test_function_info_extractors.py b/tests/test_hashing/test_function_info_extractors.py index bfa96b876..0b3a04d45 100644 --- a/tests/test_hashing/test_function_info_extractors.py +++ b/tests/test_hashing/test_function_info_extractors.py @@ -10,6 +10,12 @@ import pytest import orcapod as op from orcapod.contexts import get_default_context +from orcapod.hashing.semantic_hashing.function_info_extractors import ParameterDefault + + +def _annotations(info: dict[str, typing.Any]) -> dict[str, str]: + """Map each parameter name of an extracted description to its annotation text.""" + return {entry["name"]: entry["annotation"] for entry in info["parameters"]} class TestFunctionNameExtractor: @@ -63,14 +69,19 @@ def _make(self, **kwargs): return FunctionSignatureExtractor(**kwargs) - def test_basic_extraction_returns_dict_with_name_and_params(self): + def test_basic_extraction_returns_dict_with_name_and_parameters(self): + """The description holds the name, the module and one entry per parameter.""" + def my_func(x: int, y: str) -> bool: return True result = self._make().extract_function_info(my_func) assert "name" in result assert result["name"] == "my_func" - assert "params" in result + assert result["parameters"] == [ + {"name": "x", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "int"}, + {"name": "y", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str"}, + ] assert "module" in result def test_non_callable_raises_type_error(self): @@ -92,18 +103,54 @@ def fn(): assert "module" in result def test_include_defaults_false_strips_defaults(self): + """With ``include_defaults=False`` no entry reports a default.""" + def fn(x: int = 42, y: str = "hi") -> None: pass result = self._make(include_defaults=False).extract_function_info(fn) - assert result["params"] == "x: int, y: str" + assert _annotations(result) == {"x": "int", "y": "str"} + assert all("default" not in entry for entry in result["parameters"]) def test_include_defaults_true_keeps_defaults(self): + """A default is reported as a ``ParameterDefault`` holding the value.""" + def fn(x: int = 42) -> None: pass result = self._make(include_defaults=True).extract_function_info(fn) - assert result["params"] == "x: int = 42" + assert result["parameters"] == [ + { + "name": "x", + "kind": "POSITIONAL_OR_KEYWORD", + "annotation": "int", + "default": ParameterDefault(42), + } + ] + + def test_default_none_is_reported_and_no_default_is_absent(self): + """``y=None`` has a ``default`` entry; a required parameter has none.""" + + def fn(x: int, y: int | None = None) -> None: + pass + + x, y = self._make().extract_function_info(fn)["parameters"] + assert "default" not in x + assert y["default"] == ParameterDefault(None) + + def test_unannotated_parameter_has_no_annotation_entry(self): + """A parameter without an annotation has no ``annotation`` member.""" + + def fn(x, y=1): # noqa: ANN001, ANN202 (unannotated on purpose) + pass + + x, y = self._make().extract_function_info(fn)["parameters"] + assert x == {"name": "x", "kind": "POSITIONAL_OR_KEYWORD"} + assert y == { + "name": "y", + "kind": "POSITIONAL_OR_KEYWORD", + "default": ParameterDefault(1), + } def test_return_annotation_present(self): def fn() -> str: @@ -142,17 +189,14 @@ def fn2(x: Path | str) -> None: r2 = self._make(include_module=False).extract_function_info( fn2, function_name="fn" ) - assert r1["params"] == "x: pathlib.Path | str" - assert r2["params"] == "x: pathlib.Path | str" + assert _annotations(r1) == {"x": "pathlib.Path | str"} + assert _annotations(r2) == {"x": "pathlib.Path | str"} def test_annotation_containing_equals_preserved_when_defaults_stripped(self): """Annotations containing ``=`` are not truncated when include_defaults=False. - The old approach stripped defaults via ``str(param).split('=')[0].strip()``, - which corrupts annotations that contain ``=``. For example - ``Literal["a=b"] = "v"`` would be split to ``Literal["a``. Confirmed that - this test FAILS with the old implementation and PASSES with ``_format_param``, - which checks ``param.default is not inspect.Parameter.empty`` directly. + The annotation and the default are separate members of the parameter's + entry, so no text is ever cut at ``=``. """ from typing import Literal @@ -165,37 +209,34 @@ def fn(x: Literal["a=b"] = "default_value") -> None: # falls back and formatannotation wraps the string literal in quotes. # The key property is that the full annotation is present and the default # value ("default_value") is absent — verified exactly here. - assert "Literal" in result["params"] and "a=b" in result["params"] - assert "default_value" not in result["params"] - # No '=' from the default assignment should survive (annotation may contain - # its own '=' as part of Literal, but the default is stripped cleanly). - assert result["params"].count("=") == result["params"].count("a=b") + (entry,) = result["parameters"] + assert "Literal" in entry["annotation"] and "a=b" in entry["annotation"] + assert "default" not in entry def test_varargs_and_kwargs_with_annotations(self): - """*args and **kwargs with annotations are formatted correctly. - - Verifies that ``_format_param`` produces the right ``*`` / ``**`` prefix - for VAR_POSITIONAL and VAR_KEYWORD parameters. - """ + """*args and **kwargs are told apart by their kind, not by a name prefix.""" def fn(*args: int, **kwargs: str) -> None: pass result = self._make().extract_function_info(fn) - assert result["params"] == "*args: int, **kwargs: str" + assert result["parameters"] == [ + {"name": "args", "kind": "VAR_POSITIONAL", "annotation": "int"}, + {"name": "kwargs", "kind": "VAR_KEYWORD", "annotation": "str"}, + ] - def test_keyword_only_param_formatted_without_star_prefix(self): - """Keyword-only parameters appear without a ``*`` prefix in params. + def test_keyword_only_and_positional_only_kinds_are_recorded(self): + """``f(a, /, b, *, c)``: each parameter carries its kind (ITL-953).""" - The bare ``*`` separator is a signature-level token, not a parameter - attribute; it must not be prepended to keyword-only params. - """ - - def fn(a: int, *, b: str) -> None: + def fn(a: int, /, b: int, *, c: str) -> None: pass result = self._make().extract_function_info(fn) - assert result["params"] == "a: int, b: str" + assert [(e["name"], e["kind"]) for e in result["parameters"]] == [ + ("a", "POSITIONAL_ONLY"), + ("b", "POSITIONAL_OR_KEYWORD"), + ("c", "KEYWORD_ONLY"), + ] def test_eval_str_fallback_on_unresolvable_annotation(self): """When eval_str=True fails, falls back to unresolved signature.""" @@ -209,7 +250,7 @@ def test_eval_str_fallback_on_unresolvable_annotation(self): # __globals__, which won't have it → NameError → fallback # This should not raise result = self._make().extract_function_info(fn) - assert "params" in result + assert [entry["name"] for entry in result["parameters"]] == ["x"] class TestFunctionInfoExtractorFactory: @@ -300,7 +341,7 @@ def test_param_annotation_is_canonical_string(self, extractor): def fn(f: op.File) -> str: ... info = extractor.extract_function_info(fn) - assert info["params"] == "f: orcapod.file;7b2276657273696f6e223a317d" + assert _annotations(info) == {"f": "orcapod.file;7b2276657273696f6e223a317d"} def test_generic_param_annotation_canonical(self, extractor): """list[op.File] in a parameter is canonicalized.""" @@ -308,7 +349,9 @@ def test_generic_param_annotation_canonical(self, extractor): def fn(files: list[op.File]) -> str: ... info = extractor.extract_function_info(fn) - assert info["params"] == "files: list[orcapod.file;7b2276657273696f6e223a317d]" + assert _annotations(info) == { + "files": "list[orcapod.file;7b2276657273696f6e223a317d]" + } def test_union_return_annotation_is_raw_union(self, extractor): """op.File | None return annotation is stored as a raw union type object. @@ -377,14 +420,14 @@ def test_builtin_annotations_unchanged(self, extractor): def fn(x: int, y: str) -> float: ... info = extractor.extract_function_info(fn) - assert info["params"] == "x: int, y: str" + assert _annotations(info) == {"x": "int", "y": "str"} assert info["returns"] is float # type object, not string "float" def test_param_canonical_string_and_return_type_object(self, extractor): """op.File in a param uses canonical string; op.File as return is type object. - Params are embedded in strings so ``canonical_annotation_str`` replaces the - module path inline. Return annotations are raw objects — ``TypeObjectHandler`` + A parameter's annotation is its canonical text (``canonical_annotation_str`` + replaces the module path). Return annotations are raw objects — ``TypeObjectHandler`` canonicalises them (to ``"type:orcapod.file"``) at hash time. """ @@ -395,7 +438,9 @@ def fn_return(s: str) -> op.File: ... info_param = extractor.extract_function_info(fn_param) info_return = extractor.extract_function_info(fn_return) - assert info_param["params"] == "f: orcapod.file;7b2276657273696f6e223a317d" + assert _annotations(info_param) == { + "f": "orcapod.file;7b2276657273696f6e223a317d" + } assert info_return["returns"] is op.File def test_simulated_relocation_stable(self, extractor): @@ -412,7 +457,7 @@ def fn(f: op.File) -> op.File: ... finally: op.File.__module__ = original - assert info_before["params"] == info_after["params"] + assert info_before["parameters"] == info_after["parameters"] assert info_before["returns"] == info_after["returns"] def test_path_param_annotation_is_canonical_string(self, extractor): @@ -426,7 +471,7 @@ def test_path_param_annotation_is_canonical_string(self, extractor): def fn(p: Path) -> str: ... info = extractor.extract_function_info(fn) - assert info["params"] == "p: orcapod.path;7b2276657273696f6e223a317d" + assert _annotations(info) == {"p": "orcapod.path;7b2276657273696f6e223a317d"} def test_uuid_param_annotation_is_canonical_string(self, extractor): """uuid.UUID in a param annotation is canonicalized to 'orcapod.uuid'. @@ -438,7 +483,7 @@ def test_uuid_param_annotation_is_canonical_string(self, extractor): def fn(u: uuid.UUID) -> str: ... info = extractor.extract_function_info(fn) - assert info["params"] == "u: orcapod.uuid;7b2276657273696f6e223a317d" + assert _annotations(info) == {"u": "orcapod.uuid;7b2276657273696f6e223a317d"} def test_union_with_path_canonical(self, extractor): """str | Path union param: Path is canonicalized to 'orcapod.path'. @@ -452,7 +497,9 @@ def test_union_with_path_canonical(self, extractor): def fn(x: str | Path) -> None: ... info = extractor.extract_function_info(fn) - assert info["params"] == "x: orcapod.path;7b2276657273696f6e223a317d | str" + assert _annotations(info) == { + "x": "orcapod.path;7b2276657273696f6e223a317d | str" + } def test_path_return_annotation_type_object_hashes_to_canonical(self, extractor): """pathlib.Path as return: extractor stores raw type, TypeObjectHandler gives 'type:orcapod.path'.