Metadata-Version: 2.4
Name: polars_legacy_hash
Version: 0.0.3
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Dist: polars>=0.20.10
Requires-Dist: packaging
License-File: LICENSE
Summary: Polars 0.20.10 hash function as a plugin library
Author: Matt Richards
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# Polars legacy hash

For a specific project, I needed to preserve the hashing behaviour of polars 0.20.10 (or the underlying ahash 0.8.7),
whilst also wanting to upgrade polars itself. 

For now this plugin specifically caters to 0.20.10, but in principle could be generalised. See also [Polars Hash](https://github.com/ion-elgreco/polars-hash) which is a more general solution to this, which is coupled to a specific point in time in the history of polars. If there ever comes a use case for this, I expect to move to some version of versioning akin to stub libraries e.g. 0.20.10.20250415 and deploy these from seperate branches to avoid having to bundle multiple polars binaries into the same wheel.

## Installation
`pip install polars_legacy_hash` in your virtualenv. Note that you'll need to install polars seperately. This package doesn't depend on polars explicitly, so that if you use e.g. `polars-u64-idx` we won't pull in polars as well (TODO double check this works as intended)


## Usage
The best way to explain what this package does it to demonstrate:
```python
# /// script
# requires-python = ">=3.8"
# dependencies = [
#     "polars==0.20.10",
#     "polars_legacy_hash",
# ]
# ///
import polars as pl

import polars_legacy_hash as plh

print(f"Hashing with polars={pl.__version__} directly:")
s = pl.Series([42])
print(s.hash().item())
print("Using polars_legacy_hash:")
result = s.to_frame("test").select(plh.legacy_hash(pl.col("test"))).to_series()
print(result.item())
```
Running this with `uv run --script examples/polars_0.20.10.py` produces this:
```
Hashing with polars=0.20.10 directly:
3146795401079207122
Using polars_legacy_hash:
3146795401079207122
```
Running the analogous `uv run --script examples/polars_1.27.1.py` we get:



```
Hashing with polars=1.27.1 directly (not consistent!):
16588070273457376249
Using polars_legacy_hash:
3146795401079207122
```
i.e. we get the same consistent output, in spite of the polars version change.

For correctness checking, the CI runs `test_expectations.py` under polars 0.20.10 to
confirm that the test values in the fixtures (defined in tests/conftest.py) are consistent with polars itself from that version.


### Known limitations
- No support for polars categorical


## Development
The plugin is built with maturin, and uv is setup to rebuild an editable install whenever the rust part of the plugin changes. This means the simplest way to run the tests is
`uv run pytest -rP`

