uplid 0.0.4__py3-none-any.whl → 1.0.1__py3-none-any.whl

uplid/__init__.py

@@ -1,4 +1,8 @@
-from .uplid import UPLID, factory
+"""Universal Prefixed Literal IDs - type-safe, human-readable identifiers."""
 
-__version__ = "0.0.4"
-__all__ = ["UPLID", "factory"]
+from __future__ import annotations
+
+from uplid.uplid import UPLID, UPLIDError, UPLIDType, factory, parse
+
+
+__all__ = ["UPLID", "UPLIDError", "UPLIDType", "factory", "parse"]

uplid/uplid.py

@@ -1,206 +1,453 @@
-from datetime import datetime as Datetime
-from typing import Any, Callable, Generic, Type, TypeVar, Union, get_args, get_origin
+"""Universal Prefixed Literal IDs - type-safe, human-readable identifiers."""
 
-from ksuid import KsuidMs
-from pydantic import GetCoreSchemaHandler, ValidationError
-from pydantic_core import CoreSchema, PydanticCustomError, core_schema
-from typing_extensions import LiteralString, Self
+from __future__ import annotations
 
-PREFIX = TypeVar("PREFIX", bound=LiteralString)
+import re
+from datetime import UTC
+from datetime import datetime as dt_datetime
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    LiteralString,
+    Protocol,
+    Self,
+    get_args,
+    get_origin,
+    runtime_checkable,
+)
+from uuid import UUID, uuid7
 
+from pydantic_core import CoreSchema, core_schema
 
-class UPLID(Generic[PREFIX]):
+
+if TYPE_CHECKING:
+    import datetime as dt
+    from collections.abc import Callable
+
+
+# Base62 encoding: 0-9, A-Z, a-z (62 characters)
+# IMPORTANT: '0' must be first character for zfill padding to work correctly
+_BASE62_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+_BASE62_DECODE_MAP = {c: i for i, c in enumerate(_BASE62_ALPHABET)}
+
+# A 128-bit UUID requires ceiling(128 / log2(62)) = 22 base62 characters
+_BASE62_UUID_LENGTH = 22
+
+# UUIDv7 timestamp extraction (RFC 9562):
+# Bits 0-47 contain 48-bit Unix timestamp in milliseconds
+_UUIDV7_TIMESTAMP_SHIFT = 80  # 128 - 48 = shift to extract timestamp
+_MS_PER_SECOND = 1000
+
+# Prefix validation: snake_case (lowercase letters and single underscores)
+# - Must start and end with a letter
+# - Cannot have consecutive underscores
+# - Single character prefixes are allowed
+# - Maximum 64 characters to prevent DoS via regex on huge inputs
+_PREFIX_PATTERN = re.compile(r"^[a-z]([a-z]*(_[a-z]+)*)?$")
+_PREFIX_MAX_LENGTH = 64
+
+
+class UPLIDError(ValueError):
+    """Raised when UPLID parsing or validation fails."""
+
+
+@runtime_checkable
+class UPLIDType(Protocol):
+    """Protocol for any UPLID, useful for generic function signatures.
+
+    Example:
+        def log_entity(entity_id: UPLIDType) -> None:
+            print(f"{entity_id.prefix} created at {entity_id.datetime}")
     """
-    A class representing an ID with a prefixed lteral string identifier. The UID portion is managed using the KSUID
-    format encoded via base62.
 
-    Attributes:
-        prefix (PREFIX): A string literal prefix for the ID. Can be specified as a type param or infered from args
-        uid (KsuidMs): The KsuidMs object representing the unique identifier.
+    __slots__ = ()
 
-    Methods:
-        from_string(string: str, prefix: PREFIX): Class method to create an instance of PrefixedId from a
-            base62 string representation.
-        generate(prefix: PREFIX): Class method to generate a new PrefixedId with a given prefix, optionally can be generated
-        for a specific datetime.
+    @property
+    def prefix(self) -> str:
+        """The prefix identifier (e.g., 'usr', 'api_key')."""
+        ...
+
+    @property
+    def uid(self) -> UUID:
+        """The underlying UUIDv7."""
+        ...
+
+    @property
+    def datetime(self) -> dt.datetime:
+        """The timestamp extracted from the UUIDv7."""
+        ...
+
+    @property
+    def timestamp(self) -> float:
+        """The Unix timestamp (seconds) from the UUIDv7."""
+        ...
+
+    @property
+    def base62_uid(self) -> str:
+        """The base62-encoded UID (22 characters)."""
+        ...
+
+    def __str__(self) -> str:
+        """String representation as '<prefix>_<base62uid>'."""
+        ...
+
+
+def _int_to_base62(num: int) -> str:
+    """Convert integer to base62 string, padded to 22 chars for UUIDv7."""
+    if num == 0:
+        return "0" * _BASE62_UUID_LENGTH
+
+    result: list[str] = []
+    while num > 0:
+        num, remainder = divmod(num, 62)
+        result.append(_BASE62_ALPHABET[remainder])
+
+    return "".join(reversed(result)).zfill(_BASE62_UUID_LENGTH)
+
+
+def _base62_to_int(s: str) -> int:
+    """Convert base62 string to integer.
+
+    Raises:
+        ValueError: If input exceeds expected UUID length.
+        KeyError: If input contains invalid base62 characters.
+    """
+    if len(s) > _BASE62_UUID_LENGTH:
+        raise ValueError(f"Input exceeds maximum length of {_BASE62_UUID_LENGTH}")
+    result = 0
+    for char in s:
+        result = result * 62 + _BASE62_DECODE_MAP[char]
+    return result
+
+
+def _validate_prefix(prefix: str) -> None:
+    """Validate that prefix follows snake_case rules.
 
     Raises:
-        ValueError: If the string representation does not conform to the expected format, if prefix
-            contains non-alphabetic characters, is not lowercase, or does not match the expected prefix.
+        UPLIDError: If prefix is invalid.
+    """
+    if len(prefix) > _PREFIX_MAX_LENGTH:
+        raise UPLIDError(
+            f"Prefix must be at most {_PREFIX_MAX_LENGTH} characters, got {len(prefix)}"
+        )
+    if not _PREFIX_PATTERN.match(prefix):
+        raise UPLIDError(
+            f"Prefix must be snake_case (lowercase letters, single underscores, "
+            f"cannot start/end with underscore or have consecutive underscores), "
+            f"got {prefix!r}"
+        )
+
+
+class UPLID[PREFIX: LiteralString]:
+    """Universal Prefixed Literal ID with type-safe prefix validation.
+
+    A UPLID combines a string prefix (like 'usr', 'api_key') with a UUIDv7,
+    encoded in base62 for compactness. The prefix enables runtime and static
+    type checking to prevent mixing IDs from different domains.
+
+    Example:
+        >>> from typing import Literal
+        >>> UserId = UPLID[Literal["usr"]]
+        >>> user_id = UPLID.generate("usr")
+        >>> print(user_id)  # usr_1a2B3c4D5e6F7g8H9i0J1k
 
     Note:
-        This class requires a literal string as a type parameter for PREFIX. It integrates with Pydantic
-        for validation and serialization purposes.
+        The `datetime` and `timestamp` properties assume the underlying UUID
+        is a valid UUIDv7. If you construct a UPLID with a non-UUIDv7 UUID
+        (e.g., UUIDv4), these properties will return meaningless values.
     """
 
-    prefix: PREFIX
-    uid: KsuidMs
+    __slots__ = ("_base62_uid", "_prefix", "_uid")
 
-    def __init__(self, prefix: PREFIX, uid: Union[str, KsuidMs]) -> None:
-        self.prefix = prefix
-        if isinstance(uid, str):
-            self.uid = self._validate_uid(uid)
-        else:
-            self.uid = uid
+    def __init__(self, prefix: PREFIX, uid: UUID) -> None:
+        """Initialize a UPLID with a prefix and UUID.
 
-    def __repr__(self) -> str:
-        return str(self)
+        Args:
+            prefix: The string prefix (must be snake_case).
+            uid: The UUID (should be UUIDv7 for datetime/timestamp to be meaningful).
 
-    def __str__(self) -> str:
-        return f"{self.prefix}_{self.uid}"
-
-    def __eq__(self, other: Any) -> bool:
-        if isinstance(other, self.__class__):
-            return self.prefix == other.prefix and self.uid == other.uid
-        return False
-
-    def __gt__(self, other: Self) -> bool:
-        if isinstance(other, self.__class__):
-            if self.prefix == other.prefix:
-                return self.uid > other.uid
-            return self.prefix > other.prefix
-        raise TypeError(f"Cannot compare {self.__class__} with {other.__class__}")
-
-    def __lt__(self, other: Self) -> bool:
-        if isinstance(other, self.__class__):
-            if self.prefix == other.prefix:
-                return self.uid < other.uid
-            return self.prefix < other.prefix
-        raise TypeError(f"Cannot compare {self.__class__} with {other.__class__}")
-
-    def __gte__(self, other: Self) -> bool:
-        if isinstance(other, self.__class__):
-            if self == other:
-                return True
-            return self > other
-        raise TypeError(f"Cannot compare {self.__class__} with {other.__class__}")
-
-    def __lte__(self, other: Self) -> bool:
-        if isinstance(other, self.__class__):
-            if self == other:
-                return True
-            return self < other
-        raise TypeError(f"Cannot compare {self.__class__} with {other.__class__}")
-
-    @staticmethod
-    def _validate_uid(v: str) -> KsuidMs:
-        if len(v) != 27:
-            raise ValueError(f"Expected encoded_uid to be 27 characters long, got {len(v)}")
-        try:
-            return KsuidMs.from_base62(v)
-        except OverflowError as e:
-            raise ValueError(f"Invalid encoded_uid: {v}") from e
+        Raises:
+            UPLIDError: If prefix is not valid snake_case.
+        """
+        _validate_prefix(prefix)
+        self._prefix = prefix
+        self._uid = uid
+        self._base62_uid: str | None = None
 
     @property
-    def datetime(self) -> Datetime:
-        return self.uid.datetime
+    def prefix(self) -> PREFIX:
+        """The prefix identifier (e.g., 'usr', 'api_key')."""
+        return self._prefix
+
+    @property
+    def uid(self) -> UUID:
+        """The underlying UUID (typically UUIDv7)."""
+        return self._uid
+
+    @property
+    def base62_uid(self) -> str:
+        """The base62-encoded UID (22 characters)."""
+        if self._base62_uid is None:
+            self._base62_uid = _int_to_base62(self._uid.int)
+        return self._base62_uid
+
+    @property
+    def datetime(self) -> dt_datetime:
+        """The timestamp extracted from the UUIDv7.
+
+        Note:
+            This assumes the UUID is a valid UUIDv7. For non-UUIDv7 UUIDs,
+            the returned datetime will be meaningless.
+        """
+        ms = self._uid.int >> _UUIDV7_TIMESTAMP_SHIFT
+        return dt_datetime.fromtimestamp(ms / _MS_PER_SECOND, tz=UTC)
 
     @property
     def timestamp(self) -> float:
-        return self.uid.timestamp
+        """The Unix timestamp (seconds) from the UUIDv7.
+
+        Note:
+            This assumes the UUID is a valid UUIDv7. For non-UUIDv7 UUIDs,
+            the returned timestamp will be meaningless.
+        """
+        ms = self._uid.int >> _UUIDV7_TIMESTAMP_SHIFT
+        return ms / _MS_PER_SECOND
+
+    def __str__(self) -> str:
+        """Return the string representation as '<prefix>_<base62uid>'."""
+        return f"{self._prefix}_{self.base62_uid}"
+
+    def __repr__(self) -> str:
+        """Return a detailed representation."""
+        return f"UPLID({self._prefix!r}, {self.base62_uid!r})"
+
+    def __hash__(self) -> int:
+        """Return hash for use in sets and dict keys."""
+        return hash((self._prefix, self._uid))
+
+    def __eq__(self, other: object) -> bool:
+        """Check equality with another UPLID."""
+        if isinstance(other, UPLID):
+            return self._prefix == other._prefix and self._uid == other._uid
+        return NotImplemented
+
+    def __lt__(self, other: object) -> bool:
+        """Compare for sorting (by prefix, then by uid)."""
+        if isinstance(other, UPLID):
+            return (self._prefix, self._uid) < (other._prefix, other._uid)  # type: ignore[operator]
+        return NotImplemented
+
+    def __le__(self, other: object) -> bool:
+        """Compare for sorting (by prefix, then by uid)."""
+        if isinstance(other, UPLID):
+            return (self._prefix, self._uid) <= (other._prefix, other._uid)  # type: ignore[operator]
+        return NotImplemented
+
+    def __gt__(self, other: object) -> bool:
+        """Compare for sorting (by prefix, then by uid)."""
+        if isinstance(other, UPLID):
+            return (self._prefix, self._uid) > (other._prefix, other._uid)  # type: ignore[operator]
+        return NotImplemented
+
+    def __ge__(self, other: object) -> bool:
+        """Compare for sorting (by prefix, then by uid)."""
+        if isinstance(other, UPLID):
+            return (self._prefix, self._uid) >= (other._prefix, other._uid)  # type: ignore[operator]
+        return NotImplemented
+
+    def __copy__(self) -> Self:
+        """Return self (UPLIDs are immutable)."""
+        return self
+
+    def __deepcopy__(self, memo: dict[int, Any]) -> Self:
+        """Return self (UPLIDs are immutable)."""
+        return self
+
+    def __reduce__(self) -> tuple[type[Self], tuple[str, UUID]]:
+        """Support pickling for multiprocessing, caching, etc."""
+        return (type(self), (self._prefix, self._uid))
+
+    @classmethod
+    def generate(cls, prefix: PREFIX) -> Self:
+        """Generate a new UPLID with the given prefix.
+
+        Args:
+            prefix: The string prefix (must be snake_case: lowercase letters
+                and single underscores, cannot start/end with underscore).
+
+        Returns:
+            A new UPLID instance.
+
+        Raises:
+            UPLIDError: If the prefix is not valid snake_case.
+        """
+        _validate_prefix(prefix)
+        instance = cls.__new__(cls)
+        instance._prefix = prefix  # noqa: SLF001
+        instance._uid = uuid7()  # noqa: SLF001
+        instance._base62_uid = None  # noqa: SLF001
+        return instance
 
     @classmethod
     def from_string(cls, string: str, prefix: PREFIX) -> Self:
-        split_content = string.split("_")
-        if len(split_content) != 2:
-            raise ValueError(
-                f"Prefixed Id Strings must be of the form <prefix>_<uid>, received {string}"
+        """Parse a UPLID from its string representation.
+
+        Args:
+            string: The string to parse (format: '<prefix>_<base62uid>').
+            prefix: The expected prefix.
+
+        Returns:
+            A UPLID instance.
+
+        Raises:
+            UPLIDError: If the string format is invalid or prefix doesn't match.
+
+        Note:
+            This method does not validate that the decoded UUID is a valid
+            UUIDv7. The datetime/timestamp properties may return meaningless
+            values if the original ID was not created with a UUIDv7.
+        """
+        if "_" not in string:
+            raise UPLIDError(f"UPLID must be in format '<prefix>_<uid>', got {string!r}")
+
+        last_underscore = string.rfind("_")
+        parsed_prefix = string[:last_underscore]
+        encoded_uid = string[last_underscore + 1 :]
+
+        _validate_prefix(parsed_prefix)
+
+        if parsed_prefix != prefix:
+            raise UPLIDError(f"Expected prefix {prefix!r}, got {parsed_prefix!r}")
+
+        if len(encoded_uid) != _BASE62_UUID_LENGTH:
+            raise UPLIDError(
+                f"UID must be {_BASE62_UUID_LENGTH} characters, got {len(encoded_uid)}"
             )
-        _prefix, encoded_uid = split_content
-        if not _prefix.isalpha():
-            raise ValueError(f"Prefix can only contain alphabetic characters, got {_prefix}")
-        if not _prefix.islower():
-            raise ValueError(f"Prefix must be lowercase, got {_prefix}")
-        if _prefix != prefix:
-            raise ValueError(f"Expected prefix to be {prefix}, got {_prefix}")
-        if not encoded_uid:
-            raise ValueError("Expected encoded_uid to be a non-empty string")
-        uid = cls._validate_uid(encoded_uid)
-        return cls(prefix, uid)
 
-    @classmethod
-    def generate(cls, prefix: PREFIX, at: Union[Datetime, None] = None) -> Self:
-        return cls(prefix, KsuidMs(at))
+        try:
+            uid_int = _base62_to_int(encoded_uid)
+            uid = UUID(int=uid_int)
+        except (KeyError, ValueError) as e:
+            raise UPLIDError(f"Invalid base62 UID: {encoded_uid!r}") from e
+
+        instance = cls.__new__(cls)
+        instance._prefix = prefix  # noqa: SLF001
+        instance._uid = uid  # noqa: SLF001
+        instance._base62_uid = encoded_uid  # noqa: SLF001
+        return instance
 
     @classmethod
     def __get_pydantic_core_schema__(
-        cls, source_type: Any, handler: GetCoreSchemaHandler
+        cls,
+        source_type: Any,  # noqa: ANN401
+        handler: Any,  # noqa: ANN401
     ) -> CoreSchema:
+        """Pydantic integration for validation and serialization.
+
+        Note:
+            This method accesses typing internals (__args__, __value__) which
+            may change between Python versions. Integration tests should verify
+            compatibility with supported Python versions.
+        """
         origin = get_origin(source_type)
-        if origin is None:  # used as `x: PrefixId` without params
-            raise RuntimeError("PrefixId must be used with a prefix literal string")
-        prefix_str_type = get_args(source_type)[0]
-        type_args = get_args(prefix_str_type)
-        if not type_args:  # When prefix is a TypeVar
-            prefix_str_type = prefix_str_type.__value__
-            prefix_str = prefix_str_type.__args__[0]
-        else:
-            prefix_str = type_args[0]
-
-        if not prefix_str:
-            raise RuntimeError(f"Expected prefix to be a literal string, got {prefix_str_type}")
-
-        def val_str(v: str) -> UPLID[PREFIX]:
-            try:
-                prefixed_id = cls.from_string(v, prefix_str)
-            except ValueError as e:
-                raise AssertionError(e) from e
-            return prefixed_id
-
-        def val_prefix(v: Union[UPLID[PREFIX], str]) -> UPLID[PREFIX]:
+        if origin is None:
+            raise UPLIDError(
+                "UPLID must be parameterized with a prefix literal, e.g. UPLID[Literal['usr']]"
+            )
+
+        args = get_args(source_type)
+        if not args:  # pragma: no cover
+            raise UPLIDError("UPLID requires a Literal prefix type argument")
+
+        prefix_type = args[0]
+        prefix_args = get_args(prefix_type)
+
+        # Handle TypeVar case (Python 3.12+ type parameter syntax)
+        if not prefix_args:  # pragma: no cover
+            if hasattr(prefix_type, "__value__"):
+                prefix_args = get_args(prefix_type.__value__)
+            if not prefix_args:
+                raise UPLIDError(f"Could not extract prefix from {prefix_type}")
+
+        prefix_str: str = prefix_args[0]
+
+        def validate(v: UPLID[Any] | str) -> UPLID[Any]:
             if isinstance(v, str):
-                v = val_str(v)
-            if v.prefix == prefix_str:
+                return cls.from_string(v, prefix_str)
+            if isinstance(v, UPLID):
+                if v.prefix != prefix_str:
+                    raise UPLIDError(f"Expected prefix {prefix_str!r}, got {v.prefix!r}")
                 return v
-            raise AssertionError(f"Expected id to have prefix {prefix_str}, got {v.prefix}")
+            raise UPLIDError(f"Expected UPLID or str, got {type(v).__name__}")
 
-        python_schema = core_schema.chain_schema(
-            [
-                core_schema.no_info_plain_validator_function(val_prefix),
-            ]
-        )
         return core_schema.json_or_python_schema(
             json_schema=core_schema.chain_schema(
                 [
                     core_schema.str_schema(),
-                    core_schema.no_info_before_validator_function(val_str, python_schema),
+                    core_schema.no_info_plain_validator_function(validate),
                 ]
             ),
-            python_schema=python_schema,
-            serialization=core_schema.plain_serializer_function_ser_schema(lambda x: str(x)),
+            python_schema=core_schema.no_info_plain_validator_function(validate),
+            serialization=core_schema.plain_serializer_function_ser_schema(str),
         )
 
 
-def _get_prefix(uplid_type: Type[UPLID[PREFIX]]) -> PREFIX:
-    literal_type = uplid_type.__args__[0]  # type: ignore
-    return literal_type.__args__[0]  # type: ignore
+def _get_prefix[PREFIX: LiteralString](uplid_type: type[UPLID[PREFIX]]) -> str:
+    """Extract the prefix string from a parameterized UPLID type."""
+    args = get_args(uplid_type)
+    if not args:
+        raise UPLIDError("UPLID type must be parameterized with a Literal prefix")
+    literal_type = args[0]
+    literal_args = get_args(literal_type)
+    # Handle TypeVar case (Python 3.12+ type parameter syntax)
+    if not literal_args and hasattr(literal_type, "__value__"):  # pragma: no cover
+        literal_args = get_args(literal_type.__value__)
+    if not literal_args:  # pragma: no cover
+        raise UPLIDError(f"Could not extract prefix from {literal_type}")
+    return literal_args[0]
+
 
+def factory[PREFIX: LiteralString](
+    uplid_type: type[UPLID[PREFIX]],
+) -> Callable[[], UPLID[PREFIX]]:
+    """Create a factory function for generating new UPLIDs of a specific type.
 
-def factory(uplid_type: Type[UPLID[PREFIX]]) -> Callable[[], UPLID[PREFIX]]:
+    This is useful with Pydantic's Field(default_factory=...).
+
+    Example:
+        UserId = UPLID[Literal["usr"]]
+
+        class User(BaseModel):
+            id: UserId = Field(default_factory=factory(UserId))
+    """
     prefix = _get_prefix(uplid_type)
 
-    def f() -> UPLID[PREFIX]:
+    def _factory() -> UPLID[PREFIX]:
         return UPLID.generate(prefix)
 
-    return f
+    return _factory
 
 
-def validator(uplid_type: Type[UPLID[PREFIX]]) -> Callable[[str], UPLID[PREFIX]]:
-    prefix = _get_prefix(uplid_type)
+def parse[PREFIX: LiteralString](
+    uplid_type: type[UPLID[PREFIX]],
+) -> Callable[[str], UPLID[PREFIX]]:
+    """Create a parse function for converting strings to UPLIDs.
+
+    This is useful for parsing user input outside of Pydantic models.
+    Raises UPLIDError on invalid input.
+
+    Example:
+        UserId = UPLID[Literal["usr"]]
+        parse_user_id = parse(UserId)
 
-    def f(v: str) -> UPLID[PREFIX]:
         try:
-            return UPLID.from_string(v, prefix)
-        except ValueError as e:
-            raise ValidationError.from_exception_data(
-                f"{prefix.capitalize()}Id",
-                [
-                    {
-                        "loc": (f"{prefix}_id",),
-                        "input": v,
-                        "type": PydanticCustomError("value_error", str(e)),
-                    }
-                ],
-            ) from e
-
-    return f
+            user_id = parse_user_id("usr_1a2B3c4D5e6F7g8H9i0J1k")
+        except UPLIDError as e:
+            print(f"Invalid ID: {e}")
+    """
+    prefix = _get_prefix(uplid_type)
+
+    def _parse(v: str) -> UPLID[PREFIX]:
+        return UPLID.from_string(v, prefix)
+
+    return _parse

uplid-1.0.1.dist-info/METADATA

@@ -0,0 +1,296 @@
+Metadata-Version: 2.4
+Name: uplid
+Version: 1.0.1
+Summary: Universal Prefixed Literal IDs - type-safe, human-readable identifiers
+Keywords: uuid,id,identifier,pydantic,type-safe,uuid7
+Author: ZVS
+Author-email: ZVS <zvs@daswolf.dev>
+License-Expression: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.10
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/zvsdev/uplid
+Project-URL: Repository, https://github.com/zvsdev/uplid
+Description-Content-Type: text/markdown
+
+# UPLID
+
+Universal Prefixed Literal IDs - type-safe, human-readable identifiers for Python 3.14+.
+
+[![CI](https://github.com/zvsdev/uplid/actions/workflows/ci.yml/badge.svg)](https://github.com/zvsdev/uplid/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/uplid)](https://pypi.org/project/uplid/)
+[![Python](https://img.shields.io/pypi/pyversions/uplid)](https://pypi.org/project/uplid/)
+
+## Features
+
+- **Type-safe prefixes**: `UPLID[Literal["usr"]]` prevents mixing user IDs with org IDs at compile time
+- **Human-readable**: `usr_0M3xL9kQ7vR2nP5wY1jZ4c` (Stripe-style prefixed IDs)
+- **Time-sortable**: Built on UUIDv7 (RFC 9562) for natural chronological ordering
+- **Compact**: 22-character base62 encoding (URL-safe, no special characters)
+- **Stdlib UUIDs**: Uses Python 3.14's native `uuid7()` - no external UUID libraries
+- **Pydantic 2 native**: Full validation and serialization support
+- **Thread-safe**: ID generation is safe for concurrent use
+
+## Installation
+
+```bash
+pip install uplid
+# or
+uv add uplid
+```
+
+Requires Python 3.14+ and Pydantic 2.10+.
+
+## Quick Start
+
+```python
+from typing import Literal
+from pydantic import BaseModel, Field
+from uplid import UPLID, factory
+
+# Define typed aliases and factories
+UserId = UPLID[Literal["usr"]]
+OrgId = UPLID[Literal["org"]]
+UserIdFactory = factory(UserId)
+
+# Use in Pydantic models
+class User(BaseModel):
+    id: UserId = Field(default_factory=UserIdFactory)
+    org_id: OrgId
+
+# Generate IDs
+user_id = UPLID.generate("usr")
+print(user_id)  # usr_0M3xL9kQ7vR2nP5wY1jZ4c
+
+# Parse from string
+parsed = UPLID.from_string("usr_0M3xL9kQ7vR2nP5wY1jZ4c", "usr")
+
+# Access properties
+print(parsed.datetime)   # 2026-01-30 12:34:56.789000+00:00
+print(parsed.timestamp)  # 1738240496.789
+
+# Type safety - these are compile-time errors:
+# user.org_id = user_id  # Error: UserId is not compatible with OrgId
+```
+
+## Pydantic Serialization
+
+UPLIDs serialize to strings and deserialize with validation:
+
+```python
+from pydantic import BaseModel, Field
+from uplid import UPLID, factory
+
+UserId = UPLID[Literal["usr"]]
+UserIdFactory = factory(UserId)
+
+class User(BaseModel):
+    id: UserId = Field(default_factory=UserIdFactory)
+    name: str
+
+user = User(name="Alice")
+
+# Serialize to dict - ID becomes string
+user.model_dump()
+# {"id": "usr_0M3xL9kQ7vR2nP5wY1jZ4c", "name": "Alice"}
+
+# Serialize to JSON
+json_str = user.model_dump_json()
+
+# Deserialize - validates UPLID format and prefix
+restored = User.model_validate_json(json_str)
+assert restored.id == user.id
+
+# Wrong prefix raises ValidationError
+User(id="org_xxx...", name="Bad")  # ValidationError
+```
+
+## FastAPI Integration
+
+```python
+from typing import Annotated, Literal
+from fastapi import Cookie, Depends, FastAPI, Header, HTTPException
+from pydantic import BaseModel, Field
+from uplid import UPLID, UPLIDError, factory, parse
+
+UserId = UPLID[Literal["usr"]]
+UserIdFactory = factory(UserId)
+parse_user_id = parse(UserId)
+
+
+class User(BaseModel):
+    id: UserId = Field(default_factory=UserIdFactory)
+    name: str
+
+
+app = FastAPI()
+
+
+# Dependency for validating path/query/header/cookie parameters
+def get_user_id(user_id: str) -> UserId:
+    try:
+        return parse_user_id(user_id)
+    except UPLIDError as e:
+        raise HTTPException(422, f"Invalid user ID: {e}") from None
+
+
+# Path parameter validation
+@app.get("/users/{user_id}")
+def get_user(user_id: Annotated[UserId, Depends(get_user_id)]) -> User:
+    ...
+
+
+# JSON body - Pydantic validates UPLID fields automatically
+@app.post("/users")
+def create_user(user: User) -> User:
+    # user.id validated as UserId, wrong prefix returns 422
+    return user
+
+
+# Header validation
+def get_user_id_from_header(x_user_id: Annotated[str, Header()]) -> UserId:
+    try:
+        return parse_user_id(x_user_id)
+    except UPLIDError as e:
+        raise HTTPException(422, f"Invalid X-User-Id header: {e}") from None
+
+
+@app.get("/me")
+def get_current_user(user_id: Annotated[UserId, Depends(get_user_id_from_header)]) -> User:
+    ...
+
+
+# Cookie validation
+def get_session_user(session_user_id: Annotated[str, Cookie()]) -> UserId:
+    try:
+        return parse_user_id(session_user_id)
+    except UPLIDError as e:
+        raise HTTPException(422, f"Invalid session cookie: {e}") from None
+
+
+@app.get("/session")
+def get_session(user_id: Annotated[UserId, Depends(get_session_user)]) -> User:
+    ...
+```
+
+## Database Storage
+
+UPLIDs serialize to strings. Store as `VARCHAR(87)` (64 char prefix + 1 underscore + 22 char base62):
+
+```python
+from typing import Literal
+from sqlalchemy import String, create_engine
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, Session
+from uplid import UPLID, factory
+
+UserId = UPLID[Literal["usr"]]
+UserIdFactory = factory(UserId)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class UserRow(Base):
+    __tablename__ = "users"
+
+    id: Mapped[str] = mapped_column(String(87), primary_key=True)
+    name: Mapped[str] = mapped_column(String(100))
+
+
+# Create with UPLID, store as string
+engine = create_engine("sqlite:///:memory:")
+Base.metadata.create_all(engine)
+
+with Session(engine) as session:
+    user = UserRow(id=str(UPLID.generate("usr")), name="Alice")
+    session.add(user)
+    session.commit()
+
+    # Query and parse back to UPLID
+    row = session.query(UserRow).first()
+    user_id = UPLID.from_string(row.id, "usr")
+    print(user_id.datetime)  # When the ID was created
+```
+
+## Prefix Rules
+
+Prefixes must be snake_case:
+- Lowercase letters and single underscores only
+- Cannot start or end with underscore
+- Maximum 64 characters
+- Examples: `usr`, `api_key`, `org_member`
+
+## API Reference
+
+### `UPLID[PREFIX]`
+
+Generic class for prefixed IDs.
+
+```python
+# Generate new ID
+uid = UPLID.generate("usr")
+
+# Parse from string
+uid = UPLID.from_string("usr_0M3xL9kQ7vR2nP5wY1jZ4c", "usr")
+
+# Properties
+uid.prefix      # str: "usr"
+uid.uid         # UUID: underlying UUIDv7
+uid.base62_uid  # str: 22-char base62 encoding
+uid.datetime    # datetime: UTC timestamp from UUIDv7
+uid.timestamp   # float: Unix timestamp in seconds
+```
+
+### `factory(UPLIDType)`
+
+Creates a factory function for Pydantic's `default_factory`.
+
+```python
+UserId = UPLID[Literal["usr"]]
+UserIdFactory = factory(UserId)
+
+class User(BaseModel):
+    id: UserId = Field(default_factory=UserIdFactory)
+```
+
+### `parse(UPLIDType)`
+
+Creates a parser function that raises `UPLIDError` on invalid input.
+
+```python
+from uplid import UPLID, parse, UPLIDError
+
+UserId = UPLID[Literal["usr"]]
+parse_user_id = parse(UserId)
+
+try:
+    uid = parse_user_id("usr_0M3xL9kQ7vR2nP5wY1jZ4c")
+except UPLIDError as e:
+    print(e)
+```
+
+### `UPLIDType`
+
+Protocol for generic functions accepting any UPLID:
+
+```python
+from uplid import UPLIDType
+
+def log_entity(id: UPLIDType) -> None:
+    print(f"{id.prefix} created at {id.datetime}")
+```
+
+### `UPLIDError`
+
+Exception raised for invalid IDs. Subclasses `ValueError`.
+
+## License
+
+MIT

uplid-1.0.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+uplid/__init__.py,sha256=96PZKnozPOjHfFbWko0jGzynDNcrr6Sm6jPhwAGnQxU,253
+uplid/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+uplid/uplid.py,sha256=krCFV7eFOcFn7KV8R1ko6B9lK37AzcrEJlciMmNvgmA,15108
+uplid-1.0.1.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
+uplid-1.0.1.dist-info/METADATA,sha256=OBp_290PWT_NA2dGPyD5TwBcT60QA5Gdb2myQhHaOG8,7704
+uplid-1.0.1.dist-info/RECORD,,

{uplid-0.0.4.dist-info → uplid-1.0.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 1.8.1
+Generator: uv 0.9.28
 Root-Is-Purelib: true
 Tag: py3-none-any

uplid-0.0.4.dist-info/LICENSE

@@ -1,21 +0,0 @@
-The MIT License (MIT)
-
-Copyright (c) 2024 Zachary V Smith (ZVS)
-
-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.

uplid-0.0.4.dist-info/METADATA

@@ -1,144 +0,0 @@
-Metadata-Version: 2.1
-Name: uplid
-Version: 0.0.4
-Summary: Universal Prefixed Literal Ids, runtime/statically typed via pydanitc, designed for humans
-Home-page: https://github.com/zvsdev/uplid
-License: MIT
-Author: ZVS
-Author-email: zvs@daswolf.dev
-Requires-Python: >=3.9,<4.0
-Classifier: Framework :: Pydantic
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Typing :: Typed
-Requires-Dist: pydantic (>=2.6.0,<3.0.0)
-Requires-Dist: svix-ksuid (==0.6.2)
-Project-URL: Documentation, https://github.com/zvsdev/uplid
-Project-URL: Repository, https://github.com/zvsdev/uplid
-Description-Content-Type: text/markdown
-
-# UPLID - Universal Prefixed Literal Unique Id
-
-A pydantic compatible, human friendly prefixed id.
-
-Uses literal string types to enforce typing at both runtime (via pydantic) and during static analysis.
-
-UIDs underneath are KSUIDs allowing them to be sorted by time of creation while still being collision resistant.
-
-String representations are encoded with base62 keeping them url safe and human friendly.
-
-Python 3.9 or higher and at least pydantic 2.6 are required.
-
-Can be integrated with FastAPI.
-
-## Installation
-
-```
-pip install uplid
-```
-
-## Usage
-
-### With Pydantic
-
-```py
-from uplid import UPLID, factory
-from pydantic import BaseModel, Field
-
-UserId = UPLID[Literal["usr]]
-WorkspaceId = UPLID[Literal["wrkspace"]]
-
-class User(BaseModel):
-  id: UserId = Field(default_factory=factory(UserId))
-  workspace_id: WorkspaceId
-
-user = User(workspace_id = UPLID.generate("wrkspace))
-
-user_json = user.model_dump_json()
-
-restored_user = User.validate_json(user_json)
-```
-
-### Standalone
-
-```py
-from uplid import UPLID, validator, factory
-
-UserId = UPLID[Literal["usr]]
-WorkspaceId = UPLID[Literal['wrkspace']]
-
-UserIdFactory = factory(UserId)
-WorkspaceIdFactory = factory(WorkspaceId)
-
-user_id = UserIdFactory()
-workspace_id = WorkspaceIdFactory()
-
-def foo(bar: UserId) -> None:
-  pass
-
-foo(bar=user_id) # passes static check
-foo(bar=workspace_id) # fails static check
-
-UserIdValidator = validator(UserId)
-
-UserIdValidator(str(workspace_id)) # fails runtime check
-```
-
-### With FastAPI
-
-#### As a Query or Path Param
-
-```py
-from uplid import UPLID, validator
-from fastapi import Request, Response, Depends
-
-UserId = UPLID[Literal["usr]]
-
-async def endpoint(request: Request, user_id: UserId = Depends(validator(UserId))) -> Response:
-  ...
-```
-
-FastAPI depends does not convert pydantic's ValidationError to RequestValidationError if thrown inside of Depends.
-As a workaround, you can add a global catch at the top level, or wrap your own handler around the UPLID validator.
-
-```py
-from fastapi import Request, FastAPI
-from fastapi.exceptions import RequestValidationError
-from pydantic import ValidationError
-
-def handle_validation_error(request: Request, exc: Exception):
-  if isinstance(exc, ValidationError):
-    raise RequestValidationError(errors=exc.errors())
-  raise exc
-
-app = FastAPI()
-app.add_exception_handler(ValidationError, handle_validation_error)
-```
-
-#### As part of a Body
-
-```py
-from uplid import UPLID
-from fastapi import Request, Response
-from pydantic import BaseModel
-
-class UserRequest(BaseModel):
-  user_id: UserId
-
-async def endpoint(request: Request, body: UserRequest) -> Response:
-  ...
-```
-
-## Inspirations
-
-- https://dev.to/stripe/designing-apis-for-humans-object-ids-3o5a
-- https://pypi.org/project/django-charid-field/
-- https://pypi.org/project/django-prefix-id/
-- https://sudhir.io/uuids-ulids
-

uplid-0.0.4.dist-info/RECORD

@@ -1,7 +0,0 @@
-uplid/__init__.py,sha256=xgQbrqK1ZimSsm20GHBNmtbuNHJUVs0kPI-gyZRcsH8,88
-uplid/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-uplid/uplid.py,sha256=8wtD24TdCQ6pGje4HYLzXQ3xXEGbSEigQGxLoksM7SU,7617
-uplid-0.0.4.dist-info/LICENSE,sha256=YStW1Bz6chsLArR4K0O_NpZuLJhLlBInr9zBKD9rQmk,1088
-uplid-0.0.4.dist-info/METADATA,sha256=jR_tZNaNFugESGF1bOmFCMTnpaeevctfDMdPHDJq68k,3807
-uplid-0.0.4.dist-info/WHEEL,sha256=FMvqSimYX_P7y0a7UY-_Mc83r5zkBZsCYPm7Lr0Bsq4,88
-uplid-0.0.4.dist-info/RECORD,,