dbx-tools-core 0.6.78__tar.gz

dbx_tools_core-0.6.78/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.3
+Name: dbx-tools-core
+Version: 0.6.78
+Summary: Dependency-free cross-runtime identity helpers for dbx-tools Python packages
+Requires-Python: >=3.10
+Project-URL: Source, https://github.com/reggie-db/dbx-tools/tree/main/packages/py/core
+Description-Content-Type: text/markdown
+
+# `dbx-tools-core`
+
+Dependency-free Python helpers shared by dbx-tools packages.
+
+Install directly from this monorepo:
+
+```bash
+pip install "dbx-tools-core @ git+https://github.com/reggie-db/dbx-tools.git@main#subdirectory=packages/py/core"
+```
+
+The package intentionally contains only the cross-runtime identity primitives
+currently needed by more than one implementation:
+
+- `hash.fnv_hash()` — the single-string subset of TypeScript
+  `fnvHashWithOptions`, including UTF-16 code-unit hashing and base-32 output;
+- `object.to_stable_key()` — strict structured identity canonicalization;
+- `string.to_identifier()` — readable identifier tokenization, with the same
+  hyphen default as TypeScript and an explicit delimiter override for consumers
+  such as the underscore-delimited Postgres bus channel.
+
+These functions exist so Python packages do not copy the TypeScript algorithms
+locally and silently drift. Add broader helpers only when another Python package
+actually needs them. Their shared behavior is tested from
+`packages/test/polyglot/fixtures/core/fixture.json`, not duplicated in this
+package.

dbx_tools_core-0.6.78/README.md

@@ -0,0 +1,25 @@
+# `dbx-tools-core`
+
+Dependency-free Python helpers shared by dbx-tools packages.
+
+Install directly from this monorepo:
+
+```bash
+pip install "dbx-tools-core @ git+https://github.com/reggie-db/dbx-tools.git@main#subdirectory=packages/py/core"
+```
+
+The package intentionally contains only the cross-runtime identity primitives
+currently needed by more than one implementation:
+
+- `hash.fnv_hash()` — the single-string subset of TypeScript
+  `fnvHashWithOptions`, including UTF-16 code-unit hashing and base-32 output;
+- `object.to_stable_key()` — strict structured identity canonicalization;
+- `string.to_identifier()` — readable identifier tokenization, with the same
+  hyphen default as TypeScript and an explicit delimiter override for consumers
+  such as the underscore-delimited Postgres bus channel.
+
+These functions exist so Python packages do not copy the TypeScript algorithms
+locally and silently drift. Add broader helpers only when another Python package
+actually needs them. Their shared behavior is tested from
+`packages/test/polyglot/fixtures/core/fixture.json`, not duplicated in this
+package.

dbx_tools_core-0.6.78/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "dbx-tools-core"
+version = "0.6.78"
+description = "Dependency-free cross-runtime identity helpers for dbx-tools Python packages"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = []
+
+[project.urls]
+Source = "https://github.com/reggie-db/dbx-tools/tree/main/packages/py/core"
+
+[build-system]
+requires = ["uv_build>=0.11.28,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "dbx_tools.core"
+module-root = "src"
+namespace = true

dbx_tools_core-0.6.78/pyproject.toml.orig

@@ -0,0 +1,21 @@
+# ~~ Generated by projen. To modify, edit .projenrc.js and run "bunx projen".
+
+[project]
+name = "dbx-tools-core"
+version = "0.6.78"
+description = "Dependency-free cross-runtime identity helpers for dbx-tools Python packages"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [ ]
+
+  [project.urls]
+  Source = "https://github.com/reggie-db/dbx-tools/tree/main/packages/py/core"
+
+[build-system]
+requires = [ "uv_build>=0.11.28,<0.12.0" ]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "dbx_tools.core"
+module-root = "src"
+namespace = true

dbx_tools_core-0.6.78/src/dbx_tools/core/__init__.py

@@ -0,0 +1,16 @@
+from .hash import fnv_hash
+from .object import to_stable_key
+from .string import to_identifier
+
+fnvHash = fnv_hash
+toIdentifier = to_identifier
+toStableKey = to_stable_key
+
+__all__ = [
+    "fnvHash",
+    "fnv_hash",
+    "toIdentifier",
+    "toStableKey",
+    "to_identifier",
+    "to_stable_key",
+]

dbx_tools_core-0.6.78/src/dbx_tools/core/hash.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+_BASE32_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz"
+
+
+def fnv_hash(value: str, *, length: int = 6) -> str:
+    """Match TypeScript ``fnvHashWithOptions`` for one string value."""
+    digest = 0x811C9DC5
+    for token in ("[", "string:", value, ",", "]"):
+        encoded = token.encode("utf-16-le", "surrogatepass")
+        for index in range(0, len(encoded), 2):
+            code_unit = encoded[index] | (encoded[index + 1] << 8)
+            digest ^= code_unit
+            digest = (digest * 0x01000193) & 0xFFFFFFFF
+    encoded_digest = _to_base32(digest).rjust(7, _BASE32_ALPHABET[0])
+    return encoded_digest[: min(length, 7)]
+
+
+def _to_base32(value: int) -> str:
+    if value == 0:
+        return _BASE32_ALPHABET[0]
+    encoded = ""
+    while value:
+        encoded = _BASE32_ALPHABET[value & 31] + encoded
+        value >>= 5
+    return encoded

dbx_tools_core-0.6.78/src/dbx_tools/core/object.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from datetime import date, datetime
+
+
+def to_stable_key(value: object, seen: set[int] | None = None) -> str:
+    """Build the Python equivalent of shared-core's strict stable identity key."""
+    if value is None:
+        return "null"
+    if isinstance(value, str):
+        utf16_length = len(value.encode("utf-16-le", "surrogatepass")) // 2
+        return f"string:{utf16_length}:{value}"
+    if isinstance(value, bool):
+        return f"boolean:{str(value).lower()}"
+    if isinstance(value, int):
+        return f"number:{value}"
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise TypeError("Stable keys require finite numbers")
+        if value == 0 and math.copysign(1, value) < 0:
+            return "number:-0"
+        return f"number:{format(value, '.15g')}"
+    if isinstance(value, (datetime, date)):
+        timestamp = value.isoformat()
+        if isinstance(value, datetime) and value.tzinfo is not None:
+            timestamp = timestamp.replace("+00:00", "Z")
+        return f"date:{timestamp}"
+    seen = seen or set()
+    identity = id(value)
+    if identity in seen:
+        raise TypeError("Stable keys cannot contain cycles")
+    seen.add(identity)
+    try:
+        if isinstance(value, (list, tuple)):
+            return f"array:[{','.join(to_stable_key(item, seen) for item in value)}]"
+        if isinstance(value, (set, frozenset)):
+            return f"set:[{','.join(sorted(to_stable_key(item, seen) for item in value))}]"
+        if isinstance(value, Mapping):
+            entries = sorted(
+                f"{to_stable_key(key, seen)}={to_stable_key(item, seen)}"
+                for key, item in value.items()
+            )
+            return f"object:{{{','.join(entries)}}}"
+    finally:
+        seen.remove(identity)
+    raise TypeError(f"Unsupported stable key type: {type(value).__name__}")

dbx_tools_core-0.6.78/src/dbx_tools/core/string.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+import re
+
+
+def to_identifier(*values: object, delimiter: str = "-") -> str:
+    """Match TypeScript identifier tokenization with an overridable delimiter."""
+    tokens: list[str] = []
+    for value in values:
+        text_value = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1 \2", str(value))
+        text_value = re.sub(r"([a-z0-9])([A-Z])", r"\1 \2", text_value)
+        tokens.extend(token.lower() for token in re.findall(r"[A-Za-z0-9]+", text_value))
+    return delimiter.join(tokens)