duo-orm 0.1.0__py3-none-any.whl

duo_orm/__init__.py

@@ -0,0 +1,82 @@
+# duo_orm/__init__.py
+
+"""
+DuoORM: An opinionated, modern ORM for Python.
+
+This package provides a clean, symmetrical API for synchronous and
+asynchronous database operations, built on SQLAlchemy 2.0.
+"""
+
+__version__ = "0.1.0"
+
+# Apply lightweight operator ergonomics
+from . import patch  # noqa: F401
+
+# --- Import and re-export all common components for a modern 2.0 workflow ---
+
+# 1. The Core Factory
+from .db import Database
+
+# 2. The Model Kit (Modern 2.0 Style)
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+# 3. The Associations & Constraints Kit
+from sqlalchemy import Table, ForeignKey, UniqueConstraint, CheckConstraint, Index, not_
+
+# 4. The Types Kit
+from sqlalchemy import types
+
+# 5. The SQL Functions & Helpers Kit
+from sqlalchemy import func, text, select
+
+# 6. The Lifecycle Events Kit
+from sqlalchemy import event
+
+# 7. The Custom Exceptions
+from .exceptions import (
+    YourOrmError,
+    ConfigurationError,
+    ObjectNotFoundError,
+    MultipleObjectsFoundError,
+    InvalidQueryError,
+    UnsupportedOperationError,
+    IntegrityError,
+    ValidationError,
+)
+from .query import json, array
+
+
+__all__ = [
+    # Core Factory
+    "Database",
+    # Model Kit
+    "Mapped",
+    "mapped_column",
+    "relationship",  # Often used in model definition
+    # Associations & Constraints Kit
+    "Table",
+    "ForeignKey",
+    "UniqueConstraint",
+    "CheckConstraint",
+    "Index",
+    "not_",
+    # Types Kit
+    "types",
+    # SQL Functions & Helpers Kit
+    "func",
+    "text",
+    "select",
+    # Lifecycle Events Kit
+    "event",
+    # Custom Exceptions
+    "YourOrmError",
+    "ConfigurationError",
+    "ObjectNotFoundError",
+    "MultipleObjectsFoundError",
+    "InvalidQueryError",
+    "UnsupportedOperationError",
+    "IntegrityError",
+    "ValidationError",
+    "json",
+    "array",
+]

duo_orm/basemodel.py

@@ -0,0 +1,146 @@
+# duo_orm/basemodel.py
+
+from __future__ import annotations
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, TypeVar, Dict, Any, Iterable
+
+from sqlalchemy import inspect as sa_inspect, DateTime
+from sqlalchemy.orm import mapped_column
+
+from .query import QueryBuilder
+from .executor import _save, _delete_instance, _bulk_create
+if TYPE_CHECKING:
+    from .db import Database
+
+# This helps with type hinting for model instances.
+T = TypeVar("T")
+
+
+class _YourOrmMethods:
+    """
+    A mixin class providing the Active Record-style API.
+
+    This class is not intended to be used directly by the end-user. It will be
+    mixed into the user-facing base model that is generated by the Database
+    instance.
+    """
+    # This class attribute will be set by the Database class when it creates
+    # the user-facing Model. This is the key that links the models back
+    # to the configured database instance.
+    _db: "Database" = None
+
+    # --- Class-level Querying API ---
+
+    @classmethod
+    def _get_query_builder(cls: T) -> "QueryBuilder[T]":
+        """Internal helper to create a QueryBuilder for this model."""
+        # The `cls._db` attribute provides the crucial link to the db instance.
+        return QueryBuilder(cls, db=cls._db)
+
+    @classmethod
+    def where(cls: T, *args) -> "QueryBuilder[T]":
+        """Starts a query with a WHERE clause."""
+        return cls._get_query_builder().where(*args)
+
+    @classmethod
+    def all(cls: T):
+        """Fetches all records for this model."""
+        return cls._get_query_builder().all()
+
+    @classmethod
+    def first(cls: T):
+        """Fetches the first record for this model."""
+        return cls._get_query_builder().first()
+
+    @classmethod
+    def related(cls: T, relationship_attr, **kwargs) -> "QueryBuilder[T]":
+        """Starts a query scoped by a relationship helper."""
+        return cls._get_query_builder().related(relationship_attr, **kwargs)
+
+    @classmethod
+    def order_by(cls: T, *args, **kwargs) -> "QueryBuilder[T]":
+        """Starts a query with ordering applied."""
+        return cls._get_query_builder().order_by(*args, **kwargs)
+
+    @classmethod
+    def paginate(cls: T, *args, **kwargs) -> "QueryBuilder[T]":
+        """Starts a query with pagination applied."""
+        return cls._get_query_builder().paginate(*args, **kwargs)
+
+    @classmethod
+    def bulk_create(cls: T, instances: list[T]):
+        """Performs a bulk insert of multiple model instances."""
+        for instance in instances:
+            instance.validate()
+            instance._apply_timestamp_hooks(is_insert=True)
+        return _bulk_create(cls, instances)
+
+    # --- Instance-level Actions ---
+
+    def save(self: T):
+        """
+        Saves the current instance to the database (INSERT or UPDATE).
+        """
+        self.validate()
+        state = sa_inspect(self)
+        is_insert = state.transient or state.pending
+        self._apply_timestamp_hooks(is_insert=is_insert)
+        return _save(self)
+
+    def delete(self: T, *, force: bool = False):
+        """Deletes the current instance."""
+        return _delete_instance(self)
+
+    # --- Developer Experience Helpers ---
+
+    def validate(self: T):
+        """
+        Hook for subclasses to implement custom validation.
+
+        Raise ValidationError with an optional field/detail payload to block persistence.
+        """
+        return None
+
+    @classmethod
+    def fields(cls) -> tuple[str, ...]:
+        """Returns the column names defined on this model."""
+        mapper = sa_inspect(cls)
+        return tuple(col.key for col in mapper.columns)
+
+    def to_dict(self: T) -> Dict[str, Any]:
+        """Serializes the instance to a plain dictionary of column values."""
+        mapper = sa_inspect(self.__class__)
+        return {col.key: getattr(self, col.key) for col in mapper.columns}
+
+    def _apply_timestamp_hooks(self: T, *, is_insert: bool):
+        """Applies Django-style auto_now/auto_now_add semantics based on column info."""
+        now = _utcnow()
+        mapper = sa_inspect(self.__class__)
+        for column in mapper.columns:
+            info = getattr(column, "info", {}) or {}
+            targets: set[str] = set()
+
+            if info.get("auto_now"):
+                targets.update({"create", "update"})
+            if info.get("auto_now_add"):
+                targets.add("create")
+
+            set_on = info.get("set_on")
+            if set_on:
+                if isinstance(set_on, str):
+                    targets.add(set_on)
+                elif isinstance(set_on, Iterable):
+                    targets.update(str(value) for value in set_on)
+
+            if not targets:
+                continue
+
+            if "update" in targets:
+                setattr(self, column.key, now)
+            if is_insert and "create" in targets:
+                setattr(self, column.key, now)
+        return None
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)

duo_orm/db.py

@@ -0,0 +1,251 @@
+# duo_orm/db.py
+
+from contextlib import contextmanager, asynccontextmanager
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker, declarative_base
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.engine import make_url
+
+from .session import active_session_var, is_async_context
+from .basemodel import _YourOrmMethods
+
+
+_DRIVER_CONFIG = {
+    "postgresql": {
+        "sync": "postgresql+psycopg",
+        "async": "postgresql+psycopg",
+    },
+    "oracle": {
+        "sync": "oracle+oracledb",
+        "async": "oracle+oracledb_async",
+    },
+    "mysql": {
+        "sync": "mysql+pymysql",
+        "async": "mysql+asyncmy",
+    },
+    "mssql": {
+        "sync": "mssql+pyodbc",
+        "async": "mssql+aioodbc",
+    },
+    "sqlite": {
+        "sync": "sqlite",
+        "async": "sqlite+aiosqlite",
+    },
+}
+
+_DIALECT_ALIASES = {
+    "postgres": "postgresql",
+    "postgresql": "postgresql",
+    "mysql": "mysql",
+    "mariadb": "mysql",
+    "mssql": "mssql",
+    "sqlite": "sqlite",
+    "oracle": "oracle",
+}
+
+
+def _normalize_dialect(url_str: str) -> tuple:
+    parsed = make_url(url_str)
+    drivername = parsed.drivername or ""
+    if "+" in drivername:
+        raise ValueError(
+            "Do not include driver in URLs. Provide only the base dialect "
+            "(e.g., postgresql://..., mysql://..., sqlite:///...). "
+            "Drivers are managed automatically."
+        )
+    base = _DIALECT_ALIASES.get(drivername.lower())
+    if not base or base not in _DRIVER_CONFIG:
+        raise ValueError(f"Unsupported or unknown dialect '{drivername}'.")
+    return parsed, base
+
+
+def _resolve_urls(sync_url: str, async_url: str | None, derive_async: bool) -> tuple[str, str | None]:
+    parsed_sync, dialect = _normalize_dialect(sync_url)
+    drivers = _DRIVER_CONFIG[dialect]
+
+    resolved_sync = parsed_sync.set(drivername=drivers["sync"])
+    resolved_async: str | None = None
+
+    if async_url:
+        parsed_async, dialect_async = _normalize_dialect(async_url)
+        if dialect_async != dialect:
+            raise ValueError("async_url dialect must match the primary url dialect.")
+        resolved_async = parsed_async.set(drivername=drivers["async"]).render_as_string(hide_password=False)
+    elif derive_async:
+        resolved_async = parsed_sync.set(drivername=drivers["async"]).render_as_string(hide_password=False)
+
+    return resolved_sync.render_as_string(hide_password=False), resolved_async
+
+
+class Database:
+    """
+    The main class that manages database connections and sessions.
+
+    This class acts as a factory for a pre-configured, database-aware
+    base model class that users will inherit from.
+    """
+
+    def __init__(self, db_url: str, *, async_url: str | None = None, derive_async: bool = True):
+        if not db_url:
+            raise ValueError("Database URL cannot be empty.")
+
+        self._sync_url, self._async_url = _resolve_urls(db_url, async_url, derive_async)
+        self._db_url = self._sync_url
+        self._sync_engine = None
+        self._async_engine = None
+        self._sync_session_factory = None
+        self._async_session_factory = None
+        self._connected = False
+
+        # --- This is the new "factory" logic ---
+
+        # 1. Create a new, unique declarative base from SQLAlchemy.
+        Base = declarative_base()
+
+        # 2. Manufacture the final, user-facing Model class by combining
+        #    SQLAlchemy's base with our custom Active Record methods.
+        class Model(Base, _YourOrmMethods):
+            __abstract__ = True  # make the factory base unmapped; user models define tables
+            # This is the magic link that solves the flaw!
+            # We inject a reference to this specific `db` instance
+            # directly into the Model class itself.
+            _db = self
+
+        # 3. Attach the newly created Model class as an attribute to this
+        #    instance, so the user can access it via `db.Model`.
+        self.Model = Model
+
+    @property
+    def url(self):
+        return self._db_url
+
+    @property
+    def sync_url(self):
+        return self._sync_url
+
+    @property
+    def async_url(self):
+        return self._async_url
+
+    @property
+    def metadata(self):
+        """Returns the metadata from the manufactured Model class."""
+        # The metadata is now correctly associated with this db instance's models.
+        return self.Model.metadata
+
+    # --- The rest of the class remains the same ---
+
+    @property
+    def sync_engine(self):
+        if not self._sync_url:
+            raise RuntimeError("Sync engine is not configured for this Database.")
+        if self._sync_engine is None:
+            try:
+                self._sync_engine = create_engine(self._sync_url)
+            except TypeError as exc:
+                query_keys = make_url(self._sync_url).query.keys()
+                hint = ""
+                if query_keys:
+                    hint = (
+                        f" URL includes query parameters {sorted(query_keys)}; "
+                        "verify they are supported by the chosen driver."
+                    )
+                raise TypeError(f"Failed to create sync engine: {exc}.{hint}") from exc
+        return self._sync_engine
+
+    @property
+    def async_engine(self):
+        if not self._async_url:
+            raise RuntimeError("Async engine is not configured for this Database.")
+        if self._async_engine is None:
+            try:
+                self._async_engine = create_async_engine(self._async_url)
+            except TypeError as exc:
+                query_keys = make_url(self._async_url).query.keys()
+                hint = ""
+                if query_keys:
+                    hint = (
+                        f" URL includes query parameters {sorted(query_keys)}; "
+                        "verify they are supported by the chosen driver."
+                    )
+                raise TypeError(f"Failed to create async engine: {exc}.{hint}") from exc
+        return self._async_engine
+
+    @property
+    def sync_session_factory(self) -> sessionmaker:
+        if self._sync_session_factory is None:
+            self._sync_session_factory = sessionmaker(
+                bind=self.sync_engine, expire_on_commit=False
+            )
+        return self._sync_session_factory
+
+    @property
+    def async_session_factory(self) -> sessionmaker:
+        if self._async_session_factory is None:
+            self._async_session_factory = sessionmaker(
+                bind=self.async_engine,
+                class_=AsyncSession,
+                expire_on_commit=False,
+            )
+        return self._async_session_factory
+
+    def connect(self):
+        """
+        Eagerly initialize engines and session factories to surface configuration errors early.
+        Safe to call multiple times.
+        """
+        if self._connected:
+            return
+        # Touch available factories so any misconfiguration (bad URL, missing driver, etc.) raises immediately.
+        if self._sync_url:
+            _ = self.sync_engine
+            _ = self.sync_session_factory
+        if self._async_url:
+            _ = self.async_engine
+            _ = self.async_session_factory
+        self._connected = True
+
+    @contextmanager
+    def _sync_transaction_context(self):
+        with self.sync_session_factory() as session:
+            token = active_session_var.set(session)
+            try:
+                yield session
+                session.commit()
+            except Exception:
+                session.rollback()
+                raise
+            finally:
+                active_session_var.reset(token)
+
+    @asynccontextmanager
+    async def _async_transaction_context(self):
+        async with self.async_session_factory() as session:
+            token = active_session_var.set(session)
+            try:
+                yield session
+                await session.commit()
+            except Exception:
+                await session.rollback()
+                raise
+            finally:
+                active_session_var.reset(token)
+
+    def transaction(self):
+        if is_async_context():
+            return self._async_transaction_context()
+        else:
+            return self._sync_transaction_context()
+
+    @asynccontextmanager
+    async def standalone_session(self):
+        """Provides a raw, unmanaged SQLAlchemy AsyncSession."""
+        async with self.async_session_factory() as session:
+            yield session
+
+    @contextmanager
+    def sync_standalone_session(self):
+        """Provides a raw, unmanaged SQLAlchemy Session."""
+        with self.sync_session_factory() as session:
+            yield session

duo_orm/exceptions.py

@@ -0,0 +1,84 @@
+# duo_orm/exceptions.py
+
+"""
+This module contains the set of custom exceptions raised by DuoORM.
+
+Having custom exceptions allows users of the library to reliably catch
+errors specific to the ORM's operation, rather than generic Python errors.
+"""
+
+
+class YourOrmError(Exception):
+    """Base exception for all errors raised by DuoORM."""
+    pass
+
+
+class ConfigurationError(YourOrmError):
+    """
+    Raised when there is a problem with the ORM's configuration.
+
+    For example, if a required configuration file is missing or a
+    database URL is not provided.
+    """
+    pass
+
+
+class ObjectNotFoundError(YourOrmError):
+    """
+    Raised when a query that expects a single result finds none.
+
+    For example, a `.one()` or `.get()` method would raise this.
+    """
+    pass
+
+
+class MultipleObjectsFoundError(YourOrmError):
+    """
+    Raised when a query that expects a single result finds multiple.
+
+    Similar to ObjectNotFoundError, this would be used by `.one()` or `.get()`.
+    """
+    pass
+
+
+class InvalidQueryError(YourOrmError):
+    """
+    Raised when a query is constructed in an invalid way, for example
+    by passing an unsupported operator.
+    """
+    pass
+
+
+class UnsupportedOperationError(InvalidQueryError):
+    """
+    Raised when an operation is not supported by the current database dialect.
+
+    For example, using JSONContains on a database that does not support JSON.
+    """
+    pass
+
+
+class IntegrityError(YourOrmError):
+    """
+    Raised when a database integrity constraint is violated.
+
+    This is a wrapper around the database driver's specific integrity error
+    (e.g., sqlalchemy.exc.IntegrityError) to provide a consistent API.
+    It typically signals a unique constraint violation.
+    """
+    pass
+
+
+class ValidationError(YourOrmError):
+    """
+    Raised when model-level validation fails.
+
+    Attributes:
+        field (str | None): Optional field name associated with the error.
+        detail (Any): Optional structured detail for the error.
+    """
+
+    def __init__(self, message: str, field: str | None = None, detail=None):
+        super().__init__(message)
+        self.field = field
+        self.detail = detail