refactor: reorganize core modules

akhundMurad · akhundMurad · commit 7ec8280f4c20 · 2026-01-05T17:58:23.000+01:00
- move TypeID implementation, factory, parsing, validation, constants, and errors into typeid.core
- add typeid.codecs.base32 and keep typeid.base32 as a compatibility re-export
- update public imports and tests to use new module paths
- update CLI to live in typeid.cli.main and fix project script entrypoint
- keep legacy modules (typeid.typeid, typeid.factory, typeid.validation, typeid.errors, typeid.constants) as shims
diff --git a/pyproject.toml b/pyproject.toml
@@ -29,7 +29,7 @@ Repository = "https://github.com/akhundMurad/typeid-python"
 "Bug Tracker" = "https://github.com/akhundMurad/typeid-python/issues"
 
 [project.scripts]
-typeid = "typeid.cli:cli"
+typeid = "typeid.cli.main:cli"
 
 [dependency-groups]
 dev = [
diff --git a/tests/test_base32.py b/tests/test_base32.py
@@ -1,4 +1,4 @@
-from typeid.base32 import decode, encode
+from typeid.codecs.base32 import decode, encode
 
 
 def test_encode_decode_logic() -> None:
diff --git a/tests/test_factory.py b/tests/test_factory.py
@@ -1,7 +1,7 @@
 import pytest
 
 from typeid import TypeID, cached_typeid_factory, typeid_factory
-from typeid.errors import PrefixValidationException
+from typeid.core.errors import PrefixValidationException
 
 
 def test_typeid_factory_generates_typeid_with_prefix():
diff --git a/tests/test_spec.py b/tests/test_spec.py
@@ -2,7 +2,7 @@
 from uuid_utils import UUID
 
 from typeid import TypeID
-from typeid.errors import TypeIDException
+from typeid.core.errors import TypeIDException
 
 
 def test_invalid_spec(invalid_spec: list) -> None:
diff --git a/tests/test_typeid.py b/tests/test_typeid.py
@@ -4,7 +4,7 @@
 import uuid_utils
 
 from typeid import TypeID
-from typeid.errors import SuffixValidationException
+from typeid.core.errors import SuffixValidationException
 
 
 def test_default_suffix() -> None:
diff --git a/tests/test_validation.py b/tests/test_validation.py
@@ -2,8 +2,8 @@
 from uuid_utils import uuid7
 
 from typeid import base32
-from typeid.errors import PrefixValidationException, SuffixValidationException
-from typeid.validation import validate_prefix, validate_suffix_and_decode
+from typeid.core.errors import PrefixValidationException, SuffixValidationException
+from typeid.core.validation import validate_prefix, validate_suffix_and_decode
 
 
 def test_validate_correct_prefix() -> None:
diff --git a/typeid/__init__.py b/typeid/__init__.py
@@ -1,5 +1,6 @@
-from .factory import TypeIDFactory, cached_typeid_factory, typeid_factory
-from .typeid import TypeID, from_string, from_uuid, get_prefix_and_suffix
+from typeid.core.factory import TypeIDFactory, cached_typeid_factory, typeid_factory
+from typeid.core.typeid import TypeID, from_string, from_uuid
+from typeid.core.parsing import get_prefix_and_suffix
 
 __all__ = (
     "TypeID",
diff --git a/typeid/base32.py b/typeid/base32.py
@@ -1,9 +1,13 @@
-from typeid._base32 import encode as _encode_rust, decode as _decode_rust  # type: ignore
+# Compatibility shim.
+#
+# This module exists to preserve backward compatibility with earlier
+# versions of the library. Public symbols are re-exported from their
+# current implementation locations.
+#
+# New code should prefer importing from the canonical modules, but
+# existing imports will continue to work.
 
+from typeid.codecs.base32 import encode, decode
 
-def encode(src: bytes) -> str:
-    return _encode_rust(src)
 
-
-def decode(s: str) -> bytes:
-    return _decode_rust(s)
+__all__ = ("encode", "decode")
diff --git a/typeid/cli/__init__.py b/typeid/cli/__init__.py
@@ -0,0 +1,5 @@
+from typeid.cli.main import cli
+
+
+if __name__ == "__main__": 
+    cli()
diff --git a/typeid/cli/main.py b/typeid/cli/main.py
@@ -4,7 +4,9 @@
 import click
 from uuid_utils import UUID
 
-from typeid import TypeID, base32, from_uuid, get_prefix_and_suffix
+from typeid import TypeID
+from typeid.codecs import base32
+from typeid.core.parsing import get_prefix_and_suffix
 from typeid.explain.discovery import discover_schema_path
 from typeid.explain.engine import explain as explain_engine
 from typeid.explain.formatters import format_explanation_json, format_explanation_pretty
@@ -42,7 +44,7 @@ def encode(uuid: str, prefix: Optional[str] = None) -> None:
     (e.g. stored in a database) and need to be represented as TypeIDs.
     """
     uuid_obj = UUID(uuid)
-    typeid = from_uuid(suffix=uuid_obj, prefix=prefix)
+    typeid = TypeID.from_uuid(suffix=uuid_obj, prefix=prefix)
 
     click.echo(str(typeid))
 
@@ -151,7 +153,3 @@ def explain(
         click.echo(format_explanation_json(exp))
     else:
         click.echo(format_explanation_pretty(exp))
-
-
-if __name__ == "__main__":
-    cli()
diff --git a/typeid/codecs/__init__.py b/typeid/codecs/__init__.py
diff --git a/typeid/codecs/base32.py b/typeid/codecs/base32.py
@@ -0,0 +1,90 @@
+from typeid._base32 import encode as _encode_rust, decode as _decode_rust  # type: ignore
+
+
+def encode(src: bytes) -> str:
+    """
+    Encode 16 raw bytes into a 26-character TypeID suffix (Rust-accelerated).
+
+    This function is the low-level codec used by TypeID to transform the 16-byte
+    UUID payload into the 26-character suffix string.
+
+    It is **not** a general-purpose Base32 encoder:
+    - Input length is strictly **16 bytes**.
+    - Output length is strictly **26 characters**.
+    - The alphabet is fixed to:
+      ``0123456789abcdefghjkmnpqrstvwxyz`` (lowercase only).
+
+    The mapping is a fixed bit-packing scheme:
+    - The first 6 input bytes (48 bits) become the first 10 characters
+      (often corresponding to the UUIDv7 timestamp portion in TypeID usage).
+    - The remaining 10 bytes (80 bits) become the last 16 characters.
+
+    Parameters
+    ----------
+    src : bytes
+        Exactly 16 bytes to encode (the raw UUID bytes).
+
+    Returns
+    -------
+    str
+        A 26-character ASCII string using only the TypeID Base32 alphabet.
+
+    Raises
+    ------
+    RuntimeError
+        If ``src`` is not exactly 16 bytes long:
+        ``"Invalid length (expected 16 bytes)."``
+
+    Notes
+    -----
+    - This function is implemented in Rust and exposed via a CPython extension;
+      there is no Python fallback.
+    - The returned string is always lowercase.
+    """
+
+    return _encode_rust(src)
+
+
+def decode(s: str) -> bytes:
+    """
+    Decode a 26-character TypeID suffix into 16 raw bytes (Rust-accelerated).
+
+    This function is the inverse of :func:`encode`. It takes a TypeID suffix
+    (26 characters) and reconstructs the original 16 bytes by reversing the
+    same fixed bit-packing scheme.
+
+    Decoding is strict:
+    - Input length must be exactly **26 characters**.
+    - Only characters from the alphabet
+      ``0123456789abcdefghjkmnpqrstvwxyz`` are accepted.
+    - Uppercase letters, whitespace, separators, and Crockford aliases
+      (e.g. 'O'→'0', 'I'/'L'→'1') are **not** accepted.
+
+    Parameters
+    ----------
+    s : str
+        The 26-character suffix string to decode.
+
+    Returns
+    -------
+    bytes
+        Exactly 16 bytes (the raw UUID bytes).
+
+    Raises
+    ------
+    RuntimeError
+        If ``s`` is not exactly 26 characters long:
+        ``"Invalid length (expected 26 chars)."``
+
+        If ``s`` contains any character outside the allowed alphabet:
+        ``"Invalid base32 character."``
+
+    Notes
+    -----
+    - This function is implemented in Rust and exposed via a CPython extension;
+      there is no Python fallback.
+    - This performs only decoding/validation of the suffix encoding. It does not
+      validate UUID version/variant semantics.
+    """
+
+    return _decode_rust(s)
diff --git a/typeid/constants.py b/typeid/constants.py
@@ -1,5 +1,13 @@
-SUFFIX_LEN = 26
+# Compatibility shim.
+#
+# This module exists to preserve backward compatibility with earlier
+# versions of the library. Public symbols are re-exported from their
+# current implementation locations.
+#
+# New code should prefer importing from the canonical modules, but
+# existing imports will continue to work.
 
-PREFIX_MAX_LEN = 63
+from typeid.core.constants import PREFIX_MAX_LEN, SUFFIX_LEN, ALPHABET
 
-ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz"
+
+__all__ = ("PREFIX_MAX_LEN", "SUFFIX_LEN", "ALPHABET")
diff --git a/typeid/core/__init__.py b/typeid/core/__init__.py
diff --git a/typeid/core/constants.py b/typeid/core/constants.py
@@ -0,0 +1,5 @@
+SUFFIX_LEN = 26
+
+PREFIX_MAX_LEN = 63
+
+ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz"
diff --git a/typeid/core/errors.py b/typeid/core/errors.py
@@ -0,0 +1,14 @@
+class TypeIDException(Exception):
+    ...
+
+
+class PrefixValidationException(TypeIDException):
+    ...
+
+
+class SuffixValidationException(TypeIDException):
+    ...
+
+
+class InvalidTypeIDStringException(TypeIDException):
+    ...
diff --git a/typeid/core/factory.py b/typeid/core/factory.py
@@ -0,0 +1,40 @@
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import Callable
+
+from typeid.core.typeid import TypeID
+
+
+@dataclass(frozen=True, slots=True)
+class TypeIDFactory:
+    """
+    Callable object that generates TypeIDs with a fixed prefix.
+
+    Example:
+        user_id = TypeIDFactory("user")()
+    """
+
+    prefix: str
+
+    def __call__(self) -> TypeID:
+        return TypeID(self.prefix)
+
+
+def typeid_factory(prefix: str) -> Callable[[], TypeID]:
+    """
+    Return a zero-argument callable that generates TypeIDs with a fixed prefix.
+
+    Example:
+        user_id = typeid_factory("user")()
+    """
+    return TypeIDFactory(prefix)
+
+
+@lru_cache(maxsize=256)
+def cached_typeid_factory(prefix: str) -> Callable[[], TypeID]:
+    """
+    Same as typeid_factory, but caches factories by prefix.
+
+    Use this if you create factories repeatedly at runtime.
+    """
+    return TypeIDFactory(prefix)
diff --git a/typeid/core/parsing.py b/typeid/core/parsing.py
@@ -0,0 +1,18 @@
+from typeid.core.errors import InvalidTypeIDStringException
+
+
+def get_prefix_and_suffix(string: str) -> tuple:
+    parts = string.rsplit("_", 1)
+
+    # When there's no underscore in the string.
+    if len(parts) == 1:
+        if parts[0].strip() == "":
+            raise InvalidTypeIDStringException(f"Invalid TypeID: {string}")
+        return None, parts[0]
+
+    # When there is an underscore, unpack prefix and suffix.
+    prefix, suffix = parts
+    if prefix.strip() == "" or suffix.strip() == "":
+        raise InvalidTypeIDStringException(f"Invalid TypeID: {string}")
+
+    return prefix, suffix
diff --git a/typeid/core/typeid.py b/typeid/core/typeid.py
diff --git a/typeid/core/validation.py b/typeid/core/validation.py
diff --git a/typeid/errors.py b/typeid/errors.py
diff --git a/typeid/factory.py b/typeid/factory.py
diff --git a/typeid/typeid.py b/typeid/typeid.py
diff --git a/typeid/validation.py b/typeid/validation.py

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-from typeid.base32 import decode, encode`
	`1`	`+from typeid.codecs.base32 import decode, encode`
`2`	`2`
`3`	`3`
`4`	`4`	`def test_encode_decode_logic() -> None:`
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +from typeid.cli.main import cli
++
++
 +if __name__ == "__main__":
 +    cli()