fastapi-async-sqlalchemy 0.8.0a1__tar.gz → 0.8.0b1__tar.gz

{fastapi_async_sqlalchemy-0.8.0a1 → fastapi_async_sqlalchemy-0.8.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-async-sqlalchemy
-Version: 0.8.0a1
+Version: 0.8.0b1
 Summary: SQLAlchemy middleware for FastAPI
 Home-page: https://github.com/h0rn3t/fastapi-async-sqlalchemy.git
 Author: Eugene Shershen
@@ -219,6 +219,24 @@ above. This keeps database access available for the whole body while making it
 clear that the session lifetime belongs to the stream, not the original request
 transaction.
 
+#### Type hints for `db`
+
+Use `DBSessionMeta` (or its alias `DBSessionType`) when you need to annotate
+a function or attribute that holds the `db` proxy:
+
+```python
+from fastapi_async_sqlalchemy import DBSessionMeta, db
+
+def get_db() -> DBSessionMeta:
+    return db
+```
+
+At runtime `DBSessionMeta` is the metaclass of `db`, so `isinstance(db,
+DBSessionMeta)` and `type(db) is DBSessionMeta` both work. For static type
+checkers (mypy, pyright) and IDE autocompletion `DBSessionMeta` resolves to
+a structural `Protocol` describing the public API (`session`, `connection`,
+`gather`, and the `db(...)` call).
+
 #### SQLAlchemy events (`before_insert`, `after_insert`, ...)
 
 SQLAlchemy's event system is independent of the session/engine — register

{fastapi_async_sqlalchemy-0.8.0a1 → fastapi_async_sqlalchemy-0.8.0b1}/README.md

@@ -176,6 +176,24 @@ above. This keeps database access available for the whole body while making it
 clear that the session lifetime belongs to the stream, not the original request
 transaction.
 
+#### Type hints for `db`
+
+Use `DBSessionMeta` (or its alias `DBSessionType`) when you need to annotate
+a function or attribute that holds the `db` proxy:
+
+```python
+from fastapi_async_sqlalchemy import DBSessionMeta, db
+
+def get_db() -> DBSessionMeta:
+    return db
+```
+
+At runtime `DBSessionMeta` is the metaclass of `db`, so `isinstance(db,
+DBSessionMeta)` and `type(db) is DBSessionMeta` both work. For static type
+checkers (mypy, pyright) and IDE autocompletion `DBSessionMeta` resolves to
+a structural `Protocol` describing the public API (`session`, `connection`,
+`gather`, and the `db(...)` call).
+
 #### SQLAlchemy events (`before_insert`, `after_insert`, ...)
 
 SQLAlchemy's event system is independent of the session/engine — register

fastapi_async_sqlalchemy-0.8.0b1/fastapi_async_sqlalchemy/__init__.py

@@ -0,0 +1,32 @@
+from typing import TYPE_CHECKING
+
+from fastapi_async_sqlalchemy.middleware import (
+    SQLAlchemyMiddleware,
+    create_middleware_and_session_proxy,
+    db,
+)
+
+# DBSessionMeta exposure (Issue #18).
+#
+# At type-check time, expose a structural Protocol so users get full mypy /
+# IDE autocomplete on ``db.session``, ``db.connection()`` and ``db.gather()``
+# when they annotate code with ``DBSessionMeta``.
+#
+# At runtime, expose the actual metaclass of ``db`` (a closure-local class
+# created by ``create_middleware_and_session_proxy``) so ``isinstance(db,
+# DBSessionMeta)`` and ``type(db) is DBSessionMeta`` keep working as in v0.5.
+if TYPE_CHECKING:
+    from fastapi_async_sqlalchemy._types import DBSessionMeta, DBSessionType
+else:
+    DBSessionMeta = type(db)
+    DBSessionType = DBSessionMeta
+
+__all__ = [
+    "db",
+    "SQLAlchemyMiddleware",
+    "create_middleware_and_session_proxy",
+    "DBSessionMeta",
+    "DBSessionType",
+]
+
+__version__ = "0.8.0b1"

fastapi_async_sqlalchemy-0.8.0b1/fastapi_async_sqlalchemy/_types.py

@@ -0,0 +1,63 @@
+"""Type hints for the public ``db`` session proxy (Issue #18).
+
+The runtime ``DBSessionMeta`` is the metaclass produced by
+``create_middleware_and_session_proxy`` and lives inside that closure, so it is
+not visible to static type checkers. This module exposes a structural
+``Protocol`` with the same public API so users can annotate code as::
+
+    def get_db() -> DBSessionMeta:
+        return db
+
+and get full IDE autocomplete / mypy support on ``db.session``,
+``db.connection()`` and ``db.gather()``.
+
+At runtime ``fastapi_async_sqlalchemy.DBSessionMeta`` is rebound to
+``type(db)`` (the actual metaclass) so ``isinstance(db, DBSessionMeta)``
+keeps working as before.
+"""
+
+from __future__ import annotations
+
+from contextlib import AbstractAsyncContextManager
+from typing import Any, Protocol, runtime_checkable
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+@runtime_checkable
+class DBSessionMeta(Protocol):
+    """Structural type for the ``db`` session proxy.
+
+    Use as a return / parameter annotation when you want to pass ``db``
+    around with proper type hints instead of falling back to ``Any``.
+    """
+
+    @property
+    def session(self) -> AsyncSession:
+        """Return the ``AsyncSession`` bound to the current async context."""
+        ...
+
+    def connection(self) -> AbstractAsyncContextManager[AsyncSession]:
+        """Async context manager that yields a throttled session."""
+        ...
+
+    async def gather(
+        self,
+        *coros_or_futures: Any,
+        return_exceptions: bool = ...,
+    ) -> list[Any]:
+        """Pool-aware drop-in replacement for ``asyncio.gather``."""
+        ...
+
+    def __call__(
+        self,
+        session_args: dict[str, Any] | None = ...,
+        commit_on_exit: bool = ...,
+        multi_sessions: bool = ...,
+        max_concurrent: int | None = ...,
+    ) -> AbstractAsyncContextManager[Any]:
+        """Open an explicit session context: ``async with db(): ...``."""
+        ...
+
+
+DBSessionType = DBSessionMeta

{fastapi_async_sqlalchemy-0.8.0a1 → fastapi_async_sqlalchemy-0.8.0b1}/fastapi_async_sqlalchemy/middleware.py

@@ -5,6 +5,7 @@ import logging
 import warnings
 from contextvars import ContextVar
 from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, cast
 
 from sqlalchemy.engine.url import URL
 from sqlalchemy.ext.asyncio import (
@@ -20,6 +21,11 @@ from fastapi_async_sqlalchemy.exceptions import (
     SessionNotInitialisedError,
 )
 
+if TYPE_CHECKING:
+    # Imported under an alias to avoid colliding with the closure-local
+    # `DBSessionMeta` metaclass defined inside ``create_middleware_and_session_proxy``.
+    from fastapi_async_sqlalchemy._types import DBSessionMeta as _DBSessionMetaProtocol
+
 try:
     from sqlmodel.ext.asyncio.session import AsyncSession as SQLModelAsyncSession
 
@@ -28,7 +34,7 @@ except ImportError:
     DefaultAsyncSession: type[AsyncSession] = AsyncSession  # type: ignore
 
 
-def create_middleware_and_session_proxy() -> tuple:
+def create_middleware_and_session_proxy() -> tuple[type, _DBSessionMetaProtocol]:
     _Session: async_sessionmaker | None = None
     _Session_engine: AsyncEngine | None = None
     _session: ContextVar[AsyncSession | None] = ContextVar("_session", default=None)
@@ -771,7 +777,11 @@ def create_middleware_and_session_proxy() -> tuple:
                         _request_session.reset(self.request_session_token)
                     _session.reset(self.token)
 
-    return _SQLAlchemyMiddleware, DBSession
+    # `db` is the `DBSession` class itself; its public API (`session`,
+    # `connection`, `gather`, `__call__`) lives on the metaclass. Cast to the
+    # `DBSessionMeta` Protocol so static type checkers see that surface
+    # instead of the class object's own attributes.
+    return _SQLAlchemyMiddleware, cast("_DBSessionMetaProtocol", DBSession)
 
 
 SQLAlchemyMiddleware, db = create_middleware_and_session_proxy()

{fastapi_async_sqlalchemy-0.8.0a1 → fastapi_async_sqlalchemy-0.8.0b1}/fastapi_async_sqlalchemy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-async-sqlalchemy
-Version: 0.8.0a1
+Version: 0.8.0b1
 Summary: SQLAlchemy middleware for FastAPI
 Home-page: https://github.com/h0rn3t/fastapi-async-sqlalchemy.git
 Author: Eugene Shershen
@@ -219,6 +219,24 @@ above. This keeps database access available for the whole body while making it
 clear that the session lifetime belongs to the stream, not the original request
 transaction.
 
+#### Type hints for `db`
+
+Use `DBSessionMeta` (or its alias `DBSessionType`) when you need to annotate
+a function or attribute that holds the `db` proxy:
+
+```python
+from fastapi_async_sqlalchemy import DBSessionMeta, db
+
+def get_db() -> DBSessionMeta:
+    return db
+```
+
+At runtime `DBSessionMeta` is the metaclass of `db`, so `isinstance(db,
+DBSessionMeta)` and `type(db) is DBSessionMeta` both work. For static type
+checkers (mypy, pyright) and IDE autocompletion `DBSessionMeta` resolves to
+a structural `Protocol` describing the public API (`session`, `connection`,
+`gather`, and the `db(...)` call).
+
 #### SQLAlchemy events (`before_insert`, `after_insert`, ...)
 
 SQLAlchemy's event system is independent of the session/engine — register

{fastapi_async_sqlalchemy-0.8.0a1 → fastapi_async_sqlalchemy-0.8.0b1}/fastapi_async_sqlalchemy.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ README.md
 pyproject.toml
 setup.py
 fastapi_async_sqlalchemy/__init__.py
+fastapi_async_sqlalchemy/_types.py
 fastapi_async_sqlalchemy/exceptions.py
 fastapi_async_sqlalchemy/middleware.py
 fastapi_async_sqlalchemy/py.typed

{fastapi_async_sqlalchemy-0.8.0a1 → fastapi_async_sqlalchemy-0.8.0b1}/tests/test_type_hints_compatibility.py

@@ -210,3 +210,34 @@ def test_multiple_imports():
     assert db1 is db2
     assert type(db1) is Meta1
     assert type(db2) is Meta2
+
+
+def test_protocol_describes_public_api():
+    """The static-typing Protocol must list every public attribute of `db`.
+
+    Issue #18 — guarantee that mypy/IDE see the full public surface of the
+    proxy via the `DBSessionMeta` annotation, not just an opaque `type`.
+    """
+    from fastapi_async_sqlalchemy._types import DBSessionMeta as ProtocolMeta
+
+    # Protocol attributes that mypy / IDEs will see.
+    expected = {"session", "connection", "gather", "__call__"}
+    declared = set(getattr(ProtocolMeta, "__protocol_attrs__", set()))
+    assert expected.issubset(declared), f"Protocol is missing expected attrs: {expected - declared}"
+
+    # Each declared attribute must actually exist on `type(db)` so the
+    # annotation is structurally honest.
+    for attr in expected:
+        assert hasattr(type(db), attr), f"type(db) is missing public attr {attr!r}"
+
+
+def test_protocol_runtime_checkable_against_db():
+    """`isinstance(db, DBSessionMeta)` must succeed via the Protocol path too."""
+    from fastapi_async_sqlalchemy._types import DBSessionMeta as ProtocolMeta
+
+    assert isinstance(db, ProtocolMeta)
+
+    from fastapi_async_sqlalchemy.middleware import create_middleware_and_session_proxy
+
+    _, custom_db = create_middleware_and_session_proxy()
+    assert isinstance(custom_db, ProtocolMeta)

fastapi_async_sqlalchemy-0.8.0a1/fastapi_async_sqlalchemy/__init__.py

@@ -1,22 +0,0 @@
-from fastapi_async_sqlalchemy.middleware import (
-    SQLAlchemyMiddleware,
-    create_middleware_and_session_proxy,
-    db,
-)
-
-# Export DBSessionMeta type for type hints (Issue #18)
-# Note: DBSessionMeta is the metaclass of db, created dynamically.
-# It can be used in runtime type checks (isinstance, type(db) is DBSessionMeta)
-# but mypy may show warnings when used in type annotations due to its dynamic nature.
-DBSessionMeta = type(db)
-DBSessionType = DBSessionMeta  # Alternative name for backwards compatibility
-
-__all__ = [
-    "db",
-    "SQLAlchemyMiddleware",
-    "create_middleware_and_session_proxy",
-    "DBSessionMeta",
-    "DBSessionType",
-]
-
-__version__ = "0.8.0a1"