rakko-orm 1.0.0a0__py3-none-any.whl

rakko/apps.py

@@ -0,0 +1,356 @@
+# Copyright (c) 2026 ropmyung (Rakko ORM modifications and additions).
+# Derived from Tortoise ORM; maintained and modified for Rakko ORM.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import importlib
+import warnings
+from collections.abc import Callable, Iterable, Iterator
+from copy import copy
+from inspect import isclass
+from itertools import chain
+from types import ModuleType
+from typing import Any, cast
+
+from pypika_tortoise import Table
+from pypika_tortoise.queries import QueryBuilder
+
+from rakko.connection import ConnectionHandler
+from rakko.exceptions import ConfigurationError
+from rakko.fields.relational import (
+    BackwardFKRelation,
+    BackwardOneToOneRelation,
+    ForeignKeyFieldInstance,
+    ManyToManyFieldInstance,
+    OneToOneFieldInstance,
+)
+from rakko.filters import get_m2m_filters
+from rakko.models import Model
+
+
+class Apps:
+    def __init__(
+        self,
+        config: dict[str, dict[str, Any]] | None,
+        connections: ConnectionHandler,
+        table_name_generator: Callable[[type[Model]], str] | None = None,
+        *,
+        validate_connections: bool = True,
+    ) -> None:
+        self.apps: dict[str, dict[str, type[Model]]] = {}
+        self._config = config or {}
+        self._connections = connections
+        self._table_name_generator = table_name_generator
+        self._validate_connections = validate_connections
+        if self._config:
+            self._load_from_config()
+
+    @staticmethod
+    def _discover_models(models_path: ModuleType | str, app_label: str) -> list[type[Model]]:
+        if isinstance(models_path, ModuleType):
+            module = models_path
+        else:
+            try:
+                module = importlib.import_module(models_path)
+            except ImportError:
+                raise ConfigurationError(f'Module "{models_path}" not found')
+        discovered_models: list[type[Model]] = []
+        if possible_models := getattr(module, "__models__", None):
+            try:
+                possible_models = [*possible_models]
+            except TypeError:
+                possible_models = None
+        if not possible_models:
+            possible_models = [getattr(module, attr_name) for attr_name in dir(module)]
+        for attr in possible_models:
+            if isclass(attr) and issubclass(attr, Model) and not attr._meta.abstract:
+                if attr._meta.app and attr._meta.app != app_label:
+                    continue
+                attr._meta.app = app_label
+                discovered_models.append(attr)
+        if not discovered_models:
+            warnings.warn(f'Module "{models_path}" has no models', RuntimeWarning, stacklevel=4)
+        return discovered_models
+
+    def init_app(
+        self,
+        label: str,
+        module_list: Iterable[ModuleType | str],
+        _init_relations: bool = True,
+    ) -> dict[str, type[Model]]:
+        app_models: list[type[Model]] = []
+        for module in module_list:
+            app_models += self._discover_models(module, label)
+
+        self.apps[label] = {model.__name__: model for model in app_models}
+
+        if _init_relations:
+            self._init_relations()
+
+        return self.apps[label]
+
+    def _load_from_config(self) -> None:
+        if self._connections is None:
+            raise ConfigurationError("ConnectionHandler is required to load from config")
+        for name, info in self._config.items():
+            default_connection = info.get("default_connection", "default")
+            if self._validate_connections:
+                try:
+                    self._connections.get(default_connection)
+                except KeyError:
+                    raise ConfigurationError(
+                        f'Unknown connection "{default_connection}" for app "{name}"'
+                    )
+            else:
+                if default_connection not in self._connections.db_config:
+                    raise ConfigurationError(
+                        f'Unknown connection "{default_connection}" for app "{name}"'
+                    )
+
+            self.init_app(name, info["models"], _init_relations=False)
+
+            for model in self.apps[name].values():
+                model._meta.default_connection = default_connection
+
+        self._init_relations()
+        if self._validate_connections:
+            self._build_initial_querysets()
+
+    def _build_initial_querysets(self) -> None:
+        for app in self.apps.values():
+            for model in app.values():
+                model._meta.finalise_model()
+                model._meta.basetable = Table(name=model._meta.db_table, schema=model._meta.schema)
+                basequery = model._meta.db.query_class.from_(model._meta.basetable)
+                model._meta.basequery = cast(QueryBuilder, basequery)
+                model._meta.basequery_all_fields = cast(
+                    QueryBuilder, basequery.select(*model._meta.db_fields)
+                )
+
+    def _init_relations(self) -> None:
+        def get_related_model(related_app_name: str, related_model_name: str) -> type[Model]:
+            """
+            Test, if app and model really exist. Throws a ConfigurationError with a hopefully
+            helpful message. If successful, returns the requested model.
+
+            :raises ConfigurationError: If no such app exists.
+            """
+            try:
+                return self.apps[related_app_name][related_model_name]
+            except KeyError:
+                if related_app_name not in self.apps:
+                    raise ConfigurationError(
+                        f"No app with name '{related_app_name}' registered."
+                        f" Please check your model names in ForeignKeyFields"
+                        f" and configurations."
+                    )
+                raise ConfigurationError(
+                    f"No model with name '{related_model_name}' registered in"
+                    f" app '{related_app_name}'."
+                )
+
+        def split_reference(reference: str) -> tuple[str, str]:
+            """
+            Validate, if reference follow the official naming conventions. Throws a
+            ConfigurationError with a hopefully helpful message. If successful,
+            returns the app and the model name.
+
+            :raises ConfigurationError: If reference is invalid.
+            """
+            if len(items := reference.split(".")) != 2:  # pragma: nocoverage
+                raise ConfigurationError(
+                    f"'{reference}' is not a valid model reference Bad Reference."
+                    " Should be something like '<appname>.<modelname>'."
+                )
+            return items[0], items[1]
+
+        def init_fk_o2o_field(model: type[Model], field: str, is_o2o: bool = False) -> None:
+            fk_object = cast(
+                "OneToOneFieldInstance | ForeignKeyFieldInstance", model._meta.fields_map[field]
+            )
+            reference = fk_object.model_name
+            if not isinstance(reference, str):
+                related_model: type[Model] = reference
+                related_model_name = related_model.__name__
+            else:
+                related_app_name, related_model_name = split_reference(reference)
+                related_model = get_related_model(related_app_name, related_model_name)
+
+            if to_field := fk_object.to_field:
+                related_field = related_model._meta.fields_map.get(to_field)
+                if not related_field:
+                    raise ConfigurationError(
+                        f'there is no field named "{to_field}" in model "{related_model_name}"'
+                    )
+                if not related_field.unique:
+                    raise ConfigurationError(
+                        f'field "{to_field}" in model "{related_model_name}" is not unique'
+                    )
+            else:
+                fk_object.to_field = related_model._meta.pk_attr
+                related_field = related_model._meta.pk
+            key_fk_object = copy(related_field)
+            fk_object.to_field_instance = related_field
+            fk_object.field_type = fk_object.to_field_instance.field_type
+
+            key_field = f"{field}_id"
+            key_fk_object.reference = fk_object
+            key_fk_object.source_field = fk_object.source_field or key_field
+            for attr in ("index", "default", "null", "generated", "description", "db_default"):
+                setattr(key_fk_object, attr, getattr(fk_object, attr))
+            if is_o2o:
+                key_fk_object.pk = fk_object.pk
+                key_fk_object.unique = fk_object.unique
+            else:
+                key_fk_object.pk = False
+                key_fk_object.unique = False
+            model._meta.add_field(key_field, key_fk_object)
+            fk_object.related_model = related_model
+            fk_object.source_field = key_field
+            if (backward_relation_name := fk_object.related_name) is not False:
+                if not backward_relation_name:
+                    backward_relation_name = f"{model._meta.db_table}s"
+                if backward_relation_name in related_model._meta.fields:
+                    raise ConfigurationError(
+                        f'backward relation "{backward_relation_name}" duplicates in'
+                        f" model {related_model_name}"
+                    )
+
+                fk_relation = (
+                    BackwardOneToOneRelation(
+                        model,
+                        key_field,
+                        key_fk_object.source_field,
+                        null=True,
+                        description=fk_object.description,
+                    )
+                    if is_o2o
+                    else BackwardFKRelation(
+                        model,
+                        key_field,
+                        key_fk_object.source_field,
+                        null=fk_object.null,
+                        description=fk_object.description,
+                    )
+                )
+                fk_relation.to_field_instance = fk_object.to_field_instance
+                if isinstance(backward_relation_name, str):
+                    related_model._meta.add_field(backward_relation_name, fk_relation)
+            if is_o2o and fk_object.pk:
+                model._meta.pk_attr = key_field
+
+        for app_name, app in self.apps.items():
+            for model_name, model in app.items():
+                if model._meta._inited:
+                    continue
+                model._meta._inited = True
+                if not model._meta.db_table or (
+                    model._meta.auto_table and self._table_name_generator
+                ):
+                    model._meta.db_table = (
+                        self._table_name_generator(model)
+                        if self._table_name_generator
+                        else (model.__name__.lower())
+                    )
+
+                for field in sorted(model._meta.fk_fields):
+                    init_fk_o2o_field(model, field)
+
+                for field in model._meta.o2o_fields:
+                    init_fk_o2o_field(model, field, is_o2o=True)
+
+                for field in list(model._meta.m2m_fields):
+                    m2m_object = cast(ManyToManyFieldInstance, model._meta.fields_map[field])
+                    if m2m_object._generated:
+                        continue
+                    if not (backward_key := m2m_object.backward_key):
+                        backward_key = f"{model._meta.db_table}_id"
+                        if backward_key == m2m_object.forward_key:
+                            backward_key = f"{model._meta.db_table}_rel_id"
+                        m2m_object.backward_key = backward_key
+
+                    reference = m2m_object.model_name
+                    if not isinstance(reference, str):
+                        related_model = reference
+                        related_model_name = related_model.__name__
+                    else:
+                        related_app_name, related_model_name = split_reference(reference)
+                        related_model = get_related_model(related_app_name, related_model_name)
+
+                    m2m_object.related_model = related_model
+
+                    if not (backward_relation_name := m2m_object.related_name):
+                        backward_relation_name = m2m_object.related_name = (
+                            f"{model._meta.db_table}s"
+                        )
+                    if backward_relation_name in related_model._meta.fields:
+                        raise ConfigurationError(
+                            f'backward relation "{backward_relation_name}" duplicates in'
+                            f" model {related_model_name}"
+                        )
+
+                    if not m2m_object.through:
+                        related_model_table_name = (
+                            related_model._meta.db_table or related_model.__name__.lower()
+                        )
+                        m2m_object.through = f"{model._meta.db_table}_{related_model_table_name}"
+
+                    m2m_object.through_schema = model._meta.schema
+
+                    m2m_relation = ManyToManyFieldInstance(
+                        f"{app_name}.{model_name}",
+                        m2m_object.through,
+                        forward_key=m2m_object.backward_key,
+                        backward_key=m2m_object.forward_key,
+                        related_name=field,
+                        field_type=model,
+                        description=m2m_object.description,
+                    )
+                    m2m_relation._generated = True
+                    m2m_relation.through_schema = model._meta.schema
+                    model._meta.filters.update(get_m2m_filters(field, m2m_object))
+                    related_model._meta.add_field(backward_relation_name, m2m_relation)
+
+    def get_model_reference(self, model: type[Model]) -> str:
+        return model._meta.full_name
+
+    def get_model(self, app_label: str, model_name: str) -> type[Model]:
+        try:
+            return self.apps[app_label][model_name]
+        except KeyError:
+            if app_label not in self.apps:
+                raise ConfigurationError(f"No app with name '{app_label}' registered.")
+            raise ConfigurationError(
+                f"No model with name '{model_name}' registered in app '{app_label}'."
+            )
+
+    def get_models_iterable(self) -> Iterable[type[Model]]:
+        model_list_generator = (
+            model_list for model_list in (app.values() for app in self.apps.values())
+        )
+        return chain.from_iterable(model_list_generator)
+
+    def clear(self) -> None:
+        self.apps.clear()
+
+    def __contains__(self, key: str) -> bool:
+        return key in self.apps
+
+    def __iter__(self) -> Iterator[str]:
+        return self.apps.__iter__()
+
+    def values(self) -> Iterable[dict[str, type[Model]]]:
+        return self.apps.values()
+
+    def items(self) -> Iterable[tuple[str, dict[str, type[Model]]]]:
+        return self.apps.items()
+
+    def keys(self) -> Iterable[str]:
+        return self.apps.keys()
+
+    def __getitem__(self, key: str) -> dict[str, type[Model]]:
+        return self.apps[key]
+
+    def __setitem__(self, key: str, value: dict[str, type[Model]]) -> None:
+        self.apps[key] = value

rakko/backends/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) 2026 ropmyung (Rakko ORM modifications and additions).
+# Derived from Tortoise ORM; maintained and modified for Rakko ORM.
+# SPDX-License-Identifier: Apache-2.0
+

rakko/backends/asyncpg/__init__.py

@@ -0,0 +1,7 @@
+# Copyright (c) 2026 ropmyung (Rakko ORM modifications and additions).
+# Derived from Tortoise ORM; maintained and modified for Rakko ORM.
+# SPDX-License-Identifier: Apache-2.0
+
+from .client import AsyncpgDBClient
+
+client_class = AsyncpgDBClient

rakko/backends/asyncpg/client.py

@@ -0,0 +1,223 @@
+# Copyright (c) 2026 ropmyung (Rakko ORM modifications and additions).
+# Derived from Tortoise ORM; maintained and modified for Rakko ORM.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from typing import Any, TypeVar, cast
+
+import asyncpg
+from asyncpg.transaction import Transaction
+
+from rakko.backends.asyncpg.executor import AsyncpgExecutor
+from rakko.backends.asyncpg.schema_generator import AsyncpgSchemaGenerator
+from rakko.backends.base.client import (
+    ConnectionWrapper,
+    NestedTransactionContext,
+    TransactionalDBClient,
+    TransactionContext,
+    TransactionContextPooled,
+)
+from rakko.backends.base_postgres.client import (
+    BasePostgresClient,
+    translate_exceptions,
+)
+from rakko.exceptions import (
+    DBConnectionError,
+    IntegrityError,
+    OperationalError,
+    TransactionManagementError,
+)
+
+FuncType = Callable[..., Any]
+F = TypeVar("F", bound=FuncType)
+
+
+class AsyncpgDBClient(BasePostgresClient):
+    executor_class = AsyncpgExecutor
+    schema_generator = AsyncpgSchemaGenerator
+    connection_class = asyncpg.connection.Connection
+    _pool: asyncpg.Pool | None
+    _connection: asyncpg.connection.Connection | None = None
+
+    async def create_connection(self, with_db: bool) -> None:
+        if self.schema:
+            self.server_settings["search_path"] = self.schema
+
+        if self.application_name:
+            self.server_settings["application_name"] = self.application_name
+
+        self._template = {
+            "host": self.host,
+            "port": self.port,
+            "user": self.user,
+            "database": self.database if with_db else None,
+            "min_size": self.pool_minsize,
+            "max_size": self.pool_maxsize,
+            "connection_class": self.connection_class,
+            "loop": self.loop,
+            "server_settings": self.server_settings,
+            **self.extra,
+        }
+        try:
+            # asyncpg resolves a callable password itself, once per new connection
+            self._pool = await self.create_pool(password=self.password, **self._template)
+            await self._post_connect()
+            self.log.debug("Created connection pool %s with params: %s", self._pool, self._template)
+        except asyncpg.InvalidCatalogNameError as ex:
+            msg = "Can't establish connection to "
+            if with_db:
+                msg += f"database {self.database}"
+            else:
+                msg += f"default database. Verify environment PGDATABASE. Exception: {ex}"
+            raise DBConnectionError(msg) from ex
+
+    async def create_pool(self, **kwargs) -> asyncpg.Pool:
+        return await asyncpg.create_pool(None, **kwargs)
+
+    async def _expire_connections(self) -> None:
+        if self._pool:  # pragma: nobranch
+            await self._pool.expire_connections()
+
+    async def _close(self) -> None:
+        if self._pool:  # pragma: nobranch
+            try:
+                await asyncio.wait_for(self._pool.close(), 10)
+            except asyncio.TimeoutError:  # pragma: nocoverage
+                self._pool.terminate()
+            self._pool = None
+            self.log.debug("Closed connection pool %s with params: %s", self._pool, self._template)
+
+    async def _translate_exceptions[R](
+        self, func: Callable[..., Awaitable[R]], *args: Any, **kwargs: Any
+    ) -> R:
+        try:
+            return await func(self, *args, **kwargs)
+        except (asyncpg.SyntaxOrAccessError, asyncpg.exceptions.DataError) as exc:
+            raise OperationalError(exc) from exc
+        except asyncpg.IntegrityConstraintViolationError as exc:
+            raise IntegrityError(exc) from exc
+        except asyncpg.InvalidTransactionStateError as exc:  # pragma: nocoverage
+            raise TransactionManagementError(exc) from exc
+
+    async def db_delete(self) -> None:
+        try:
+            return await super().db_delete()
+        except asyncpg.InvalidCatalogNameError:  # pragma: nocoverage
+            pass
+        await self.close()
+
+    def _in_transaction(self) -> TransactionContext:
+        return TransactionContextPooled(TransactionWrapper(self), self._pool_init_lock)
+
+    @translate_exceptions
+    async def execute_insert(self, query: str, values: list) -> asyncpg.Record | None:
+        async with self.acquire_connection() as connection:
+            self.log.debug("%s: %s", query, values)
+            # TODO: Cache prepared statement
+            return await connection.fetchrow(query, *values)
+
+    @translate_exceptions
+    async def execute_many(self, query: str, values: list) -> None:
+        async with self.acquire_connection() as connection:
+            self.log.debug("%s: %s", query, values)
+            # TODO: Consider using copy_records_to_table instead
+            transaction = connection.transaction()
+            await transaction.start()
+            try:
+                await connection.executemany(query, values)
+            except Exception:
+                await transaction.rollback()
+                raise
+            else:
+                await transaction.commit()
+
+    @translate_exceptions
+    async def execute_query(self, query: str, values: list | None = None) -> tuple[int, list[dict]]:
+        async with self.acquire_connection() as connection:
+            self.log.debug("%s: %s", query, values)
+            params = [query, *values] if values else [query]
+            normalized = query.lstrip().upper()
+            if normalized.startswith(("UPDATE", "DELETE", "INSERT")):
+                res = await connection.execute(*params)
+                try:
+                    rows_affected = int(res.split(" ")[1])
+                except (AttributeError, IndexError, ValueError):  # pragma: nocoverage
+                    rows_affected = 0
+                return rows_affected, []
+
+            rows = await connection.fetch(*params)
+            return len(rows), rows
+
+    @translate_exceptions
+    async def execute_query_dict(self, query: str, values: list | None = None) -> list[dict]:
+        async with self.acquire_connection() as connection:
+            self.log.debug("%s: %s", query, values)
+            params = [query, *values] if values else [query]
+            results = await connection.fetch(*params)
+            return [dict(i) for i in results]
+
+
+class TransactionWrapper(AsyncpgDBClient, TransactionalDBClient):
+    """A transactional connection wrapper for asyncpg.
+
+    asyncpg implements nested transactions (savepoints) natively, so we don't need to.
+    """
+
+    _connection: asyncpg.Connection  # Put it here to improve type hints
+
+    def __init__(self, connection: AsyncpgDBClient) -> None:
+        self._connection = cast(asyncpg.Connection, connection._connection)  # type: ignore[assignment]
+        self._lock = asyncio.Lock()
+        self.log = connection.log
+        self.connection_name = connection.connection_name
+        self.transaction: Transaction | None = None
+        self._finalized = False
+        self._parent: AsyncpgDBClient = connection  # type: ignore[assignment]
+
+    def _in_transaction(self) -> TransactionContext:
+        # since we need to store the transaction object for each transaction block,
+        # we need to wrap the connection with its own TransactionWrapper
+        return NestedTransactionContext(TransactionWrapper(self))
+
+    def acquire_connection(self) -> ConnectionWrapper[asyncpg.Connection]:
+        return ConnectionWrapper(self._lock, self)
+
+    @translate_exceptions
+    async def execute_many(self, query: str, values: list) -> None:
+        async with self.acquire_connection() as connection:
+            self.log.debug("%s: %s", query, values)
+            # TODO: Consider using copy_records_to_table instead
+            await connection.executemany(query, values)
+
+    @translate_exceptions
+    async def begin(self) -> None:
+        self.transaction = self._connection.transaction()
+        await self.transaction.start()
+
+    async def savepoint(self) -> None:
+        return await self.begin()
+
+    async def commit(self) -> None:
+        if not self.transaction:
+            raise TransactionManagementError("Transaction is in invalid state")
+        if self._finalized:
+            raise TransactionManagementError("Transaction already finalised")
+        await self.transaction.commit()
+        self._finalized = True
+
+    async def release_savepoint(self) -> None:
+        return await self.commit()
+
+    async def rollback(self) -> None:
+        if not self.transaction:
+            raise TransactionManagementError("Transaction is in invalid state")
+        if self._finalized:
+            raise TransactionManagementError("Transaction already finalised")
+        await self.transaction.rollback()
+        self._finalized = True
+
+    async def savepoint_rollback(self) -> None:
+        await self.rollback()

rakko/backends/asyncpg/executor.py

@@ -0,0 +1,20 @@
+# Copyright (c) 2026 ropmyung (Rakko ORM modifications and additions).
+# Derived from Tortoise ORM; maintained and modified for Rakko ORM.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, cast
+
+import asyncpg
+
+from rakko import Model
+from rakko.backends.base_postgres.executor import BasePostgresExecutor
+
+
+class AsyncpgExecutor(BasePostgresExecutor):
+    async def _process_insert_result(
+        self, instance: Model, results: asyncpg.Record | Mapping[str, Any] | None
+    ) -> None:
+        return await super()._process_insert_result(instance, cast(Mapping[str, Any] | None, results))

rakko/backends/asyncpg/schema_generator.py

@@ -0,0 +1,17 @@
+# Copyright (c) 2026 ropmyung (Rakko ORM modifications and additions).
+# Derived from Tortoise ORM; maintained and modified for Rakko ORM.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rakko.backends.base_postgres.schema_generator import BasePostgresSchemaGenerator
+
+if TYPE_CHECKING:  # pragma: nocoverage
+    from rakko.backends.asyncpg.client import AsyncpgDBClient
+
+
+class AsyncpgSchemaGenerator(BasePostgresSchemaGenerator):
+    def __init__(self, client: AsyncpgDBClient) -> None:
+        super().__init__(client)

rakko/backends/base/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) 2026 ropmyung (Rakko ORM modifications and additions).
+# Derived from Tortoise ORM; maintained and modified for Rakko ORM.
+# SPDX-License-Identifier: Apache-2.0
+