uplid 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

uplid/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from uplid.uplid import UPLID, UPLIDError, UPLIDType, factory, parse
+from uplid.uplid import UPLID, UPLIDError, UPLIDType, _get_prefix, factory, parse
 
 
-__all__ = ["UPLID", "UPLIDError", "UPLIDType", "factory", "parse"]
+__all__ = ["UPLID", "UPLIDError", "UPLIDType", "_get_prefix", "factory", "parse"]

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/uplid.py

@@ -234,24 +234,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
 
@@ -282,6 +286,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
@@ -421,9 +433,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.1.0.dist-info/METADATA

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: uplid
+Version: 1.1.0
+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.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+uplid/__init__.py,sha256=gtEVlE30N9TrHaTEpinM5t428HT6NzGjMTDq6ABsKMY,281
+uplid/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+uplid/sqlalchemy.py,sha256=FFELyg-7GCUPPiSBncIXSHEkoAaxxoqK1IYvS8Ja5Bg,6311
+uplid/uplid.py,sha256=Gj2sDzOG4vC3HlXoHZzHdhg2ht5stpzE1E15HLS54sg,15844
+uplid-1.1.0.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
+uplid-1.1.0.dist-info/METADATA,sha256=wddvXPWjuXsMr_wX9UDXaB1M8_hqMdkS-HxUGQ5-clA,6241
+uplid-1.1.0.dist-info/RECORD,,

uplid-1.0.0.dist-info/METADATA

@@ -1,159 +0,0 @@
-Metadata-Version: 2.4
-Name: uplid
-Version: 1.0.0
-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
-- **Human-readable**: `usr_4mJ9k2L8nP3qR7sT1vW5xY` (Stripe-style)
-- **Time-sortable**: Built on UUIDv7 for natural ordering
-- **Compact**: 22-character base62 encoding
-- **Zero external deps**: Uses Python 3.14's stdlib `uuid7()`
-- **Pydantic 2 native**: Full validation and serialization support
-
-## Installation
-
-```bash
-pip install uplid
-# or
-uv add uplid
-```
-
-Requires Python 3.14+.
-
-## Quick Start
-
-```python
-from typing import Literal
-from pydantic import BaseModel, Field
-from uplid import UPLID, factory
-
-# Define typed ID aliases
-UserId = UPLID[Literal["usr"]]
-OrgId = UPLID[Literal["org"]]
-
-# Use in Pydantic models
-class User(BaseModel):
-    id: UserId = Field(default_factory=factory(UserId))
-    org_id: OrgId
-
-# Generate IDs
-user_id = UPLID.generate("usr")
-print(user_id)  # usr_4mJ9k2L8nP3qR7sT1vW5xY
-
-# Parse from string
-parsed = UPLID.from_string("usr_4mJ9k2L8nP3qR7sT1vW5xY", "usr")
-
-# Type safety - these are compile-time errors with ty/mypy:
-# user.org_id = user_id  # Error: UserId != OrgId
-```
-
-## Prefix Rules
-
-Prefixes must be snake_case:
-- Lowercase letters and underscores only
-- Cannot start or end with underscore
-- 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_abc123...", "usr")
-
-# Properties
-uid.prefix      # "usr"
-uid.uid         # UUID object
-uid.datetime    # datetime from UUIDv7
-uid.timestamp   # float (Unix timestamp)
-uid.base62_uid  # "abc123..." (22 chars)
-```
-
-### `factory(UPLIDType)`
-
-Creates a factory function for Pydantic's `default_factory`.
-
-```python
-UserId = UPLID[Literal["usr"]]
-
-class User(BaseModel):
-    id: UserId = Field(default_factory=factory(UserId))
-```
-
-### `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_abc123...")
-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`.
-
-```python
-from uplid import UPLIDError
-
-try:
-    UPLID.from_string("invalid", "usr")
-except UPLIDError as e:
-    print(e)
-except ValueError:  # Also works
-    pass
-```
-
-## License
-
-MIT

uplid-1.0.0.dist-info/RECORD

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