iceaxe 0.2.1__tar.gz → 0.2.3.dev1__tar.gz

{iceaxe-0.2.1 → iceaxe-0.2.3.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: iceaxe
-Version: 0.2.1
+Version: 0.2.3.dev1
 Summary: A modern, fast ORM for Python.
 Author: Pierce Freeman
 Author-email: pierce@freeman.vc

iceaxe-0.2.3.dev1/iceaxe/__tests__/conf_models.py

@@ -0,0 +1,81 @@
+from contextlib import contextmanager
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+from pyinstrument import Profiler
+
+from iceaxe.base import Field, TableBase
+
+
+class UserDemo(TableBase):
+    id: int = Field(primary_key=True, default=None)
+    name: str
+    email: str
+
+
+class ArtifactDemo(TableBase):
+    id: int = Field(primary_key=True, default=None)
+    title: str
+    user_id: int = Field(foreign_key="userdemo.id")
+
+
+class ComplexDemo(TableBase):
+    id: int = Field(primary_key=True, default=None)
+    string_list: list[str]
+    json_data: dict[str, str] = Field(is_json=True)
+
+
+class Employee(TableBase):
+    id: int = Field(primary_key=True, default=None)
+    email: str = Field(unique=True)
+    first_name: str
+    last_name: str
+    department: str
+    salary: float
+
+
+class Department(TableBase):
+    id: int = Field(primary_key=True, default=None)
+    name: str = Field(unique=True)
+    budget: float
+    location: str
+
+
+class ProjectAssignment(TableBase):
+    id: int = Field(primary_key=True, default=None)
+    employee_id: int = Field(foreign_key="employee.id")
+    project_name: str
+    role: str
+    start_date: str
+
+
+class EmployeeStatus(StrEnum):
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+    ON_LEAVE = "on_leave"
+
+
+class EmployeeMetadata(TableBase):
+    id: int = Field(primary_key=True, default=None)
+    employee_id: int = Field(foreign_key="employee.id")
+    status: EmployeeStatus
+    tags: list[str] = Field(is_json=True)
+    additional_info: dict[str, Any] = Field(is_json=True)
+
+
+@contextmanager
+def run_profile(request):
+    TESTS_ROOT = Path.cwd()
+    PROFILE_ROOT = TESTS_ROOT / ".profiles"
+
+    # Turn profiling on
+    profiler = Profiler()
+    profiler.start()
+
+    yield  # Run test
+
+    profiler.stop()
+    PROFILE_ROOT.mkdir(exist_ok=True)
+    results_file = PROFILE_ROOT / f"{request.node.name}.html"
+    profiler.write_html(results_file)

iceaxe-0.2.3.dev1/iceaxe/__tests__/mountaineer/dependencies/test_core.py

@@ -0,0 +1,73 @@
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import asyncpg
+import pytest
+from mountaineer import CoreDependencies
+
+from iceaxe.mountaineer.config import DatabaseConfig
+from iceaxe.mountaineer.dependencies.core import get_db_connection
+from iceaxe.session import DBConnection
+
+
+@pytest.fixture(autouse=True)
+def mock_db_connect():
+    conn = AsyncMock(spec=asyncpg.Connection)
+    conn.close = AsyncMock()
+
+    with patch("asyncpg.connect", new_callable=AsyncMock) as mock:
+        mock.return_value = conn
+        yield mock
+
+
+@pytest.fixture
+def mock_config():
+    return DatabaseConfig(
+        POSTGRES_HOST="test-host",
+        POSTGRES_PORT=5432,
+        POSTGRES_USER="test-user",
+        POSTGRES_PASSWORD="test-pass",
+        POSTGRES_DB="test-db",
+    )
+
+
+@pytest.fixture
+def mock_connection():
+    conn = AsyncMock(spec=asyncpg.Connection)
+    conn.close = AsyncMock()
+    return conn
+
+
+@pytest.mark.asyncio
+async def test_get_db_connection_closes_after_yield(
+    mock_config: DatabaseConfig,
+    mock_connection: AsyncMock,
+    mock_db_connect: AsyncMock,
+):
+    mock_get_config = MagicMock(return_value=mock_config)
+    CoreDependencies.get_config_with_type = mock_get_config
+
+    mock_db_connect.return_value = mock_connection
+
+    # Get the generator
+    db_gen = get_db_connection(mock_config)
+
+    # Get the connection
+    connection = await anext(db_gen)  # noqa: F821
+
+    assert isinstance(connection, DBConnection)
+    assert connection.conn == mock_connection
+    mock_db_connect.assert_called_once_with(
+        host=mock_config.POSTGRES_HOST,
+        port=mock_config.POSTGRES_PORT,
+        user=mock_config.POSTGRES_USER,
+        password=mock_config.POSTGRES_PASSWORD,
+        database=mock_config.POSTGRES_DB,
+    )
+
+    # Simulate the end of the generator's scope
+    try:
+        await db_gen.aclose()
+    except StopAsyncIteration:
+        pass
+
+    mock_connection.close.assert_called_once()

{iceaxe-0.2.1 → iceaxe-0.2.3.dev1}/iceaxe/__tests__/test_comparison.py

@@ -4,7 +4,7 @@ import pytest
 
 from iceaxe.base import TableBase
 from iceaxe.comparison import ComparisonType, FieldComparison
-from iceaxe.field import DBFieldClassDefinition, FieldInfo
+from iceaxe.field import DBFieldClassDefinition, DBFieldInfo
 
 
 def test_comparison_type_enum():
@@ -24,7 +24,7 @@ def test_comparison_type_enum():
 @pytest.fixture
 def db_field():
     return DBFieldClassDefinition(
-        root_model=TableBase, key="test_key", field_definition=FieldInfo()
+        root_model=TableBase, key="test_key", field_definition=DBFieldInfo()
     )
 
 
@@ -137,7 +137,7 @@ def test_compare(db_field: DBFieldClassDefinition):
         3.14,
         complex(1, 2),
         DBFieldClassDefinition(
-            root_model=TableBase, key="other_key", field_definition=FieldInfo()
+            root_model=TableBase, key="other_key", field_definition=DBFieldInfo()
         ),
     ],
 )

{iceaxe-0.2.1 → iceaxe-0.2.3.dev1}/iceaxe/__tests__/test_field.py

@@ -4,13 +4,13 @@ import pytest
 
 from iceaxe.base import TableBase
 from iceaxe.comparison import ComparisonType, FieldComparison
-from iceaxe.field import DBFieldClassDefinition, FieldInfo
+from iceaxe.field import DBFieldClassDefinition, DBFieldInfo
 
 
 @pytest.fixture
 def db_field():
     return DBFieldClassDefinition(
-        root_model=TableBase, key="test_key", field_definition=FieldInfo()
+        root_model=TableBase, key="test_key", field_definition=DBFieldInfo()
     )
 
 
@@ -107,7 +107,7 @@ def test_compare(db_field: DBFieldClassDefinition):
         3.14,
         complex(1, 2),
         DBFieldClassDefinition(
-            root_model=TableBase, key="other_key", field_definition=FieldInfo()
+            root_model=TableBase, key="other_key", field_definition=DBFieldInfo()
         ),
     ],
 )
@@ -132,8 +132,8 @@ def test_comparison_with_different_types(db_field: DBFieldClassDefinition, value
 
 def test_db_field_class_definition_instantiation():
     field_def = DBFieldClassDefinition(
-        root_model=TableBase, key="test_key", field_definition=FieldInfo()
+        root_model=TableBase, key="test_key", field_definition=DBFieldInfo()
     )
     assert field_def.root_model == TableBase
     assert field_def.key == "test_key"
-    assert isinstance(field_def.field_definition, FieldInfo)
+    assert isinstance(field_def.field_definition, DBFieldInfo)

{iceaxe-0.2.1 → iceaxe-0.2.3.dev1}/iceaxe/__tests__/test_session.py

@@ -512,3 +512,182 @@ async def test_db_connection_insert_update_enum(db_connection: DBConnection):
     result = await db_connection.conn.fetch("SELECT * FROM enumdemo")
     assert len(result) == 1
     assert result[0]["value"] == "b"
+
+
+#
+# Upsert
+#
+
+
+@pytest.mark.asyncio
+async def test_upsert_basic_insert(db_connection: DBConnection):
+    """
+    Test basic insert when no conflict exists
+
+    """
+    await db_connection.conn.execute(
+        """
+        ALTER TABLE userdemo
+        ADD CONSTRAINT email_unique UNIQUE (email)
+        """
+    )
+
+    user = UserDemo(name="John Doe", email="john@example.com")
+    result = await db_connection.upsert(
+        [user],
+        conflict_fields=(UserDemo.email,),
+        returning_fields=(UserDemo.id, UserDemo.name, UserDemo.email),
+    )
+
+    assert result is not None
+    assert len(result) == 1
+    assert result[0][1] == "John Doe"
+    assert result[0][2] == "john@example.com"
+
+    # Verify in database
+    db_result = await db_connection.conn.fetch("SELECT * FROM userdemo")
+    assert len(db_result) == 1
+    assert db_result[0][1] == "John Doe"
+
+
+@pytest.mark.asyncio
+async def test_upsert_update_on_conflict(db_connection: DBConnection):
+    """
+    Test update when conflict exists
+
+    """
+    await db_connection.conn.execute(
+        """
+        ALTER TABLE userdemo
+        ADD CONSTRAINT email_unique UNIQUE (email)
+        """
+    )
+
+    # First insert
+    user = UserDemo(name="John Doe", email="john@example.com")
+    await db_connection.insert([user])
+
+    # Attempt upsert with same email but different name
+    new_user = UserDemo(name="Johnny Doe", email="john@example.com")
+    result = await db_connection.upsert(
+        [new_user],
+        conflict_fields=(UserDemo.email,),
+        update_fields=(UserDemo.name,),
+        returning_fields=(UserDemo.id, UserDemo.name, UserDemo.email),
+    )
+
+    assert result is not None
+    assert len(result) == 1
+    assert result[0][1] == "Johnny Doe"
+
+    # Verify only one record exists
+    db_result = await db_connection.conn.fetch("SELECT * FROM userdemo")
+    assert len(db_result) == 1
+    assert db_result[0]["name"] == "Johnny Doe"
+
+
+@pytest.mark.asyncio
+async def test_upsert_do_nothing_on_conflict(db_connection: DBConnection):
+    """
+    Test DO NOTHING behavior when no update_fields specified
+
+    """
+    await db_connection.conn.execute(
+        """
+        ALTER TABLE userdemo
+        ADD CONSTRAINT email_unique UNIQUE (email)
+        """
+    )
+
+    # First insert
+    user = UserDemo(name="John Doe", email="john@example.com")
+    await db_connection.insert([user])
+
+    # Attempt upsert with same email but different name
+    new_user = UserDemo(name="Johnny Doe", email="john@example.com")
+    result = await db_connection.upsert(
+        [new_user],
+        conflict_fields=(UserDemo.email,),
+        returning_fields=(UserDemo.id, UserDemo.name, UserDemo.email),
+    )
+
+    # Should return empty list as no update was performed
+    assert result == []
+
+    # Verify original record unchanged
+    db_result = await db_connection.conn.fetch("SELECT * FROM userdemo")
+    assert len(db_result) == 1
+    assert db_result[0][1] == "John Doe"
+
+
+@pytest.mark.asyncio
+async def test_upsert_multiple_objects(db_connection: DBConnection):
+    """
+    Test upserting multiple objects at once
+
+    """
+    await db_connection.conn.execute(
+        """
+        ALTER TABLE userdemo
+        ADD CONSTRAINT email_unique UNIQUE (email)
+        """
+    )
+
+    users = [
+        UserDemo(name="John Doe", email="john@example.com"),
+        UserDemo(name="Jane Doe", email="jane@example.com"),
+    ]
+    result = await db_connection.upsert(
+        users,
+        conflict_fields=(UserDemo.email,),
+        returning_fields=(UserDemo.name, UserDemo.email),
+    )
+
+    assert result is not None
+    assert len(result) == 2
+    assert {r[1] for r in result} == {"john@example.com", "jane@example.com"}
+
+
+@pytest.mark.asyncio
+async def test_upsert_empty_list(db_connection: DBConnection):
+    await db_connection.conn.execute(
+        """
+        ALTER TABLE userdemo
+        ADD CONSTRAINT email_unique UNIQUE (email)
+        """
+    )
+
+    """Test upserting an empty list"""
+    result = await db_connection.upsert(
+        [], conflict_fields=(UserDemo.email,), returning_fields=(UserDemo.id,)
+    )
+    assert result is None
+
+
+@pytest.mark.asyncio
+async def test_upsert_multiple_conflict_fields(db_connection: DBConnection):
+    """
+    Test upserting with multiple conflict fields
+
+    """
+    await db_connection.conn.execute(
+        """
+        ALTER TABLE userdemo
+        ADD CONSTRAINT email_unique UNIQUE (name, email)
+        """
+    )
+
+    users = [
+        UserDemo(name="John Doe", email="john@example.com"),
+        UserDemo(name="John Doe", email="john@example.com"),
+        UserDemo(name="Jane Doe", email="jane@example.com"),
+    ]
+    result = await db_connection.upsert(
+        users,
+        conflict_fields=(UserDemo.name, UserDemo.email),
+        returning_fields=(UserDemo.name, UserDemo.email),
+    )
+
+    assert result is not None
+    assert len(result) == 2
+    assert {r[1] for r in result} == {"john@example.com", "jane@example.com"}

{iceaxe-0.2.1 → iceaxe-0.2.3.dev1}/iceaxe/field.py

@@ -1,3 +1,4 @@
+from json import dumps as json_dumps
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -92,6 +93,11 @@ class DBFieldInfo(FieldInfo):
             **field._attributes_set,  # type: ignore
         )
 
+    def to_db_value(self, value: Any):
+        if self.is_json:
+            return json_dumps(value)
+        return value
+
 
 def __get_db_field(_: Callable[Concatenate[Any, P], Any] = PydanticField):  # type: ignore
     """
@@ -136,13 +142,13 @@ def __get_db_field(_: Callable[Concatenate[Any, P], Any] = PydanticField):  # ty
 class DBFieldClassDefinition(ComparisonBase):
     root_model: Type["TableBase"]
     key: str
-    field_definition: FieldInfo
+    field_definition: DBFieldInfo
 
     def __init__(
         self,
         root_model: Type["TableBase"],
         key: str,
-        field_definition: FieldInfo,
+        field_definition: DBFieldInfo,
     ):
         self.root_model = root_model
         self.key = key

{iceaxe-0.2.1 → iceaxe-0.2.3.dev1}/iceaxe/mountaineer/dependencies/core.py

@@ -3,6 +3,8 @@ Optional compatibility layer for `mountaineer` dependency access.
 
 """
 
+from typing import AsyncGenerator
+
 import asyncpg
 from mountaineer import CoreDependencies, Depends
 
@@ -14,7 +16,7 @@ async def get_db_connection(
     config: DatabaseConfig = Depends(
         CoreDependencies.get_config_with_type(DatabaseConfig)
     ),
-) -> DBConnection:
+) -> AsyncGenerator[DBConnection, None]:
     conn = await asyncpg.connect(
         host=config.POSTGRES_HOST,
         port=config.POSTGRES_PORT,
@@ -22,4 +24,7 @@ async def get_db_connection(
         password=config.POSTGRES_PASSWORD,
         database=config.POSTGRES_DB,
     )
-    return DBConnection(conn)
+    try:
+        yield DBConnection(conn)
+    finally:
+        await conn.close()

{iceaxe-0.2.1 → iceaxe-0.2.3.dev1}/iceaxe/session.py

@@ -1,6 +1,5 @@
 from collections import defaultdict
 from contextlib import asynccontextmanager
-from json import dumps as json_dumps
 from typing import (
     Any,
     Literal,
@@ -13,6 +12,7 @@ from typing import (
 )
 
 import asyncpg
+from typing_extensions import TypeVarTuple
 
 from iceaxe.base import TableBase
 from iceaxe.logging import LOGGER
@@ -27,6 +27,7 @@ from iceaxe.session_optimized import optimize_exec_casting
 
 P = ParamSpec("P")
 T = TypeVar("T")
+Ts = TypeVarTuple("Ts")
 
 
 class DBConnection:
@@ -94,23 +95,11 @@ class DBConnection:
             return
 
         for model, model_objects in self._aggregate_models_by_table(objects):
-            # We let the DB handle autoincrement keys
-            auto_increment_keys = [
-                field
-                for field, info in model.model_fields.items()
-                if info.autoincrement
-            ]
-
             table_name = QueryIdentifier(model.get_table_name())
-            fields = [
-                field
+            fields = {
+                field: info
                 for field, info in model.model_fields.items()
-                if not info.exclude
-                and not info.autoincrement
-                and field not in auto_increment_keys
-            ]
-            json_fields = {
-                field for field, info in model.model_fields.items() if info.is_json
+                if (not info.exclude and not info.autoincrement)
             }
             field_string = ", ".join(f'"{field}"' for field in fields)
             primary_key = self._get_primary_key(model)
@@ -124,10 +113,8 @@ class DBConnection:
                 for obj in model_objects:
                     obj_values = obj.model_dump()
                     values = [
-                        obj_values[field]
-                        if field not in json_fields
-                        else json_dumps(obj_values[field])
-                        for field in fields
+                        info.to_db_value(obj_values[field])
+                        for field, info in fields.items()
                     ]
                     result = await self.conn.fetchrow(query, *values)
 
@@ -135,6 +122,119 @@ class DBConnection:
                         setattr(obj, primary_key, result[primary_key])
                     obj.clear_modified_attributes()
 
+    @overload
+    async def upsert(
+        self,
+        objects: Sequence[TableBase],
+        *,
+        conflict_fields: tuple[Any, ...],
+        update_fields: tuple[Any, ...] | None = None,
+        returning_fields: tuple[T, *Ts],
+    ) -> list[tuple[T, *Ts]]: ...
+
+    @overload
+    async def upsert(
+        self,
+        objects: Sequence[TableBase],
+        *,
+        conflict_fields: tuple[Any, ...],
+        update_fields: tuple[Any, ...] | None = None,
+        returning_fields: None,
+    ) -> None: ...
+
+    async def upsert(
+        self,
+        objects: Sequence[TableBase],
+        *,
+        conflict_fields: tuple[Any, ...],
+        update_fields: tuple[Any, ...] | None = None,
+        returning_fields: tuple[T, *Ts] | None = None,
+    ) -> list[tuple[T, *Ts]] | None:
+        """
+        Performs an upsert (INSERT ... ON CONFLICT DO UPDATE) operation for the given objects.
+
+        :param objects: Sequence of TableBase objects to upsert
+        :param conflict_fields: Fields to check for conflicts (ON CONFLICT)
+        :param update_fields: Fields to update on conflict. If None, updates all non-excluded fields
+        :param returning_fields: Fields to return after the operation. If None, returns nothing
+
+        :return List of dictionaries containing the returned fields if returning_fields is specified
+
+        """
+        if not objects:
+            return None
+
+        # Evaluate column types
+        conflict_fields_cols = [field for field in conflict_fields if is_column(field)]
+        update_fields_cols = [
+            field for field in update_fields or [] if is_column(field)
+        ]
+        returning_fields_cols = [
+            field for field in returning_fields or [] if is_column(field)
+        ]
+
+        results: list[tuple[T, *Ts]] = []
+        async with self._ensure_transaction():
+            for model, model_objects in self._aggregate_models_by_table(objects):
+                table_name = QueryIdentifier(model.get_table_name())
+                fields = {
+                    field: info
+                    for field, info in model.model_fields.items()
+                    if (not info.exclude and not info.autoincrement)
+                }
+
+                field_string = ", ".join(f'"{field}"' for field in fields)
+                placeholders = ", ".join(f"${i}" for i in range(1, len(fields) + 1))
+                query = (
+                    f"INSERT INTO {table_name} ({field_string}) VALUES ({placeholders})"
+                )
+                if conflict_fields_cols:
+                    conflict_field_string = ", ".join(
+                        f'"{field.key}"' for field in conflict_fields_cols
+                    )
+                    query += f" ON CONFLICT ({conflict_field_string})"
+
+                    if update_fields_cols:
+                        set_values = ", ".join(
+                            f'"{field.key}" = EXCLUDED."{field.key}"'
+                            for field in update_fields_cols
+                        )
+                        query += f" DO UPDATE SET {set_values}"
+                    else:
+                        query += " DO NOTHING"
+
+                if returning_fields_cols:
+                    returning_string = ", ".join(
+                        f'"{field.key}"' for field in returning_fields_cols
+                    )
+                    query += f" RETURNING {returning_string}"
+
+                # Execute for each object
+                for obj in model_objects:
+                    obj_values = obj.model_dump()
+                    values = [
+                        info.to_db_value(obj_values[field])
+                        for field, info in fields.items()
+                    ]
+
+                    if returning_fields_cols:
+                        result = await self.conn.fetchrow(query, *values)
+                        if result:
+                            results.append(
+                                tuple(
+                                    [
+                                        result[field.key]
+                                        for field in returning_fields_cols
+                                    ]
+                                )
+                            )
+                    else:
+                        await self.conn.execute(query, *values)
+
+                    obj.clear_modified_attributes()
+
+        return results if returning_fields_cols else None
+
     async def update(self, objects: Sequence[TableBase]):
         if not objects:
             return

{iceaxe-0.2.1 → iceaxe-0.2.3.dev1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "iceaxe"
-version = "0.2.1"
+version = "0.2.3.dev1"
 description = "A modern, fast ORM for Python."
 authors = ["Pierce Freeman <pierce@freeman.vc>"]
 readme = "README.md"

{iceaxe-0.2.1 → iceaxe-0.2.3.dev1}/setup.py

@@ -6,6 +6,8 @@ packages = \
  'iceaxe.__tests__',
  'iceaxe.__tests__.benchmarks',
  'iceaxe.__tests__.migrations',
+ 'iceaxe.__tests__.mountaineer',
+ 'iceaxe.__tests__.mountaineer.dependencies',
  'iceaxe.__tests__.schemas',
  'iceaxe.migrations',
  'iceaxe.mountaineer',
@@ -20,7 +22,7 @@ install_requires = \
 
 setup_kwargs = {
     'name': 'iceaxe',
-    'version': '0.2.1',
+    'version': '0.2.3.dev1',
     'description': 'A modern, fast ORM for Python.',
     'long_description': '# iceaxe\n\nA modern, fast ORM for Python. We have the following goals:\n\n- 🏎️ **Performance**: We want to exceed or match the fastest ORMs in Python. We want our ORM\nto be as close as possible to raw-[asyncpg](https://github.com/MagicStack/asyncpg) speeds. See the "Benchmarks" section for more.\n- 📝 **Typehinting**: Everything should be typehinted with expected types. Declare your data as you\nexpect in Python and it should bidirectionally sync to the database.\n- 🐘 **Postgres only**: Leverage native Postgres features and simplify the implementation.\n- ⚡ **Common things are easy, rare things are possible**: 99% of the SQL queries we write are\nvanilla SELECT/INSERT/UPDATEs. These should be natively supported by your ORM. If you\'re writing _really_\ncomplex queries, these are better done by hand so you can see exactly what SQL will be run.\n\nIceaxe is in early alpha. It\'s also an independent project. It\'s compatible with the [Mountaineer](https://github.com/piercefreeman/mountaineer) ecosystem, but you can use it in whatever\nproject and web framework you\'re using.\n\n## Installation\n\nIf you\'re using poetry to manage your dependencies:\n\n```bash\npoetry add iceaxe\n```\n\nOtherwise install with pip:\n\n```bash\npip install iceaxe\n```\n\n## Usage\n\nDefine your models as a `TableBase` subclass:\n\n```python\nfrom iceaxe import TableBase\n\nclass Person(TableBase):\n    id: int\n    name: str\n    age: int\n```\n\nTableBase is a subclass of Pydantic\'s `BaseModel`, so you get all of the validation and Field customization\nout of the box. We provide our own `Field` constructor that adds database-specific configuration. For instance, to make the\n`id` field a primary key / auto-incrementing you can do:\n\n```python\nfrom iceaxe import Field\n\nclass Person(TableBase):\n    id: int = Field(primary_key=True)\n    name: str\n    age: int\n```\n\nOkay now you have a model. How do you interact with it?\n\nDatabases are based on a few core primitives to insert data, update it, and fetch it out again.\nTo do so you\'ll need a _database connection_, which is a connection over the network from your code\nto your Postgres database. The `DBConnection` is the core class for all ORM actions against the database.\n\n```python\nfrom iceaxe import DBConnection\nimport asyncpg\n\nconn = DBConnection(\n    await asyncpg.connect(\n        host="localhost",\n        port=5432,\n        user="db_user",\n        password="yoursecretpassword",\n        database="your_db",\n    )\n)\n```\n\nThe Person class currently just lives in memory. To back it with a full\ndatabase table, we can run raw SQL or run a migration to add it:\n\n```python\nawait conn.conn.execute(\n    """\n    CREATE TABLE IF NOT EXISTS person (\n        id SERIAL PRIMARY KEY,\n        name TEXT NOT NULL,\n        age INT NOT NULL\n    )\n    """\n)\n```\n\n### Inserting Data\n\nInstantiate object classes as you normally do:\n\n```python\npeople = [\n    Person(name="Alice", age=30),\n    Person(name="Bob", age=40),\n    Person(name="Charlie", age=50),\n]\nawait conn.insert(people)\n\nprint(people[0].id) # 1\nprint(people[1].id) # 2\n```\n\nBecause we\'re using an auto-incrementing primary key, the `id` field will be populated after the insert.\nIceaxe will automatically update the object in place with the newly assigned value.\n\n### Updating data\n\nNow that we have these lovely people, let\'s modify them.\n\n```python\nperson = people[0]\nperson.name = "Blice"\n```\n\nRight now, we have a Python object that\'s out of state with the database. But that\'s often okay. We can inspect it\nand further write logic - it\'s fully decoupled from the database.\n\n```python\ndef ensure_b_letter(person: Person):\n    if person.name[0].lower() != "b":\n        raise ValueError("Name must start with \'B\'")\n\nensure_b_letter(person)\n```\n\nTo sync the values back to the database, we can call `update`:\n\n```python\nawait conn.update([person])\n```\n\nIf we were to query the database directly, we see that the name has been updated:\n\n```\nid | name  | age\n----+-------+-----\n  1 | Blice |  31\n  2 | Bob   |  40\n  3 | Charlie | 50\n```\n\nBut no other fields have been touched. This lets a potentially concurrent process\nmodify `Alice`\'s record - say, updating the age to 31. By the time we update the data, we\'ll\nchange the name but nothing else. Under the hood we do this by tracking the fields that\nhave been modified in-memory and creating a targeted UPDATE to modify only those values.\n\n### Selecting data\n\nTo select data, we can use a `QueryBuilder`. For a shortcut to `select` query functions,\nyou can also just import select directly. This method takes the desired value parameters\nand returns a list of the desired objects.\n\n```python\nfrom iceaxe import select\n\nquery = select(Person).where(Person.name == "Blice", Person.age > 25)\nresults = await conn.exec(query)\n```\n\nIf we inspect the typing of `results`, we see that it\'s a `list[Person]` objects. This matches\nthe typehint of the `select` function. You can also target columns directly:\n\n```python\nquery = select((Person.id, Person.name)).where(Person.age > 25)\nresults = await conn.exec(query)\n```\n\nThis will return a list of tuples, where each tuple is the id and name of the person: `list[tuple[int, str]]`.\n\nWe support most of the common SQL operations. Just like the results, these are typehinted\nto their proper types as well. Static typecheckers and your IDE will throw an error if you try to compare\na string column to an integer, for instance. A more complex example of a query:\n\n```python\nquery = select((\n    Person.id,\n    FavoriteColor,\n)).join(\n    FavoriteColor,\n    Person.id == FavoriteColor.person_id,\n).where(\n    Person.age > 25,\n    Person.name == "Blice",\n).order_by(\n    Person.age.desc(),\n).limit(10)\nresults = await conn.exec(query)\n```\n\nAs expected this will deliver results - and typehint - as a `list[tuple[int, FavoriteColor]]`\n\n## Production\n\n> [!IMPORTANT]\n> Iceaxe is in early alpha. We\'re using it internally and showly rolling out to our production\napplications, but we\'re not yet ready to recommend it for general use. The API and larger\nstability is subject to change.\n\nNote that underlying Postgres connection wrapped by `conn` will be alive for as long as your object is in memory. This uses up one\nof the allowable connections to your database. Your overall limit depends on your Postgres configuration\nor hosting provider, but most managed solutions top out around 150-300. If you need more concurrent clients\nconnected (and even if you don\'t - connection creation at the Postgres level is expensive), you can adopt\na load balancer like `pgbouncer` to better scale to traffic. More deployment notes to come.\n\nIt\'s also worth noting the absence of request pooling in this initialization. This is a feature of many ORMs that lets you limit\nthe overall connections you make to Postgres, and re-use these over time. We specifically don\'t offer request\npooling as part of Iceaxe, despite being supported by our underlying engine `asyncpg`. This is a bit more\naligned to how things should be structured in production. Python apps are always bound to one process thanks to\nthe GIL. So no matter what your connection pool will always be tied to the current Python process / runtime. When you\'re deploying onto a server with multiple cores, the pool will be duplicated across CPUs and largely defeats the purpose of capping\nnetwork connections in the first place.\n\n## Benchmarking\n\nWe have basic benchmarking tests in the `__tests__/benchmarks` directory. To run them, you\'ll need to execute the pytest suite:\n\n```bash\npoetry run pytest -m integration_tests\n```\n\nCurrent benchmarking as of October 11 2024 is:\n\n|                   | raw asyncpg | iceaxe | external overhead                             |   |\n|-------------------|-------------|--------|-----------------------------------------------|---|\n| TableBase columns | 0.098s      | 0.093s |                                               |   |\n| TableBase full    | 0.164s      | 1.345s | 10%: dict construction | 90%: pydantic overhead |   |\n\n## Development\n\nIf you update your Cython implementation during development, you\'ll need to re-compile the Cython code. This can be done with\na simple poetry install. Poetry is set up to create a dynamic `setup.py` based on our `build.py` definition.\n\n```bash\npoetry install\n```\n\n## TODOs\n\n- [ ] Additional documentation with usage examples.\n',
     'author': 'Pierce Freeman',

iceaxe-0.2.1/iceaxe/__tests__/conf_models.py

@@ -1,41 +0,0 @@
-from contextlib import contextmanager
-from pathlib import Path
-
-from pyinstrument import Profiler
-
-from iceaxe.base import Field, TableBase
-
-
-class UserDemo(TableBase):
-    id: int = Field(primary_key=True, default=None)
-    name: str
-    email: str
-
-
-class ArtifactDemo(TableBase):
-    id: int = Field(primary_key=True, default=None)
-    title: str
-    user_id: int = Field(foreign_key="userdemo.id")
-
-
-class ComplexDemo(TableBase):
-    id: int = Field(primary_key=True, default=None)
-    string_list: list[str]
-    json_data: dict[str, str] = Field(is_json=True)
-
-
-@contextmanager
-def run_profile(request):
-    TESTS_ROOT = Path.cwd()
-    PROFILE_ROOT = TESTS_ROOT / ".profiles"
-
-    # Turn profiling on
-    profiler = Profiler()
-    profiler.start()
-
-    yield  # Run test
-
-    profiler.stop()
-    PROFILE_ROOT.mkdir(exist_ok=True)
-    results_file = PROFILE_ROOT / f"{request.node.name}.html"
-    profiler.write_html(results_file)