iceaxe 0.8.3__cp313-cp313-macosx_11_0_arm64.whl

iceaxe/session_optimized.pyx

@@ -0,0 +1,212 @@
+from typing import Any, List, Tuple
+from iceaxe.base import TableBase
+from iceaxe.queries import FunctionMetadata
+from iceaxe.alias_values import Alias
+from json import loads as json_loads
+from cpython.ref cimport PyObject
+from cpython.object cimport PyObject_GetItem
+from libc.stdlib cimport malloc, free
+from libc.string cimport memcpy
+from cpython.ref cimport Py_INCREF, Py_DECREF
+
+cdef struct FieldInfo:
+    char* name                # Field name
+    char* select_attribute    # Corresponding attribute in the select_raw
+    bint is_json              # Flag indicating if the field is JSON
+
+cdef char* allocate_cstring(bytes data):
+    cdef Py_ssize_t length = len(data)
+    cdef char* c_str = <char*>malloc((length + 1) * sizeof(char))
+    if not c_str:
+        raise MemoryError("Failed to allocate memory for C string.")
+    memcpy(c_str, <char*>data, length)  # Cast bytes to char* for memcpy
+    c_str[length] = 0  # Null-terminate the string
+    return c_str
+
+cdef void free_fields(FieldInfo** fields, Py_ssize_t* num_fields_array, Py_ssize_t num_selects):
+    cdef Py_ssize_t j, k
+    if fields:
+        for j in range(num_selects):
+            if fields[j]:
+                for k in range(num_fields_array[j]):
+                    free(fields[j][k].name)
+                    free(fields[j][k].select_attribute)
+                free(fields[j])
+        free(fields)
+    if num_fields_array:
+        free(num_fields_array)
+
+cdef FieldInfo** precompute_fields(list select_raws, list select_types, Py_ssize_t num_selects, Py_ssize_t* num_fields_array):
+    cdef FieldInfo** fields = <FieldInfo**>malloc(num_selects * sizeof(FieldInfo*))
+    cdef Py_ssize_t j, k, num_fields
+    cdef dict field_dict
+    cdef bytes select_bytes, field_bytes
+    cdef char* c_select
+    cdef char* c_field
+    cdef object select_raw
+    cdef bint raw_is_table, raw_is_column, raw_is_function_metadata
+
+    if not fields:
+        raise MemoryError("Failed to allocate memory for fields.")
+
+    for j in range(num_selects):
+        select_raw = select_raws[j]
+        raw_is_table, raw_is_column, raw_is_function_metadata = select_types[j]
+
+        if raw_is_table:
+            field_dict = {field: info.is_json for field, info in select_raw.get_client_fields().items() if not info.exclude}
+            num_fields = len(field_dict)
+            num_fields_array[j] = num_fields
+            fields[j] = <FieldInfo*>malloc(num_fields * sizeof(FieldInfo))
+            if not fields[j]:
+                raise MemoryError("Failed to allocate memory for FieldInfo.")
+
+            for k, (field, is_json) in enumerate(field_dict.items()):
+                select_bytes = f"{select_raw.get_table_name()}_{field}".encode('utf-8')
+                c_select = allocate_cstring(select_bytes)
+
+                field_bytes = field.encode('utf-8')
+                c_field = allocate_cstring(field_bytes)
+
+                fields[j][k].select_attribute = c_select
+                fields[j][k].name = c_field
+                fields[j][k].is_json = is_json
+        else:
+            num_fields_array[j] = 0
+            fields[j] = NULL
+
+    return fields
+
+cdef list process_values(
+    list values,
+    FieldInfo** fields,
+    Py_ssize_t* num_fields_array,
+    list select_raws,
+    list select_types,
+    Py_ssize_t num_selects
+):
+    cdef Py_ssize_t num_values = len(values)
+    cdef list result_all = [None] * num_values
+    cdef Py_ssize_t i, j, k, num_fields
+    cdef PyObject** result_value
+    cdef object value, obj, item
+    cdef dict obj_dict
+    cdef bint raw_is_table, raw_is_column, raw_is_function_metadata, raw_is_alias
+    cdef char* field_name_c
+    cdef char* select_name_c
+    cdef str field_name
+    cdef str select_name
+    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]
+        result_value = <PyObject**>malloc(num_selects * sizeof(PyObject*))
+        if not result_value:
+            raise MemoryError("Failed to allocate memory for result_value.")
+        try:
+            for j in range(num_selects):
+                select_raw = select_raws[j]
+                raw_is_table, raw_is_column, raw_is_function_metadata = select_types[j]
+                raw_is_alias = isinstance(select_raw, Alias)
+
+                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
+                        field_name = field_name_c.decode('utf-8')
+                        select_name = select_name_c.decode('utf-8')
+
+                        try:
+                            field_value = value[select_name]
+                        except KeyError:
+                            raise KeyError(f"Key '{select_name}' not found in 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
+
+                    # 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:
+                        # Use the table-qualified column name
+                        table_name = select_raw.root_model.get_table_name()
+                        column_name = select_raw.key
+                        item = value[f"{table_name}_{column_name}"]
+                    except KeyError:
+                        raise KeyError(f"Key '{table_name}_{column_name}' not found in value.")
+                    result_value[j] = <PyObject*>item
+                    Py_INCREF(item)
+
+                elif raw_is_function_metadata:
+                    try:
+                        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
+                    Py_INCREF(item)
+
+                elif raw_is_alias:
+                    try:
+                        item = value[select_raw.name]
+                    except KeyError:
+                        raise KeyError(f"Key '{select_raw.name}' not found in value.")
+                    result_value[j] = <PyObject*>item
+                    Py_INCREF(item)
+
+            # Assemble the result
+            if num_selects == 1:
+                result_all[i] = <object>result_value[0]
+                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])
+                result_all[i] = result_tuple
+
+        finally:
+            free(result_value)
+
+    return result_all
+
+cdef list optimize_casting(list values, list select_raws, list select_types):
+    cdef Py_ssize_t num_selects = len(select_raws)
+    cdef Py_ssize_t* num_fields_array = <Py_ssize_t*>malloc(num_selects * sizeof(Py_ssize_t))
+    cdef FieldInfo** fields
+    cdef list result_all
+
+    if not num_fields_array:
+        raise MemoryError("Failed to allocate memory for num_fields_array.")
+
+    try:
+        fields = precompute_fields(select_raws, select_types, num_selects, num_fields_array)
+        result_all = process_values(values, fields, num_fields_array, select_raws, select_types, num_selects)
+    finally:
+        free_fields(fields, num_fields_array, num_selects)
+
+    return result_all
+
+def optimize_exec_casting(
+    values: List[Any],
+    select_raws: List[Any],
+    select_types: List[Tuple[bool, bool, bool]]
+) -> List[Any]:
+    return optimize_casting(values, select_raws, select_types)

iceaxe/sql_types.py

@@ -0,0 +1,149 @@
+from datetime import date, datetime, time, timedelta
+from enum import Enum, StrEnum
+from uuid import UUID
+
+
+class ColumnType(StrEnum):
+    # The values of the enum are the actual SQL types. When constructing
+    # the column they can be case-insensitive, but when we're casting from
+    # the database to memory they must align with the on-disk representation
+    # which is lowercase.
+    #
+    # Note: The SQL standard requires that writing just "timestamp" be equivalent
+    # to "timestamp without time zone", and PostgreSQL honors that behavior.
+    # Similarly, "time" is equivalent to "time without time zone".
+
+    # Numeric Types
+    SMALLINT = "smallint"
+    INTEGER = "integer"
+    BIGINT = "bigint"
+    DECIMAL = "decimal"
+    NUMERIC = "numeric"
+    REAL = "real"
+    DOUBLE_PRECISION = "double precision"
+    SERIAL = "serial"
+    BIGSERIAL = "bigserial"
+    SMALLSERIAL = "smallserial"
+
+    # Monetary Type
+    MONEY = "money"
+
+    # Character Types
+    CHAR = "char"
+    VARCHAR = "character varying"
+    TEXT = "text"
+
+    # Binary Data Types
+    BYTEA = "bytea"
+
+    # Date/Time Types
+    DATE = "date"
+    TIME_WITHOUT_TIME_ZONE = "time without time zone"
+    TIME_WITH_TIME_ZONE = "time with time zone"
+    TIMESTAMP_WITHOUT_TIME_ZONE = "timestamp without time zone"
+    TIMESTAMP_WITH_TIME_ZONE = "timestamp with time zone"
+    INTERVAL = "interval"
+
+    # Boolean Type
+    BOOLEAN = "boolean"
+
+    # Geometric Types
+    POINT = "point"
+    LINE = "line"
+    LSEG = "lseg"
+    BOX = "box"
+    PATH = "path"
+    POLYGON = "polygon"
+    CIRCLE = "circle"
+
+    # Network Address Types
+    CIDR = "cidr"
+    INET = "inet"
+    MACADDR = "macaddr"
+    MACADDR8 = "macaddr8"
+
+    # Bit String Types
+    BIT = "bit"
+    BIT_VARYING = "bit varying"
+
+    # Text Search Types
+    TSVECTOR = "tsvector"
+    TSQUERY = "tsquery"
+
+    # UUID Type
+    UUID = "uuid"
+
+    # XML Type
+    XML = "xml"
+
+    # JSON Types
+    JSON = "json"
+    JSONB = "jsonb"
+
+    # Range Types
+    INT4RANGE = "int4range"
+    NUMRANGE = "numrange"
+    TSRANGE = "tsrange"
+    TSTZRANGE = "tstzrange"
+    DATERANGE = "daterange"
+
+    # Object Identifier Type
+    OID = "oid"
+
+    @classmethod
+    def _missing_(cls, value: object):
+        """
+        Handle SQL standard aliases when the exact enum value is not found.
+
+        The SQL standard requires that "timestamp" be equivalent to "timestamp without time zone"
+        and "time" be equivalent to "time without time zone".
+        """
+        # Only handle string values for SQL type aliases
+        if not isinstance(value, str):
+            return None
+
+        aliases = {
+            "timestamp": "timestamp without time zone",
+            "time": "time without time zone",
+        }
+
+        # Check if this is an alias we can resolve
+        if value in aliases:
+            # Return the actual enum member for the aliased value
+            return cls(aliases[value])
+
+        # If not an alias, let the default enum behavior handle it
+        return None
+
+
+class ConstraintType(StrEnum):
+    PRIMARY_KEY = "PRIMARY KEY"
+    FOREIGN_KEY = "FOREIGN KEY"
+    UNIQUE = "UNIQUE"
+    CHECK = "CHECK"
+    INDEX = "INDEX"
+
+
+def get_python_to_sql_mapping():
+    """
+    Returns a mapping of Python types to their corresponding SQL types.
+    """
+    return {
+        int: ColumnType.INTEGER,
+        float: ColumnType.DOUBLE_PRECISION,
+        str: ColumnType.VARCHAR,
+        bool: ColumnType.BOOLEAN,
+        bytes: ColumnType.BYTEA,
+        UUID: ColumnType.UUID,
+        datetime: ColumnType.TIMESTAMP_WITHOUT_TIME_ZONE,
+        date: ColumnType.DATE,
+        time: ColumnType.TIME_WITHOUT_TIME_ZONE,
+        timedelta: ColumnType.INTERVAL,
+    }
+
+
+def enum_to_name(enum: Enum) -> str:
+    """
+    Returns the name of the enum as a string.
+    """
+    return enum.__name__.lower()

iceaxe/typing.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from datetime import date, datetime, time, timedelta
+from enum import Enum, IntEnum, StrEnum
+from inspect import isclass
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Type,
+    TypeGuard,
+    TypeVar,
+)
+from uuid import UUID
+
+if TYPE_CHECKING:
+    from iceaxe.alias_values import Alias
+    from iceaxe.base import (
+        DBFieldClassDefinition,
+        TableBase,
+    )
+    from iceaxe.comparison import FieldComparison, FieldComparisonGroup
+    from iceaxe.functions import FunctionMetadata
+
+
+ALL_ENUM_TYPES = Type[Enum | StrEnum | IntEnum]
+PRIMITIVE_TYPES = int | float | str | bool | bytes | UUID
+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
+
+    return isclass(obj) and issubclass(obj, TableBase)
+
+
+def is_column(obj: T) -> TypeGuard[DBFieldClassDefinition[T]]:
+    from iceaxe.base import DBFieldClassDefinition
+
+    return isinstance(obj, DBFieldClassDefinition)
+
+
+def is_comparison(obj: Any) -> TypeGuard[FieldComparison]:
+    from iceaxe.comparison import FieldComparison
+
+    return isinstance(obj, FieldComparison)
+
+
+def is_comparison_group(obj: Any) -> TypeGuard[FieldComparisonGroup]:
+    from iceaxe.comparison import FieldComparisonGroup
+
+    return isinstance(obj, FieldComparisonGroup)
+
+
+def is_function_metadata(obj: Any) -> TypeGuard[FunctionMetadata]:
+    from iceaxe.functions import FunctionMetadata
+
+    return isinstance(obj, FunctionMetadata)
+
+
+def is_alias(obj: Any) -> TypeGuard[Alias]:
+    from iceaxe.alias_values import Alias
+
+    return isinstance(obj, Alias)
+
+
+def column(obj: T) -> DBFieldClassDefinition[T]:
+    if not is_column(obj):
+        raise ValueError(f"Invalid column: {obj}")
+    return obj

iceaxe-0.8.3.dist-info/METADATA

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: iceaxe
+Version: 0.8.3
+Summary: A modern, fast ORM for Python.
+Author-email: Pierce Freeman <pierce@freeman.vc>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: asyncpg<1,>=0.30
+Requires-Dist: click>=8
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: rich>=13
+Dynamic: license-file
+
+# iceaxe
+
+![Iceaxe Logo](https://raw.githubusercontent.com/piercefreeman/iceaxe/main/media/header.png)
+
+![Python Version](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fpiercefreeman%2Ficeaxe%2Frefs%2Fheads%2Fmain%2Fpyproject.toml) [![Test status](https://github.com/piercefreeman/iceaxe/actions/workflows/test.yml/badge.svg)](https://github.com/piercefreeman/iceaxe/actions)
+
+A modern, fast ORM for Python. We have the following goals:
+
+- 🏎️ **Performance**: We want to exceed or match the fastest ORMs in Python. We want our ORM
+to be as close as possible to raw-[asyncpg](https://github.com/MagicStack/asyncpg) speeds. See the "Benchmarks" section for more.
+- 📝 **Typehinting**: Everything should be typehinted with expected types. Declare your data as you
+expect in Python and it should bidirectionally sync to the database.
+- 🐘 **Postgres only**: Leverage native Postgres features and simplify the implementation.
+- ⚡ **Common things are easy, rare things are possible**: 99% of the SQL queries we write are
+vanilla SELECT/INSERT/UPDATEs. These should be natively supported by your ORM. If you're writing _really_
+complex queries, these are better done by hand so you can see exactly what SQL will be run.
+
+Iceaxe is used in production at several companies. 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
+project and web framework you're using.
+
+For comprehensive documentation, visit [https://iceaxe.sh](https://iceaxe.sh).
+
+To auto-optimize your self hosted Postgres install, check out our new [autopg](https://github.com/piercefreeman/autopg) project.
+
+## Installation
+
+If you're using poetry to manage your dependencies:
+
+```bash
+uv add iceaxe
+```
+
+Otherwise install with pip:
+
+```bash
+pip install iceaxe
+```
+
+## Usage
+
+Define your models as a `TableBase` subclass:
+
+```python
+from iceaxe import TableBase
+
+class Person(TableBase):
+    id: int
+    name: str
+    age: int
+```
+
+TableBase is a subclass of Pydantic's `BaseModel`, so you get all of the validation and Field customization
+out of the box. We provide our own `Field` constructor that adds database-specific configuration. For instance, to make the
+`id` field a primary key / auto-incrementing you can do:
+
+```python
+from iceaxe import Field
+
+class Person(TableBase):
+    id: int = Field(primary_key=True)
+    name: str
+    age: int
+```
+
+Okay now you have a model. How do you interact with it?
+
+Databases are based on a few core primitives to insert data, update it, and fetch it out again.
+To do so you'll need a _database connection_, which is a connection over the network from your code
+to your Postgres database. The `DBConnection` is the core class for all ORM actions against the database.
+
+```python
+from iceaxe import DBConnection
+import asyncpg
+
+conn = DBConnection(
+    await asyncpg.connect(
+        host="localhost",
+        port=5432,
+        user="db_user",
+        password="yoursecretpassword",
+        database="your_db",
+    )
+)
+```
+
+The Person class currently just lives in memory. To back it with a full
+database table, we can run raw SQL or run a migration to add it:
+
+```python
+await conn.conn.execute(
+    """
+    CREATE TABLE IF NOT EXISTS person (
+        id SERIAL PRIMARY KEY,
+        name TEXT NOT NULL,
+        age INT NOT NULL
+    )
+    """
+)
+```
+
+### Inserting Data
+
+Instantiate object classes as you normally do:
+
+```python
+people = [
+    Person(name="Alice", age=30),
+    Person(name="Bob", age=40),
+    Person(name="Charlie", age=50),
+]
+await conn.insert(people)
+
+print(people[0].id) # 1
+print(people[1].id) # 2
+```
+
+Because we're using an auto-incrementing primary key, the `id` field will be populated after the insert.
+Iceaxe will automatically update the object in place with the newly assigned value.
+
+### Updating data
+
+Now that we have these lovely people, let's modify them.
+
+```python
+person = people[0]
+person.name = "Blice"
+```
+
+Right now, we have a Python object that's out of state with the database. But that's often okay. We can inspect it
+and further write logic - it's fully decoupled from the database.
+
+```python
+def ensure_b_letter(person: Person):
+    if person.name[0].lower() != "b":
+        raise ValueError("Name must start with 'B'")
+
+ensure_b_letter(person)
+```
+
+To sync the values back to the database, we can call `update`:
+
+```python
+await conn.update([person])
+```
+
+If we were to query the database directly, we see that the name has been updated:
+
+```
+id | name  | age
+----+-------+-----
+  1 | Blice |  31
+  2 | Bob   |  40
+  3 | Charlie | 50
+```
+
+But no other fields have been touched. This lets a potentially concurrent process
+modify `Alice`'s record - say, updating the age to 31. By the time we update the data, we'll
+change the name but nothing else. Under the hood we do this by tracking the fields that
+have been modified in-memory and creating a targeted UPDATE to modify only those values.
+
+### Selecting data
+
+To select data, we can use a `QueryBuilder`. For a shortcut to `select` query functions,
+you can also just import select directly. This method takes the desired value parameters
+and returns a list of the desired objects.
+
+```python
+from iceaxe import select
+
+query = select(Person).where(Person.name == "Blice", Person.age > 25)
+results = await conn.exec(query)
+```
+
+If we inspect the typing of `results`, we see that it's a `list[Person]` objects. This matches
+the typehint of the `select` function. You can also target columns directly:
+
+```python
+query = select((Person.id, Person.name)).where(Person.age > 25)
+results = await conn.exec(query)
+```
+
+This will return a list of tuples, where each tuple is the id and name of the person: `list[tuple[int, str]]`.
+
+We support most of the common SQL operations. Just like the results, these are typehinted
+to their proper types as well. Static typecheckers and your IDE will throw an error if you try to compare
+a string column to an integer, for instance. A more complex example of a query:
+
+```python
+query = select((
+    Person.id,
+    FavoriteColor,
+)).join(
+    FavoriteColor,
+    Person.id == FavoriteColor.person_id,
+).where(
+    Person.age > 25,
+    Person.name == "Blice",
+).order_by(
+    Person.age.desc(),
+).limit(10)
+results = await conn.exec(query)
+```
+
+As expected this will deliver results - and typehint - as a `list[tuple[int, FavoriteColor]]`
+
+## Production
+
+> [!IMPORTANT]
+> Iceaxe is in early alpha. We're using it internally and showly rolling out to our production
+applications, but we're not yet ready to recommend it for general use. The API and larger
+stability is subject to change.
+
+Note that underlying Postgres connection wrapped by `conn` will be alive for as long as your object is in memory. This uses up one
+of the allowable connections to your database. Your overall limit depends on your Postgres configuration
+or hosting provider, but most managed solutions top out around 150-300. If you need more concurrent clients
+connected (and even if you don't - connection creation at the Postgres level is expensive), you can adopt
+a load balancer like `pgbouncer` to better scale to traffic. More deployment notes to come.
+
+It's also worth noting the absence of request pooling in this initialization. This is a feature of many ORMs that lets you limit
+the overall connections you make to Postgres, and re-use these over time. We specifically don't offer request
+pooling as part of Iceaxe, despite being supported by our underlying engine `asyncpg`. This is a bit more
+aligned to how things should be structured in production. Python apps are always bound to one process thanks to
+the 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
+network connections in the first place.
+
+## Benchmarking
+
+We have basic benchmarking tests in the `__tests__/benchmarks` directory. To run them, you'll need to execute the pytest suite:
+
+```bash
+uv run pytest -m integration_tests
+```
+
+Current benchmarking as of October 11 2024 is:
+
+|                   | raw asyncpg | iceaxe | external overhead                             |   |
+|-------------------|-------------|--------|-----------------------------------------------|---|
+| TableBase columns | 0.098s      | 0.093s |                                               |   |
+| TableBase full    | 0.164s      | 1.345s | 10%: dict construction | 90%: pydantic overhead |   |
+
+## Development
+
+If you update your Cython implementation during development, you'll need to re-compile the Cython code. This can be done with
+a simple uv sync.
+
+```bash
+uv sync
+```