iceaxe 0.7.1__cp313-cp313-macosx_11_0_arm64.whl

iceaxe/modifications.py

@@ -0,0 +1,176 @@
+import logging
+import traceback
+from dataclasses import dataclass
+from typing import Literal, Sequence, TypeVar
+
+from iceaxe.base import TableBase
+from iceaxe.logging import LOGGER
+
+MODIFICATION_TRACKER_VERBOSITY = Literal["ERROR", "WARNING", "INFO"] | None
+T = TypeVar("T", bound=TableBase)
+
+
+@dataclass
+class Modification:
+    """
+    Tracks a single modification to a database model instance, including stack trace information.
+
+    This class stores both the full stack trace and a simplified user-specific stack trace
+    that excludes library code. This helps with debugging by showing where in the user's
+    code a modification was made.
+
+    :param instance: The model instance that was modified
+    :param stack_trace: The complete stack trace at the time of modification
+    :param user_stack_trace: The most relevant user code stack trace, excluding library code
+    """
+
+    instance: TableBase
+
+    # The full stack trace of the modification.
+    stack_trace: str
+
+    # Most specific line of the stack trace that is part of the user's code.
+    user_stack_trace: str
+
+    @staticmethod
+    def get_current_stack_trace(
+        package_allow_list: list[str] | None = None,
+        package_deny_list: list[str] | None = None,
+    ) -> tuple[str, str]:
+        """
+        Get both the full stack trace and the most specific user code stack trace.
+
+        The user stack trace filters out library code and frozen code to focus on
+        the most relevant user code location where a modification occurred.
+
+        :return: A tuple containing (full_stack_trace, user_stack_trace)
+        :rtype: tuple[str, str]
+        """
+        stack = traceback.extract_stack()[:-1]  # Remove the current frame
+        full_trace = "".join(traceback.format_list(stack))
+
+        # Find the most specific user code stack trace by filtering out library code
+        user_traces = [
+            frame
+            for frame in stack
+            if (
+                package_allow_list is None
+                or any(pkg in frame.filename for pkg in package_allow_list)
+            )
+            and (
+                package_deny_list is None
+                or not any(pkg in frame.filename for pkg in package_deny_list)
+            )
+        ]
+
+        user_trace = ""
+        if user_traces:
+            user_trace = "".join(traceback.format_list([user_traces[-1]]))
+
+        return full_trace, user_trace
+
+
+class ModificationTracker:
+    """
+    Tracks modifications to database model instances and manages their lifecycle.
+
+    This class maintains a record of all modified model instances that haven't been
+    committed yet. It provides functionality to track new modifications, handle commits,
+    and log any remaining uncommitted modifications.
+
+    The tracker organizes modifications by model class and prevents duplicate tracking
+    of the same instance. It also captures stack traces at the point of modification
+    to help with debugging.
+    """
+
+    modified_models: dict[int, Modification]
+    """
+    Dictionary mapping model classes to lists of their modifications
+    """
+
+    verbosity: MODIFICATION_TRACKER_VERBOSITY | None
+    """
+    The logging level to use when reporting uncommitted modifications
+    """
+
+    def __init__(
+        self,
+        verbosity: MODIFICATION_TRACKER_VERBOSITY | None = None,
+        known_first_party: list[str] | None = None,
+    ):
+        """
+        Initialize a new ModificationTracker.
+
+        Creates an empty modification tracking dictionary and sets the initial
+        verbosity level to None.
+        """
+        self.modified_models = {}
+        self.verbosity = verbosity
+        self.known_first_party = known_first_party
+
+    def track_modification(self, instance: TableBase) -> None:
+        """
+        Track a modification to a model instance along with its stack trace.
+
+        This method records a modification to a model instance if it hasn't already
+        been tracked. It captures both the full stack trace and a user-specific
+        stack trace at the point of modification.
+
+        :param instance: The model instance that was modified
+        :type instance: TableBase
+        """
+        # Get stack traces. By default we filter out all iceaxe code, but allow users to override this behavior
+        # if we want to still test this logic under test.
+        full_trace, user_trace = Modification.get_current_stack_trace(
+            package_allow_list=self.known_first_party,
+            package_deny_list=["iceaxe"] if not self.known_first_party else None,
+        )
+
+        # Only track if we haven't already tracked this instance
+        instance_id = id(instance)
+        if instance_id not in self.modified_models:
+            modification = Modification(
+                instance=instance, stack_trace=full_trace, user_stack_trace=user_trace
+            )
+            self.modified_models[instance_id] = modification
+
+    def clear_status(self, models: Sequence[TableBase]) -> None:
+        """
+        Remove models that are about to be committed from tracking.
+
+        This method should be called before committing changes to the database.
+        It removes the specified models from tracking since they will no longer
+        be in an uncommitted state.
+
+        :param models: List of model instances that will be committed
+        :type models: list[TableBase]
+        """
+        for instance in models:
+            instance_id = id(instance)
+            if instance_id in self.modified_models:
+                del self.modified_models[instance_id]
+
+    def log(self) -> None:
+        """
+        Log all uncommitted modifications with their stack traces.
+
+        This method logs information about all tracked modifications that haven't
+        been committed yet. The logging level is determined by the tracker's
+        verbosity setting. At the INFO level, it includes the full stack trace
+        in addition to the user stack trace.
+
+        If verbosity is not set (None), this method does nothing.
+        """
+        if not self.verbosity:
+            return
+
+        log_level = getattr(logging, self.verbosity)
+        LOGGER.setLevel(log_level)  # Ensure logger will capture messages at this level
+
+        for mod in self.modified_models.values():
+            LOGGER.log(
+                log_level, f"Object modified locally but not committed: {mod.instance}"
+            )
+            LOGGER.log(log_level, f"Modified at:\n{mod.user_stack_trace}")
+            if self.verbosity == "INFO":
+                LOGGER.log(log_level, f"Full stack trace:\n{mod.stack_trace}")

iceaxe/mountaineer/__init__.py

@@ -0,0 +1,10 @@
+from iceaxe.mountaineer import (
+    dependencies as DatabaseDependencies,  # noqa: F401
+)
+
+from .cli import (
+    apply_migration as apply_migration,
+    generate_migration as generate_migration,
+    rollback_migration as rollback_migration,
+)
+from .config import DatabaseConfig as DatabaseConfig

iceaxe/mountaineer/cli.py

@@ -0,0 +1,74 @@
+"""
+Alternative entrypoints to migrations/cli that use Mountaineer configurations
+to simplify the setup of the database connection.
+
+"""
+
+from mountaineer import ConfigBase, CoreDependencies, Depends
+from mountaineer.dependencies import get_function_dependencies
+
+from iceaxe.migrations.cli import handle_apply, handle_generate, handle_rollback
+from iceaxe.mountaineer.config import DatabaseConfig
+from iceaxe.mountaineer.dependencies.core import get_db_connection
+from iceaxe.session import DBConnection
+
+
+async def generate_migration(message: str | None = None):
+    async def _inner(
+        db_config: DatabaseConfig = Depends(
+            CoreDependencies.get_config_with_type(DatabaseConfig)
+        ),
+        core_config: ConfigBase = Depends(
+            CoreDependencies.get_config_with_type(ConfigBase)
+        ),
+        db_connection: DBConnection = Depends(get_db_connection),
+    ):
+        if not core_config.PACKAGE:
+            raise ValueError("No package provided in the configuration")
+
+        await handle_generate(
+            package=core_config.PACKAGE,
+            db_connection=db_connection,
+            message=message,
+        )
+
+    async with get_function_dependencies(callable=_inner) as values:
+        await _inner(**values)
+
+
+async def apply_migration():
+    async def _inner(
+        core_config: ConfigBase = Depends(
+            CoreDependencies.get_config_with_type(ConfigBase)
+        ),
+        db_connection: DBConnection = Depends(get_db_connection),
+    ):
+        if not core_config.PACKAGE:
+            raise ValueError("No package provided in the configuration")
+
+        await handle_apply(
+            package=core_config.PACKAGE,
+            db_connection=db_connection,
+        )
+
+    async with get_function_dependencies(callable=_inner) as values:
+        await _inner(**values)
+
+
+async def rollback_migration():
+    async def _inner(
+        core_config: ConfigBase = Depends(
+            CoreDependencies.get_config_with_type(ConfigBase)
+        ),
+        db_connection: DBConnection = Depends(get_db_connection),
+    ):
+        if not core_config.PACKAGE:
+            raise ValueError("No package provided in the configuration")
+
+        await handle_rollback(
+            package=core_config.PACKAGE,
+            db_connection=db_connection,
+        )
+
+    async with get_function_dependencies(callable=_inner) as values:
+        await _inner(**values)

iceaxe/mountaineer/config.py

@@ -0,0 +1,46 @@
+from pydantic_settings import BaseSettings
+
+from iceaxe.modifications import MODIFICATION_TRACKER_VERBOSITY
+
+
+class DatabaseConfig(BaseSettings):
+    """
+    Configuration settings for PostgreSQL database connection.
+    This class uses Pydantic's BaseSettings to manage environment-based configuration.
+    """
+
+    POSTGRES_HOST: str
+    """
+    The hostname where the PostgreSQL server is running.
+    This can be a domain name or IP address (e.g., 'localhost' or '127.0.0.1').
+    """
+
+    POSTGRES_USER: str
+    """
+    The username to authenticate with the PostgreSQL server.
+    This user should have appropriate permissions for the database operations.
+    """
+
+    POSTGRES_PASSWORD: str
+    """
+    The password for authenticating the PostgreSQL user.
+    This should be kept secure and not exposed in code or version control.
+    """
+
+    POSTGRES_DB: str
+    """
+    The name of the PostgreSQL database to connect to.
+    This database should exist on the server before attempting connection.
+    """
+
+    POSTGRES_PORT: int = 5432
+    """
+    The port number where PostgreSQL server is listening.
+    Defaults to the standard PostgreSQL port 5432 if not specified.
+    """
+
+    ICEAXE_UNCOMMITTED_VERBOSITY: MODIFICATION_TRACKER_VERBOSITY | None = None
+    """
+    The verbosity level for uncommitted modifications.
+    If set to None, uncommitted modifications will not be tracked.
+    """

iceaxe/mountaineer/dependencies/__init__.py

@@ -0,0 +1,6 @@
+"""
+Database dependencies for use in API endpoint routes.
+
+"""
+
+from .core import get_db_connection as get_db_connection

iceaxe/mountaineer/dependencies/core.py

@@ -0,0 +1,67 @@
+"""
+Optional compatibility layer for `mountaineer` dependency access.
+
+"""
+
+from typing import AsyncGenerator
+
+import asyncpg
+from mountaineer import CoreDependencies, Depends
+
+from iceaxe.mountaineer.config import DatabaseConfig
+from iceaxe.session import DBConnection
+
+
+async def get_db_connection(
+    config: DatabaseConfig = Depends(
+        CoreDependencies.get_config_with_type(DatabaseConfig)
+    ),
+) -> AsyncGenerator[DBConnection, None]:
+    """
+    A dependency that provides a database connection for use in FastAPI endpoints or other
+    dependency-injected contexts. The connection is automatically closed when the endpoint
+    finishes processing.
+
+    This dependency:
+    - Creates a new PostgreSQL connection using the provided configuration
+    - Wraps it in a DBConnection for ORM functionality
+    - Initializes the connection's type cache to support enums without per-connection
+      type introspection
+    - Automatically closes the connection when done
+    - Integrates with Mountaineer's dependency injection system
+
+    :param config: DatabaseConfig instance containing connection parameters.
+                  Automatically injected by Mountaineer if not provided.
+    :return: An async generator yielding a DBConnection instance
+
+    ```python
+    from fastapi import FastAPI, Depends
+    from iceaxe.mountaineer.dependencies import get_db_connection
+    from iceaxe.session import DBConnection
+
+    app = FastAPI()
+
+    # Basic usage in a FastAPI endpoint
+    @app.get("/users")
+    async def get_users(db: DBConnection = Depends(get_db_connection)):
+        users = await db.exec(select(User))
+        return users
+    ```
+    """
+    conn = await asyncpg.connect(
+        host=config.POSTGRES_HOST,
+        port=config.POSTGRES_PORT,
+        user=config.POSTGRES_USER,
+        password=config.POSTGRES_PASSWORD,
+        database=config.POSTGRES_DB,
+    )
+
+    connection = DBConnection(
+        conn, uncommitted_verbosity=config.ICEAXE_UNCOMMITTED_VERBOSITY
+    )
+    await connection.initialize_types()
+
+    try:
+        yield connection
+    finally:
+        await connection.close()

iceaxe/postgres.py

@@ -0,0 +1,133 @@
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class LexemePriority(StrEnum):
+    """Enum representing text search lexeme priority weights in Postgres."""
+
+    HIGHEST = "A"
+    HIGH = "B"
+    LOW = "C"
+    LOWEST = "D"
+
+
+class PostgresFieldBase(BaseModel):
+    """
+    Extensions to python core types that specify addition arguments
+    used by Postgres.
+
+    """
+
+    pass
+
+
+class PostgresDateTime(PostgresFieldBase):
+    """
+    Extension to Python's datetime type that specifies additional Postgres-specific configuration.
+    Used to customize the timezone behavior of datetime fields in Postgres.
+
+    ```python {{sticky: True}}
+    from iceaxe import Field, TableBase
+    class Event(TableBase):
+        id: int = Field(primary_key=True)
+        created_at: datetime = Field(postgres_config=PostgresDateTime(timezone=True))
+    ```
+    """
+
+    timezone: bool = False
+    """
+    Whether the datetime field should include timezone information in Postgres.
+        If True, maps to TIMESTAMP WITH TIME ZONE.
+        If False, maps to TIMESTAMP WITHOUT TIME ZONE.
+        Defaults to False.
+
+    """
+
+
+class PostgresTime(PostgresFieldBase):
+    """
+    Extension to Python's time type that specifies additional Postgres-specific configuration.
+    Used to customize the timezone behavior of time fields in Postgres.
+
+    ```python {{sticky: True}}
+    from iceaxe import Field, TableBase
+    class Schedule(TableBase):
+        id: int = Field(primary_key=True)
+        start_time: time = Field(postgres_config=PostgresTime(timezone=True))
+    ```
+    """
+
+    timezone: bool = False
+    """
+    Whether the time field should include timezone information in Postgres.
+        If True, maps to TIME WITH TIME ZONE.
+        If False, maps to TIME WITHOUT TIME ZONE.
+        Defaults to False.
+
+    """
+
+
+class PostgresFullText(PostgresFieldBase):
+    """
+    Extension to Python's string type that specifies additional Postgres-specific configuration
+    for full-text search. Used to customize the behavior of text search fields in Postgres.
+
+    ```python {{sticky: True}}
+    from iceaxe import TableBase, Field
+    from iceaxe.postgres import PostgresFullText, LexemePriority
+
+    class Article(TableBase):
+        id: int = Field(primary_key=True)
+        title: str = Field(postgres_config=PostgresFullText(
+            language="english",
+            weight=LexemePriority.HIGHEST  # or "A"
+        ))
+        content: str = Field(postgres_config=PostgresFullText(
+            language="english",
+            weight=LexemePriority.HIGH  # or "B"
+        ))
+    ```
+    """
+
+    language: str = "english"
+    """
+    The language to use for text search operations.
+    Defaults to 'english'.
+    """
+    weight: Literal["A", "B", "C", "D"] | LexemePriority = LexemePriority.HIGHEST
+    """
+    The weight to assign to matches in this column.
+    Can be specified either as a string literal ("A", "B", "C", "D") or using LexemePriority enum.
+    A/HIGHEST is highest priority, D/LOWEST is lowest priority.
+    Defaults to LexemePriority.HIGHEST (A).
+    """
+
+
+ForeignKeyModifications = Literal[
+    "RESTRICT", "NO ACTION", "CASCADE", "SET DEFAULT", "SET NULL"
+]
+
+
+class PostgresForeignKey(PostgresFieldBase):
+    """
+    Extension to Python's ForeignKey type that specifies additional Postgres-specific configuration.
+    Used to customize the behavior of foreign key constraints in Postgres.
+
+    ```python {{sticky: True}}
+    from iceaxe import TableBase, Field
+
+    class Office(TableBase):
+        id: int = Field(primary_key=True)
+        name: str
+
+    class Employee(TableBase):
+        id: int = Field(primary_key=True)
+        name: str
+        office_id: int = Field(foreign_key="office.id", postgres_config=PostgresForeignKey(on_delete="CASCADE", on_update="CASCADE"))
+    ```
+    """
+
+    on_delete: ForeignKeyModifications = "NO ACTION"
+    on_update: ForeignKeyModifications = "NO ACTION"