FastSQLA 0.3.0__py3-none-any.whl → 0.4.4__py3-none-any.whl

{FastSQLA-0.3.0.dist-info → fastsqla-0.4.4.dist-info}/METADATA

@@ -1,9 +1,8 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: FastSQLA
-Version: 0.3.0
+Version: 0.4.4
 Summary: SQLAlchemy extension for FastAPI that supports asynchronous sessions and includes built-in pagination.
-Author-email: Hadrien David <bonjour@hadriendavid.com>
-License: MIT License
+Author-email: Hadrien David <h@driendavid.com>
 Project-URL: Homepage, https://github.com/hadrien/fastsqla
 Project-URL: Documentation, https://github.com/hadrien/fastsqla
 Project-URL: Repository, https://github.com/hadrien/fastsqla
@@ -19,7 +18,6 @@ Classifier: Framework :: Pydantic
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Information Technology
 Classifier: Intended Audience :: System Administrators
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.12
@@ -36,12 +34,12 @@ Classifier: Topic :: Software Development
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
-License-File: LICENSE
 Requires-Dist: fastapi>=0.115.6
 Requires-Dist: sqlalchemy[asyncio]>=2.0.37
 Requires-Dist: structlog>=24.4.0
 Provides-Extra: docs
 Requires-Dist: mkdocs-glightbox>=0.4.0; extra == "docs"
+Requires-Dist: mkdocs-llmstxt>=0.2.0; extra == "docs"
 Requires-Dist: mkdocs-material>=9.5.50; extra == "docs"
 Requires-Dist: mkdocstrings[python]>=0.27.0; extra == "docs"
 Provides-Extra: sqlmodel

fastsqla-0.4.4.dist-info/RECORD

@@ -0,0 +1,5 @@
+fastsqla.py,sha256=wO4KpgkA3jVOCtpbwORlaUuOu4YsEQoRslzg9wjDNBk,12364
+fastsqla-0.4.4.dist-info/METADATA,sha256=lyIlPmzzZ99nG1uKAmrpi1lH7Zpclod8LUTmNj0OOuo,12425
+fastsqla-0.4.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+fastsqla-0.4.4.dist-info/top_level.txt,sha256=Uh-1ssTtuSS4_SYCBeDoDVOxqWTrRAPEBZkuih5isSE,9
+fastsqla-0.4.4.dist-info/RECORD,,

{FastSQLA-0.3.0.dist-info → fastsqla-0.4.4.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.8.0)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

fastsqla.py

@@ -1,7 +1,7 @@
 import math
 import os
 from collections.abc import AsyncGenerator, Awaitable, Callable, Iterable
-from contextlib import asynccontextmanager
+from contextlib import _AsyncGeneratorContextManager, asynccontextmanager
 from typing import Annotated, Generic, TypeVar, TypedDict
 
 from fastapi import Depends, FastAPI, Query
@@ -78,79 +78,118 @@ class State(TypedDict):
     fastsqla_engine: AsyncEngine
 
 
-@asynccontextmanager
-async def lifespan(app: FastAPI) -> AsyncGenerator[State, None]:
-    """Use `fastsqla.lifespan` to set up SQLAlchemy.
-
-    In an ASGI application, [lifespan events](https://asgi.readthedocs.io/en/latest/specs/lifespan.html)
-    are used to communicate startup & shutdown events.
+def new_lifespan(
+    url: str | None = None, **kw
+) -> Callable[[FastAPI], _AsyncGeneratorContextManager[State, None]]:
+    """Create a new lifespan async context manager.
 
-    The [`lifespan`](https://fastapi.tiangolo.com/advanced/events/#lifespan) parameter of
-    the `FastAPI` app can be assigned to a context manager, which is opened when the app
-    starts and closed when the app stops.
+    It expects the exact same parameters as
+    [`sqlalchemy.ext.asyncio.create_async_engine`][sqlalchemy.ext.asyncio.create_async_engine]
 
-    In order for `FastSQLA` to setup `SQLAlchemy` before the app is started, set
-    `lifespan` parameter to `fastsqla.lifespan`:
+    Example:
 
     ```python
     from fastapi import FastAPI
-    from fastsqla import lifespan
+    from fastsqla import new_lifespan
 
+    lifespan = new_lifespan(
+        "sqlite+aiosqlite:///app/db.sqlite", connect_args={"autocommit": False}
+    )
 
     app = FastAPI(lifespan=lifespan)
     ```
 
-    If multiple lifespan contexts are required, create an async context manager function
-    to handle them and set it as the app's lifespan:
+    Args:
+        url (str): Database url.
+        kw (dict): Configuration parameters as expected by [`sqlalchemy.ext.asyncio.create_async_engine`][sqlalchemy.ext.asyncio.create_async_engine]
+    """
 
-    ```python
-    from collections.abc import AsyncGenerator
-    from contextlib import asynccontextmanager
+    has_config = url is not None
 
-    from fastapi import FastAPI
-    from fastsqla import lifespan as fastsqla_lifespan
-    from this_other_library import another_lifespan
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncGenerator[State, None]:
+        if has_config:
+            prefix = ""
+            sqla_config = {**kw, **{"url": url}}
 
+        else:
+            prefix = "sqlalchemy_"
+            sqla_config = {k.lower(): v for k, v in os.environ.items()}
 
-    @asynccontextmanager
-    async def lifespan(app:FastAPI) -> AsyncGenerator[dict, None]:
-        async with AsyncExitStack() as stack:
-            yield {
-                **stack.enter_async_context(lifespan(app)),
-                **stack.enter_async_context(another_lifespan(app)),
-            }
+        try:
+            engine = async_engine_from_config(sqla_config, prefix=prefix)
 
+        except KeyError as exc:
+            raise Exception(f"Missing {prefix}{exc.args[0]} in environ.") from exc
 
-    app = FastAPI(lifespan=lifespan)
-    ```
+        async with engine.begin() as conn:
+            await conn.run_sync(Base.prepare)
 
-    To learn more about lifespan protocol:
+        SessionFactory.configure(bind=engine)
 
-    * [Lifespan Protocol](https://asgi.readthedocs.io/en/latest/specs/lifespan.html)
-    * [Use Lifespan State instead of `app.state`](https://github.com/Kludex/fastapi-tips?tab=readme-ov-file#6-use-lifespan-state-instead-of-appstate)
-    * [FastAPI lifespan documentation](https://fastapi.tiangolo.com/advanced/events/)
-    """
-    prefix = "sqlalchemy_"
-    sqla_config = {k.lower(): v for k, v in os.environ.items()}
-    try:
-        engine = async_engine_from_config(sqla_config, prefix=prefix)
+        await logger.ainfo("Configured SQLAlchemy.")
 
-    except KeyError as exc:
-        raise Exception(f"Missing {prefix}{exc.args[0]} in environ.") from exc
+        yield {"fastsqla_engine": engine}
 
-    async with engine.begin() as conn:
-        await conn.run_sync(Base.prepare)
+        SessionFactory.configure(bind=None)
+        await engine.dispose()
 
-    SessionFactory.configure(bind=engine)
+        await logger.ainfo("Cleared SQLAlchemy config.")
 
-    await logger.ainfo("Configured SQLAlchemy.")
+    return lifespan
 
-    yield {"fastsqla_engine": engine}
 
-    SessionFactory.configure(bind=None)
-    await engine.dispose()
+lifespan = new_lifespan()
+"""Use `fastsqla.lifespan` to set up SQLAlchemy directly from environment variables.
 
-    await logger.ainfo("Cleared SQLAlchemy config.")
+In an ASGI application, [lifespan events](https://asgi.readthedocs.io/en/latest/specs/lifespan.html)
+are used to communicate startup & shutdown events.
+
+The [`lifespan`](https://fastapi.tiangolo.com/advanced/events/#lifespan) parameter of
+the `FastAPI` app can be assigned to a context manager, which is opened when the app
+starts and closed when the app stops.
+
+In order for `FastSQLA` to setup `SQLAlchemy` before the app is started, set
+`lifespan` parameter to `fastsqla.lifespan`:
+
+```python
+from fastapi import FastAPI
+from fastsqla import lifespan
+
+
+app = FastAPI(lifespan=lifespan)
+```
+
+If multiple lifespan contexts are required, create an async context manager function
+to handle them and set it as the app's lifespan:
+
+```python
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastsqla import lifespan as fastsqla_lifespan
+from this_other_library import another_lifespan
+
+
+@asynccontextmanager
+async def lifespan(app:FastAPI) -> AsyncGenerator[dict, None]:
+    async with AsyncExitStack() as stack:
+        yield {
+            **stack.enter_async_context(lifespan(app)),
+            **stack.enter_async_context(another_lifespan(app)),
+        }
+
+
+app = FastAPI(lifespan=lifespan)
+```
+
+To learn more about lifespan protocol:
+
+* [Lifespan Protocol](https://asgi.readthedocs.io/en/latest/specs/lifespan.html)
+* [Use Lifespan State instead of `app.state`](https://github.com/Kludex/fastapi-tips?tab=readme-ov-file#6-use-lifespan-state-instead-of-appstate)
+* [FastAPI lifespan documentation](https://fastapi.tiangolo.com/advanced/events/)
+"""
 
 
 @asynccontextmanager
@@ -225,12 +264,15 @@ At the end of request handling:
 
 * If no exceptions are raised, the session is automatically committed.
 * If an exception is raised, the session is automatically rolled back.
-* In alls cases, the session is closed and the associated connection is returned to the
+* In all cases, the session is closed and the associated connection is returned to the
   connection pool.
 
 Example:
 
-``` py title="example.py" hl_lines="3"
+``` py title="example.py" hl_lines="6"
+from fastsqla import Item, Session
+...
+
 @app.get("/heros/{hero_id}", response_model=Item[HeroItem])
 async def get_items(
     session: Session, # (1)!
@@ -252,6 +294,10 @@ If you need data generated by the database server, such as auto-incremented IDs,
 the session instead:
 
 ```python
+from fastsqla import Item, Session
+...
+
+
 @app.post("/heros", response_model=Item[HeroItem])
 async def create_item(session: Session, new_hero: HeroBase):
     hero = Hero(**new_hero.model_dump())
@@ -283,6 +329,23 @@ class Collection(BaseModel, Generic[T]):
 
 
 class Page(Collection[T]):
+    """Generic container that contains collection data and page metadata.
+
+    The `Page` model is used to return paginated data in paginated endpoints:
+
+    ```json
+    {
+        "data": list[T],
+        "meta": {
+            "offset": int,
+            "total_items": int,
+            "total_pages": int,
+            "page_number": int,
+        }
+    }
+    ```
+    """
+
     meta: Meta
 
 
@@ -360,18 +423,5 @@ Paginate = Annotated[PaginateType[T], Depends(new_pagination())]
 """A dependency used in endpoints to paginate `SQLAlchemy` select queries.
 
 It adds **`offset`** and **`limit`** query parameters to the endpoint, which are used to
-paginate. The model returned by the endpoint is a `Page` model. It contains a page of
-data and metadata:
-
-```json
-{
-    "data": List[T],
-    "meta": {
-        "offset": int,
-        "total_items": int,
-        "total_pages": int,
-        "page_number": int,
-    }
-}
-```
+paginate. The model returned by the endpoint is a [`Page`][fastsqla.Page] model.
 """

FastSQLA-0.3.0.dist-info/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Hadrien David
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

FastSQLA-0.3.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-fastsqla.py,sha256=yxfc96izBhaT8zobtm74OEigO5rfeCfmbRGZ5-jN3EM,11131
-FastSQLA-0.3.0.dist-info/LICENSE,sha256=uNKcyfhTq0YUZxgSDiDGBHoJfflKjGWecSfWxpYe_O4,1070
-FastSQLA-0.3.0.dist-info/METADATA,sha256=JuDDHA6vy8mzszl2C7iIqcPZvl8vLmQdNIPIKEMa5EM,12473
-FastSQLA-0.3.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-FastSQLA-0.3.0.dist-info/top_level.txt,sha256=Uh-1ssTtuSS4_SYCBeDoDVOxqWTrRAPEBZkuih5isSE,9
-FastSQLA-0.3.0.dist-info/RECORD,,