uplid 1.0.1__tar.gz → 1.1.1__tar.gz

uplid-1.1.1/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: uplid
+Version: 1.1.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
+
+```
+██╗   ██╗██████╗ ██╗     ██╗██████╗
+██║   ██║██╔══██╗██║     ██║██╔══██╗
+██║   ██║██████╔╝██║     ██║██║  ██║
+██║   ██║██╔═══╝ ██║     ██║██║  ██║
+╚██████╔╝██║     ███████╗██║██████╔╝
+ ╚═════╝ ╚═╝     ╚══════╝╚═╝╚═════╝
+```
+
+**Stripe-style IDs for Python.**
+
+```python
+# Before: WTF is this?
+"550e8400-e29b-41d4-a716-446655440000"
+
+# After: It's a user.
+"usr_0M3xL9kQ7vR2nP5wY1jZ4c"
+```
+
+[![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/)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/zvsdev/uplid)
+
+## Install
+
+```bash
+pip install uplid
+```
+
+Requires Python 3.14+ and Pydantic 2.10+.
+
+## Quick Start
+
+```python
+>>> from uplid import UPLID
+>>> UPLID.generate("usr")
+usr_0M3xL9kQ7vR2nP5wY1jZ4c
+>>> UPLID.generate("ord")
+ord_7x9KmNpQrStUvWxYz012Ab
+```
+
+## Why UPLID?
+
+**Debuggable** - See `usr_` in your logs and instantly know it's a user, not an order, not a session, not a mystery.
+
+```
+# Your logs now:
+"User usr_0M3xL9kQ7vR2nP5wY1jZ4c created order ord_1a2B3c4D5e6F7g..."
+
+# vs the nightmare:
+"User 550e8400-e29b-41d4... created order 7c9e6679-7425-40de..."
+```
+
+**Type-safe** - Your type checker catches `user_id = order_id` mistakes before they hit production.
+
+```python
+UserId = UPLID[Literal["usr"]]
+OrgId = UPLID[Literal["org"]]
+
+def get_user(user_id: UserId) -> User: ...
+
+get_user(org_id)  # Type error! Caught by mypy/pyright/ty
+```
+
+**Time-sortable** - Built on UUIDv7. Sort by ID = sort by creation time. No extra column needed.
+
+**URL-safe** - 26 characters, no special characters, no encoding. `usr_0M3xL9kQ7vR2nP5wY1jZ4c`
+
+**Minimal dependencies** - Just Pydantic. UUID generation uses Python 3.14's stdlib `uuid7()`.
+
+> Inspired by Stripe's prefixed IDs (`sk_live_...`, `cus_...`, `pi_...`) - the same pattern trusted by millions of API calls daily.
+
+## Pydantic Integration
+
+```python
+from typing import Literal
+from pydantic import BaseModel, Field
+from uplid import UPLID, factory
+
+UserId = UPLID[Literal["usr"]]
+
+class User(BaseModel):
+    id: UserId = Field(default_factory=factory(UserId))
+    name: str
+
+user = User(name="Alice")
+user.model_dump()  # {"id": "usr_0M3xL9kQ7vR2nP5wY1jZ4c", "name": "Alice"}
+
+User(id="org_xxx...", name="Bad")  # ValidationError: wrong prefix
+```
+
+## FastAPI Integration
+
+```python
+from typing import Annotated, Literal
+from fastapi import Depends, FastAPI, HTTPException
+from uplid import UPLID, UPLIDError, parse
+
+UserId = UPLID[Literal["usr"]]
+parse_user_id = parse(UserId)
+
+def validate_user_id(user_id: str) -> UserId:
+    try:
+        return parse_user_id(user_id)
+    except UPLIDError as e:
+        raise HTTPException(422, str(e)) from None
+
+@app.get("/users/{user_id}")
+def get_user(user_id: Annotated[UserId, Depends(validate_user_id)]) -> User:
+    ...  # user_id is validated and typed
+```
+
+## SQLAlchemy Integration
+
+```python
+from uplid import UPLID, factory
+from uplid.sqlalchemy import uplid_column
+
+UserId = UPLID[Literal["usr"]]
+
+class User(Base):
+    __tablename__ = "users"
+    id: Mapped[UserId] = uplid_column(UserId, primary_key=True)
+    name: Mapped[str]
+
+# Stores as TEXT, returns as UPLID objects
+user = session.execute(select(User)).scalar_one()
+user.id.prefix    # "usr"
+user.id.datetime  # When the ID was created
+```
+
+## SQLModel Integration
+
+```python
+from uplid import UPLID, factory
+from uplid.sqlalchemy import uplid_field
+
+UserId = UPLID[Literal["usr"]]
+
+class User(SQLModel, table=True):
+    id: UserId = uplid_field(UserId, default_factory=factory(UserId), primary_key=True)
+    name: str
+
+user.model_dump()  # {"id": "usr_...", "name": "Alice"} - Pydantic just works
+```
+
+## Prefix Rules
+
+Prefixes must be snake_case: lowercase letters and single underscores, cannot start/end with underscore, max 64 characters.
+
+Examples: `usr`, `api_key`, `org_member`, `sk_live`
+
+## API Reference
+
+### `UPLID[PREFIX]`
+
+```python
+uid = UPLID.generate("usr")                              # Generate new
+uid = UPLID.from_string("usr_0M3xL9kQ7vR2nP5wY1jZ4c", "usr")  # Parse
+
+uid.prefix      # "usr"
+uid.uid         # UUID object
+uid.base62_uid  # "0M3xL9kQ7vR2nP5wY1jZ4c"
+uid.datetime    # When created (from UUIDv7)
+uid.timestamp   # Unix timestamp
+```
+
+### `factory(UPLIDType)` / `parse(UPLIDType)`
+
+```python
+UserId = UPLID[Literal["usr"]]
+UserIdFactory = factory(UserId)  # For Pydantic default_factory
+parse_user_id = parse(UserId)    # For manual parsing, raises UPLIDError
+```
+
+### `UPLIDType`
+
+Protocol for functions accepting any UPLID:
+
+```python
+def log_entity(id: UPLIDType) -> None:
+    print(f"{id.prefix} created at {id.datetime}")
+```
+
+### `uplid_column` / `uplid_field`
+
+```python
+from uplid.sqlalchemy import uplid_column, uplid_field
+
+# SQLAlchemy
+id: Mapped[UserId] = uplid_column(UserId, primary_key=True)
+
+# SQLModel
+id: UserId = uplid_field(UserId, default_factory=factory(UserId), primary_key=True)
+```
+
+## License
+
+MIT

uplid-1.1.1/README.md

@@ -0,0 +1,202 @@
+# UPLID
+
+```
+██╗   ██╗██████╗ ██╗     ██╗██████╗
+██║   ██║██╔══██╗██║     ██║██╔══██╗
+██║   ██║██████╔╝██║     ██║██║  ██║
+██║   ██║██╔═══╝ ██║     ██║██║  ██║
+╚██████╔╝██║     ███████╗██║██████╔╝
+ ╚═════╝ ╚═╝     ╚══════╝╚═╝╚═════╝
+```
+
+**Stripe-style IDs for Python.**
+
+```python
+# Before: WTF is this?
+"550e8400-e29b-41d4-a716-446655440000"
+
+# After: It's a user.
+"usr_0M3xL9kQ7vR2nP5wY1jZ4c"
+```
+
+[![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/)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/zvsdev/uplid)
+
+## Install
+
+```bash
+pip install uplid
+```
+
+Requires Python 3.14+ and Pydantic 2.10+.
+
+## Quick Start
+
+```python
+>>> from uplid import UPLID
+>>> UPLID.generate("usr")
+usr_0M3xL9kQ7vR2nP5wY1jZ4c
+>>> UPLID.generate("ord")
+ord_7x9KmNpQrStUvWxYz012Ab
+```
+
+## Why UPLID?
+
+**Debuggable** - See `usr_` in your logs and instantly know it's a user, not an order, not a session, not a mystery.
+
+```
+# Your logs now:
+"User usr_0M3xL9kQ7vR2nP5wY1jZ4c created order ord_1a2B3c4D5e6F7g..."
+
+# vs the nightmare:
+"User 550e8400-e29b-41d4... created order 7c9e6679-7425-40de..."
+```
+
+**Type-safe** - Your type checker catches `user_id = order_id` mistakes before they hit production.
+
+```python
+UserId = UPLID[Literal["usr"]]
+OrgId = UPLID[Literal["org"]]
+
+def get_user(user_id: UserId) -> User: ...
+
+get_user(org_id)  # Type error! Caught by mypy/pyright/ty
+```
+
+**Time-sortable** - Built on UUIDv7. Sort by ID = sort by creation time. No extra column needed.
+
+**URL-safe** - 26 characters, no special characters, no encoding. `usr_0M3xL9kQ7vR2nP5wY1jZ4c`
+
+**Minimal dependencies** - Just Pydantic. UUID generation uses Python 3.14's stdlib `uuid7()`.
+
+> Inspired by Stripe's prefixed IDs (`sk_live_...`, `cus_...`, `pi_...`) - the same pattern trusted by millions of API calls daily.
+
+## Pydantic Integration
+
+```python
+from typing import Literal
+from pydantic import BaseModel, Field
+from uplid import UPLID, factory
+
+UserId = UPLID[Literal["usr"]]
+
+class User(BaseModel):
+    id: UserId = Field(default_factory=factory(UserId))
+    name: str
+
+user = User(name="Alice")
+user.model_dump()  # {"id": "usr_0M3xL9kQ7vR2nP5wY1jZ4c", "name": "Alice"}
+
+User(id="org_xxx...", name="Bad")  # ValidationError: wrong prefix
+```
+
+## FastAPI Integration
+
+```python
+from typing import Annotated, Literal
+from fastapi import Depends, FastAPI, HTTPException
+from uplid import UPLID, UPLIDError, parse
+
+UserId = UPLID[Literal["usr"]]
+parse_user_id = parse(UserId)
+
+def validate_user_id(user_id: str) -> UserId:
+    try:
+        return parse_user_id(user_id)
+    except UPLIDError as e:
+        raise HTTPException(422, str(e)) from None
+
+@app.get("/users/{user_id}")
+def get_user(user_id: Annotated[UserId, Depends(validate_user_id)]) -> User:
+    ...  # user_id is validated and typed
+```
+
+## SQLAlchemy Integration
+
+```python
+from uplid import UPLID, factory
+from uplid.sqlalchemy import uplid_column
+
+UserId = UPLID[Literal["usr"]]
+
+class User(Base):
+    __tablename__ = "users"
+    id: Mapped[UserId] = uplid_column(UserId, primary_key=True)
+    name: Mapped[str]
+
+# Stores as TEXT, returns as UPLID objects
+user = session.execute(select(User)).scalar_one()
+user.id.prefix    # "usr"
+user.id.datetime  # When the ID was created
+```
+
+## SQLModel Integration
+
+```python
+from uplid import UPLID, factory
+from uplid.sqlalchemy import uplid_field
+
+UserId = UPLID[Literal["usr"]]
+
+class User(SQLModel, table=True):
+    id: UserId = uplid_field(UserId, default_factory=factory(UserId), primary_key=True)
+    name: str
+
+user.model_dump()  # {"id": "usr_...", "name": "Alice"} - Pydantic just works
+```
+
+## Prefix Rules
+
+Prefixes must be snake_case: lowercase letters and single underscores, cannot start/end with underscore, max 64 characters.
+
+Examples: `usr`, `api_key`, `org_member`, `sk_live`
+
+## API Reference
+
+### `UPLID[PREFIX]`
+
+```python
+uid = UPLID.generate("usr")                              # Generate new
+uid = UPLID.from_string("usr_0M3xL9kQ7vR2nP5wY1jZ4c", "usr")  # Parse
+
+uid.prefix      # "usr"
+uid.uid         # UUID object
+uid.base62_uid  # "0M3xL9kQ7vR2nP5wY1jZ4c"
+uid.datetime    # When created (from UUIDv7)
+uid.timestamp   # Unix timestamp
+```
+
+### `factory(UPLIDType)` / `parse(UPLIDType)`
+
+```python
+UserId = UPLID[Literal["usr"]]
+UserIdFactory = factory(UserId)  # For Pydantic default_factory
+parse_user_id = parse(UserId)    # For manual parsing, raises UPLIDError
+```
+
+### `UPLIDType`
+
+Protocol for functions accepting any UPLID:
+
+```python
+def log_entity(id: UPLIDType) -> None:
+    print(f"{id.prefix} created at {id.datetime}")
+```
+
+### `uplid_column` / `uplid_field`
+
+```python
+from uplid.sqlalchemy import uplid_column, uplid_field
+
+# SQLAlchemy
+id: Mapped[UserId] = uplid_column(UserId, primary_key=True)
+
+# SQLModel
+id: UserId = uplid_field(UserId, default_factory=factory(UserId), primary_key=True)
+```
+
+## License
+
+MIT

{uplid-1.0.1 → uplid-1.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uplid"
-version = "1.0.1"
+version = "1.1.1"
 description = "Universal Prefixed Literal IDs - type-safe, human-readable identifiers"
 authors = [{ name = "ZVS", email = "zvs@daswolf.dev" }]
 readme = "README.md"
@@ -36,6 +36,7 @@ dev = [
     "fastapi>=0.115,<1",
     "httpx>=0.28,<1",
     "sqlalchemy>=2.0,<3",
+    "sqlmodel>=0.0.22,<1",
 ]
 
 [tool.ruff]
@@ -72,7 +73,7 @@ python-version = "3.14"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-addopts = ["--cov=uplid", "--cov-report=term-missing", "--cov-fail-under=95"]
+addopts = ["--cov=uplid", "--cov-report=term-missing", "--cov-fail-under=100"]
 
 [tool.coverage.run]
 branch = true

uplid-1.1.1/src/uplid/__init__.py

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

uplid-1.1.1/src/uplid/sqlalchemy.py

@@ -0,0 +1,205 @@
+"""SQLAlchemy integration for UPLID.
+
+Provides a TypeDecorator and helper for using UPLIDs as typed columns
+that store as TEXT in the database.
+
+Example:
+    from typing import Literal
+    from sqlalchemy.orm import DeclarativeBase, Mapped
+    from uplid import UPLID
+    from uplid.sqlalchemy import uplid_column
+
+    UserId = UPLID[Literal["usr"]]
+    OrgId = UPLID[Literal["org"]]
+
+    class Base(DeclarativeBase):
+        pass
+
+    class User(Base):
+        __tablename__ = "users"
+
+        id: Mapped[UserId] = uplid_column(UserId, primary_key=True)
+        org_id: Mapped[OrgId | None] = uplid_column(OrgId)
+        name: Mapped[str]
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, TypedDict, Unpack, cast
+
+from sqlalchemy import Text
+from sqlalchemy.orm import mapped_column
+from sqlalchemy.types import TypeDecorator
+
+from uplid import UPLID, UPLIDError, UPLIDType, _get_prefix
+
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from sqlalchemy.engine import Dialect
+    from sqlalchemy.orm import MappedColumn
+
+
+class UPLIDColumnKwargs(TypedDict, total=False):
+    """Keyword arguments for uplid_column, matching mapped_column's common options."""
+
+    primary_key: bool
+    nullable: bool
+    default: object
+    default_factory: Callable[[], object]
+    index: bool
+    unique: bool
+    insert_default: object
+    onupdate: object
+
+
+class UPLIDColumn(TypeDecorator[UPLIDType]):
+    """SQLAlchemy TypeDecorator for UPLID storage as TEXT.
+
+    Automatically serializes UPLID objects to strings on write
+    and deserializes back to UPLID objects on read.
+
+    Args:
+        prefix: The expected prefix for UPLIDs in this column.
+
+    Example:
+        id: Mapped[UserId] = mapped_column(UPLIDColumn("usr"), primary_key=True)
+    """
+
+    impl = Text
+    cache_ok = True
+
+    def __init__(self, prefix: str) -> None:
+        """Initialize with the expected UPLID prefix."""
+        self.prefix = prefix
+        super().__init__()
+
+    def process_bind_param(
+        self,
+        value: UPLIDType | str | None,
+        dialect: Dialect,  # noqa: ARG002
+    ) -> str | None:
+        """Convert UPLID to string for database storage.
+
+        Validates that strings have the correct prefix before storing.
+        This catches prefix mismatches at write time rather than read time.
+        """
+        if value is None:
+            return None
+        if isinstance(value, UPLIDType):
+            if value.prefix != self.prefix:
+                msg = f"Expected prefix {self.prefix!r}, got {value.prefix!r}"
+                raise ValueError(msg)
+            return str(value)
+        # Validate string format and prefix before storing
+        if isinstance(value, str):
+            UPLID.from_string(value, self.prefix)  # Raises UPLIDError if invalid
+            return value
+        return value  # pragma: no cover
+
+    def process_result_value(
+        self,
+        value: str | None,
+        dialect: Dialect,  # noqa: ARG002
+    ) -> UPLIDType | None:
+        """Convert database string to UPLID object."""
+        if value is None:
+            return None
+        return UPLID.from_string(value, self.prefix)
+
+
+def _extract_prefix[T](uplid_type: type[T]) -> str:
+    """Extract prefix from a parameterized UPLID type like UPLID[Literal["usr"]].
+
+    Wraps _get_prefix to convert UPLIDError to TypeError for SQLAlchemy context.
+    """
+    try:
+        return _get_prefix(uplid_type)  # type: ignore[arg-type]
+    except UPLIDError as e:
+        raise TypeError(str(e)) from e
+
+
+def uplid_column[T](
+    uplid_type: type[T],
+    **kwargs: Unpack[UPLIDColumnKwargs],
+) -> MappedColumn[T]:
+    """Create a mapped_column for a UPLID type (pure SQLAlchemy).
+
+    Infers the prefix from the type parameter, so you don't need to
+    specify it twice.
+
+    Args:
+        uplid_type: A parameterized UPLID type like UPLID[Literal["usr"]].
+        **kwargs: Additional arguments passed to mapped_column.
+            Supports: primary_key, nullable, default, default_factory,
+            index, unique, insert_default, onupdate.
+
+    Returns:
+        A mapped_column configured with the appropriate UPLIDColumn.
+
+    Example:
+        UserId = UPLID[Literal["usr"]]
+        OrgId = UPLID[Literal["org"]]
+
+        class User(Base):
+            __tablename__ = "users"
+
+            id: Mapped[UserId] = uplid_column(UserId, primary_key=True)
+            org_id: Mapped[OrgId | None] = uplid_column(OrgId)
+    """
+    prefix = _extract_prefix(uplid_type)
+    return mapped_column(UPLIDColumn(prefix), **kwargs)
+
+
+class UPLIDFieldKwargs(TypedDict, total=False):
+    """Keyword arguments for uplid_field, matching SQLModel Field's common options."""
+
+    default: object
+    default_factory: Callable[[], object]
+    primary_key: bool
+    nullable: bool
+    index: bool
+    unique: bool
+
+
+def uplid_field[T](
+    uplid_type: type[T],
+    **kwargs: Unpack[UPLIDFieldKwargs],
+) -> Any:  # noqa: ANN401 - return type matches SQLModel's Field
+    """Create a SQLModel Field for a UPLID type.
+
+    Infers the prefix from the type parameter and configures sa_type
+    automatically.
+
+    Args:
+        uplid_type: A parameterized UPLID type like UPLID[Literal["usr"]].
+        **kwargs: Additional arguments passed to Field.
+            Supports: default, default_factory, primary_key, index, unique.
+
+    Returns:
+        A SQLModel Field configured with the appropriate UPLIDColumn.
+
+    Example:
+        from sqlmodel import SQLModel
+        from uplid import UPLID, factory
+        from uplid.sqlalchemy import uplid_field
+
+        UserId = UPLID[Literal["usr"]]
+        UserIdFactory = factory(UserId)
+
+        class User(SQLModel, table=True):
+            id: UserId = uplid_field(UserId, default_factory=UserIdFactory, primary_key=True)
+            org_id: OrgId | None = uplid_field(OrgId, default=None)
+    """
+    # Import here to avoid hard dependency on sqlmodel
+    from sqlmodel import Field
+
+    prefix = _extract_prefix(uplid_type)
+    # SQLModel's sa_type is incorrectly typed as type[Any] but accepts TypeEngine instances.
+    # Use cast to satisfy the type checker until SQLModel fixes their stubs.
+    sa_type = cast("type[Any]", UPLIDColumn(prefix))
+    return Field(sa_type=sa_type, **kwargs)
+
+
+__all__ = ["UPLIDColumn", "uplid_column", "uplid_field"]

{uplid-1.0.1 → uplid-1.1.1}/src/uplid/uplid.py

@@ -7,7 +7,6 @@ from datetime import UTC
 from datetime import datetime as dt_datetime
 from typing import (
     TYPE_CHECKING,
-    Any,
     LiteralString,
     Protocol,
     Self,
@@ -234,24 +233,28 @@ class UPLID[PREFIX: LiteralString]:
     def __lt__(self, other: object) -> bool:
         """Compare for sorting (by prefix, then by uid)."""
         if isinstance(other, UPLID):
+            # type: ignore needed because UUID comparison is not recognized by type checkers
             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):
+            # type: ignore needed because UUID comparison is not recognized by type checkers
             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):
+            # type: ignore needed because UUID comparison is not recognized by type checkers
             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):
+            # type: ignore needed because UUID comparison is not recognized by type checkers
             return (self._prefix, self._uid) >= (other._prefix, other._uid)  # type: ignore[operator]
         return NotImplemented
 
@@ -259,7 +262,7 @@ class UPLID[PREFIX: LiteralString]:
         """Return self (UPLIDs are immutable)."""
         return self
 
-    def __deepcopy__(self, memo: dict[int, Any]) -> Self:
+    def __deepcopy__(self, memo: object) -> Self:
         """Return self (UPLIDs are immutable)."""
         return self
 
@@ -282,6 +285,14 @@ class UPLID[PREFIX: LiteralString]:
             UPLIDError: If the prefix is not valid snake_case.
         """
         _validate_prefix(prefix)
+        return cls._generate_unchecked(prefix)
+
+    @classmethod
+    def _generate_unchecked(cls, prefix: PREFIX) -> Self:
+        """Generate a new UPLID without validating the prefix.
+
+        Internal method for use when prefix has already been validated.
+        """
         instance = cls.__new__(cls)
         instance._prefix = prefix  # noqa: SLF001
         instance._uid = uuid7()  # noqa: SLF001
@@ -339,8 +350,8 @@ class UPLID[PREFIX: LiteralString]:
     @classmethod
     def __get_pydantic_core_schema__(
         cls,
-        source_type: Any,  # noqa: ANN401
-        handler: Any,  # noqa: ANN401
+        source_type: type[Self],
+        handler: object,
     ) -> CoreSchema:
         """Pydantic integration for validation and serialization.
 
@@ -371,7 +382,7 @@ class UPLID[PREFIX: LiteralString]:
 
         prefix_str: str = prefix_args[0]
 
-        def validate(v: UPLID[Any] | str) -> UPLID[Any]:
+        def validate(v: UPLIDType | str) -> UPLIDType:
             if isinstance(v, str):
                 return cls.from_string(v, prefix_str)
             if isinstance(v, UPLID):
@@ -421,9 +432,10 @@ def factory[PREFIX: LiteralString](
             id: UserId = Field(default_factory=factory(UserId))
     """
     prefix = _get_prefix(uplid_type)
+    _validate_prefix(prefix)  # Validate once at factory creation
 
     def _factory() -> UPLID[PREFIX]:
-        return UPLID.generate(prefix)
+        return UPLID._generate_unchecked(prefix)  # noqa: SLF001
 
     return _factory
 

uplid-1.0.1/PKG-INFO

@@ -1,296 +0,0 @@
-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/README.md

@@ -1,275 +0,0 @@
-# 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/src/uplid/__init__.py

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