feat: add Python bindings

py-gxhash/.cargo/config.toml

@@ -0,0 +1,2 @@
+[build]
+rustflags = ["-C", "target-cpu=native"]

py-gxhash/Cargo.toml

@@ -0,0 +1,40 @@
+[profile.release]
+codegen-units = 1
+lto = "fat"
+panic = "abort"
+strip = "symbols"
+
+[package]
+name = "py-gxhash"
+version = "0.2.3"
+edition = "2024"
+
+[lib]
+name = "gxhash"
+crate-type = ["cdylib"]
+
+[features]
+hybrid = ["gxhash/hybrid"]
+
+[dependencies.pyo3]
+version = "0.27.1"
+default-features = false
+features = ["macros"]
+
+[dependencies.pyo3-async-runtimes]
+version = "0.27.0"
+default-features = false
+features = ["tokio-runtime"]
+
+[dependencies.gxhash]
+version = "3.5.0"
+default-features = false
+
+[dependencies.tokio]
+version = "1.44.1"
+default-features = false
+
+[build-dependencies.pyo3-build-config]
+version = "0.27.1"
+default-features = false
+features = ["resolve-config"]

py-gxhash/Makefile

@@ -0,0 +1,9 @@
+all:
+	rm -rf dist
+	uv run maturin sdist --out dist
+
+publish:
+	uv publish
+
+clean:
+	rm -rf dist target .venv

py-gxhash/README.md

@@ -0,0 +1,59 @@
+# gxhash-py
+
+Python bindings for [GxHash](https://github.com/ogxd/gxhash), a blazingly fast and robust non-cryptographic hashing algorithm.
+
+## Features
+
+- **Blazingly Fast**: Minimal-overhead binding to leverage the full speed of GxHash.
+- **Zero Python**: Pure Rust backend with zero additional Python runtime overhead.
+- **Async-Ready**: Tokio-powered async hashing for fast and efficient concurrency.
+- **Fully Typesafe**: Predictable, clean API with complete type safety.
+
+## Installation
+
+You must have [rustup](https://rustup.rs/) installed and set to `nightly`.
+
+```bash
+pip install gxhash
+```
+
+For the best performance, you can enable the `hybrid` feature with the following.
+
+```bash
+pip install gxhash --config-settings build-args="--features hybrid"
+```
+
+By default, `gxhash` uses your system's vectorisation features. You can disable this by setting the relevant `RUSTFLAGS`.
+
+```bash
+RUSTFLAGS="-C target-cpu=x86-64 -C target-feature=+aes,+avx2" pip install gxhash
+```
+
+## Usage
+
+Hashing bytes.
+
+```python
+from gxhash import GxHash32
+
+def main():
+    gxhash = GxHash32(seed=0)
+    result = gxhash.hash(b"Hello, world!")
+
+if __name__ == "__main__":
+    main()
+```
+
+Hashing bytes asynchronously.
+
+```python
+from asyncio import run
+from gxhash import GxHash128
+
+async def main():
+    gxhash = GxHash128(seed=0)
+    result = await gxhash.hash_async(b"Hello, world!")
+
+if __name__ == "__main__":
+    run(main())
+```

py-gxhash/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    pyo3_build_config::use_pyo3_cfgs();
+}

py-gxhash/gxhash.pyi

@@ -0,0 +1,95 @@
+from typing import Protocol
+
+class Hasher(Protocol):
+    def __init__(self, *, seed: int) -> None:
+        """
+        Summary
+        -------
+        Initialise `Hasher` with a `seed`.
+        The `seed` should not be exposed as it is used to deterministically generate the hash.
+        An exposed `seed` would put your service at a higher risk of a DoS attack.
+
+        Parameters
+        ----------
+        seed (`int`)
+            a seed for the hasher
+
+        Example
+        -------
+        ```python
+        hasher = GxHash32(seed=1234)
+        ```
+        """
+
+    def hash(self, bytes: bytes, /) -> int:
+        """
+        Summary
+        -------
+        Hashes `bytes` to an `int`.
+        If your input is in `bytes`, this is the most performant variant of the hasher.
+
+        Parameters
+        ----------
+        bytes (`bytes`)
+            input bytes
+
+        Returns
+        -------
+        hash (`int`)
+            the hash of the input bytes
+
+        Example
+        -------
+        ```python
+        hasher = GxHash64(seed=1234)
+        print(f"Hash is {hasher.hash(bytes([42] * 1000))}!")
+        ```
+        """
+
+    async def hash_async(self, bytes: bytes, /) -> int:
+        """
+        Summary
+        -------
+        Hashes `bytes` to an `int` asynchronously.
+        This method allows you to perform multiple hashes with true multi-threaded parallelism.
+        If called sequentially, this method is slightly less performant than the default `hash` method.
+        Otherwise, this variant offers the best raw multi-threaded performance.
+
+        Parameters
+        ----------
+        bytes (`bytes`)
+            input bytes
+
+        Returns
+        -------
+        hash (`int`)
+            the hash of the input bytes
+
+        Example
+        -------
+        ```python
+        hasher = GxHash128(seed=1234)
+        print(f"Hash is {await hasher.hash_async(bytes([42] * 1000))}!")
+        ```
+        """
+
+class GxHash32(Hasher):
+    """
+    Summary
+    -------
+    This class exposes GxHash's 32-bit hash methods.
+    """
+
+class GxHash64(Hasher):
+    """
+    Summary
+    -------
+    This class exposes GxHash's 64-bit hash methods.
+    """
+
+class GxHash128(Hasher):
+    """
+    Summary
+    -------
+    This class exposes GxHash's 128-bit hash methods.
+    """

py-gxhash/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "gxhash"
+description = "Python bindings for GxHash"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+dynamic = ["version"]
+classifiers = [
+    "Programming Language :: Rust",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: Implementation :: PyPy",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+[dependency-groups]
+dev = ["maturin==1.10.2", "pyright>=1.1.407", "ruff>=0.14.6"]
+
+[build-system]
+requires = ["maturin>=1.10.2, <2.0.0"]
+build-backend = "maturin"
+
+[tool.maturin]
+profile = "release"
+locked = true
+strip = true
+features = ["pyo3/extension-module"]
+exclude = ["**/uv.lock", "Makefile"]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "PYI021",
+    "A002",
+    "COM812",
+    "D203",
+    "D205",
+    "D211",
+    "D212",
+    "D400",
+    "D413",
+    "D415",
+    "D417",
+]
+
+[tool.pyright]
+typeCheckingMode = "strict"

py-gxhash/src/lib.rs

@@ -0,0 +1,62 @@
+use pyo3::prelude::Bound;
+use pyo3::prelude::PyResult;
+use pyo3::prelude::Python;
+use pyo3::prelude::pyclass;
+use pyo3::prelude::pymethods;
+use pyo3::types::PyModuleMethods;
+
+#[cfg_attr(not(any(Py_3_8, Py_3_9)), pyclass(frozen, immutable_type))]
+#[cfg_attr(any(Py_3_8, Py_3_9), pyclass(frozen))]
+struct GxHash32 {
+    seed: i64,
+}
+
+#[cfg_attr(not(any(Py_3_8, Py_3_9)), pyclass(frozen, immutable_type))]
+#[cfg_attr(any(Py_3_8, Py_3_9), pyclass(frozen))]
+struct GxHash64 {
+    seed: i64,
+}
+
+#[cfg_attr(not(any(Py_3_8, Py_3_9)), pyclass(frozen, immutable_type))]
+#[cfg_attr(any(Py_3_8, Py_3_9), pyclass(frozen))]
+struct GxHash128 {
+    seed: i64,
+}
+
+macro_rules! impl_gxhash_methods {
+    ($Self:ident, $return_type:ty, $hasher:path) => {
+        #[pymethods]
+        impl $Self {
+            #[new]
+            fn new(seed: i64) -> Self {
+                $Self { seed }
+            }
+
+            fn hash(&self, bytes: &[u8]) -> $return_type {
+                $hasher(bytes, self.seed)
+            }
+
+            fn hash_async<'a>(&self, py: Python<'a>, bytes: pyo3::prelude::Py<pyo3::types::PyBytes>) -> PyResult<Bound<'a, pyo3::prelude::PyAny>> {
+                let seed = self.seed;
+
+                pyo3_async_runtimes::tokio::future_into_py(py, async move {
+                    tokio::task::spawn_blocking(move || $hasher(Python::attach(|py| bytes.as_bytes(py)), seed))
+                        .await
+                        .map_err(|e| pyo3::exceptions::PyRuntimeError::new_err(format!("Task Join Error: {}", e)))
+                })
+            }
+        }
+    };
+}
+
+impl_gxhash_methods!(GxHash32, u32, gxhash::gxhash32);
+impl_gxhash_methods!(GxHash64, u64, gxhash::gxhash64);
+impl_gxhash_methods!(GxHash128, u128, gxhash::gxhash128);
+
+#[pyo3::prelude::pymodule(name = "gxhash")]
+fn pygxhash(m: &Bound<'_, pyo3::prelude::PyModule>) -> PyResult<()> {
+    m.add_class::<GxHash32>()?;
+    m.add_class::<GxHash64>()?;
+    m.add_class::<GxHash128>()?;
+    Ok(())
+}