sqlspec 0.47.0__cp314-cp314-win_amd64.whl

sqlspec/extensions/flask/__init__.py

@@ -0,0 +1,38 @@
+"""Flask extension for SQLSpec.
+
+Provides request-scoped session management, automatic transaction handling,
+and async adapter support via portal pattern.
+
+Example:
+    from flask import Flask
+    from sqlspec import SQLSpec
+    from sqlspec.adapters.sqlite import SqliteConfig
+    from sqlspec.extensions.flask import SQLSpecPlugin
+
+    sqlspec = SQLSpec()
+    config = SqliteConfig(
+        connection_config={"database": "app.db"},
+        extension_config={
+            "flask": {
+                "commit_mode": "autocommit",
+                "session_key": "db"
+            }
+        }
+    )
+    sqlspec.add_config(config)
+
+    app = Flask(__name__)
+    plugin = SQLSpecPlugin(sqlspec, app)
+
+    @app.route("/users")
+    def list_users():
+        db = plugin.get_session()
+        result = db.execute("SELECT * FROM users")
+        return {"users": result.all()}
+"""
+
+from sqlspec.extensions.flask._state import FlaskConfigState
+from sqlspec.extensions.flask.extension import SQLSpecPlugin
+from sqlspec.service import SQLSpecAsyncService, SQLSpecSyncService
+
+__all__ = ("FlaskConfigState", "SQLSpecAsyncService", "SQLSpecPlugin", "SQLSpecSyncService")

sqlspec/extensions/flask/_state.py

@@ -0,0 +1,87 @@
+"""Flask configuration state management."""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal
+
+from sqlspec.exceptions import ImproperConfigurationError
+
+if TYPE_CHECKING:
+    from sqlspec.config import DatabaseConfigProtocol
+
+__all__ = ("FlaskConfigState",)
+
+HTTP_SUCCESS_MIN = 200
+HTTP_SUCCESS_MAX = 300
+HTTP_REDIRECT_MAX = 400
+
+
+@dataclass
+class FlaskConfigState:
+    """Internal state for each database configuration in Flask extension.
+
+    Holds configuration, state keys, commit settings, and transaction logic.
+    """
+
+    config: "DatabaseConfigProtocol[Any, Any, Any]"
+    connection_key: str
+    session_key: str
+    commit_mode: Literal["manual", "autocommit", "autocommit_include_redirect"]
+    extra_commit_statuses: "set[int] | None"
+    extra_rollback_statuses: "set[int] | None"
+    is_async: bool
+    disable_di: bool
+    enable_correlation_middleware: bool = False
+    correlation_header: str = "x-request-id"
+    correlation_headers: "tuple[str, ...] | None" = None
+    auto_trace_headers: bool = True
+    enable_sqlcommenter_middleware: bool = True
+
+    def __post_init__(self) -> None:
+        """Validate status configuration."""
+        extra_commit_statuses = self.extra_commit_statuses or set()
+        extra_rollback_statuses = self.extra_rollback_statuses or set()
+        if extra_commit_statuses & extra_rollback_statuses:
+            msg = "Extra rollback statuses and commit statuses must not share any status codes"
+            raise ImproperConfigurationError(msg)
+
+    def should_commit(self, status_code: int) -> bool:
+        """Determine if HTTP status code should trigger commit.
+
+        Args:
+            status_code: HTTP response status code.
+
+        Returns:
+            True if status should trigger commit, False otherwise.
+        """
+        if self.extra_commit_statuses and status_code in self.extra_commit_statuses:
+            return True
+
+        if self.extra_rollback_statuses and status_code in self.extra_rollback_statuses:
+            return False
+
+        if self.commit_mode == "manual":
+            return False
+
+        if self.commit_mode == "autocommit":
+            return HTTP_SUCCESS_MIN <= status_code < HTTP_SUCCESS_MAX
+
+        if self.commit_mode == "autocommit_include_redirect":
+            return HTTP_SUCCESS_MIN <= status_code < HTTP_REDIRECT_MAX
+
+        return False
+
+    def should_rollback(self, status_code: int) -> bool:
+        """Determine if HTTP status code should trigger rollback.
+
+        In autocommit modes, anything that doesn't commit should rollback.
+
+        Args:
+            status_code: HTTP response status code.
+
+        Returns:
+            True if status should trigger rollback, False otherwise.
+        """
+        if self.commit_mode == "manual":
+            return False
+
+        return not self.should_commit(status_code)

sqlspec/extensions/flask/_utils.py

@@ -0,0 +1,71 @@
+"""Helper utilities for Flask extension."""
+
+from typing import TYPE_CHECKING, Any, cast
+
+if TYPE_CHECKING:
+    from sqlspec.extensions.flask._state import FlaskConfigState
+    from sqlspec.protocols import DictProtocol
+    from sqlspec.utils.portal import Portal
+
+__all__ = ("get_context_value", "get_or_create_session", "has_context_value", "pop_context_value", "set_context_value")
+
+_MISSING = object()
+
+
+def _get_context_dict(target: Any) -> dict[str, Any]:
+    """Return the underlying context dictionary."""
+    return cast("DictProtocol", target).__dict__
+
+
+def get_context_value(target: Any, key: str, default: Any = _MISSING) -> Any:
+    """Get a value from a Flask context object."""
+    data = _get_context_dict(target)
+    if default is _MISSING:
+        return data[key]
+    return data.get(key, default)
+
+
+def set_context_value(target: Any, key: str, value: Any) -> None:
+    """Set a value on a Flask context object."""
+    _get_context_dict(target)[key] = value
+
+
+def pop_context_value(target: Any, key: str) -> Any | None:
+    """Remove a value from a Flask context object."""
+    return _get_context_dict(target).pop(key, None)
+
+
+def has_context_value(target: Any, key: str) -> bool:
+    """Check if a Flask context object has a stored value."""
+    return key in _get_context_dict(target)
+
+
+def get_or_create_session(config_state: "FlaskConfigState", portal: "Portal | None") -> Any:
+    """Get or create database session for current request.
+
+    Sessions are cached per request in Flask g object to ensure
+    the same session is reused throughout the request lifecycle.
+
+    Args:
+        config_state: Configuration state for this database.
+        portal: Portal for async operations (None for sync).
+
+    Returns:
+        Database session (driver instance).
+    """
+    from flask import g
+
+    cache_key = f"sqlspec_session_cache_{config_state.session_key}"
+
+    cached_session = get_context_value(g, cache_key, None)
+    if cached_session is not None:
+        return cached_session
+
+    connection = get_context_value(g, config_state.connection_key)
+
+    session = config_state.config.driver_type(
+        connection=connection, statement_config=config_state.config.statement_config
+    )
+
+    set_context_value(g, cache_key, session)
+    return session