fleche-pandas 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,29 @@
1
+ BSD 3-Clause License
2
+
3
+ Copyright (c) 2026, Marvin Poul
4
+ All rights reserved.
5
+
6
+ Redistribution and use in source and binary forms, with or without
7
+ modification, are permitted provided that the following conditions are met:
8
+
9
+ * Redistributions of source code must retain the above copyright notice, this
10
+ list of conditions and the following disclaimer.
11
+
12
+ * Redistributions in binary form must reproduce the above copyright notice,
13
+ this list of conditions and the following disclaimer in the documentation
14
+ and/or other materials provided with the distribution.
15
+
16
+ * Neither the name of the copyright holder nor the names of its
17
+ contributors may be used to endorse or promote products derived from
18
+ this software without specific prior written permission.
19
+
20
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1,33 @@
1
+ Metadata-Version: 2.4
2
+ Name: fleche-pandas
3
+ Version: 1.0.0
4
+ Summary: pandas digest hooks for fleche
5
+ Author-email: Marvin Poul <pmrv@posteo.de>
6
+ License-Expression: BSD-3-Clause
7
+ Project-URL: Homepage, https://github.com/pmrv/fleche
8
+ Project-URL: Documentation, https://fleche.readthedocs.io/
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Operating System :: OS Independent
11
+ Requires-Python: <3.15,>=3.11
12
+ Description-Content-Type: text/markdown
13
+ License-File: LICENSE
14
+ Requires-Dist: fleche>=0.24.0.dev0
15
+ Requires-Dist: fleche-numpy>=1.0.0
16
+ Requires-Dist: pandas<4,>=2.2
17
+ Dynamic: license-file
18
+
19
+ # fleche-pandas
20
+
21
+ [fleche](https://github.com/pmrv/fleche) digest hooks for pandas: `DataFrame`, `Series`, `Index` (with `MultiIndex`, `RangeIndex`, ...), `pd.Timedelta` and `pd.NA`.
22
+
23
+ ```bash
24
+ pip install fleche-pandas
25
+ ```
26
+
27
+ Installing it is all it takes: fleche finds the hooks through its `fleche` entry point group.
28
+ Without it, fleche does not digest these values.
29
+ It pulls in [fleche-numpy](https://pypi.org/project/fleche-numpy/), since object columns are digested element by element and often hold arrays.
30
+
31
+ How pandas objects are digested is described in fleche's [pandas documentation](https://fleche.readthedocs.io/en/latest/digests/pandas.html).
32
+
33
+ This package lives in the fleche repository, under `src/fleche-pandas`, and is versioned and released independently of fleche itself.
@@ -0,0 +1,15 @@
1
+ # fleche-pandas
2
+
3
+ [fleche](https://github.com/pmrv/fleche) digest hooks for pandas: `DataFrame`, `Series`, `Index` (with `MultiIndex`, `RangeIndex`, ...), `pd.Timedelta` and `pd.NA`.
4
+
5
+ ```bash
6
+ pip install fleche-pandas
7
+ ```
8
+
9
+ Installing it is all it takes: fleche finds the hooks through its `fleche` entry point group.
10
+ Without it, fleche does not digest these values.
11
+ It pulls in [fleche-numpy](https://pypi.org/project/fleche-numpy/), since object columns are digested element by element and often hold arrays.
12
+
13
+ How pandas objects are digested is described in fleche's [pandas documentation](https://fleche.readthedocs.io/en/latest/digests/pandas.html).
14
+
15
+ This package lives in the fleche repository, under `src/fleche-pandas`, and is versioned and released independently of fleche itself.
@@ -0,0 +1,150 @@
1
+ """fleche digest hooks for pandas: ``DataFrame``, ``Series``, ``Index``,
2
+ ``pd.Timedelta`` and ``pd.NA``.
3
+
4
+ Registered through the ``fleche`` entry point group (see :data:`digest_hooks`),
5
+ so installing this package is all it takes. Without it, fleche does not digest
6
+ these values. A ``pd.Timedelta`` digests by its length in nanoseconds, apart
7
+ from the ``datetime.timedelta`` it subclasses.
8
+
9
+ Builds on :mod:`fleche_numpy`: object columns are digested element by element.
10
+
11
+ Object columns need care (#1004). ``pd.util.hash_pandas_object`` hashes a
12
+ column of strings by their encoded bytes, and every missing value by one shared
13
+ marker. It mishandles every other object column:
14
+
15
+ - unhashable elements such as arrays, lists and dicts make it raise ``TypeError``;
16
+ - everything else is hashed through ``str()``, so ``1`` collides with ``"1"`` and
17
+ ``object()`` is keyed on its address.
18
+
19
+ ``bytes`` fall in the second group: ``b"a"`` hashes like ``"a"``.
20
+
21
+ Such columns are digested element by element with our own hash, and pandas is
22
+ handed the column of hex digests instead. No marker records the swap, so as for
23
+ a list, a column digests the same as the column of its elements' digests.
24
+ """
25
+
26
+ from collections.abc import Callable
27
+ from typing import Any
28
+
29
+ import numpy as np
30
+ import pandas as pd
31
+ from pandas.api.types import infer_dtype
32
+
33
+ # The defining module of pd.util.hash_pandas_object, the very same function.
34
+ # pandas 3.1 reaches pd.util's names through a module __getattr__ annotated
35
+ # ``-> object``, which leaves type checkers nothing callable to check.
36
+ from pandas.core.util.hashing import hash_pandas_object
37
+
38
+ from fleche.hashing import running_hash
39
+ from fleche.digest import Digest, Indigestible, digest
40
+ from fleche_numpy import timedelta64_length
41
+
42
+ __all__ = ["digest_hooks", "digest_pandas"]
43
+
44
+ # What ``infer_dtype`` calls the object columns pandas hashes faithfully.
45
+ SAFE_OBJECT = frozenset({"string", "empty"})
46
+
47
+
48
+ def needs_element_digests(values) -> bool:
49
+ """Whether pandas cannot be trusted to hash the elements of *values*."""
50
+ dtype = values.dtype
51
+ if isinstance(dtype, pd.CategoricalDtype):
52
+ # A categorical is hashed by the values of its categories, which suffer
53
+ # the same str() fallback when they are objects.
54
+ values = dtype.categories
55
+ dtype = values.dtype
56
+ return dtype == object and infer_dtype(values, skipna=True) not in SAFE_OBJECT
57
+
58
+
59
+ def element_digests(values, digest_bytes: Callable[[Any], bytes]) -> np.ndarray:
60
+ """Return the hex digest of each element of *values*, as an object array.
61
+
62
+ Elements it cannot digest raise :exc:`~fleche.digest.Indigestible`, as they
63
+ would anywhere else, rather than falling back to pandas' unstable ``str()``.
64
+ """
65
+ return np.array([digest_bytes(v).decode() for v in values], dtype=object)
66
+
67
+
68
+ def digest_pandas(value, digest_bytes: Callable[[Any], bytes]) -> bytes:
69
+ """Return the digest of the pandas *value*, in the format of *digest_bytes*.
70
+
71
+ Raises KeyError for a ``pd.Timedelta`` in a unit without a known length.
72
+ """
73
+ with running_hash(type(value).__name__.encode()) as m:
74
+ match value:
75
+ case pd.DataFrame():
76
+ # We digest columns/dtypes/index ourselves and pass index=False to
77
+ # hash_pandas_object rather than letting index=True fold the index in.
78
+ # hash_pandas_object only mixes per-element value bytes — it ignores
79
+ # column names, column dtypes, index.name, and index.dtype — so
80
+ # index=True alone would still collide DataFrames whose indices differ
81
+ # only in name or dtype. Recursing through digest_bytes on
82
+ # value.index also reuses the pd.Index arm below, keeping a standalone
83
+ # Index and a DataFrame's .index digest-consistent.
84
+ m.update(digest_bytes(list(value.columns)))
85
+ m.update(digest_bytes([str(d) for d in value.dtypes]))
86
+ m.update(digest_bytes(value.index))
87
+ own = [i for i, (_, col) in enumerate(value.items()) if needs_element_digests(col)]
88
+ if own:
89
+ value = value.copy(deep=False)
90
+ for i in own:
91
+ # isetitem, not value[label] = ...: column labels may repeat.
92
+ value.isetitem(i, element_digests(value.iloc[:, i], digest_bytes))
93
+ m.update(hash_pandas_object(value, index=False).values.tobytes())
94
+ case pd.Series():
95
+ # Same reasoning as DataFrame: hash_pandas_object ignores name/dtype/
96
+ # index metadata, so we digest those ourselves and pass index=False.
97
+ m.update(digest_bytes(value.name))
98
+ m.update(digest_bytes(str(value.dtype)))
99
+ m.update(digest_bytes(value.index))
100
+ if needs_element_digests(value):
101
+ value = pd.Series(element_digests(value, digest_bytes), dtype=object)
102
+ m.update(hash_pandas_object(value, index=False).values.tobytes())
103
+ case pd.MultiIndex():
104
+ # pandas hashes a MultiIndex level by level, through str() for object
105
+ # levels, and ignores the level names (value.name is None). Instead
106
+ # each level is digested as an Index of its values, name included,
107
+ # and the tuple of their digests folded. The values, not
108
+ # value.levels: those may hold entries no row uses.
109
+ m.update(digest_bytes(tuple(value.get_level_values(i) for i in range(value.nlevels))))
110
+ case pd.Index():
111
+ m.update(digest_bytes(value.name))
112
+ m.update(digest_bytes(str(value.dtype)))
113
+ if needs_element_digests(value):
114
+ value = pd.Index(element_digests(value, digest_bytes), dtype=object)
115
+ m.update(hash_pandas_object(value).values.tobytes())
116
+ case pd.Timedelta():
117
+ # Its exact length in nanoseconds, whatever unit it stores; .value
118
+ # would overflow for a second-unit Timedelta beyond int64 ns.
119
+ # KeyError for a unit without a known length, which the hook
120
+ # raises as Indigestible; pandas only stores s, ms, us or ns.
121
+ _, attoseconds = timedelta64_length(value.to_timedelta64())
122
+ m.update(digest_bytes(attoseconds // 10**9))
123
+ case _ if value is pd.NA:
124
+ # A singleton like None; it turns up in object columns, which the
125
+ # arms above digest element by element.
126
+ m.update(b"__NA__")
127
+ return m.result
128
+
129
+
130
+ def _digest_bytes(value: Any) -> bytes:
131
+ return digest(value).encode()
132
+
133
+
134
+ def _pandas_digest(value) -> Digest:
135
+ try:
136
+ return Digest(digest_pandas(value, _digest_bytes).decode())
137
+ except KeyError as err:
138
+ # A pd.Timedelta in a unit without a known length.
139
+ raise Indigestible(value) from err
140
+
141
+
142
+ #: The hooks fleche loads from this package's ``fleche``/``digest`` entry point.
143
+ #: ``pd.Index`` covers its subclasses, ``MultiIndex`` and ``RangeIndex`` among them.
144
+ digest_hooks = [
145
+ (pd.DataFrame, _pandas_digest),
146
+ (pd.Series, _pandas_digest),
147
+ (pd.Index, _pandas_digest),
148
+ (pd.Timedelta, _pandas_digest),
149
+ (type(pd.NA), _pandas_digest),
150
+ ]
@@ -0,0 +1,33 @@
1
+ Metadata-Version: 2.4
2
+ Name: fleche-pandas
3
+ Version: 1.0.0
4
+ Summary: pandas digest hooks for fleche
5
+ Author-email: Marvin Poul <pmrv@posteo.de>
6
+ License-Expression: BSD-3-Clause
7
+ Project-URL: Homepage, https://github.com/pmrv/fleche
8
+ Project-URL: Documentation, https://fleche.readthedocs.io/
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Operating System :: OS Independent
11
+ Requires-Python: <3.15,>=3.11
12
+ Description-Content-Type: text/markdown
13
+ License-File: LICENSE
14
+ Requires-Dist: fleche>=0.24.0.dev0
15
+ Requires-Dist: fleche-numpy>=1.0.0
16
+ Requires-Dist: pandas<4,>=2.2
17
+ Dynamic: license-file
18
+
19
+ # fleche-pandas
20
+
21
+ [fleche](https://github.com/pmrv/fleche) digest hooks for pandas: `DataFrame`, `Series`, `Index` (with `MultiIndex`, `RangeIndex`, ...), `pd.Timedelta` and `pd.NA`.
22
+
23
+ ```bash
24
+ pip install fleche-pandas
25
+ ```
26
+
27
+ Installing it is all it takes: fleche finds the hooks through its `fleche` entry point group.
28
+ Without it, fleche does not digest these values.
29
+ It pulls in [fleche-numpy](https://pypi.org/project/fleche-numpy/), since object columns are digested element by element and often hold arrays.
30
+
31
+ How pandas objects are digested is described in fleche's [pandas documentation](https://fleche.readthedocs.io/en/latest/digests/pandas.html).
32
+
33
+ This package lives in the fleche repository, under `src/fleche-pandas`, and is versioned and released independently of fleche itself.
@@ -0,0 +1,10 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ fleche_pandas/__init__.py
5
+ fleche_pandas.egg-info/PKG-INFO
6
+ fleche_pandas.egg-info/SOURCES.txt
7
+ fleche_pandas.egg-info/dependency_links.txt
8
+ fleche_pandas.egg-info/entry_points.txt
9
+ fleche_pandas.egg-info/requires.txt
10
+ fleche_pandas.egg-info/top_level.txt
@@ -0,0 +1,2 @@
1
+ [fleche]
2
+ digest = fleche_pandas:digest_hooks
@@ -0,0 +1,3 @@
1
+ fleche>=0.24.0.dev0
2
+ fleche-numpy>=1.0.0
3
+ pandas<4,>=2.2
@@ -0,0 +1 @@
1
+ fleche_pandas
@@ -0,0 +1,34 @@
1
+ [build-system]
2
+ requires = ["setuptools>=64.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [tool.setuptools]
6
+ packages = ["fleche_pandas"]
7
+
8
+ [project]
9
+ name = "fleche-pandas"
10
+ # Bumped by release-please (release-type "python"); see release-please-config.json.
11
+ version = "1.0.0"
12
+ description = "pandas digest hooks for fleche"
13
+ authors = [
14
+ { name="Marvin Poul", email="pmrv@posteo.de" },
15
+ ]
16
+ readme = "README.md"
17
+ requires-python = ">=3.11,<3.15"
18
+ classifiers = [
19
+ "Programming Language :: Python :: 3",
20
+ "Operating System :: OS Independent",
21
+ ]
22
+ license = "BSD-3-Clause"
23
+ dependencies = [
24
+ 'fleche >= 0.24.0.dev0',
25
+ 'fleche-numpy >= 1.0.0',
26
+ 'pandas >= 2.2, <4',
27
+ ]
28
+
29
+ [project.urls]
30
+ Homepage = "https://github.com/pmrv/fleche"
31
+ Documentation = "https://fleche.readthedocs.io/"
32
+
33
+ [project.entry-points.'fleche']
34
+ digest = 'fleche_pandas:digest_hooks'
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+