gxhash 0.1.2__cp313-cp313-manylinux_2_34_x86_64.whl

gxhash/__init__.py

@@ -0,0 +1,5 @@
+from .gxhash import *
+
+__doc__ = gxhash.__doc__
+if hasattr(gxhash, "__all__"):
+    __all__ = gxhash.__all__

gxhash/__init__.pyi

@@ -0,0 +1,194 @@
+from typing import Protocol
+
+class File(Protocol):
+    def fileno(self) -> int:
+        """
+        Summary
+        -------
+        Returns the file descriptor of the file.
+        Some file-like objects like `io.BytesIO` have an unimplemented `fileno` method.
+        If you are uncertain whether the file has a valid `fileno` method,
+        you should write to a `tempfile.TemporaryFile` and pass that to the hasher.
+
+        Returns
+        -------
+        file_descriptor (`int`)
+            the file descriptor of the file
+        """
+
+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 = GxHash128(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 = GxHash128(1234)
+        print(f"Hash is {hasher.hash(bytes([42] * 1000))}!")
+        ```
+        """
+    def hash_nogil(self, bytes: bytes) -> int:
+        """
+        Summary
+        -------
+        Hashes `bytes` to an `int` without the GIL.
+        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)
+        input_bytes = bytes([42] * 1000)
+        thread_pool = ThreadPoolExecutor()
+        future = thread_pool.submit(hasher.hash_nogil, input_bytes)
+        hash_result = await wrap_future(future)
+        print(f"Hash is {hash_result}!")
+        ```
+        """
+    def hash_file(self, file: File) -> int:
+        """
+        Summary
+        -------
+        Hashes a `File` to an `int`.
+        This method duplicates the file descriptor and memory maps the file entirely in Rust.
+        This operation is many times faster than reading the file in Python and passing the bytes to the hasher.
+        If your input is already in `bytes`, this method may be slightly less performant than `hash` and `hash_nogil`.
+        If the `bytes` is really large, writing to a `TemporaryFile` and passing it to this method may be more
+        performant than passing the `bytes` directly to `hash` or `hash_nogil`.
+
+        Parameters
+        ----------
+        file (`File`)
+            a file object
+
+        Returns
+        -------
+        hash (`int`)
+            the hash of the input file
+
+        Example
+        -------
+        Converting `bytes` to a `TemporaryFile` and hashing.
+
+        ```python
+        hasher = GxHash128(seed=1234)
+        file = TemporaryFile()
+        file.write(bytes([42] * 1000))
+        file.seek(0)
+        print(f"Hash is {hasher.hash_file(file)}!")
+        ```
+
+        Hashing a file directly.
+
+        ```python
+        file = open('really_large_file.img', 'rb')
+        hasher = GxHash128(seed=1234)
+        print(f"Hash is {hasher.hash_file(file)}!")
+        ```
+        """
+    async def hash_file_async(self, file: File) -> int:
+        """
+        Summary
+        -------
+        Asynchronous variant of `hash_file`.
+        This method allows you to perform multiple hashes with true multi-threaded parallelism.
+        If called sequentially, this method is slightly less performant than `hash_file`.
+        It is only ever faster than a multi-threaded `hash_nogil` when the input is a `File`,
+        and that is due to the performance overhead of reading a `File` in Python.
+
+        Parameters
+        ----------
+        file (`File`)
+            a file object
+
+        Returns
+        -------
+        hash (`int`)
+            the hash of the input file
+
+        Example
+        -------
+        Converting `bytes` to a `TemporaryFile` and hashing.
+
+        ```python
+        hasher = GxHash128(seed=1234)
+        file = TemporaryFile()
+        file.write(bytes([42] * 1000))
+        file.seek(0)
+        print(f"Hash is {await hasher.hash_file_asymc(file)}!")
+        ```
+
+        Hashing a file directly.
+
+        ```python
+        file = open('really_large_file.img', 'rb')
+        hasher = GxHash128(seed=1234)
+        print(f"Hash is {await hasher.hash_file_async(file)}!")
+        ```
+        """
+
+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.
+    """

gxhash-0.1.2.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: gxhash
+Version: 0.1.2
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# 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.
+- **Fine-Grained Control**: Build true multi-threaded or async hashing pipelines with GIL-free APIs.
+- **Faster File Hashing**: Hash files using memory-mapped I/O via Rust — 3x faster than Python's sequential I/O.
+- **Async-Ready**: Tokio-powered async hashing for fast and efficient concurrency.
+- **Fully Typesafe**: Predictable, clean API with complete type safety.
+
+## Installation
+
+```bash
+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 a file.
+
+```python
+from gxhash import GxHash64
+
+def main():
+    gxhash = GxHash64(seed=0)
+    file = open("path/to/file.dmg", "rb")
+    result = gxhash.hash_file(file)
+
+if __name__ == "__main__":
+    main()
+```
+
+Hashing a file asynchronously.
+
+```python
+from asyncio import run
+from gxhash import GxHash128
+
+async def main():
+    gxhash = GxHash128(seed=0)
+    file = open("path/to/file.dmg", "rb")
+    result = await gxhash.hash_file_async(file)
+
+if __name__ == "__main__":
+    run(main())
+```
+

gxhash-0.1.2.dist-info/RECORD

@@ -0,0 +1,7 @@
+gxhash-0.1.2.dist-info/METADATA,sha256=4wwfZMVnQKJfZF7tDir7DMyAVDhV2fgKf3uPOi2sxoY,1765
+gxhash-0.1.2.dist-info/WHEEL,sha256=0T3ERfOVy2_NA0spmJ9W283dd80DxGxyjANqE-4dteM,108
+gxhash/__init__.py,sha256=zLP3Jdvo2-JFQKZIocwkNCWkjYJVXauBSG3JSAW8rA0,107
+gxhash/__init__.pyi,sha256=9HtHNSOemmwH6A1Av5GI2HsAiIf-s7JKIpC6uPzxzqM,5539
+gxhash/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gxhash/gxhash.cpython-313-x86_64-linux-gnu.so,sha256=7z0NvbmCFuoc4nvn6xYYKXOH-WbTxqoTq1c5y3Y0EsM,642424
+gxhash-0.1.2.dist-info/RECORD,,

gxhash-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.8.3)
+Root-Is-Purelib: false
+Tag: cp313-cp313-manylinux_2_34_x86_64