Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
122 commits
Select commit Hold shift + click to select a range
0886ffd
docs(plan): ITL-910 adopt starfix 0.5 investigation and plan (WIP)
Nov 11, 2026
1b57f9b
docs(plan): ITL-910 suite findings under starfix 0.5 (WIP)
Nov 11, 2026
b9f4465
test(hashing): failing tests for starfix hash format 2 under arrow_v0…
Nov 11, 2026
ca5d8cd
feat(hashing): adopt starfix 0.5 (hash format 2) under label arrow_v0…
Nov 11, 2026
bd252f2
test(golden): regenerate golden hashes for starfix hash format 2 / ar…
Nov 11, 2026
a5ceb0a
test: re-pin format-1 digests and record-id order in starfix format 2…
Nov 11, 2026
f5433ff
docs: starfix hash format 2 / arrow_v0.2 in CHANGELOG, hashing refere…
Nov 11, 2026
bf8784f
style: ruff format and type the format-2 tests (ITL-910)
Nov 11, 2026
6dfb456
docs(plan): ITL-910 D1 design (explicit failure on foreign hash labels)
Nov 11, 2026
722a098
test(pipeline): failing tests: stores with rows under another Arrow h…
Nov 11, 2026
0c05cbd
feat(store): refuse stored rows hashed under another Arrow hash label…
Nov 12, 2026
9bef94e
fix(store): hash-label check ignores non-digest record ids, works on …
Nov 12, 2026
6df680c
docs: v0.3 refuses stores written by v0.2 (StoreHashLabelError); corr…
Nov 12, 2026
a49ba10
style: type the stored-hash-label helpers (ITL-910)
Nov 12, 2026
d5d564e
refactor: break the stored-hash-label import cycle; type the new test…
Nov 12, 2026
5363bfb
docs(plan): ITL-910 worker report
Nov 12, 2026
4f907c4
docs(plan): ITL-942 step 1 analysis of the wrong-hash findings
Nov 12, 2026
5acdf37
test(hashing): failing regression tests for the ITL-942 wrong-hash fi…
Nov 12, 2026
34960c8
feat(store): ignore rows hashed under another Arrow label instead of …
Nov 12, 2026
66517c5
docs: v0.3 ignores rows hashed under arrow_v0.1, recomputes and keeps…
Nov 12, 2026
92ffb2e
style: type the stored-hash-label filter and its tests (ITL-910)
Nov 12, 2026
bcd905b
feat(store): warn with the number of skipped rows; side-effect logs u…
Nov 12, 2026
b88f7eb
docs(plan): ITL-910 follow-up status (rows of another label ignored, …
Nov 12, 2026
69f4b98
Merge remote-tracking branch 'origin/eywalker/itl-910-adopt-starfix-0…
Nov 12, 2026
c30f04c
docs(plan): ITL-942 finding R (fixed by #292) and G re-check
Nov 12, 2026
007ea85
docs(plan): ITL-935 logical type identifiers, step 1 plan
Nov 12, 2026
7bfcb54
docs(plan): ITL-944 step 1 plan for data context v1
Nov 12, 2026
26dcbc5
feat(contexts): data context std:v1:default with a frozen-manifest ch…
Nov 12, 2026
87df847
wip(store): __data_context column, new table layouts, read filter, ol…
Nov 12, 2026
02db3f0
wip(store): function version column, tests moved to the new layouts (…
Nov 12, 2026
5c34afb
docs(plan): ITL-945 step 1 plan for the hash label rule
Nov 12, 2026
4030f55
docs(plan): ITL-945 tracer results and open points
Nov 12, 2026
9b1c2be
feat(store): __data_context on every stored row, new table layouts, o…
Nov 12, 2026
2dc0d24
test(hashing): failing tests for the hash label rule (ITL-945)
Nov 12, 2026
8a1f5a1
refactor(hashing)!: rename hash labels to <algorithm>_v1 (ITL-945)
Nov 12, 2026
db94f0f
feat(hashing)!: keep hash labels out of every hash input (ITL-945)
Nov 12, 2026
2e619aa
feat(contexts): manifest fields of the versioning design; logical typ…
Nov 12, 2026
2c4b1e3
feat(core)!: bare hex digests inside names; stream identity without t…
Nov 12, 2026
a7691dc
feat(store): function pods that take the invocation context fail on a…
Nov 12, 2026
4b9e825
feat(store)!: labelled row keys for operator-cache and cached-source …
Nov 12, 2026
de11a36
test(golden): pinned hash values after the hash label rule (ITL-945)
Nov 12, 2026
bc012b3
refactor(hashing): define each hash label once, beside its algorithm …
Nov 12, 2026
07ccf30
refactor(store)!: remove the v0.1 manifest and the v0 to v1 migration…
Nov 12, 2026
50d453e
docs: the hash label rule in the hashing reference, CHANGELOG, DESIGN…
Nov 12, 2026
18a110b
feat(store): refuse an input of another data context (ITL-944)
Nov 12, 2026
f7a7c87
fix(hashing): sort set items by canonical JSON, not str() (ITL-942 L1)
Nov 12, 2026
45787de
fix(sources): record-id system tag is large_binary everywhere (ITL-94…
Nov 12, 2026
58198d8
fix(function_pod): default function version is v0.0 for every entry p…
Nov 12, 2026
ed81f34
fix(hashing): Arrow hashed type depends on the declared type only (IT…
Nov 12, 2026
ca6fb1c
fix(operators): fold system-tag source ids over the canonical member …
Nov 12, 2026
8b05071
fix(store): address CodeRabbit review of PR #313 (ITL-944)
Nov 12, 2026
53577ff
fix(operators): column selection identity is the set of names (ITL-94…
Nov 12, 2026
55ba591
fix(streams): keep tag sorting in the producer-less stream identity; …
Nov 12, 2026
d54020d
fix(hashing): dict keys keep their type in structure hashes (ITL-942 …
Nov 12, 2026
a690970
test(hashing): pin MergeJoin input identity as intended; document the…
Nov 12, 2026
f3157b0
fix(hashing): only the hasher and type handlers write '__type__' obje…
Nov 12, 2026
a6adec1
docs: a v0.2 side-effect log is not detected at the v0.3 path (ITL-94…
Nov 12, 2026
088502a
test(hashing): regenerate golden values for the ITL-942 fixes
Nov 12, 2026
749778d
docs: CHANGELOG and DESIGN_ISSUES entries for the ITL-942 wrong-hash …
Nov 12, 2026
603e2c3
feat(logical_types): identifiers for built-in types; whole identifier…
Nov 12, 2026
a63896b
style: type the Encoded expansion and the side-effect version test (I…
Nov 12, 2026
4c0a820
docs: logical type identifiers page, changelog, design issue, agent r…
Nov 12, 2026
7b6626b
docs(plan): ITL-954 plan and the store fixture written by Orcapod v0.2.0
Nov 12, 2026
0111b39
feat(databases): list_table_paths lists the tables under a path prefi…
Nov 12, 2026
7af5cd7
docs(changelog): a fresh store does not prevent repeated side effects…
Nov 12, 2026
03b4be2
test(store): pre-v0.3 tables on the real v0.2.0 store, as written and…
Nov 12, 2026
531ab89
fix(hashing): a namedtuple's field order is part of its hash (ITL-942 T)
Nov 12, 2026
930e94b
feat(store): find tables written before v0.3 under a node's name, wha…
Nov 12, 2026
81ccd84
refactor(operators): delete the dead duplicate SelectDataColumns in f…
Nov 12, 2026
654ae9f
docs: record ITL-942 T in CHANGELOG and DESIGN_ISSUES
Nov 12, 2026
40a7102
fix(sources): default derived source ids keep the hash label (ITL-945)
Nov 12, 2026
5bf7935
docs(store): pre-v0.3 tables are found by name; list_table_paths (ITL…
Nov 12, 2026
43f88cc
test(hashing): address CodeRabbit round 1 on PR #315 (ITL-942)
Nov 12, 2026
6addbf0
fix(job): a node without a name path claims no table in the job total…
Nov 12, 2026
b8990fa
feat(logical_types): wrapper identifiers in the schema hash; golden r…
Nov 12, 2026
3a6a075
feat(logical_types): native containers carry no version; fix []/[None…
Nov 12, 2026
ed2653e
docs(plan): ITL-935 decisions and outcome
Nov 12, 2026
a853811
docs(plan): ITL-942 worker report
Nov 12, 2026
8b291c9
docs(changelog): move the ITL-954 entry to a changelog fragment (ITL-…
Nov 12, 2026
c4490d5
docs(changelog): move the ITL-910 entry to a changelog fragment (ITL-…
Nov 12, 2026
a0b3825
Merge branch 'eywalker/itl-910-adopt-starfix-05-hash-format-2-in-orca…
Nov 12, 2026
13111d5
Merge branch 'eywalker/itl-910-adopt-starfix-05-hash-format-2-in-orca…
Nov 12, 2026
2d2c02f
Merge branch 'eywalker/itl-910-adopt-starfix-05-hash-format-2-in-orca…
Nov 12, 2026
3192a8a
docs(changelog): move the ITL-945 entry to a changelog fragment (ITL-…
Nov 12, 2026
6fb74c2
docs(changelog): move the ITL-942 entry to a changelog fragment (ITL-…
Nov 12, 2026
2369d75
docs(changelog): move the ITL-935 entry to a changelog fragment (ITL-…
Nov 12, 2026
81da973
docs(changelog): move the ITL-944 entry to a changelog fragment (ITL-…
Nov 12, 2026
c19cb9f
docs(plans): ITL-967 combined hash-step merge plan
Nov 12, 2026
f2c1fd8
Merge branch 'eywalker/itl-910-adopt-starfix-05-hash-format-2-in-orca…
Nov 12, 2026
07e9bd3
Merge branch 'eywalker/itl-944-data-context-v1-frozen-manifest' (#313…
Nov 12, 2026
c1949b2
Merge remote-tracking branch 'origin/eywalker/itl-954-find-tables-wri…
Nov 12, 2026
c8f1194
Merge branch 'eywalker/itl-945-apply-the-hash-label-rule-one-format-l…
Nov 12, 2026
128b2c5
Merge branch 'eywalker/itl-942-fix-the-wrong-hash-findings-of-the-has…
Nov 12, 2026
6ba6cc3
Merge remote-tracking branch 'origin/eywalker/itl-935-design-make-the…
Nov 12, 2026
cdf5459
test(hashing): failing tests and plan for function defaults through t…
Nov 12, 2026
76dd906
fix(data_function): stored signature hash takes defaults through the …
Nov 12, 2026
b30b6fa
fix(sources): name every column the Arrow hasher refuses, as ValueErr…
Nov 12, 2026
2e351b3
wip: structured parameter description (ITL-953)
Nov 12, 2026
1be364d
wip: update extractor tests for the structured form (ITL-953)
Nov 12, 2026
7337b36
wip: docs, changelog fragment, design issue, golden cases, identity t…
Nov 12, 2026
8780cfa
docs(plans): ITL-953 decisions and status
Nov 12, 2026
b14a56c
fix(review): CodeRabbit findings on the ITL-910 code, on the combined…
Nov 12, 2026
257ff0f
docs(hashing): unhashable defaults raise in v0.3; follow-up ITL-971 (…
Nov 12, 2026
8c2066a
test(hashing): regenerate the golden hashes once for the v0.3 hash st…
Nov 12, 2026
27fb14a
Merge remote-tracking branch 'origin/eywalker/itl-967-v03-hash-step-c…
Nov 12, 2026
fdc6362
test(pipeline): type the values read in the combined-branch tests (IT…
Nov 12, 2026
fcb676f
test(golden): pin function hashes after the structured signature (ITL…
Nov 12, 2026
dad1111
docs(plans): ITL-967 list of golden entries that move relative to main
Nov 12, 2026
970ccf0
Merge remote-tracking branch 'origin/main' (#316, ITL-955) into ITL-967
Nov 12, 2026
444bd35
test(hashing): regenerate the golden hashes after merging main (ITL-9…
Nov 12, 2026
c4b1e4a
docs(design-issues): move the ITL-910, ITL-944, ITL-954, ITL-945, ITL…
Nov 12, 2026
b61b6a6
Merge remote-tracking branch 'origin/eywalker/itl-967-v03-hash-step-c…
Nov 12, 2026
3ed0d41
docs(plans): ITL-953 status after merging ITL-967 c4b1e4a7
Nov 12, 2026
617efe9
docs(plans): ITL-967 progress notes
Nov 12, 2026
8edd9be
test(hashing): docstrings on the function-default tests (ITL-953)
Nov 12, 2026
3c9c583
Merge remote-tracking branch 'origin/main' (#317, ITL-939) into ITL-967
Nov 12, 2026
9743004
test(hashing): regenerate the golden hashes after merging main (ITL-9…
Nov 12, 2026
889c2cc
Merge remote-tracking branch 'origin/eywalker/itl-967-v03-hash-step-c…
Nov 12, 2026
20f17af
docs(plans): ITL-953 review round 1 and merge of ITL-967 9743004d
Nov 12, 2026
3fe5b56
docs(design-issues): ITL-953 FD1 in the per-file entry format (ITL-968)
Nov 12, 2026
11e9332
chore: merge main (hash step #324, squashed) into ITL-953
Nov 12, 2026
46fc6a5
chore: merge main (user-class kinds, #325) into itl-953
Nov 12, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions changelog.d/ITL-953.md
Original file line number Diff line number Diff line change
@@ -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).
31 changes: 31 additions & 0 deletions design_issues/ITL-953-FD1.md
Original file line number Diff line number Diff line change
@@ -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.
6 changes: 6 additions & 0 deletions docs/concepts/function-pods.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
57 changes: 57 additions & 0 deletions docs/reference/hashing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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": <module>, "name": <name>,
"parameters": [{"name": ..., "kind": ..., "annotation": ..., "default": ...}, ...],
"returns": <return annotation>}
```

| 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
Expand Down
7 changes: 5 additions & 2 deletions src/orcapod/core/data_function.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down
6 changes: 4 additions & 2 deletions src/orcapod/hashing/hash_utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand All @@ -248,8 +252,6 @@ def get_function_signature(
# Replace ": <old_ann>" with ": <new_ann>" (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)})"
Expand Down
66 changes: 65 additions & 1 deletion src/orcapod/hashing/semantic_hashing/builtin_handlers.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand All @@ -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:
Expand Down
Loading
Loading