scicanonicalhash 0.1.0__tar.gz

scicanonicalhash-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+.venv
+.DS_Store
+*/*/__pycache__
+others_projects/sciforge
+scistack-gui/extension/node_modules/
+scistack-gui/frontend/node_modules/__pycache__/ 
+*.pyc 
+__pycache__/ 
+*.pyc
+*.pyo
+
+# Generated database artifacts (DuckDB data/lineage + write-ahead logs)
+*.duckdb
+*.duckdb.wal
+*.wal

scicanonicalhash-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: scicanonicalhash
+Version: 0.1.0
+Summary: Deterministic hashing for arbitrary Python objects
+Project-URL: Repository, https://github.com/example/scicanonicalhash
+Project-URL: Issues, https://github.com/example/scicanonicalhash/issues
+Author: SciStack Contributors
+License-Expression: MIT
+Keywords: cache-key,canonical,data-science,deterministic,hash,reproducibility
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: all
+Requires-Dist: numpy>=1.20; extra == 'all'
+Requires-Dist: pandas>=1.3; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: numpy
+Requires-Dist: numpy>=1.20; extra == 'numpy'
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.3; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# Canonical Hash
+
+Deterministic hashing for arbitrary Python objects.
+
+Provides utilities for creating stable, deterministic hashes of Python objects, essential for cache key computation, data versioning, and reproducibility.
+
+## Usage
+
+```python
+from scicanonicalhash import canonical_hash, generate_record_id
+
+# Hash any supported Python object
+h = canonical_hash(42)
+h = canonical_hash([1, 2, 3])
+h = canonical_hash({"key": "value"})
+
+# Generates a 16-character hex string (first 64 bits of SHA-256)
+assert len(h) == 16
+assert canonical_hash(42) == canonical_hash(42)  # Deterministic
+```
+
+## Supported Types
+
+1. JSON-serializable primitives (None, bool, int, float, str)
+2. numpy ndarrays (via shape + dtype + raw bytes)
+3. pandas DataFrames (via columns + index + array serialization)
+4. pandas Series (via name + array serialization)
+5. Dicts (sorted keys, recursive serialization)
+6. Lists/tuples (order-preserving, recursive serialization)
+
+## `generate_record_id`
+
+Generate a unique record ID from type, schema version, content hash, and metadata:
+
+```python
+rid = generate_record_id("MyData", 1, "abc123", {"subject": 1})
+```

scicanonicalhash-0.1.0/README.md

@@ -0,0 +1,37 @@
+# Canonical Hash
+
+Deterministic hashing for arbitrary Python objects.
+
+Provides utilities for creating stable, deterministic hashes of Python objects, essential for cache key computation, data versioning, and reproducibility.
+
+## Usage
+
+```python
+from scicanonicalhash import canonical_hash, generate_record_id
+
+# Hash any supported Python object
+h = canonical_hash(42)
+h = canonical_hash([1, 2, 3])
+h = canonical_hash({"key": "value"})
+
+# Generates a 16-character hex string (first 64 bits of SHA-256)
+assert len(h) == 16
+assert canonical_hash(42) == canonical_hash(42)  # Deterministic
+```
+
+## Supported Types
+
+1. JSON-serializable primitives (None, bool, int, float, str)
+2. numpy ndarrays (via shape + dtype + raw bytes)
+3. pandas DataFrames (via columns + index + array serialization)
+4. pandas Series (via name + array serialization)
+5. Dicts (sorted keys, recursive serialization)
+6. Lists/tuples (order-preserving, recursive serialization)
+
+## `generate_record_id`
+
+Generate a unique record ID from type, schema version, content hash, and metadata:
+
+```python
+rid = generate_record_id("MyData", 1, "abc123", {"subject": 1})
+```

scicanonicalhash-0.1.0/pyproject.toml

@@ -0,0 +1,91 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "scicanonicalhash"
+version = "0.1.0"
+description = "Deterministic hashing for arbitrary Python objects"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "SciStack Contributors" }
+]
+keywords = [
+    "hash",
+    "deterministic",
+    "canonical",
+    "cache-key",
+    "reproducibility",
+    "data-science",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+numpy = ["numpy>=1.20"]
+pandas = ["pandas>=1.3"]
+all = ["numpy>=1.20", "pandas>=1.3"]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "mypy>=1.0",
+    "ruff>=0.1.0",
+]
+
+[project.urls]
+Repository = "https://github.com/example/scicanonicalhash"
+Issues = "https://github.com/example/scicanonicalhash/issues"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/scicanonicalhash"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # Pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+]
+ignore = [
+    "E501",  # line too long (handled by formatter)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["scicanonicalhash"]

scicanonicalhash-0.1.0/src/scicanonicalhash/__init__.py

@@ -0,0 +1,11 @@
+"""Deterministic hashing for arbitrary Python objects.
+
+This package provides utilities for creating stable, deterministic hashes
+of Python objects, essential for cache key computation, data versioning,
+and reproducibility in data pipelines.
+"""
+
+from scicanonicalhash.hashing import canonical_hash, generate_record_id
+
+__all__ = ["canonical_hash", "generate_record_id"]
+__version__ = "0.1.0"

scicanonicalhash-0.1.0/src/scicanonicalhash/hashing.py

@@ -0,0 +1,147 @@
+"""Deterministic hashing for arbitrary Python objects.
+
+This module provides utilities for creating stable, deterministic hashes
+of Python objects, which is essential for cache key computation, data
+versioning, and reproducibility.
+"""
+
+import hashlib
+import json
+from typing import Any
+
+
+def canonical_hash(obj: Any) -> str:
+    """
+    Generate a deterministic hash for arbitrary Python objects.
+
+    Strategy:
+    1. For JSON-serializable primitives (None, bool, int, float, str): use JSON
+    2. For numpy ndarrays: use shape + dtype + raw bytes
+    3. For pandas DataFrames: use columns + index + array serialization
+    4. For pandas Series: use name + array serialization
+    5. For dicts: sort keys, recursively serialize
+    6. For lists/tuples: preserve order, recursively serialize
+    7. For other objects: raise ValueError
+
+    Args:
+        obj: Any Python object to hash
+
+    Returns:
+        16-character hex string (first 64 bits of SHA-256)
+
+    Raises:
+        ValueError: If an unserializable object is provided
+
+    Example:
+        >>> h = canonical_hash(42)
+        >>> len(h) == 16 and all(c in '0123456789abcdef' for c in h)
+        True
+        >>> canonical_hash(42) == canonical_hash(42)  # Deterministic
+        True
+        >>> canonical_hash([1, 2, 3]) != canonical_hash([1, 2, 4])  # Content-sensitive
+        True
+    """
+    serialized = _serialize_for_hash(obj)
+    return hashlib.sha256(serialized).hexdigest()[:16]
+
+
+def _serialize_for_hash(obj: Any) -> bytes:
+    """Convert object to bytes for hashing."""
+
+    # Primitives - use JSON for stability
+    if isinstance(obj, (type(None), bool, int, float, str)):
+        return json.dumps(obj).encode("utf-8")
+
+    # Dicts - sort keys for determinism
+    if isinstance(obj, dict):
+        sorted_items = sorted(obj.items(), key=lambda x: str(x[0]))
+        parts = []
+        for k, v in sorted_items:
+            parts.append(_serialize_for_hash(k))
+            parts.append(_serialize_for_hash(v))
+        return b"dict:" + b"|".join(parts)
+
+    # Lists/tuples - preserve order
+    if isinstance(obj, (list, tuple)):
+        type_prefix = b"list:" if isinstance(obj, list) else b"tuple:"
+        parts = [_serialize_for_hash(item) for item in obj]
+        return type_prefix + b"|".join(parts)
+
+    # Numpy arrays - use shape, dtype, and raw bytes
+    if hasattr(obj, "tobytes") and hasattr(obj, "dtype") and hasattr(obj, "shape"):
+        return (
+            b"ndarray:"
+            + str(obj.shape).encode()
+            + b":"
+            + str(obj.dtype).encode()
+            + b":"
+            + obj.tobytes()
+        )
+
+    # Pandas DataFrame
+    if hasattr(obj, "to_numpy") and hasattr(obj, "columns"):
+        arr = obj.to_numpy()
+        cols = list(obj.columns)
+        idx = list(obj.index) if hasattr(obj, "index") else []
+        return (
+            b"dataframe:"
+            + _serialize_for_hash(cols)
+            + b":"
+            + _serialize_for_hash(idx)
+            + b":"
+            + _serialize_for_hash(arr)
+        )
+
+    # Pandas Series
+    if hasattr(obj, "to_numpy") and hasattr(obj, "name") and not hasattr(obj, "columns"):
+        return (
+            b"series:"
+            + _serialize_for_hash(obj.name)
+            + b":"
+            + _serialize_for_hash(obj.to_numpy())
+        )
+
+    # Python array.array (MATLAB bridge can produce these)
+    import array as _array_mod
+    if isinstance(obj, _array_mod.array):
+        import numpy as np
+        return _serialize_for_hash(np.array(obj))
+
+    # Unsupported type
+    raise ValueError(f"Unserializable data type: {type(obj)}")
+
+
+def generate_record_id(
+    class_name: str,
+    schema_version: int,
+    content_hash: str,
+    metadata: dict,
+) -> str:
+    """
+    Generate a unique record ID from components.
+
+    The record_id uniquely identifies a record by its type, schema, content,
+    and metadata. Useful for addressing/querying versioned data.
+
+    Args:
+        class_name: The record type (e.g., "RotationMatrix")
+        schema_version: Integer version of the serialization schema
+        content_hash: Pre-computed hash of the data content
+        metadata: The addressing metadata (subject, trial, etc.)
+
+    Returns:
+        16-character hex string
+
+    Example:
+        >>> rid = generate_record_id("MyData", 1, "abc123", {"subject": 1})
+        >>> len(rid) == 16 and all(c in '0123456789abcdef' for c in rid)
+        True
+    """
+    components = [
+        f"class:{class_name}",
+        f"schema:{schema_version}",
+        f"content:{content_hash}",
+        f"meta:{canonical_hash(metadata)}",
+    ]
+    combined = "|".join(components).encode("utf-8")
+    return hashlib.sha256(combined).hexdigest()[:16]