Class TortoiseContext

tortoise/context.py:119–522

Encapsulates all Tortoise ORM state for a single execution context. Each TortoiseContext instance owns: - A ConnectionHandler with database connections - An Apps registry with model definitions - Initialization state tracking Use cases: - Isolated test environments (py

class TortoiseContext:
    """
    Encapsulates all Tortoise ORM state for a single execution context.

    Each TortoiseContext instance owns:
    - A ConnectionHandler with database connections
    - An Apps registry with model definitions
    - Initialization state tracking

    Use cases:
    - Isolated test environments (pytest fixtures)
    - Parallel test execution with pytest-xdist
    - Multiple database configurations in the same process
    - Scoped database sessions with automatic cleanup

    The context is tracked via contextvars, allowing async code to
    automatically resolve the correct connections without explicit passing.

    Example:
        async with TortoiseContext() as ctx:
            await ctx.init(
                db_url="sqlite://:memory:",
                modules={"models": ["myapp.models"]}
            )
            await ctx.generate_schemas()
            # Models use this context's connections automatically
            user = await User.create(name="test")
    """

    def __init__(self) -> None:
        self._connections: ConnectionHandler | None = None
        self._apps: Apps | None = None
        self._inited: bool = False
        self._token: contextvars.Token[TortoiseContext | None] | None = None
        self._table_name_generator: Callable[[type[Model]], str] | None = None
        self._default_connection: str | None = None
        # Timezone settings
        self._use_tz: bool = True
        self._timezone: str = "UTC"
        # Routers
        self._routers: list[type] = []

    @property
    def connections(self) -> ConnectionHandler:
        """
        Get the ConnectionHandler for this context.

        Creates a new ConnectionHandler on first access (lazy initialization).
        The handler uses instance-level storage for true isolation between contexts.

        Returns:
            The ConnectionHandler instance owned by this context.
        """
        if self._connections is None:
            # ConnectionHandler always uses instance storage for isolation
            self._connections = ConnectionHandler()
        return self._connections