FastSQLA 0.7.0__tar.gz → 0.8.0__tar.gz

{fastsqla-0.7.0 → fastsqla-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: FastSQLA
-Version: 0.7.0
+Version: 0.8.0
 Summary: SQLAlchemy extension for FastAPI that supports asynchronous sessions and includes built-in pagination.
 Author-email: Hadrien David <h@driendavid.com>
 Project-URL: Homepage, https://github.com/hadrien/fastsqla
@@ -8,7 +8,7 @@ Project-URL: Documentation, https://github.com/hadrien/fastsqla
 Project-URL: Repository, https://github.com/hadrien/fastsqla
 Project-URL: Issues, https://github.com/hadrien/fastsqla/issues
 Project-URL: Changelog, https://github.com/hadrien/fastsqla/releases
-Keywords: FastAPI,SQLAlchemy,AsyncIO
+Keywords: fastapi,sqlalchemy,async,session,pagination,sqlmodel
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Web Environment
 Classifier: Framework :: AsyncIO
@@ -37,11 +37,6 @@ Description-Content-Type: text/markdown
 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.5.2; extra == "docs"
-Requires-Dist: mkdocs-llmstxt>=0.5.0; extra == "docs"
-Requires-Dist: mkdocs-material>=9.7.1; extra == "docs"
-Requires-Dist: mkdocstrings[python]>=1.0.0; extra == "docs"
 Provides-Extra: sqlmodel
 Requires-Dist: sqlmodel>=0.0.22; extra == "sqlmodel"
 
@@ -71,7 +66,6 @@ providing boilerplate and intuitive helpers. Additionally, it offers built-in
 customizable pagination and automatically manages the `SQLAlchemy` session lifecycle
 following [`SQLAlchemy`'s best practices](https://docs.sqlalchemy.org/en/20/orm/session_basics.html#when-do-i-construct-a-session-when-do-i-commit-it-and-when-do-i-close-it).
 
-
 ## Features
 
 * Easy setup at app startup using
@@ -154,17 +148,23 @@ following [`SQLAlchemy`'s best practices](https://docs.sqlalchemy.org/en/20/orm/
     ```
 
 * Pagination customization:
+
     ```python
-    ...
-    from fastapi import Page, new_pagination
-    ...
+    from typing import Annotated
 
-    Paginate = new_pagination(min_page_size=5, max_page_size=500)
+    from fastapi import Depends
+    from fastsqla import Page, PaginateType, new_pagination
 
-    @app.get("/heros", response_model=Page[HeroModel])
-    async def get_heros(paginate:Paginate):
-        return paginate(select(Hero))
+    CustomPaginate = Annotated[
+        PaginateType[HeroModel],
+        Depends(new_pagination(default_page_size=5, max_page_size=500)),
+    ]
+
+    @app.get("/heroes", response_model=Page[HeroModel])
+    async def get_heroes(paginate: CustomPaginate):
+        return await paginate(select(Hero))
     ```
+
 * Session lifecycle management: session is commited on request success or rollback on
   failure.
 
@@ -355,3 +355,33 @@ You can also check the generated openapi doc by opening your browser to
 ## License
 
 This project is licensed under the terms of the [MIT license](https://github.com/hadrien/FastSQLA/blob/main/LICENSE).
+
+## For coding agents and LLMs
+
+FastSQLA publishes agent-readable documentation alongside the website:
+
+- [`llms.txt`](https://hadrien.github.io/FastSQLA/llms.txt) is the concise documentation
+  index.
+- [`llms-full.txt`](https://hadrien.github.io/FastSQLA/llms-full.txt) contains the
+  complete documentation in one file.
+- Every indexed page has a Markdown twin, such as
+  [`setup/index.md`](https://hadrien.github.io/FastSQLA/setup/index.md).
+- [Context7](https://context7.com/hadrien/fastsqla) serves the current documentation and
+  FastSQLA-specific usage rules.
+
+The repository also bundles Agent Skills for setup, session management, and pagination.
+Install all three as one plugin:
+
+### Claude Code
+
+```bash
+claude plugin marketplace add hadrien/FastSQLA
+claude plugin install fastsqla@fastsqla
+```
+
+### Codex
+
+```bash
+codex plugin marketplace add hadrien/FastSQLA
+codex plugin add fastsqla@fastsqla
+```

{fastsqla-0.7.0 → fastsqla-0.8.0}/README.md

@@ -24,7 +24,6 @@ providing boilerplate and intuitive helpers. Additionally, it offers built-in
 customizable pagination and automatically manages the `SQLAlchemy` session lifecycle
 following [`SQLAlchemy`'s best practices](https://docs.sqlalchemy.org/en/20/orm/session_basics.html#when-do-i-construct-a-session-when-do-i-commit-it-and-when-do-i-close-it).
 
-
 ## Features
 
 * Easy setup at app startup using
@@ -107,17 +106,23 @@ following [`SQLAlchemy`'s best practices](https://docs.sqlalchemy.org/en/20/orm/
     ```
 
 * Pagination customization:
+
     ```python
-    ...
-    from fastapi import Page, new_pagination
-    ...
+    from typing import Annotated
 
-    Paginate = new_pagination(min_page_size=5, max_page_size=500)
+    from fastapi import Depends
+    from fastsqla import Page, PaginateType, new_pagination
 
-    @app.get("/heros", response_model=Page[HeroModel])
-    async def get_heros(paginate:Paginate):
-        return paginate(select(Hero))
+    CustomPaginate = Annotated[
+        PaginateType[HeroModel],
+        Depends(new_pagination(default_page_size=5, max_page_size=500)),
+    ]
+
+    @app.get("/heroes", response_model=Page[HeroModel])
+    async def get_heroes(paginate: CustomPaginate):
+        return await paginate(select(Hero))
     ```
+
 * Session lifecycle management: session is commited on request success or rollback on
   failure.
 
@@ -308,3 +313,33 @@ You can also check the generated openapi doc by opening your browser to
 ## License
 
 This project is licensed under the terms of the [MIT license](https://github.com/hadrien/FastSQLA/blob/main/LICENSE).
+
+## For coding agents and LLMs
+
+FastSQLA publishes agent-readable documentation alongside the website:
+
+- [`llms.txt`](https://hadrien.github.io/FastSQLA/llms.txt) is the concise documentation
+  index.
+- [`llms-full.txt`](https://hadrien.github.io/FastSQLA/llms-full.txt) contains the
+  complete documentation in one file.
+- Every indexed page has a Markdown twin, such as
+  [`setup/index.md`](https://hadrien.github.io/FastSQLA/setup/index.md).
+- [Context7](https://context7.com/hadrien/fastsqla) serves the current documentation and
+  FastSQLA-specific usage rules.
+
+The repository also bundles Agent Skills for setup, session management, and pagination.
+Install all three as one plugin:
+
+### Claude Code
+
+```bash
+claude plugin marketplace add hadrien/FastSQLA
+claude plugin install fastsqla@fastsqla
+```
+
+### Codex
+
+```bash
+codex plugin marketplace add hadrien/FastSQLA
+codex plugin add fastsqla@fastsqla
+```

{fastsqla-0.7.0 → fastsqla-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "FastSQLA"
-version = "0.7.0"
+version = "0.8.0"
 description = "SQLAlchemy extension for FastAPI that supports asynchronous sessions and includes built-in pagination."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -30,7 +30,7 @@ classifiers = [
     "Topic :: Software Development",
     "Typing :: Typed",
 ]
-keywords = ["FastAPI", "SQLAlchemy", "AsyncIO"]
+keywords = ["fastapi", "sqlalchemy", "async", "session", "pagination", "sqlmodel"]
 dependencies = ["fastapi>=0.115.6", "sqlalchemy[asyncio]>=2.0.37", "structlog>=24.4.0"]
 
 [project.urls]
@@ -44,18 +44,19 @@ Changelog = "https://github.com/hadrien/fastsqla/releases"
 license-files = []
 
 [project.optional-dependencies]
-docs = [
-    "mkdocs-glightbox>=0.5.2",
-    "mkdocs-llmstxt>=0.5.0",
-    "mkdocs-material>=9.7.1",
-    "mkdocstrings[python]>=1.0.0",
-]
 sqlmodel = ["sqlmodel>=0.0.22"]
 
 [tool.uv]
 package = true
 
 [dependency-groups]
+docs = [
+    "mkdocs-glightbox>=0.5.2",
+    "mkdocs-llmstxt>=0.5.0",
+    "mkdocs-material>=9.7.1",
+    "mkdocstrings[python]>=1.0.0",
+    "pygments @ git+https://github.com/pygments/pygments.git@b6f6dab78e13652741d5e5811b4256b4dcb5fcd8",
+]
 dev = [
     "asgi-lifespan>=2.1.0",
     "coverage>=7.6.1",
@@ -93,6 +94,24 @@ env = "GH_TOKEN"
 [tool.semantic_release]
 version_toml = ["pyproject.toml:project.version"]
 allow_zero_version = true
+build_command_env = ["TWINE_USERNAME", "TWINE_PASSWORD"]
+build_command = """
+uv lock &&
+git add uv.lock &&
+uv build &&
+uv run twine check dist/* &&
+uv run twine upload --non-interactive --skip-existing --verbose dist/*
+"""
+commit_message = """\
+chore(release): v{version}
+
+Automatically generated by python-semantic-release
+"""
+
+[tool.semantic_release.commit_parser_options]
+minor_tags = ["feat"]
+patch_tags = ["build", "ci", "docs", "fix", "perf", "refactor", "style", "test"]
+other_allowed_tags = ["chore"]
 
 [tool.semantic_release.changelog]
 mode = "init"

{fastsqla-0.7.0 → fastsqla-0.8.0}/src/FastSQLA.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: FastSQLA
-Version: 0.7.0
+Version: 0.8.0
 Summary: SQLAlchemy extension for FastAPI that supports asynchronous sessions and includes built-in pagination.
 Author-email: Hadrien David <h@driendavid.com>
 Project-URL: Homepage, https://github.com/hadrien/fastsqla
@@ -8,7 +8,7 @@ Project-URL: Documentation, https://github.com/hadrien/fastsqla
 Project-URL: Repository, https://github.com/hadrien/fastsqla
 Project-URL: Issues, https://github.com/hadrien/fastsqla/issues
 Project-URL: Changelog, https://github.com/hadrien/fastsqla/releases
-Keywords: FastAPI,SQLAlchemy,AsyncIO
+Keywords: fastapi,sqlalchemy,async,session,pagination,sqlmodel
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Web Environment
 Classifier: Framework :: AsyncIO
@@ -37,11 +37,6 @@ Description-Content-Type: text/markdown
 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.5.2; extra == "docs"
-Requires-Dist: mkdocs-llmstxt>=0.5.0; extra == "docs"
-Requires-Dist: mkdocs-material>=9.7.1; extra == "docs"
-Requires-Dist: mkdocstrings[python]>=1.0.0; extra == "docs"
 Provides-Extra: sqlmodel
 Requires-Dist: sqlmodel>=0.0.22; extra == "sqlmodel"
 
@@ -71,7 +66,6 @@ providing boilerplate and intuitive helpers. Additionally, it offers built-in
 customizable pagination and automatically manages the `SQLAlchemy` session lifecycle
 following [`SQLAlchemy`'s best practices](https://docs.sqlalchemy.org/en/20/orm/session_basics.html#when-do-i-construct-a-session-when-do-i-commit-it-and-when-do-i-close-it).
 
-
 ## Features
 
 * Easy setup at app startup using
@@ -154,17 +148,23 @@ following [`SQLAlchemy`'s best practices](https://docs.sqlalchemy.org/en/20/orm/
     ```
 
 * Pagination customization:
+
     ```python
-    ...
-    from fastapi import Page, new_pagination
-    ...
+    from typing import Annotated
 
-    Paginate = new_pagination(min_page_size=5, max_page_size=500)
+    from fastapi import Depends
+    from fastsqla import Page, PaginateType, new_pagination
 
-    @app.get("/heros", response_model=Page[HeroModel])
-    async def get_heros(paginate:Paginate):
-        return paginate(select(Hero))
+    CustomPaginate = Annotated[
+        PaginateType[HeroModel],
+        Depends(new_pagination(default_page_size=5, max_page_size=500)),
+    ]
+
+    @app.get("/heroes", response_model=Page[HeroModel])
+    async def get_heroes(paginate: CustomPaginate):
+        return await paginate(select(Hero))
     ```
+
 * Session lifecycle management: session is commited on request success or rollback on
   failure.
 
@@ -355,3 +355,33 @@ You can also check the generated openapi doc by opening your browser to
 ## License
 
 This project is licensed under the terms of the [MIT license](https://github.com/hadrien/FastSQLA/blob/main/LICENSE).
+
+## For coding agents and LLMs
+
+FastSQLA publishes agent-readable documentation alongside the website:
+
+- [`llms.txt`](https://hadrien.github.io/FastSQLA/llms.txt) is the concise documentation
+  index.
+- [`llms-full.txt`](https://hadrien.github.io/FastSQLA/llms-full.txt) contains the
+  complete documentation in one file.
+- Every indexed page has a Markdown twin, such as
+  [`setup/index.md`](https://hadrien.github.io/FastSQLA/setup/index.md).
+- [Context7](https://context7.com/hadrien/fastsqla) serves the current documentation and
+  FastSQLA-specific usage rules.
+
+The repository also bundles Agent Skills for setup, session management, and pagination.
+Install all three as one plugin:
+
+### Claude Code
+
+```bash
+claude plugin marketplace add hadrien/FastSQLA
+claude plugin install fastsqla@fastsqla
+```
+
+### Codex
+
+```bash
+codex plugin marketplace add hadrien/FastSQLA
+codex plugin add fastsqla@fastsqla
+```

fastsqla-0.8.0/src/FastSQLA.egg-info/requires.txt

@@ -0,0 +1,6 @@
+fastapi>=0.115.6
+sqlalchemy[asyncio]>=2.0.37
+structlog>=24.4.0
+
+[sqlmodel]
+sqlmodel>=0.0.22

{fastsqla-0.7.0 → fastsqla-0.8.0}/src/fastsqla.py

@@ -1,8 +1,10 @@
+import functools
 import math
 import os
+import warnings
 from collections.abc import AsyncGenerator, Awaitable, Callable, Iterable
 from contextlib import _AsyncGeneratorContextManager, asynccontextmanager
-from typing import Annotated, Generic, TypedDict, TypeVar
+from typing import Annotated, TypedDict, TypeVar
 
 from fastapi import Depends as BaseDepends
 from fastapi import FastAPI, Query
@@ -31,6 +33,7 @@ __all__ = [
     "Base",
     "Collection",
     "Item",
+    "MissingConfigurationError",
     "Page",
     "Paginate",
     "PaginateType",
@@ -88,6 +91,10 @@ class State(TypedDict):
     fastsqla_engine: AsyncEngine
 
 
+class MissingConfigurationError(RuntimeError):
+    """Raised when a required SQLAlchemy setting is missing."""
+
+
 def new_lifespan(
     url: str | None = None, **kw
 ) -> Callable[[FastAPI | None], _AsyncGeneratorContextManager[State, None]]:
@@ -112,6 +119,9 @@ def new_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]
+
+    Raises:
+        MissingConfigurationError: If a required SQLAlchemy setting is missing.
     """
 
     has_config = url is not None
@@ -120,7 +130,7 @@ def new_lifespan(
     async def lifespan(app: FastAPI | None) -> AsyncGenerator[State, None]:
         if has_config:
             prefix = ""
-            sqla_config = {**kw, **{"url": url}}
+            sqla_config = {**kw, "url": url}
 
         else:
             prefix = "sqlalchemy_"
@@ -130,7 +140,9 @@ def new_lifespan(
             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
+            raise MissingConfigurationError(
+                f"Missing {prefix}{exc.args[0]} in environ."
+            ) from exc
 
         async with engine.begin() as conn:
             await conn.run_sync(Base.prepare)
@@ -330,11 +342,11 @@ class Meta(BaseModel):
 T = TypeVar("T")
 
 
-class Item(BaseModel, Generic[T]):
+class Item[T](BaseModel):
     data: T
 
 
-class Collection(BaseModel, Generic[T]):
+class Collection[T](BaseModel):
     data: list[T]
 
 
@@ -387,18 +399,62 @@ async def _paginate(
     )
 
 
+def _accept_deprecated_page_size_option[**P, R](
+    function: Callable[P, R],
+) -> Callable[P, R]:
+    @functools.wraps(function)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        if "min_page_size" in kwargs:
+            if args or "default_page_size" in kwargs:
+                raise TypeError(
+                    "new_pagination() cannot receive both default_page_size and "
+                    "min_page_size"
+                )
+            warnings.warn(
+                "min_page_size is deprecated; use default_page_size instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        return function(*args, **kwargs)
+
+    return wrapper
+
+
+@_accept_deprecated_page_size_option
 def new_pagination(
-    min_page_size: int = 10,
+    default_page_size: int = 10,
     max_page_size: int = 100,
     query_count_dependency: Callable[..., Awaitable[int]] | None = None,
     result_processor: Callable[[Result], Iterable] = lambda result: iter(
         result.unique().scalars()
     ),
+    *,
+    min_page_size: int | None = None,
 ):
+    """Create a FastAPI pagination dependency.
+
+    Args:
+        default_page_size: Default value of the `limit` query parameter.
+        max_page_size: Maximum accepted value of the `limit` query parameter.
+        query_count_dependency: Optional dependency that returns the total item count.
+        result_processor: Function that transforms the SQLAlchemy result into page data.
+        min_page_size: Deprecated alias for `default_page_size`.
+
+    Raises:
+        TypeError: Both page-size parameter names are supplied.
+        ValueError: The page-size configuration is invalid.
+    """
+    if min_page_size is not None:
+        default_page_size = min_page_size
+    if max_page_size < 1:
+        raise ValueError("max_page_size must be at least 1")
+    if not 1 <= default_page_size <= max_page_size:
+        raise ValueError("default_page_size must be between 1 and max_page_size")
+
     def default_dependency(
         session: Session,
         offset: int = Query(0, ge=0),
-        limit: int = Query(min_page_size, ge=1, le=max_page_size),
+        limit: int = Query(default_page_size, ge=1, le=max_page_size),
     ) -> PaginateType[T]:
         async def paginate(stmt: Select) -> Page:
             total_items = await _query_count(session, stmt)
@@ -411,7 +467,7 @@ def new_pagination(
     def dependency(
         session: Session,
         offset: int = Query(0, ge=0),
-        limit: int = Query(min_page_size, ge=1, le=max_page_size),
+        limit: int = Query(default_page_size, ge=1, le=max_page_size),
         total_items: int = Depends(query_count_dependency),
     ) -> PaginateType[T]:
         async def paginate(stmt: Select) -> Page:

fastsqla-0.7.0/src/FastSQLA.egg-info/requires.txt

@@ -1,12 +0,0 @@
-fastapi>=0.115.6
-sqlalchemy[asyncio]>=2.0.37
-structlog>=24.4.0
-
-[docs]
-mkdocs-glightbox>=0.5.2
-mkdocs-llmstxt>=0.5.0
-mkdocs-material>=9.7.1
-mkdocstrings[python]>=1.0.0
-
-[sqlmodel]
-sqlmodel>=0.0.22