duckling-orm 0.0.3__tar.gz → 0.0.4__tar.gz

{duckling_orm-0.0.3/src/duckling_orm.egg-info → duckling_orm-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: duckling-orm
-Version: 0.0.3
+Version: 0.0.4
 Summary: A Beanie-inspired ORM for DuckDB — async-first, Pydantic-powered.
 Author: Duckling Contributors
 License: Apache-2.0
@@ -108,7 +108,8 @@ init_duckling_sync(database="app.db", document_models=[User])
 
 ### Defining Models
 
-Duckling models are Pydantic `BaseModel` subclasses with an auto-generated `id` primary key:
+Duckling models are Pydantic `BaseModel` subclasses. By default, `id` is an
+auto-generated, auto-incrementing integer primary key:
 
 ```python
 from duckling import Document, IndexSpec
@@ -129,6 +130,32 @@ class Product(Document):
 
 **Supported types:** `str`, `int`, `float`, `bool`, `bytes`, `datetime.date`, `datetime.datetime`, `datetime.time`, `uuid.UUID`, `Optional[T]`, `List[T]` (→ JSON), `dict` (→ JSON), nested Pydantic models (→ JSON), `Enum`.
 
+### Custom Primary Keys (UUID, ULID, string)
+
+Override `id` with any type other than `int` to opt out of the auto-increment
+sequence and use your own primary key — a UUID, a sortable ULID, or a plain
+caller-supplied string:
+
+```python
+import uuid
+from pydantic import Field
+from duckling import Document, generate_ulid
+
+class Session(Document):
+    id: str = Field(default_factory=generate_ulid)   # sortable string PK
+    user_email: str
+
+class ApiKey(Document):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4)  # UUID PK
+    label: str
+
+class Tag(Document):
+    id: str            # no default — caller must supply an id
+    name: str
+```
+
+Inserting a document whose `id` already exists raises `DocumentAlreadyExists`.
+
 ### Indexed Fields
 
 ```python

{duckling_orm-0.0.3 → duckling_orm-0.0.4}/README.md

@@ -77,7 +77,8 @@ init_duckling_sync(database="app.db", document_models=[User])
 
 ### Defining Models
 
-Duckling models are Pydantic `BaseModel` subclasses with an auto-generated `id` primary key:
+Duckling models are Pydantic `BaseModel` subclasses. By default, `id` is an
+auto-generated, auto-incrementing integer primary key:
 
 ```python
 from duckling import Document, IndexSpec
@@ -98,6 +99,32 @@ class Product(Document):
 
 **Supported types:** `str`, `int`, `float`, `bool`, `bytes`, `datetime.date`, `datetime.datetime`, `datetime.time`, `uuid.UUID`, `Optional[T]`, `List[T]` (→ JSON), `dict` (→ JSON), nested Pydantic models (→ JSON), `Enum`.
 
+### Custom Primary Keys (UUID, ULID, string)
+
+Override `id` with any type other than `int` to opt out of the auto-increment
+sequence and use your own primary key — a UUID, a sortable ULID, or a plain
+caller-supplied string:
+
+```python
+import uuid
+from pydantic import Field
+from duckling import Document, generate_ulid
+
+class Session(Document):
+    id: str = Field(default_factory=generate_ulid)   # sortable string PK
+    user_email: str
+
+class ApiKey(Document):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4)  # UUID PK
+    label: str
+
+class Tag(Document):
+    id: str            # no default — caller must supply an id
+    name: str
+```
+
+Inserting a document whose `id` already exists raises `DocumentAlreadyExists`.
+
 ### Indexed Fields
 
 ```python

{duckling_orm-0.0.3 → duckling_orm-0.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "duckling-orm"
-version = "0.0.3"
+version = "0.0.4"
 description = "A Beanie-inspired ORM for DuckDB — async-first, Pydantic-powered."
 readme = "README.md"
 license = {text = "Apache-2.0"}
@@ -44,6 +44,7 @@ dev = [
 
 
 
+
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["duckling*"]

{duckling_orm-0.0.3 → duckling_orm-0.0.4}/src/duckling/__init__.py

@@ -40,6 +40,7 @@ from .fields import (
     IndexSpec,
     SortDirection,
 )
+from .ids import generate_ulid
 from .init import init_duckling, init_duckling_sync
 from .operators import (
     And,
@@ -84,6 +85,8 @@ __all__ = [
     "SortDirection",
     "FieldProxy",
     "Expression",
+    # IDs
+    "generate_ulid",
     # Query
     "FindQuery",
     # Operators

{duckling_orm-0.0.3 → duckling_orm-0.0.4}/src/duckling/document.py

@@ -46,10 +46,11 @@ from typing import (
     get_type_hints,
 )
 
+import duckdb
 from pydantic import BaseModel, ConfigDict
 
 from .connection import DucklingSession, get_session
-from .exceptions import DocumentNotFound, InvalidQueryError
+from .exceptions import DocumentAlreadyExists, DocumentNotFound, InvalidQueryError
 from .fields import Expression, FieldProxy, IndexSpec, SortDirection
 from .query import FindQuery
 
@@ -287,6 +288,35 @@ class Document(BaseModel, metaclass=DocumentMeta):
                         indexed.append((name, arg))
         return indexed
 
+    # ── Primary key strategy ──────────────────
+
+    @classmethod
+    def _is_auto_increment_id(cls) -> bool:
+        """
+        True if the `id` field resolves to `int` (the default primary key
+        strategy: an auto-incrementing INTEGER backed by a DuckDB SEQUENCE).
+
+        Any other resolved type (str, uuid.UUID, ...) is treated as a
+        caller/default_factory-supplied primary key with no sequence.
+        """
+        import typing
+
+        hints = get_type_hints(cls, include_extras=True)
+        py_type = hints.get("id", int)
+
+        origin = get_origin(py_type)
+        if origin is getattr(typing, "Annotated", None):
+            py_type = get_args(py_type)[0]
+            origin = get_origin(py_type)
+
+        args = get_args(py_type)
+        if args:
+            non_none = [a for a in args if a is not type(None)]
+            if non_none:
+                py_type = non_none[0]
+
+        return py_type is int
+
     # ── Table creation ────────────────────────
 
     @classmethod
@@ -296,24 +326,28 @@ class Document(BaseModel, metaclass=DocumentMeta):
         col_types = cls._get_column_types()
         indexed = dict(cls._get_indexed_fields())
 
+        if cls._is_auto_increment_id():
+            id_def = f'"id" INTEGER PRIMARY KEY DEFAULT(nextval(\'seq_{table}_id\'))'
+        else:
+            id_def = f'"id" {col_types["id"]} PRIMARY KEY'
+
         columns = []
         for col_name, col_type in col_types.items():
-            parts = [f'"{col_name}"', col_type]
             if col_name == "id":
-                parts = ['"id"', "INTEGER PRIMARY KEY DEFAULT(nextval('seq_" + table + "_id'))"]
-                continue  # handled separately
+                continue
+            parts = [f'"{col_name}"', col_type]
             if col_name in indexed and indexed[col_name].unique:
                 parts.append("UNIQUE")
             columns.append(" ".join(parts))
 
-        # id column first
-        col_defs = [f'"id" INTEGER PRIMARY KEY DEFAULT(nextval(\'seq_{table}_id\'))']
-        col_defs.extend(columns)
+        col_defs = [id_def] + columns
 
         return f'CREATE TABLE IF NOT EXISTS "{table}" (\n  ' + ",\n  ".join(col_defs) + "\n)"
 
     @classmethod
-    def _build_sequence_sql(cls) -> str:
+    def _build_sequence_sql(cls) -> Optional[str]:
+        if not cls._is_auto_increment_id():
+            return None
         table = cls._get_table_name()
         return f"CREATE SEQUENCE IF NOT EXISTS seq_{table}_id START 1"
 
@@ -321,7 +355,9 @@ class Document(BaseModel, metaclass=DocumentMeta):
     def _create_table_sync(cls) -> None:
         """Create the table synchronously."""
         session = get_session()
-        session.execute(cls._build_sequence_sql())
+        seq_sql = cls._build_sequence_sql()
+        if seq_sql:
+            session.execute(seq_sql)
         session.execute(cls._build_create_table_sql())
 
         # Create indexes
@@ -370,8 +406,10 @@ class Document(BaseModel, metaclass=DocumentMeta):
         table = self._get_table_name()
         data = self._to_row_dict()
 
-        # Remove id if None (auto-generated)
-        if data.get("id") is None:
+        # Remove id if None so the auto-increment sequence default applies.
+        # A non-auto-increment (str/UUID) id left None is kept so the
+        # missing-primary-key error surfaces from the database.
+        if self._is_auto_increment_id() and data.get("id") is None:
             data.pop("id", None)
 
         columns = list(data.keys())
@@ -381,7 +419,12 @@ class Document(BaseModel, metaclass=DocumentMeta):
 
         sql = f'INSERT INTO "{table}" ({col_str}) VALUES ({placeholders}) RETURNING "id"'
 
-        row = await session.async_fetchone(sql, values)
+        try:
+            row = await session.async_fetchone(sql, values)
+        except duckdb.ConstraintException as e:
+            raise DocumentAlreadyExists(
+                f"{self.__class__.__name__} with id={data.get('id')!r} already exists"
+            ) from e
         if row:
             self.id = row[0]
         return self
@@ -392,7 +435,7 @@ class Document(BaseModel, metaclass=DocumentMeta):
         table = self._get_table_name()
         data = self._to_row_dict()
 
-        if data.get("id") is None:
+        if self._is_auto_increment_id() and data.get("id") is None:
             data.pop("id", None)
 
         columns = list(data.keys())
@@ -401,7 +444,12 @@ class Document(BaseModel, metaclass=DocumentMeta):
         values = [data[c] for c in columns]
 
         sql = f'INSERT INTO "{table}" ({col_str}) VALUES ({placeholders}) RETURNING "id"'
-        row = session.fetchone(sql, values)
+        try:
+            row = session.fetchone(sql, values)
+        except duckdb.ConstraintException as e:
+            raise DocumentAlreadyExists(
+                f"{self.__class__.__name__} with id={data.get('id')!r} already exists"
+            ) from e
         if row:
             self.id = row[0]
         return self
@@ -541,7 +589,7 @@ class Document(BaseModel, metaclass=DocumentMeta):
     # ── Query: get by id ──────────────────────
 
     @classmethod
-    async def get(cls: Type[T], doc_id: int) -> Optional[T]:
+    async def get(cls: Type[T], doc_id: Any) -> Optional[T]:
         """Get a document by its primary key id."""
         session = get_session()
         table = cls._get_table_name()
@@ -553,7 +601,7 @@ class Document(BaseModel, metaclass=DocumentMeta):
         return cls._from_row(row, cls._get_column_names())
 
     @classmethod
-    def get_sync(cls: Type[T], doc_id: int) -> Optional[T]:
+    def get_sync(cls: Type[T], doc_id: Any) -> Optional[T]:
         """Get a document by id synchronously."""
         session = get_session()
         table = cls._get_table_name()

duckling_orm-0.0.4/src/duckling/ids.py

@@ -0,0 +1,26 @@
+"""ID generation helpers for custom primary keys."""
+
+import os
+import time
+
+_CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+
+def generate_ulid() -> str:
+    """
+    Generate a 26-character ULID (48-bit ms timestamp + 80-bit randomness),
+    lexicographically sortable by creation time.
+
+    Usage:
+        class Session(Document):
+            id: str = Field(default_factory=generate_ulid)
+    """
+    ms = int(time.time() * 1000)
+    randomness = int.from_bytes(os.urandom(10), "big")
+    value = (ms << 80) | randomness
+
+    chars = []
+    for _ in range(26):
+        value, rem = divmod(value, 32)
+        chars.append(_CROCKFORD[rem])
+    return "".join(reversed(chars))

{duckling_orm-0.0.3 → duckling_orm-0.0.4/src/duckling_orm.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: duckling-orm
-Version: 0.0.3
+Version: 0.0.4
 Summary: A Beanie-inspired ORM for DuckDB — async-first, Pydantic-powered.
 Author: Duckling Contributors
 License: Apache-2.0
@@ -108,7 +108,8 @@ init_duckling_sync(database="app.db", document_models=[User])
 
 ### Defining Models
 
-Duckling models are Pydantic `BaseModel` subclasses with an auto-generated `id` primary key:
+Duckling models are Pydantic `BaseModel` subclasses. By default, `id` is an
+auto-generated, auto-incrementing integer primary key:
 
 ```python
 from duckling import Document, IndexSpec
@@ -129,6 +130,32 @@ class Product(Document):
 
 **Supported types:** `str`, `int`, `float`, `bool`, `bytes`, `datetime.date`, `datetime.datetime`, `datetime.time`, `uuid.UUID`, `Optional[T]`, `List[T]` (→ JSON), `dict` (→ JSON), nested Pydantic models (→ JSON), `Enum`.
 
+### Custom Primary Keys (UUID, ULID, string)
+
+Override `id` with any type other than `int` to opt out of the auto-increment
+sequence and use your own primary key — a UUID, a sortable ULID, or a plain
+caller-supplied string:
+
+```python
+import uuid
+from pydantic import Field
+from duckling import Document, generate_ulid
+
+class Session(Document):
+    id: str = Field(default_factory=generate_ulid)   # sortable string PK
+    user_email: str
+
+class ApiKey(Document):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4)  # UUID PK
+    label: str
+
+class Tag(Document):
+    id: str            # no default — caller must supply an id
+    name: str
+```
+
+Inserting a document whose `id` already exists raises `DocumentAlreadyExists`.
+
 ### Indexed Fields
 
 ```python

{duckling_orm-0.0.3 → duckling_orm-0.0.4}/src/duckling_orm.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ src/duckling/connection.py
 src/duckling/document.py
 src/duckling/exceptions.py
 src/duckling/fields.py
+src/duckling/ids.py
 src/duckling/init.py
 src/duckling/operators.py
 src/duckling/query.py
@@ -15,6 +16,7 @@ src/duckling_orm.egg-info/dependency_links.txt
 src/duckling_orm.egg-info/requires.txt
 src/duckling_orm.egg-info/top_level.txt
 tests/test_connection.py
+tests/test_custom_ids.py
 tests/test_document.py
 tests/test_fields.py
 tests/test_init.py

duckling_orm-0.0.4/tests/test_custom_ids.py

@@ -0,0 +1,84 @@
+"""Tests for custom (non auto-increment) primary keys — str, UUID, ULID."""
+
+import uuid
+
+import pytest
+
+from duckling import DocumentAlreadyExists, get_session
+
+from .models import ApiKey, Session, Tag
+
+
+class TestSyncCustomIds:
+    def test_ulid_id_is_generated_and_unique(self, sync_db):
+        a = Session(user_email="a@test.com")
+        b = Session(user_email="b@test.com")
+        a.insert_sync()
+        b.insert_sync()
+
+        assert isinstance(a.id, str) and len(a.id) == 26
+        assert a.id != b.id
+
+    def test_uuid_id_round_trip(self, sync_db):
+        key = ApiKey(label="prod")
+        key.insert_sync()
+        assert isinstance(key.id, uuid.UUID)
+
+        found = ApiKey.get_sync(key.id)
+        assert found is not None
+        assert found.label == "prod"
+
+    def test_caller_supplied_id_round_trip(self, sync_db):
+        tag = Tag(id="billing", name="Billing")
+        tag.insert_sync()
+
+        found = Tag.get_sync("billing")
+        assert found is not None
+        assert found.name == "Billing"
+
+    def test_duplicate_caller_supplied_id_raises(self, sync_db):
+        Tag(id="dup", name="First").insert_sync()
+        with pytest.raises(DocumentAlreadyExists):
+            Tag(id="dup", name="Second").insert_sync()
+
+    def test_no_sequence_created_for_string_id_model(self, sync_db):
+        session = get_session()
+        rows = session.fetchall(
+            "SELECT sequence_name FROM duckdb_sequences() WHERE sequence_name = ?",
+            ["seq_tags_id"],
+        )
+        assert rows == []
+
+
+class TestAsyncCustomIds:
+    @pytest.mark.asyncio
+    async def test_ulid_id_is_generated_and_unique(self, async_db):
+        a = Session(user_email="a@test.com")
+        b = Session(user_email="b@test.com")
+        await a.insert()
+        await b.insert()
+
+        assert isinstance(a.id, str) and len(a.id) == 26
+        assert a.id != b.id
+
+    @pytest.mark.asyncio
+    async def test_duplicate_caller_supplied_id_raises(self, async_db):
+        await Tag(id="dup", name="First").insert()
+        with pytest.raises(DocumentAlreadyExists):
+            await Tag(id="dup", name="Second").insert()
+
+    @pytest.mark.asyncio
+    async def test_recreate_tables_with_mixed_pk_types(self):
+        from duckling import get_session, init_duckling
+
+        from .models import ALL_MODELS
+
+        session = await init_duckling(database=":memory:", document_models=ALL_MODELS)
+        conn = session.connection
+
+        # Reuse the same live connection so recreate_tables actually drops
+        # and rebuilds tables/sequences that exist, instead of a fresh :memory: db.
+        await init_duckling(
+            connection=conn, document_models=ALL_MODELS, recreate_tables=True
+        )
+        assert get_session().connection is conn