base-typed-id 0.1.0__tar.gz

base_typed_id-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Eldeniz Guseinli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

base_typed_id-0.1.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: base-typed-id
+Version: 0.1.0
+Summary: Strict typed UUID identifier base class with exact runtime subtype preservation and optional Pydantic v2 support.
+Author-email: Eldeniz Guseinli <eldenizfamilyanskicode@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/eldenizfamilyanskicode/base-typed-id
+Project-URL: Repository, https://github.com/eldenizfamilyanskicode/base-typed-id
+Project-URL: Issues, https://github.com/eldenizfamilyanskicode/base-typed-id/issues
+Keywords: typing,uuid,typed-id,value-object,pydantic,domain-model
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pydantic
+Requires-Dist: pydantic<3,>=2.6; extra == "pydantic"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Requires-Dist: pydantic<3,>=2.6; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff>=0.5; extra == "lint"
+Provides-Extra: typecheck
+Requires-Dist: mypy>=1.10; extra == "typecheck"
+Requires-Dist: pyright>=1.1; extra == "typecheck"
+Requires-Dist: pydantic<3,>=2.6; extra == "typecheck"
+Provides-Extra: build
+Requires-Dist: build>=1.2; extra == "build"
+Requires-Dist: twine>=5.1; extra == "build"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pyright>=1.1; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: pydantic<3,>=2.6; extra == "dev"
+Dynamic: license-file
+
+# base-typed-id
+
+Strict typed UUID identifier base class with exact runtime subtype preservation and optional Pydantic v2 support.
+
+## Why
+
+`BaseTypedId` lets you define domain-specific UUID-backed string subtypes such as `UserId`, `OrderId`, or `ExternalEventId`.
+
+Goals:
+
+- exact runtime subtype preservation
+- plain `str` compatibility
+- plain string serialization
+- pickle roundtrip support
+- Pydantic v2 support
+- OpenAPI `format: uuid`
+
+## Why not `NewType`, `Annotated[str, ...]`, or wrapper value objects?
+
+There are several ways to model typed identifiers in Python. This library focuses on one specific trade-off: keeping a domain-specific runtime subtype while staying fully compatible with plain `str`.
+
+### Why not `typing.NewType`?
+
+`NewType` is excellent when you only need a static type distinction for type checkers.
+
+However, at runtime a `NewType` value is still just a plain `str`. It does not:
+
+- preserve an exact runtime subtype
+- validate UUID format on construction
+- provide subtype-preserving pickle behavior
+- integrate as a real runtime subtype inside containers and model fields
+
+Use `NewType` when static typing alone is enough.
+
+### Why not `Annotated[str, ...]`?
+
+`Annotated` is useful for attaching metadata to a type, especially for validators and frameworks.
+
+But it still does not create a distinct runtime type. If you need runtime identity such as `type(user_id) is UserId`, `Annotated[str, ...]` is not enough.
+
+### Why not wrapper value objects?
+
+A wrapper class such as `UserId(value: str)` gives a stronger domain boundary and is often a good choice in rich domain models.
+
+The trade-off is interoperability friction:
+
+- it is no longer a plain string
+- JSON serialization usually needs custom handling
+- dictionary key compatibility is less transparent
+- many integrations require explicit `.value` extraction
+
+Use a wrapper when you want additional domain behavior beyond typed identity.
+
+### What this library optimizes for
+
+`BaseTypedId` is for the narrower case where you want all of the following at once:
+
+- exact runtime subtype preservation
+- plain `str` compatibility
+- UUID parsing and version checks at the boundary
+- plain string serialization
+- Pydantic v2 / OpenAPI compatibility
+- pickle roundtrip support
+
+## When not to use this library
+
+This library is not the best fit if:
+
+- static-only type distinction is enough for you (`NewType` may be simpler)
+- you want rich domain behavior on the identifier itself (a wrapper value object may be better)
+- your identifiers are not UUID-based
+
+## Installation
+
+```bash
+pip install base-typed-id
+```
+
+With Pydantic support:
+
+```bash
+pip install "base-typed-id[pydantic]"
+```
+
+## Basic usage
+
+```python
+from base_typed_id import BaseTypedId
+
+
+class UserId(BaseTypedId):
+    pass
+
+
+user_id: UserId = UserId("123e4567-e89b-42d3-a456-426614174000")
+generated_user_id: UserId = UserId()
+
+assert type(user_id) is UserId
+assert isinstance(user_id, str)
+```
+
+## UUID version control
+
+By default, `BaseTypedId` expects UUID v4.
+
+```python
+from base_typed_id import BaseTypedId
+
+
+class ExternalEventId(BaseTypedId):
+    uuid_version = 5
+```
+
+`uuid_version = None` disables version restriction.
+
+## Pydantic v2
+
+```python
+from pydantic import BaseModel
+
+from base_typed_id import BaseTypedId
+
+
+class UserId(BaseTypedId):
+    pass
+
+
+class UserModel(BaseModel):
+    user_id: UserId
+```
+
+Behavior:
+
+* inside model: exact subtype is preserved
+* after `model_dump()` / `model_dump_json()`: plain string is exported
+* generated schema keeps `type: string` and `format: uuid`
+
+## Deterministic identifiers
+
+```python
+from base_typed_id import BaseTypedId
+from base_typed_id.factories import deterministically_from_words
+
+
+class ExternalEventId(BaseTypedId):
+    uuid_version = 5
+
+
+event_id: ExternalEventId = deterministically_from_words(
+    ExternalEventId,
+    words=[
+        "workspace:house-of-ai",
+        "provider:telegram",
+        "event:message-created",
+        "message:42",
+    ],
+)
+```
+
+Rules:
+
+* same words -> same identifier
+* order matters
+* deterministic generation requires `uuid_version = 5` or `uuid_version = None`
+
+## Guarantees
+
+* exact subtype is preserved in runtime objects
+* exact subtype is preserved in containers
+* exact subtype is preserved through pickle roundtrip
+* serialized/exported representation is plain string
+
+## Non-goals
+
+* no extra domain behavior beyond typed identity
+* no automatic semantic validation beyond UUID parsing/version checks

base_typed_id-0.1.0/README.md

@@ -0,0 +1,176 @@
+# base-typed-id
+
+Strict typed UUID identifier base class with exact runtime subtype preservation and optional Pydantic v2 support.
+
+## Why
+
+`BaseTypedId` lets you define domain-specific UUID-backed string subtypes such as `UserId`, `OrderId`, or `ExternalEventId`.
+
+Goals:
+
+- exact runtime subtype preservation
+- plain `str` compatibility
+- plain string serialization
+- pickle roundtrip support
+- Pydantic v2 support
+- OpenAPI `format: uuid`
+
+## Why not `NewType`, `Annotated[str, ...]`, or wrapper value objects?
+
+There are several ways to model typed identifiers in Python. This library focuses on one specific trade-off: keeping a domain-specific runtime subtype while staying fully compatible with plain `str`.
+
+### Why not `typing.NewType`?
+
+`NewType` is excellent when you only need a static type distinction for type checkers.
+
+However, at runtime a `NewType` value is still just a plain `str`. It does not:
+
+- preserve an exact runtime subtype
+- validate UUID format on construction
+- provide subtype-preserving pickle behavior
+- integrate as a real runtime subtype inside containers and model fields
+
+Use `NewType` when static typing alone is enough.
+
+### Why not `Annotated[str, ...]`?
+
+`Annotated` is useful for attaching metadata to a type, especially for validators and frameworks.
+
+But it still does not create a distinct runtime type. If you need runtime identity such as `type(user_id) is UserId`, `Annotated[str, ...]` is not enough.
+
+### Why not wrapper value objects?
+
+A wrapper class such as `UserId(value: str)` gives a stronger domain boundary and is often a good choice in rich domain models.
+
+The trade-off is interoperability friction:
+
+- it is no longer a plain string
+- JSON serialization usually needs custom handling
+- dictionary key compatibility is less transparent
+- many integrations require explicit `.value` extraction
+
+Use a wrapper when you want additional domain behavior beyond typed identity.
+
+### What this library optimizes for
+
+`BaseTypedId` is for the narrower case where you want all of the following at once:
+
+- exact runtime subtype preservation
+- plain `str` compatibility
+- UUID parsing and version checks at the boundary
+- plain string serialization
+- Pydantic v2 / OpenAPI compatibility
+- pickle roundtrip support
+
+## When not to use this library
+
+This library is not the best fit if:
+
+- static-only type distinction is enough for you (`NewType` may be simpler)
+- you want rich domain behavior on the identifier itself (a wrapper value object may be better)
+- your identifiers are not UUID-based
+
+## Installation
+
+```bash
+pip install base-typed-id
+```
+
+With Pydantic support:
+
+```bash
+pip install "base-typed-id[pydantic]"
+```
+
+## Basic usage
+
+```python
+from base_typed_id import BaseTypedId
+
+
+class UserId(BaseTypedId):
+    pass
+
+
+user_id: UserId = UserId("123e4567-e89b-42d3-a456-426614174000")
+generated_user_id: UserId = UserId()
+
+assert type(user_id) is UserId
+assert isinstance(user_id, str)
+```
+
+## UUID version control
+
+By default, `BaseTypedId` expects UUID v4.
+
+```python
+from base_typed_id import BaseTypedId
+
+
+class ExternalEventId(BaseTypedId):
+    uuid_version = 5
+```
+
+`uuid_version = None` disables version restriction.
+
+## Pydantic v2
+
+```python
+from pydantic import BaseModel
+
+from base_typed_id import BaseTypedId
+
+
+class UserId(BaseTypedId):
+    pass
+
+
+class UserModel(BaseModel):
+    user_id: UserId
+```
+
+Behavior:
+
+* inside model: exact subtype is preserved
+* after `model_dump()` / `model_dump_json()`: plain string is exported
+* generated schema keeps `type: string` and `format: uuid`
+
+## Deterministic identifiers
+
+```python
+from base_typed_id import BaseTypedId
+from base_typed_id.factories import deterministically_from_words
+
+
+class ExternalEventId(BaseTypedId):
+    uuid_version = 5
+
+
+event_id: ExternalEventId = deterministically_from_words(
+    ExternalEventId,
+    words=[
+        "workspace:house-of-ai",
+        "provider:telegram",
+        "event:message-created",
+        "message:42",
+    ],
+)
+```
+
+Rules:
+
+* same words -> same identifier
+* order matters
+* deterministic generation requires `uuid_version = 5` or `uuid_version = None`
+
+## Guarantees
+
+* exact subtype is preserved in runtime objects
+* exact subtype is preserved in containers
+* exact subtype is preserved through pickle roundtrip
+* serialized/exported representation is plain string
+
+## Non-goals
+
+* no extra domain behavior beyond typed identity
+* no automatic semantic validation beyond UUID parsing/version checks

base_typed_id-0.1.0/pyproject.toml

@@ -0,0 +1,143 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "base-typed-id"
+version = "0.1.0"
+description = "Strict typed UUID identifier base class with exact runtime subtype preservation and optional Pydantic v2 support."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    { name = "Eldeniz Guseinli", email = "eldenizfamilyanskicode@gmail.com" },
+]
+license = "MIT"
+keywords = [
+    "typing",
+    "uuid",
+    "typed-id",
+    "value-object",
+    "pydantic",
+    "domain-model",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+pydantic = [
+    "pydantic>=2.6,<3",
+]
+test = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "pydantic>=2.6,<3",
+]
+lint = [
+    "ruff>=0.5",
+]
+typecheck = [
+    "mypy>=1.10",
+    "pyright>=1.1",
+    "pydantic>=2.6,<3",
+]
+build = [
+    "build>=1.2",
+    "twine>=5.1",
+]
+dev = [
+    "build>=1.2",
+    "twine>=5.1",
+    "mypy>=1.10",
+    "pyright>=1.1",
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.5",
+    "pydantic>=2.6,<3",
+]
+
+[project.urls]
+Homepage = "https://github.com/eldenizfamilyanskicode/base-typed-id"
+Repository = "https://github.com/eldenizfamilyanskicode/base-typed-id"
+Issues = "https://github.com/eldenizfamilyanskicode/base-typed-id/issues"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["base_typed_id*"]
+
+[tool.setuptools.package-data]
+base_typed_id = ["py.typed"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = [
+    "--strict-config",
+    "--strict-markers",
+    "--cov=base_typed_id",
+    "--cov-report=term-missing",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["base_typed_id"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+fail_under = 100
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["base_typed_id"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.mypy]
+python_version = "3.10"
+mypy_path = "src"
+strict = true
+disallow_untyped_defs = true
+check_untyped_defs = true
+warn_redundant_casts = true
+warn_unused_configs = true
+warn_return_any = true
+strict_equality = true
+no_implicit_optional = true
+allow_redefinition = false
+show_error_codes = true
+packages = ["base_typed_id"]
+
+[tool.pyright]
+pythonVersion = "3.10"
+typeCheckingMode = "strict"
+include = ["src", "tests"]
+exclude = [
+    "**/.*",
+    "**/__pycache__/**",
+    "venv/**",
+    ".venv/**",
+    "**/node_modules/**",
+]

base_typed_id-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

base_typed_id-0.1.0/src/base_typed_id/__init__.py

@@ -0,0 +1,15 @@
+from ._base_typed_id import BaseTypedId
+from ._exceptions import (
+    BaseTypedIdError,
+    BaseTypedIdInvalidInputValueError,
+    BaseTypedIdInvariantViolationError,
+)
+from .factories import deterministically_from_words
+
+__all__ = [
+    "BaseTypedId",
+    "BaseTypedIdError",
+    "BaseTypedIdInvalidInputValueError",
+    "BaseTypedIdInvariantViolationError",
+    "deterministically_from_words",
+]

base_typed_id-0.1.0/src/base_typed_id/_base_typed_id.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+from typing import Any, ClassVar, Literal, TypeVar
+from uuid import UUID, uuid4
+
+from ._exceptions import (
+    BaseTypedIdInvalidInputValueError,
+    BaseTypedIdInvariantViolationError,
+)
+
+BaseTypedIdType = TypeVar(
+    "BaseTypedIdType",
+    bound="BaseTypedId",
+)
+
+
+class BaseTypedId(str):
+    """
+    Transparent domain-typed identifier based on UUID.
+
+    Design rules:
+    - stores an exact runtime subtype
+    - serializes as plain str
+    - preserves subtype in containers, pickle, and Pydantic model fields
+    - uses native pydantic-core uuid schema for OpenAPI format "uuid"
+    - defaults to UUID v4 and auto-generates on None
+    """
+
+    __slots__ = ()
+
+    uuid_version: ClassVar[Literal[1, 3, 4, 5, 6, 7, 8] | None] = 4
+
+    def __new__(
+        cls: type[BaseTypedIdType],
+        value: str | UUID | None = None,
+    ) -> BaseTypedIdType:
+        parsed_uuid_value: UUID = cls._parse_uuid_value(value=value)
+        cls._validate_uuid_version(parsed_uuid_value=parsed_uuid_value)
+        return str.__new__(cls, str(parsed_uuid_value))
+
+    @classmethod
+    def _parse_uuid_value(
+        cls,
+        value: str | UUID | None,
+    ) -> UUID:
+        if value is None:
+            if cls.uuid_version not in (None, 4):
+                raise BaseTypedIdInvalidInputValueError(
+                    f"{cls.__name__} cannot auto-generate from None when "
+                    f"uuid_version is {cls.uuid_version!r}. "
+                    "Provide an explicit UUID value."
+                )
+            return uuid4()
+
+        if isinstance(value, UUID):
+            return value
+
+        # Runtime guard is intentional because the library is callable from untyped code
+        if not isinstance(value, str):  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise BaseTypedIdInvalidInputValueError(
+                "BaseTypedId must be initialized with None, str, or uuid.UUID. "
+                f"Got: {type(value).__name__}."
+            )
+
+        try:
+            return UUID(value)
+        except ValueError as validation_error:
+            raise BaseTypedIdInvalidInputValueError(
+                "BaseTypedId must be initialized with a valid UUID string. "
+                f"Got: {value!r}."
+            ) from validation_error
+
+    @classmethod
+    def _validate_uuid_version(
+        cls,
+        parsed_uuid_value: UUID,
+    ) -> None:
+        expecteduuid_version: int | None = cls.uuid_version
+        if expecteduuid_version is None:
+            return
+
+        actual_uuid_version: int | None = parsed_uuid_value.version
+        if actual_uuid_version != expecteduuid_version:
+            raise BaseTypedIdInvalidInputValueError(
+                f"{cls.__name__} expects UUID v{expecteduuid_version}. "
+                f"Got UUID v{actual_uuid_version}: {parsed_uuid_value}."
+            )
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({str(self)!r})"
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls,
+        source_type: Any,
+        handler: Any,
+    ) -> Any:
+        """
+        Provide Pydantic v2 validation and serialization.
+
+        Validation:
+        - accepts UUID objects
+        - accepts strict UUID strings
+        - rejects bytes and other non-declared runtime inputs
+        - returns the exact subclass instance
+
+        Serialization:
+        - serializes as plain str in both python and json dump modes
+
+        Schema:
+        - uses native uuid schema for JSON/OpenAPI, so format stays `uuid`
+        """
+        del source_type
+        del handler
+
+        try:
+            from pydantic_core import core_schema
+        except ImportError as import_error:  # pragma: no cover
+            raise BaseTypedIdInvariantViolationError(
+                "pydantic-core is required to build BaseTypedId schema."
+            ) from import_error
+
+        def serialize_to_plain_string(value: BaseTypedId) -> str:
+            return str(value)
+
+        python_input_schema = core_schema.union_schema(
+            [
+                core_schema.is_instance_schema(UUID),
+                core_schema.str_schema(strict=True),
+            ]
+        )
+
+        json_input_schema = core_schema.uuid_schema(version=cls.uuid_version)
+
+        return core_schema.json_or_python_schema(
+            json_schema=core_schema.no_info_after_validator_function(
+                cls,
+                json_input_schema,
+            ),
+            python_schema=core_schema.no_info_after_validator_function(
+                cls,
+                python_input_schema,
+            ),
+            serialization=core_schema.plain_serializer_function_ser_schema(
+                serialize_to_plain_string,
+                return_schema=core_schema.str_schema(),
+            ),
+        )
+
+    def __reduce__(
+        self,
+    ) -> tuple[type[BaseTypedId], tuple[str]]:
+        return (self.__class__, (str(self),))

base_typed_id-0.1.0/src/base_typed_id/_exceptions.py

@@ -0,0 +1,10 @@
+class BaseTypedIdError(Exception):
+    """Root exception for all base_typed_id errors."""
+
+
+class BaseTypedIdInvalidInputValueError(BaseTypedIdError, ValueError):
+    """Raised when an invalid input value is provided."""
+
+
+class BaseTypedIdInvariantViolationError(BaseTypedIdError):
+    """Raised when an internal invariant or contract is violated."""

base_typed_id-0.1.0/src/base_typed_id/factories.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from typing import TypeVar
+from uuid import UUID, uuid5
+
+from ._base_typed_id import BaseTypedId
+from ._exceptions import (
+    BaseTypedIdInvalidInputValueError,
+    BaseTypedIdInvariantViolationError,
+)
+
+BaseTypedIdType = TypeVar("BaseTypedIdType", bound=BaseTypedId)
+
+_DEFAULT_DETERMINISTIC_NAMESPACE: UUID = UUID("0b8d2f0f-5c07-4fd9-a7d3-2c9d9d7c0f52")
+
+
+def deterministically_from_words(
+    typed_id_type: type[BaseTypedIdType],
+    *,
+    words: Iterable[str],
+) -> BaseTypedIdType:
+    """
+    Build a stable typed identifier from ordered semantic words.
+
+    Rules:
+    - same words -> same identifier
+    - order matters
+    - words are serialized as canonical JSON before UUID v5 generation
+
+    Important:
+    - intended only for idempotent identifiers
+    - requires `uuid_version = 5` or `uuid_version = None`
+    """
+    # Runtime guard is intentional because the library is callable from untyped code.
+    if not isinstance(typed_id_type, type) or not issubclass(  # pyright: ignore[reportUnnecessaryIsInstance]
+        typed_id_type,
+        BaseTypedId,
+    ):
+        raise BaseTypedIdInvalidInputValueError(
+            "typed_id_type must inherit from BaseTypedId."
+        )
+
+    expected_uuid_version: int | None = typed_id_type.uuid_version
+    if expected_uuid_version not in (None, 5):
+        raise BaseTypedIdInvariantViolationError(
+            "deterministically_from_words requires a BaseTypedId subclass with "
+            "uuid_version = 5 or uuid_version = None."
+        )
+
+    normalized_words: list[str] = []
+    for word in words:
+        # Runtime guard is intentional because the library is callable from untyped code
+        if not isinstance(word, str):  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise BaseTypedIdInvalidInputValueError(
+                "deterministically_from_words accepts only str items in words. "
+                f"Got: {type(word).__name__}."
+            )
+        normalized_words.append(word)
+
+    if len(normalized_words) == 0:
+        raise BaseTypedIdInvalidInputValueError(
+            "deterministically_from_words requires at least one word."
+        )
+
+    canonical_payload: str = json.dumps(
+        normalized_words,
+        ensure_ascii=False,
+        separators=(",", ":"),
+    )
+    deterministic_uuid_value: UUID = uuid5(
+        _DEFAULT_DETERMINISTIC_NAMESPACE,
+        canonical_payload,
+    )
+    return typed_id_type(deterministic_uuid_value)

base_typed_id-0.1.0/src/base_typed_id.egg-info/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: base-typed-id
+Version: 0.1.0
+Summary: Strict typed UUID identifier base class with exact runtime subtype preservation and optional Pydantic v2 support.
+Author-email: Eldeniz Guseinli <eldenizfamilyanskicode@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/eldenizfamilyanskicode/base-typed-id
+Project-URL: Repository, https://github.com/eldenizfamilyanskicode/base-typed-id
+Project-URL: Issues, https://github.com/eldenizfamilyanskicode/base-typed-id/issues
+Keywords: typing,uuid,typed-id,value-object,pydantic,domain-model
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pydantic
+Requires-Dist: pydantic<3,>=2.6; extra == "pydantic"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Requires-Dist: pydantic<3,>=2.6; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff>=0.5; extra == "lint"
+Provides-Extra: typecheck
+Requires-Dist: mypy>=1.10; extra == "typecheck"
+Requires-Dist: pyright>=1.1; extra == "typecheck"
+Requires-Dist: pydantic<3,>=2.6; extra == "typecheck"
+Provides-Extra: build
+Requires-Dist: build>=1.2; extra == "build"
+Requires-Dist: twine>=5.1; extra == "build"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pyright>=1.1; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: pydantic<3,>=2.6; extra == "dev"
+Dynamic: license-file
+
+# base-typed-id
+
+Strict typed UUID identifier base class with exact runtime subtype preservation and optional Pydantic v2 support.
+
+## Why
+
+`BaseTypedId` lets you define domain-specific UUID-backed string subtypes such as `UserId`, `OrderId`, or `ExternalEventId`.
+
+Goals:
+
+- exact runtime subtype preservation
+- plain `str` compatibility
+- plain string serialization
+- pickle roundtrip support
+- Pydantic v2 support
+- OpenAPI `format: uuid`
+
+## Why not `NewType`, `Annotated[str, ...]`, or wrapper value objects?
+
+There are several ways to model typed identifiers in Python. This library focuses on one specific trade-off: keeping a domain-specific runtime subtype while staying fully compatible with plain `str`.
+
+### Why not `typing.NewType`?
+
+`NewType` is excellent when you only need a static type distinction for type checkers.
+
+However, at runtime a `NewType` value is still just a plain `str`. It does not:
+
+- preserve an exact runtime subtype
+- validate UUID format on construction
+- provide subtype-preserving pickle behavior
+- integrate as a real runtime subtype inside containers and model fields
+
+Use `NewType` when static typing alone is enough.
+
+### Why not `Annotated[str, ...]`?
+
+`Annotated` is useful for attaching metadata to a type, especially for validators and frameworks.
+
+But it still does not create a distinct runtime type. If you need runtime identity such as `type(user_id) is UserId`, `Annotated[str, ...]` is not enough.
+
+### Why not wrapper value objects?
+
+A wrapper class such as `UserId(value: str)` gives a stronger domain boundary and is often a good choice in rich domain models.
+
+The trade-off is interoperability friction:
+
+- it is no longer a plain string
+- JSON serialization usually needs custom handling
+- dictionary key compatibility is less transparent
+- many integrations require explicit `.value` extraction
+
+Use a wrapper when you want additional domain behavior beyond typed identity.
+
+### What this library optimizes for
+
+`BaseTypedId` is for the narrower case where you want all of the following at once:
+
+- exact runtime subtype preservation
+- plain `str` compatibility
+- UUID parsing and version checks at the boundary
+- plain string serialization
+- Pydantic v2 / OpenAPI compatibility
+- pickle roundtrip support
+
+## When not to use this library
+
+This library is not the best fit if:
+
+- static-only type distinction is enough for you (`NewType` may be simpler)
+- you want rich domain behavior on the identifier itself (a wrapper value object may be better)
+- your identifiers are not UUID-based
+
+## Installation
+
+```bash
+pip install base-typed-id
+```
+
+With Pydantic support:
+
+```bash
+pip install "base-typed-id[pydantic]"
+```
+
+## Basic usage
+
+```python
+from base_typed_id import BaseTypedId
+
+
+class UserId(BaseTypedId):
+    pass
+
+
+user_id: UserId = UserId("123e4567-e89b-42d3-a456-426614174000")
+generated_user_id: UserId = UserId()
+
+assert type(user_id) is UserId
+assert isinstance(user_id, str)
+```
+
+## UUID version control
+
+By default, `BaseTypedId` expects UUID v4.
+
+```python
+from base_typed_id import BaseTypedId
+
+
+class ExternalEventId(BaseTypedId):
+    uuid_version = 5
+```
+
+`uuid_version = None` disables version restriction.
+
+## Pydantic v2
+
+```python
+from pydantic import BaseModel
+
+from base_typed_id import BaseTypedId
+
+
+class UserId(BaseTypedId):
+    pass
+
+
+class UserModel(BaseModel):
+    user_id: UserId
+```
+
+Behavior:
+
+* inside model: exact subtype is preserved
+* after `model_dump()` / `model_dump_json()`: plain string is exported
+* generated schema keeps `type: string` and `format: uuid`
+
+## Deterministic identifiers
+
+```python
+from base_typed_id import BaseTypedId
+from base_typed_id.factories import deterministically_from_words
+
+
+class ExternalEventId(BaseTypedId):
+    uuid_version = 5
+
+
+event_id: ExternalEventId = deterministically_from_words(
+    ExternalEventId,
+    words=[
+        "workspace:house-of-ai",
+        "provider:telegram",
+        "event:message-created",
+        "message:42",
+    ],
+)
+```
+
+Rules:
+
+* same words -> same identifier
+* order matters
+* deterministic generation requires `uuid_version = 5` or `uuid_version = None`
+
+## Guarantees
+
+* exact subtype is preserved in runtime objects
+* exact subtype is preserved in containers
+* exact subtype is preserved through pickle roundtrip
+* serialized/exported representation is plain string
+
+## Non-goals
+
+* no extra domain behavior beyond typed identity
+* no automatic semantic validation beyond UUID parsing/version checks

base_typed_id-0.1.0/src/base_typed_id.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/base_typed_id/__init__.py
+src/base_typed_id/_base_typed_id.py
+src/base_typed_id/_exceptions.py
+src/base_typed_id/factories.py
+src/base_typed_id/py.typed
+src/base_typed_id.egg-info/PKG-INFO
+src/base_typed_id.egg-info/SOURCES.txt
+src/base_typed_id.egg-info/dependency_links.txt
+src/base_typed_id.egg-info/requires.txt
+src/base_typed_id.egg-info/top_level.txt
+tests/test_base_typed_id.py
+tests/test_factories.py
+tests/test_pickle_roundtrip.py
+tests/test_pydantic_integration.py

base_typed_id-0.1.0/src/base_typed_id.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

base_typed_id-0.1.0/src/base_typed_id.egg-info/requires.txt

@@ -0,0 +1,30 @@
+
+[build]
+build>=1.2
+twine>=5.1
+
+[dev]
+build>=1.2
+twine>=5.1
+mypy>=1.10
+pyright>=1.1
+pytest>=8.0
+pytest-cov>=5.0
+ruff>=0.5
+pydantic<3,>=2.6
+
+[lint]
+ruff>=0.5
+
+[pydantic]
+pydantic<3,>=2.6
+
+[test]
+pytest>=8.0
+pytest-cov>=5.0
+pydantic<3,>=2.6
+
+[typecheck]
+mypy>=1.10
+pyright>=1.1
+pydantic<3,>=2.6

base_typed_id-0.1.0/src/base_typed_id.egg-info/top_level.txt

@@ -0,0 +1 @@
+base_typed_id

base_typed_id-0.1.0/tests/test_base_typed_id.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from uuid import UUID
+
+import pytest
+
+from base_typed_id import BaseTypedId
+from base_typed_id import BaseTypedIdInvalidInputValueError
+
+
+class UserId(BaseTypedId):
+    pass
+
+
+class ExternalEventId(BaseTypedId):
+    uuid_version = 5
+
+
+def test_none_generates_uuid_v4_typed_id() -> None:
+    generated_user_id: UserId = UserId()
+    parsed_uuid_value: UUID = UUID(str(generated_user_id))
+
+    assert type(generated_user_id) is UserId
+    assert parsed_uuid_value.version == 4
+
+
+def test_string_input_preserves_exact_subtype() -> None:
+    raw_uuid_string: str = "123e4567-e89b-42d3-a456-426614174000"
+
+    user_id: UserId = UserId(raw_uuid_string)
+
+    assert type(user_id) is UserId
+    assert user_id == raw_uuid_string
+
+
+def test_uuid_input_preserves_exact_subtype() -> None:
+    raw_uuid_value: UUID = UUID("123e4567-e89b-42d3-a456-426614174000")
+
+    user_id: UserId = UserId(raw_uuid_value)
+
+    assert type(user_id) is UserId
+    assert user_id == str(raw_uuid_value)
+
+
+def test_invalid_uuid_string_raises_error() -> None:
+    with pytest.raises(BaseTypedIdInvalidInputValueError):
+        UserId("not-a-uuid")
+
+
+def test_unsupported_input_type_raises_error() -> None:
+    with pytest.raises(BaseTypedIdInvalidInputValueError):
+        UserId(123)  # type: ignore[arg-type]
+
+
+def testuuid_version_mismatch_raises_error() -> None:
+    with pytest.raises(BaseTypedIdInvalidInputValueError):
+        UserId("123e4567-e89b-52d3-a456-426614174000")
+
+
+def test_non_v4_subclass_cannot_auto_generate_from_none() -> None:
+    with pytest.raises(BaseTypedIdInvalidInputValueError):
+        ExternalEventId()
+
+
+def test_normal_string_operations_return_plain_str() -> None:
+    user_id: UserId = UserId("123e4567-e89b-42d3-a456-426614174000")
+
+    uppercased_value: str = user_id.upper()
+    concatenated_value: str = user_id + "_debug"
+
+    assert type(uppercased_value) is str
+    assert type(concatenated_value) is str
+
+
+def test_repr_contains_exact_subtype_name() -> None:
+    user_id: UserId = UserId("123e4567-e89b-42d3-a456-426614174000")
+
+    assert repr(user_id) == "UserId('123e4567-e89b-42d3-a456-426614174000')"

base_typed_id-0.1.0/tests/test_factories.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from base_typed_id import (
+    BaseTypedId,
+    BaseTypedIdInvalidInputValueError,
+    BaseTypedIdInvariantViolationError,
+)
+from base_typed_id.factories import deterministically_from_words
+
+
+class StableEventId(BaseTypedId):
+    uuid_version = 5
+
+
+class FlexibleEventId(BaseTypedId):
+    uuid_version = None
+
+
+class UserId(BaseTypedId):
+    pass
+
+
+def test_same_words_produce_same_typed_id() -> None:
+    first_event_id: StableEventId = deterministically_from_words(
+        StableEventId,
+        words=["workspace", "provider", "message", "42"],
+    )
+    second_event_id: StableEventId = deterministically_from_words(
+        StableEventId,
+        words=["workspace", "provider", "message", "42"],
+    )
+
+    assert type(first_event_id) is StableEventId
+    assert type(second_event_id) is StableEventId
+    assert first_event_id == second_event_id
+
+
+def test_word_order_changes_identifier() -> None:
+    first_event_id: StableEventId = deterministically_from_words(
+        StableEventId,
+        words=["workspace", "provider", "message", "42"],
+    )
+    second_event_id: StableEventId = deterministically_from_words(
+        StableEventId,
+        words=["42", "message", "provider", "workspace"],
+    )
+
+    assert first_event_id != second_event_id
+
+
+def test_factory_supports_version_agnostic_subclass() -> None:
+    flexible_event_id: FlexibleEventId = deterministically_from_words(
+        FlexibleEventId,
+        words=["workspace", "provider", "message", "42"],
+    )
+
+    assert type(flexible_event_id) is FlexibleEventId
+
+
+def test_factory_rejects_version_four_subclass() -> None:
+    with pytest.raises(BaseTypedIdInvariantViolationError):
+        deterministically_from_words(
+            UserId,
+            words=["workspace", "provider", "message", "42"],
+        )
+
+
+def test_factory_rejects_empty_words() -> None:
+    with pytest.raises(BaseTypedIdInvalidInputValueError):
+        deterministically_from_words(
+            StableEventId,
+            words=[],
+        )
+
+
+def test_factory_rejects_non_string_words() -> None:
+    with pytest.raises(BaseTypedIdInvalidInputValueError):
+        deterministically_from_words(
+            StableEventId,
+            words=["workspace", "provider", 42],  # type: ignore[list-item]
+        )
+
+
+def test_deterministically_from_words_rejects_non_type_typed_id_type() -> None:
+    invalid_typed_id_type: Any = "UserId"
+
+    with pytest.raises(
+        BaseTypedIdInvalidInputValueError,
+        match="typed_id_type must inherit from BaseTypedId.",
+    ):
+        deterministically_from_words(
+            invalid_typed_id_type,
+            words=["workspace:house-of-ai"],
+        )

base_typed_id-0.1.0/tests/test_pickle_roundtrip.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import pickle
+
+from base_typed_id import BaseTypedId
+
+
+class UserId(BaseTypedId):
+    pass
+
+
+def test_pickle_roundtrip_preserves_exact_subtype() -> None:
+    source_user_id: UserId = UserId("123e4567-e89b-42d3-a456-426614174000")
+
+    serialized_user_id: bytes = pickle.dumps(source_user_id)
+    restored_user_id: object = pickle.loads(serialized_user_id)
+
+    assert restored_user_id == "123e4567-e89b-42d3-a456-426614174000"
+    assert type(restored_user_id) is UserId
+    assert isinstance(restored_user_id, str)
+    assert isinstance(restored_user_id, UserId)

base_typed_id-0.1.0/tests/test_pydantic_integration.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import json
+
+import pytest
+from pydantic import BaseModel, Field, ValidationError
+
+from base_typed_id import BaseTypedId
+
+
+class UserId(BaseTypedId):
+    pass
+
+
+class UserModel(BaseModel):
+    user_id: UserId
+
+
+class GeneratedUserModel(BaseModel):
+    user_id: UserId = Field(default_factory=UserId)
+
+
+def test_model_validation_builds_exact_subtype() -> None:
+    user_model: UserModel = UserModel.model_validate(
+        {"user_id": "123e4567-e89b-42d3-a456-426614174000"}
+    )
+
+    assert type(user_model.user_id) is UserId
+
+
+def test_model_dump_flattens_to_plain_string() -> None:
+    user_model: UserModel = UserModel.model_validate(
+        {"user_id": "123e4567-e89b-42d3-a456-426614174000"}
+    )
+
+    dumped_python: dict[str, object] = user_model.model_dump()
+
+    assert type(dumped_python["user_id"]) is str
+    assert dumped_python["user_id"] == "123e4567-e89b-42d3-a456-426614174000"
+
+
+def test_model_dump_json_flattens_to_plain_string() -> None:
+    user_model: UserModel = UserModel.model_validate(
+        {"user_id": "123e4567-e89b-42d3-a456-426614174000"}
+    )
+
+    dumped_json: str = user_model.model_dump_json()
+    loaded_json_payload: dict[str, object] = json.loads(dumped_json)
+
+    assert type(loaded_json_payload["user_id"]) is str
+    assert loaded_json_payload["user_id"] == "123e4567-e89b-42d3-a456-426614174000"
+
+
+def test_model_validate_from_dump_reconstructs_exact_subtype() -> None:
+    source_model: UserModel = UserModel.model_validate(
+        {"user_id": "123e4567-e89b-42d3-a456-426614174000"}
+    )
+    dumped_python: dict[str, object] = source_model.model_dump()
+
+    restored_model: UserModel = UserModel.model_validate(dumped_python)
+
+    assert type(restored_model.user_id) is UserId
+
+
+def test_json_schema_uses_native_uuid_format() -> None:
+    json_schema: dict[str, object] = UserModel.model_json_schema()
+    properties_schema: dict[str, object] = json_schema["properties"]  # type: ignore[assignment]
+    user_id_schema: dict[str, object] = properties_schema["user_id"]  # type: ignore[assignment]
+
+    assert user_id_schema["type"] == "string"
+    assert user_id_schema["format"] == "uuid"
+
+
+def test_default_factory_generates_typed_id() -> None:
+    generated_user_model: GeneratedUserModel = GeneratedUserModel.model_validate({})
+
+    assert type(generated_user_model.user_id) is UserId
+
+
+def test_none_is_rejected_for_required_field() -> None:
+    with pytest.raises(ValidationError):
+        UserModel.model_validate({"user_id": None})