iceaxe 0.2.3.dev2__tar.gz → 0.2.3.dev4__tar.gz

{iceaxe-0.2.3.dev2 → iceaxe-0.2.3.dev4}/PKG-INFO

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

iceaxe-0.2.3.dev4/iceaxe/__tests__/helpers.py

@@ -0,0 +1,263 @@
+import ast
+import inspect
+import os
+from contextlib import contextmanager
+from dataclasses import dataclass
+from json import JSONDecodeError, dump as json_dump, loads as json_loads
+from re import Pattern
+from tempfile import NamedTemporaryFile, TemporaryDirectory
+from textwrap import dedent
+
+from pyright import run
+
+
+@dataclass
+class PyrightDiagnostic:
+    file: str
+    severity: str
+    message: str
+    rule: str | None
+    line: int
+    column: int
+
+
+class ExpectedPyrightError(Exception):
+    """
+    Exception raised when Pyright doesn't produce the expected error
+
+    """
+
+    pass
+
+
+def get_imports_from_module(module_source: str) -> set[str]:
+    """
+    Extract all import statements from module source
+
+    """
+    tree = ast.parse(module_source)
+    imports: set[str] = set()
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for name in node.names:
+                imports.add(f"import {name.name}")
+        elif isinstance(node, ast.ImportFrom):
+            names = ", ".join(name.name for name in node.names)
+            if node.module is None:
+                # Handle "from . import x" case
+                imports.add(f"from . import {names}")
+            else:
+                imports.add(f"from {node.module} import {names}")
+
+    return imports
+
+
+def strip_type_ignore(line: str) -> str:
+    """
+    Strip type: ignore comments from a line while preserving the line content
+
+    """
+    if "#" not in line:
+        return line
+
+    # Split only on the first #
+    code_part, *comment_parts = line.split("#", 1)
+    if not comment_parts:
+        return line
+
+    comment = comment_parts[0]
+    # If this is a type: ignore comment, return just the code
+    if "type:" in comment and "ignore" in comment:
+        return code_part.rstrip()
+
+    # Otherwise return the full line
+    return line
+
+
+def extract_current_function_code():
+    """
+    Extracts the source code of the function calling this utility,
+    along with any necessary imports at the module level. This only works for
+    functions in a pytest testing context that are prefixed with `test_`.
+
+    """
+    # Get the frame of the calling function
+    frame = inspect.currentframe()
+
+    try:
+        # Go up until we find the test function; workaround to not
+        # knowing the entrypoint of our contextmanager at runtime
+        while frame is not None:
+            func_name = frame.f_code.co_name
+            if func_name.startswith("test_"):
+                test_frame = frame
+                break
+            frame = frame.f_back
+        else:
+            raise RuntimeError("Could not find test function frame")
+
+        # Source code of the function
+        func_source = inspect.getsource(test_frame.f_code)
+
+        # Source code of the larger test file, which contains the test function
+        # All the imports used by the test function should be within this file
+        module = inspect.getmodule(test_frame)
+        if not module:
+            raise RuntimeError("Could not find module for test function")
+
+        module_source = inspect.getsource(module)
+
+        # Postprocess the source code to build into a valid new module
+        imports = get_imports_from_module(module_source)
+        filtered_lines = [strip_type_ignore(line) for line in func_source.split("\n")]
+        return "\n".join(sorted(imports)) + "\n\n" + dedent("\n".join(filtered_lines))
+
+    finally:
+        del frame  # Avoid reference cycles
+
+
+def create_pyright_config():
+    """
+    Creates a new pyright configuration that ignores unused imports or other
+    issues that are not related to context-manager wrapped type checking.
+
+    """
+    return {
+        "include": ["."],
+        "exclude": [],
+        "ignore": [],
+        "strict": [],
+        "typeCheckingMode": "strict",
+        "reportUnusedImport": False,
+        "reportUnusedVariable": False,
+        # Focus only on type checking
+        "reportOptionalMemberAccess": True,
+        "reportGeneralTypeIssues": True,
+        "reportPropertyTypeMismatch": True,
+        "reportFunctionMemberAccess": True,
+        "reportTypeCommentUsage": True,
+        "reportMissingTypeStubs": False,
+        # Only typehint intentional typehints, not inferred values
+        "reportUnknownParameterType": False,
+        "reportUnknownVariableType": False,
+        "reportUnknownMemberType": False,
+        "reportUnknownArgumentType": False,
+        "reportMissingParameterType": False,
+    }
+
+
+def run_pyright(file_path: str) -> list[PyrightDiagnostic]:
+    """
+    Run pyright on a file and return the diagnostics
+
+    """
+    try:
+        with TemporaryDirectory() as temp_dir:
+            # Create pyright config
+            config_path = os.path.join(temp_dir, "pyrightconfig.json")
+            with open(config_path, "w") as f:
+                json_dump(create_pyright_config(), f)
+
+            # Copy the file to analyze into the project directory
+            test_file = os.path.join(temp_dir, "test.py")
+            with open(file_path, "r") as src, open(test_file, "w") as dst:
+                dst.write(src.read())
+
+            # Run pyright with the config
+            result = run(
+                "--project",
+                temp_dir,
+                "--outputjson",
+                test_file,
+                capture_output=True,
+                text=True,
+            )
+
+            try:
+                output = json_loads(result.stdout)
+            except JSONDecodeError:
+                print(f"Failed to parse pyright output: {result.stdout}")  # noqa: T201
+                print(f"Stderr: {result.stderr}")  # noqa: T201
+                raise
+
+            if "generalDiagnostics" not in output:
+                raise RuntimeError(
+                    f"Unknown pyright output, missing generalDiagnostics: {output}"
+                )
+
+            diagnostics: list[PyrightDiagnostic] = []
+            for diag in output["generalDiagnostics"]:
+                diagnostics.append(
+                    PyrightDiagnostic(
+                        file=diag["file"],
+                        severity=diag["severity"],
+                        message=diag["message"],
+                        rule=diag.get("rule"),
+                        line=diag["range"]["start"]["line"] + 1,  # Convert to 1-based
+                        column=(
+                            diag["range"]["start"]["character"]
+                            + 1  # Convert to 1-based
+                        ),
+                    )
+                )
+
+            return diagnostics
+
+    except Exception as e:
+        raise RuntimeError(f"Failed to run pyright: {str(e)}")
+
+
+@contextmanager
+def pyright_raises(
+    expected_rule: str,
+    expected_line: int | None = None,
+    matches: Pattern | None = None,
+):
+    """
+    Context manager that verifies code produces a specific Pyright error.
+
+    :params expected_rule: The Pyright rule that should be violated
+    :params expected_line: Optional line number where the error should occur
+
+    :raises ExpectedPyrightError: If Pyright doesn't produce the expected error
+
+    """
+    # Create a temporary file to store the code
+    with NamedTemporaryFile(mode="w", suffix=".py") as temp_file:
+        temp_path = temp_file.name
+
+        # Extract the source code of the calling function
+        source_code = extract_current_function_code()
+        print(f"Running Pyright on:\n{source_code}")  # noqa: T201
+
+        # Write the source code to the temporary file
+        temp_file.write(source_code)
+        temp_file.flush()
+
+        # At runtime, our actual code is probably a no-op but we still let it run
+        # inside the scope of the contextmanager
+        yield
+
+        # Run Pyright on the temporary file
+        diagnostics = run_pyright(temp_path)
+
+        # Check if any of the diagnostics match our expected error
+        for diagnostic in diagnostics:
+            if diagnostic.rule == expected_rule:
+                if expected_line is not None and diagnostic.line != expected_line:
+                    continue
+                if matches and not matches.search(diagnostic.message):
+                    continue
+                # Found matching error
+                return
+
+        # If we get here, we didn't find the expected error
+        actual_errors = [
+            f"{d.rule or 'unknown'} on line {d.line}: {d.message}" for d in diagnostics
+        ]
+        raise ExpectedPyrightError(
+            f"Expected Pyright error {expected_rule}"
+            f"{f' on line {expected_line}' if expected_line else ''}"
+            f" but got: {', '.join(actual_errors) if actual_errors else 'no errors'}"
+        )

{iceaxe-0.2.3.dev2 → iceaxe-0.2.3.dev4}/iceaxe/__tests__/test_comparison.py

@@ -1,10 +1,14 @@
+from re import compile as re_compile
 from typing import Any
 
 import pytest
+from typing_extensions import assert_type
 
+from iceaxe.__tests__.helpers import pyright_raises
 from iceaxe.base import TableBase
 from iceaxe.comparison import ComparisonType, FieldComparison
 from iceaxe.field import DBFieldClassDefinition, DBFieldInfo
+from iceaxe.typing import column
 
 
 def test_comparison_type_enum():
@@ -17,6 +21,9 @@ def test_comparison_type_enum():
     assert ComparisonType.IN == "IN"
     assert ComparisonType.NOT_IN == "NOT IN"
     assert ComparisonType.LIKE == "LIKE"
+    assert ComparisonType.NOT_LIKE == "NOT LIKE"
+    assert ComparisonType.ILIKE == "ILIKE"
+    assert ComparisonType.NOT_ILIKE == "NOT ILIKE"
     assert ComparisonType.IS == "IS"
     assert ComparisonType.IS_NOT == "IS NOT"
 
@@ -158,3 +165,31 @@ def test_comparison_with_different_types(db_field: DBFieldClassDefinition, value
         assert result.left == db_field
         assert isinstance(result.comparison, ComparisonType)
         assert result.right == value
+
+
+#
+# Typehinting
+# These checks are run as part of the static typechecking we do
+# for our codebase, not as part of the pytest runtime.
+#
+
+
+def test_typehint_ilike():
+    class UserDemo(TableBase):
+        id: int
+        value_str: str
+        value_int: int
+
+    str_col = column(UserDemo.value_str)
+    int_col = column(UserDemo.value_int)
+
+    assert_type(str_col, DBFieldClassDefinition[str])
+    assert_type(int_col, DBFieldClassDefinition[int])
+
+    assert_type(str_col.ilike("test"), bool)
+
+    with pyright_raises(
+        "reportAttributeAccessIssue",
+        matches=re_compile('Cannot access attribute "ilike"'),
+    ):
+        int_col.ilike(5)  # type: ignore

iceaxe-0.2.3.dev4/iceaxe/__tests__/test_helpers.py

@@ -0,0 +1,9 @@
+from iceaxe.__tests__.helpers import pyright_raises
+
+
+def test_basic_type_error():
+    def type_error_func(x: int) -> int:
+        return 10
+
+    with pyright_raises("reportArgumentType"):
+        type_error_func("20")  # type: ignore

{iceaxe-0.2.3.dev2 → iceaxe-0.2.3.dev4}/iceaxe/__tests__/test_queries.py

@@ -267,3 +267,13 @@ def test_select_multiple_typehints():
     query = select((UserDemo, UserDemo.id, UserDemo.name))
     if TYPE_CHECKING:
         _: QueryBuilder[tuple[UserDemo, int, str], Literal["SELECT"]] = query
+
+
+def test_allow_branching():
+    base_query = select(UserDemo)
+
+    query_1 = base_query.limit(1)
+    query_2 = base_query.limit(2)
+
+    assert query_1.limit_value == 1
+    assert query_2.limit_value == 2

{iceaxe-0.2.3.dev2 → iceaxe-0.2.3.dev4}/iceaxe/__tests__/test_session.py

@@ -442,6 +442,32 @@ async def test_select_with_left_join(db_connection: DBConnection):
     assert result[1] == ("John", 2)
 
 
+@pytest.mark.asyncio
+async def test_select_with_left_join_object(db_connection: DBConnection):
+    users = [
+        UserDemo(name="John", email="john@example.com"),
+        UserDemo(name="Jane", email="jane@example.com"),
+    ]
+    await db_connection.insert(users)
+
+    posts = [
+        ArtifactDemo(title="John's Post", user_id=users[0].id),
+        ArtifactDemo(title="Another Post", user_id=users[0].id),
+    ]
+    await db_connection.insert(posts)
+
+    query = (
+        QueryBuilder()
+        .select((UserDemo, ArtifactDemo))
+        .join(ArtifactDemo, UserDemo.id == ArtifactDemo.user_id, "LEFT")
+    )
+    result = await db_connection.exec(query)
+    assert len(result) == 3
+    assert result[0] == (users[0], posts[0])
+    assert result[1] == (users[0], posts[1])
+    assert result[2] == (users[1], None)
+
+
 # @pytest.mark.asyncio
 # async def test_select_with_subquery(db_connection: DBConnection):
 #     users = [

{iceaxe-0.2.3.dev2 → iceaxe-0.2.3.dev4}/iceaxe/comparison.py

@@ -7,6 +7,7 @@ from iceaxe.queries_str import QueryElementBase, QueryLiteral
 from iceaxe.typing import is_column, is_comparison, is_comparison_group
 
 T = TypeVar("T", bound="ComparisonBase")
+J = TypeVar("J")
 
 
 class ComparisonType(StrEnum):
@@ -18,7 +19,12 @@ class ComparisonType(StrEnum):
     GE = ">="
     IN = "IN"
     NOT_IN = "NOT IN"
+
     LIKE = "LIKE"
+    NOT_LIKE = "NOT LIKE"
+    ILIKE = "ILIKE"
+    NOT_ILIKE = "NOT ILIKE"
+
     IS = "IS"
     IS_NOT = "IS NOT"
 
@@ -95,7 +101,7 @@ class FieldComparisonGroup:
         return QueryLiteral(queries), all_variables
 
 
-class ComparisonBase(ABC):
+class ComparisonBase(ABC, Generic[J]):
     def __eq__(self, other):  # type: ignore
         if other is None:
             return self._compare(ComparisonType.IS, None)
@@ -124,9 +130,26 @@ class ComparisonBase(ABC):
     def not_in(self, other) -> bool:
         return self._compare(ComparisonType.NOT_IN, other)  # type: ignore
 
-    def like(self, other) -> bool:
+    def like(
+        self: "ComparisonBase[str] | ComparisonBase[str | None]", other: str
+    ) -> bool:
         return self._compare(ComparisonType.LIKE, other)  # type: ignore
 
+    def not_like(
+        self: "ComparisonBase[str] | ComparisonBase[str | None]", other: str
+    ) -> bool:
+        return self._compare(ComparisonType.NOT_LIKE, other)  # type: ignore
+
+    def ilike(
+        self: "ComparisonBase[str] | ComparisonBase[str | None]", other: str
+    ) -> bool:
+        return self._compare(ComparisonType.ILIKE, other)  # type: ignore
+
+    def not_ilike(
+        self: "ComparisonBase[str] | ComparisonBase[str | None]", other: str
+    ) -> bool:
+        return self._compare(ComparisonType.NOT_ILIKE, other)  # type: ignore
+
     def _compare(self, comparison: ComparisonType, other: Any) -> FieldComparison[Self]:
         return FieldComparison(left=self, comparison=comparison, right=other)
 

{iceaxe-0.2.3.dev2 → iceaxe-0.2.3.dev4}/iceaxe/field.py

@@ -4,8 +4,10 @@ from typing import (
     Any,
     Callable,
     Concatenate,
+    Generic,
     ParamSpec,
     Type,
+    TypeVar,
     Unpack,
     cast,
 )
@@ -139,7 +141,10 @@ def __get_db_field(_: Callable[Concatenate[Any, P], Any] = PydanticField):  # ty
     return func
 
 
-class DBFieldClassDefinition(ComparisonBase):
+T = TypeVar("T")
+
+
+class DBFieldClassDefinition(Generic[T], ComparisonBase[T]):
     root_model: Type["TableBase"]
     key: str
     field_definition: DBFieldInfo

{iceaxe-0.2.3.dev2 → iceaxe-0.2.3.dev4}/iceaxe/queries.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from copy import copy
+from functools import wraps
 from typing import Any, Generic, Literal, Type, TypeVar, TypeVarTuple, cast, overload
 
 from iceaxe.base import (
@@ -53,6 +55,22 @@ JoinType = Literal["INNER", "LEFT", "RIGHT", "FULL"]
 OrderDirection = Literal["ASC", "DESC"]
 
 
+def allow_branching(fn):
+    """
+    Allows query method modifiers to implement their logic as if `self` is being
+    modified, but in the background we'll actually return a new instance of the
+    query builder to allow for branching of the same underlying query.
+
+    """
+
+    @wraps(fn)
+    def new_fn(self, *args, **kwargs):
+        self = copy(self)
+        return fn(self, *args, **kwargs)
+
+    return new_fn
+
+
 class QueryBuilder(Generic[P, QueryType]):
     """
     The QueryBuilder owns all construction of the SQL string given
@@ -118,6 +136,7 @@ class QueryBuilder(Generic[P, QueryType]):
         self, fields: tuple[T | Type[T], T2 | Type[T2], T3 | Type[T3], *Ts]
     ) -> QueryBuilder[tuple[T, T2, T3, *Ts], Literal["SELECT"]]: ...
 
+    @allow_branching
     def select(
         self,
         fields: (
@@ -212,6 +231,7 @@ class QueryBuilder(Generic[P, QueryType]):
                 self.select_raw.append(field)
                 self.select_aggregate_count += 1
 
+    @allow_branching
     def update(self, model: Type[TableBase]) -> QueryBuilder[None, Literal["UPDATE"]]:
         """
         Creates a new update query for the given model. Returns the same
@@ -222,6 +242,7 @@ class QueryBuilder(Generic[P, QueryType]):
         self.main_model = model
         return self  # type: ignore
 
+    @allow_branching
     def delete(self, model: Type[TableBase]) -> QueryBuilder[None, Literal["DELETE"]]:
         """
         Creates a new delete query for the given model. Returns the same
@@ -232,6 +253,7 @@ class QueryBuilder(Generic[P, QueryType]):
         self.main_model = model
         return self  # type: ignore
 
+    @allow_branching
     def where(self, *conditions: bool):
         """
         Adds a where condition to the query. The conditions are combined with
@@ -250,6 +272,7 @@ class QueryBuilder(Generic[P, QueryType]):
         self.where_conditions += validated_comparisons
         return self
 
+    @allow_branching
     def order_by(self, field: Any, direction: OrderDirection = "ASC"):
         """
         Adds an order by clause to the query. The field must be a column.
@@ -265,6 +288,7 @@ class QueryBuilder(Generic[P, QueryType]):
         self.order_by_clauses.append(f"{field_token} {direction}")
         return self
 
+    @allow_branching
     def join(self, table: Type[TableBase], on: bool, join_type: JoinType = "INNER"):
         """
         Adds a join clause to the query. The `on` parameter should be a comparison
@@ -289,6 +313,7 @@ class QueryBuilder(Generic[P, QueryType]):
         self.join_clauses.append(join_sql)
         return self
 
+    @allow_branching
     def set(self, column: T, value: T | None):
         """
         Sets a column to a specific value in an update query.
@@ -300,6 +325,7 @@ class QueryBuilder(Generic[P, QueryType]):
         self.update_values.append((column, value))
         return self
 
+    @allow_branching
     def limit(self, value: int):
         """
         Limit the number of rows returned by the query. Useful in pagination
@@ -309,6 +335,7 @@ class QueryBuilder(Generic[P, QueryType]):
         self.limit_value = value
         return self
 
+    @allow_branching
     def offset(self, value: int):
         """
         Offset the number of rows returned by the query.
@@ -317,6 +344,7 @@ class QueryBuilder(Generic[P, QueryType]):
         self.offset_value = value
         return self
 
+    @allow_branching
     def group_by(self, *fields: Any):
         """
         Groups the results of the query by the given fields. This allows
@@ -334,6 +362,7 @@ class QueryBuilder(Generic[P, QueryType]):
         self.group_by_fields = valid_fields
         return self
 
+    @allow_branching
     def having(self, *conditions: bool):
         """
         Require the result of an aggregation query like func.sum(MyTable.column)
@@ -351,6 +380,7 @@ class QueryBuilder(Generic[P, QueryType]):
         self.having_conditions += valid_conditions
         return self
 
+    @allow_branching
     def text(self, query: str, *variables: Any):
         """
         Override the ORM builder and use a raw SQL query instead.

{iceaxe-0.2.3.dev2 → iceaxe-0.2.3.dev4}/iceaxe/session_optimized.pyx

@@ -98,6 +98,7 @@ cdef list process_values(
     cdef object field_value
     cdef object select_raw
     cdef PyObject* temp_obj
+    cdef bint all_none
 
     for i in range(num_values):
         value = values[i]
@@ -112,6 +113,9 @@ cdef list process_values(
                 if raw_is_table:
                     obj_dict = {}
                     num_fields = num_fields_array[j]
+                    all_none = True
+
+                    # First pass: collect all fields and check if they're all None
                     for k in range(num_fields):
                         field_name_c = fields[j][k].name
                         select_name_c = fields[j][k].select_attribute
@@ -119,22 +123,29 @@ cdef list process_values(
                         select_name = select_name_c.decode('utf-8')
 
                         try:
-                            field_value = value[select_name]  # Use Python dictionary access instead of PyObject_GetItem
+                            field_value = value[select_name]
                         except KeyError:
                             raise KeyError(f"Key '{select_name}' not found in value.")
 
-                        if fields[j][k].is_json:
-                            field_value = json_loads(field_value)
+                        if field_value is not None:
+                            all_none = False
+                            if fields[j][k].is_json:
+                                field_value = json_loads(field_value)
 
                         obj_dict[field_name] = field_value
 
-                    obj = select_raw(**obj_dict)
-                    result_value[j] = <PyObject*>obj
-                    Py_INCREF(obj)  # Increment reference count for the stored object
+                    # If all fields are None, store None instead of creating the table object
+                    if all_none:
+                        result_value[j] = <PyObject*>None
+                        Py_INCREF(None)
+                    else:
+                        obj = select_raw(**obj_dict)
+                        result_value[j] = <PyObject*>obj
+                        Py_INCREF(obj)
 
                 elif raw_is_column:
                     try:
-                        item = value[select_raw.key]  # Use Python dictionary access
+                        item = value[select_raw.key]
                     except KeyError:
                         raise KeyError(f"Key '{select_raw.key}' not found in value.")
                     result_value[j] = <PyObject*>item
@@ -142,7 +153,7 @@ cdef list process_values(
 
                 elif raw_is_function_metadata:
                     try:
-                        item = value[select_raw.local_name]  # Use Python dictionary access
+                        item = value[select_raw.local_name]
                     except KeyError:
                         raise KeyError(f"Key '{select_raw.local_name}' not found in value.")
                     result_value[j] = <PyObject*>item
@@ -151,11 +162,11 @@ cdef list process_values(
             # Assemble the result
             if num_selects == 1:
                 result_all[i] = <object>result_value[0]
-                Py_DECREF(<object>result_value[0])  # Decrement reference count
+                Py_DECREF(<object>result_value[0])
             else:
                 result_tuple = tuple([<object>result_value[j] for j in range(num_selects)])
                 for j in range(num_selects):
-                    Py_DECREF(<object>result_value[j])  # Decrement reference count for each item
+                    Py_DECREF(<object>result_value[j])
                 result_all[i] = result_tuple
 
         finally:

{iceaxe-0.2.3.dev2 → iceaxe-0.2.3.dev4}/iceaxe/typing.py

@@ -8,6 +8,7 @@ from typing import (
     Any,
     Type,
     TypeGuard,
+    TypeVar,
 )
 from uuid import UUID
 
@@ -27,6 +28,8 @@ PRIMITIVE_WRAPPER_TYPES = list[PRIMITIVE_TYPES] | PRIMITIVE_TYPES
 DATE_TYPES = datetime | date | time | timedelta
 JSON_WRAPPER_FALLBACK = list[Any] | dict[Any, Any]
 
+T = TypeVar("T")
+
 
 def is_base_table(obj: Any) -> TypeGuard[type[TableBase]]:
     from iceaxe.base import TableBase
@@ -34,7 +37,7 @@ def is_base_table(obj: Any) -> TypeGuard[type[TableBase]]:
     return isclass(obj) and issubclass(obj, TableBase)
 
 
-def is_column(obj: Any) -> TypeGuard[DBFieldClassDefinition]:
+def is_column(obj: T) -> TypeGuard[DBFieldClassDefinition[T]]:
     from iceaxe.base import DBFieldClassDefinition
 
     return isinstance(obj, DBFieldClassDefinition)
@@ -64,7 +67,7 @@ def is_function_metadata(obj: Any) -> TypeGuard[FunctionMetadata]:
     return isinstance(obj, FunctionMetadata)
 
 
-def column(obj: Any):
+def column(obj: T) -> DBFieldClassDefinition[T]:
     if not is_column(obj):
         raise ValueError(f"Invalid column: {obj}")
     return obj

{iceaxe-0.2.3.dev2 → iceaxe-0.2.3.dev4}/pyproject.toml

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

{iceaxe-0.2.3.dev2 → iceaxe-0.2.3.dev4}/setup.py

@@ -22,7 +22,7 @@ install_requires = \
 
 setup_kwargs = {
     'name': 'iceaxe',
-    'version': '0.2.3.dev2',
+    'version': '0.2.3.dev4',
     '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',