fastapi-toolsets 0.1.0__tar.gz

fastapi_toolsets-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 d3vyce
+
+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.

fastapi_toolsets-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: fastapi-toolsets
+Version: 0.1.0
+Summary: Reusable tools for FastAPI: async CRUD, fixtures, CLI, and standardized responses for SQLAlchemy + PostgreSQL
+Keywords: fastapi,sqlalchemy,postgresql
+Author: d3vyce
+Author-email: d3vyce <contact@d3vyce.fr>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: FastAPI
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development
+Classifier: Typing :: Typed
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Requires-Dist: asyncpg>=0.29.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: fastapi-toolsets[test] ; extra == 'dev'
+Requires-Dist: ruff>=0.1.0 ; extra == 'dev'
+Requires-Dist: ty>=0.0.1a0 ; extra == 'dev'
+Requires-Dist: pytest>=8.0.0 ; extra == 'test'
+Requires-Dist: pytest-anyio>=0.0.0 ; extra == 'test'
+Requires-Dist: coverage>=7.0.0 ; extra == 'test'
+Requires-Dist: pytest-cov>=4.0.0 ; extra == 'test'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/d3vyce/fastapi-toolsets
+Project-URL: Documentation, https://fastapi-toolsets.d3vyce.fr/
+Project-URL: Repository, https://github.com/d3vyce/fastapi-toolsets
+Project-URL: Issues, https://github.com/d3vyce/fastapi-toolsets/issues
+Provides-Extra: dev
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
+# FastAPI Toolsets
+
+FastAPI Toolsets provides production-ready utilities for FastAPI applications built with async SQLAlchemy and PostgreSQL. It includes generic CRUD operations, a fixture system with dependency resolution, a Django-like CLI, standardized API responses, and structured exception handling with automatic OpenAPI documentation.
+
+[![CI](https://github.com/d3vyce/fastapi-toolsets/actions/workflows/ci.yml/badge.svg)](https://github.com/d3vyce/fastapi-toolsets/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/d3vyce/fastapi-toolsets/graph/badge.svg)](https://codecov.io/gh/d3vyce/fastapi-toolsets)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+**Documentation**: [https://fastapi-toolsets.d3vyce.fr](https://fastapi-toolsets.d3vyce.fr)
+
+**Source Code**: [https://github.com/d3vyce/fastapi-toolsets](https://github.com/d3vyce/fastapi-toolsets)
+
+---
+
+## Installation
+
+```bash
+uv add fastapi-toolsets
+```
+
+## Features
+
+- **CRUD**: Generic async CRUD operations with `CrudFactory`
+- **Fixtures**: Fixture system with dependency management, context support and pytest integration
+- **CLI**: Django-like command-line interface for fixtures and custom commands
+- **Standardized API Responses**: Consistent response format across your API
+- **Exception Handling**: Structured error responses with automatic OpenAPI documentation
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues and pull requests.

fastapi_toolsets-0.1.0/README.md

@@ -0,0 +1,41 @@
+# FastAPI Toolsets
+
+FastAPI Toolsets provides production-ready utilities for FastAPI applications built with async SQLAlchemy and PostgreSQL. It includes generic CRUD operations, a fixture system with dependency resolution, a Django-like CLI, standardized API responses, and structured exception handling with automatic OpenAPI documentation.
+
+[![CI](https://github.com/d3vyce/fastapi-toolsets/actions/workflows/ci.yml/badge.svg)](https://github.com/d3vyce/fastapi-toolsets/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/d3vyce/fastapi-toolsets/graph/badge.svg)](https://codecov.io/gh/d3vyce/fastapi-toolsets)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+**Documentation**: [https://fastapi-toolsets.d3vyce.fr](https://fastapi-toolsets.d3vyce.fr)
+
+**Source Code**: [https://github.com/d3vyce/fastapi-toolsets](https://github.com/d3vyce/fastapi-toolsets)
+
+---
+
+## Installation
+
+```bash
+uv add fastapi-toolsets
+```
+
+## Features
+
+- **CRUD**: Generic async CRUD operations with `CrudFactory`
+- **Fixtures**: Fixture system with dependency management, context support and pytest integration
+- **CLI**: Django-like command-line interface for fixtures and custom commands
+- **Standardized API Responses**: Consistent response format across your API
+- **Exception Handling**: Structured error responses with automatic OpenAPI documentation
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues and pull requests.

fastapi_toolsets-0.1.0/pyproject.toml

@@ -0,0 +1,82 @@
+[project]
+name = "fastapi-toolsets"
+version = "0.1.0"
+description = "Reusable tools for FastAPI: async CRUD, fixtures, CLI, and standardized responses for SQLAlchemy + PostgreSQL"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [
+    { name = "d3vyce", email = "contact@d3vyce.fr" }
+]
+keywords = ["fastapi", "sqlalchemy", "postgresql"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Framework :: FastAPI",
+    "Framework :: Pydantic",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development",
+    "Typing :: Typed",
+]
+dependencies = [
+    "fastapi>=0.100.0",
+    "sqlalchemy[asyncio]>=2.0",
+    "asyncpg>=0.29.0",
+    "pydantic>=2.0",
+    "typer>=0.9.0",
+    "httpx>=0.25.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/d3vyce/fastapi-toolsets"
+Documentation = "https://fastapi-toolsets.d3vyce.fr/"
+Repository = "https://github.com/d3vyce/fastapi-toolsets"
+Issues = "https://github.com/d3vyce/fastapi-toolsets/issues"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0.0",
+    "pytest-anyio>=0.0.0",
+    "coverage>=7.0.0",
+    "pytest-cov>=4.0.0",
+]
+dev = [
+    "fastapi-toolsets[test]",
+    "ruff>=0.1.0",
+    "ty>=0.0.1a0",
+]
+
+[project.scripts]
+fastapi-toolsets = "fastapi_toolsets.cli:app"
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+]
+
+[tool.coverage.run]
+source = ["src/fastapi_toolsets"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]

fastapi_toolsets-0.1.0/src/fastapi_toolsets/__init__.py

@@ -0,0 +1,24 @@
+"""FastAPI utilities package.
+
+Provides CRUD operations, fixtures, CLI, and standardized API responses
+for FastAPI with async SQLAlchemy and PostgreSQL.
+
+Example usage:
+    from fastapi import FastAPI, Depends
+    from fastapi_toolsets.exceptions import init_exceptions_handlers
+    from fastapi_toolsets.crud import CrudFactory
+    from fastapi_toolsets.db import create_db_dependency
+    from fastapi_toolsets.schemas import Response
+
+    app = FastAPI()
+    init_exceptions_handlers(app)
+
+    UserCrud = CrudFactory(User)
+
+    @app.get("/users/{user_id}", response_model=Response[dict])
+    async def get_user(user_id: int, session = Depends(get_db)):
+        user = await UserCrud.get(session, [User.id == user_id])
+        return Response(data={"user": user.username}, message="Success")
+"""
+
+__version__ = "0.1.0"

fastapi_toolsets-0.1.0/src/fastapi_toolsets/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI for FastAPI projects."""
+
+from .app import app, register_command
+
+__all__ = ["app", "register_command"]

fastapi_toolsets-0.1.0/src/fastapi_toolsets/cli/app.py

@@ -0,0 +1,97 @@
+"""Main CLI application."""
+
+import importlib.util
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from .commands import fixtures
+
+app = typer.Typer(
+    name="fastapi-utils",
+    help="CLI utilities for FastAPI projects.",
+    no_args_is_help=True,
+)
+
+# Register built-in commands
+app.add_typer(fixtures.app, name="fixtures")
+
+
+def register_command(command: typer.Typer, name: str) -> None:
+    """Register a custom command group.
+
+    Args:
+        command: Typer app for the command group
+        name: Name for the command group
+
+    Example:
+        # In your project's cli.py:
+        import typer
+        from fastapi_toolsets.cli import app, register_command
+
+        my_commands = typer.Typer()
+
+        @my_commands.command()
+        def seed():
+            '''Seed the database.'''
+            ...
+
+        register_command(my_commands, "db")
+        # Now available as: fastapi-utils db seed
+    """
+    app.add_typer(command, name=name)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    config: Annotated[
+        Path | None,
+        typer.Option(
+            "--config",
+            "-c",
+            help="Path to project config file (Python module with fixtures registry).",
+            envvar="FASTAPI_TOOLSETS_CONFIG",
+        ),
+    ] = None,
+) -> None:
+    """FastAPI utilities CLI."""
+    ctx.ensure_object(dict)
+
+    if config:
+        ctx.obj["config_path"] = config
+        # Load the config module
+        config_module = _load_module_from_path(config)
+        ctx.obj["config_module"] = config_module
+
+
+def _load_module_from_path(path: Path) -> object:
+    """Load a Python module from a file path.
+
+    Handles both absolute and relative imports by adding the config's
+    parent directory to sys.path temporarily.
+    """
+    path = path.resolve()
+
+    # Add the parent directory to sys.path to support relative imports
+    parent_dir = str(
+        path.parent.parent
+    )  # Go up two levels (e.g., from app/cli_config.py to project root)
+    if parent_dir not in sys.path:
+        sys.path.insert(0, parent_dir)
+
+    # Also add immediate parent for direct module imports
+    immediate_parent = str(path.parent)
+    if immediate_parent not in sys.path:
+        sys.path.insert(0, immediate_parent)
+
+    spec = importlib.util.spec_from_file_location("config", path)
+    if spec is None or spec.loader is None:
+        raise typer.BadParameter(f"Cannot load module from {path}")
+
+    module = importlib.util.module_from_spec(spec)
+    sys.modules["config"] = module
+    spec.loader.exec_module(module)
+    return module

fastapi_toolsets-0.1.0/src/fastapi_toolsets/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Built-in CLI commands."""

fastapi_toolsets-0.1.0/src/fastapi_toolsets/cli/commands/fixtures.py

@@ -0,0 +1,225 @@
+"""Fixture management commands."""
+
+import asyncio
+from typing import Annotated
+
+import typer
+
+from ...fixtures import Context, FixtureRegistry, LoadStrategy, load_fixtures_by_context
+
+app = typer.Typer(
+    name="fixtures",
+    help="Manage database fixtures.",
+    no_args_is_help=True,
+)
+
+
+def _get_registry(ctx: typer.Context) -> FixtureRegistry:
+    """Get fixture registry from context."""
+    config = ctx.obj.get("config_module") if ctx.obj else None
+    if config is None:
+        raise typer.BadParameter(
+            "No config provided. Use --config to specify a config file with a 'fixtures' registry."
+        )
+
+    registry = getattr(config, "fixtures", None)
+    if registry is None:
+        raise typer.BadParameter(
+            "Config module must have a 'fixtures' attribute (FixtureRegistry instance)."
+        )
+
+    if not isinstance(registry, FixtureRegistry):
+        raise typer.BadParameter(
+            f"'fixtures' must be a FixtureRegistry instance, got {type(registry).__name__}"
+        )
+
+    return registry
+
+
+def _get_db_context(ctx: typer.Context):
+    """Get database context manager from config."""
+    config = ctx.obj.get("config_module") if ctx.obj else None
+    if config is None:
+        raise typer.BadParameter("No config provided.")
+
+    get_db_context = getattr(config, "get_db_context", None)
+    if get_db_context is None:
+        raise typer.BadParameter("Config module must have a 'get_db_context' function.")
+
+    return get_db_context
+
+
+@app.command("list")
+def list_fixtures(
+    ctx: typer.Context,
+    context: Annotated[
+        str | None,
+        typer.Option(
+            "--context",
+            "-c",
+            help="Filter by context (base, production, development, testing).",
+        ),
+    ] = None,
+) -> None:
+    """List all registered fixtures."""
+    registry = _get_registry(ctx)
+
+    if context:
+        fixtures = registry.get_by_context(context)
+    else:
+        fixtures = registry.get_all()
+
+    if not fixtures:
+        typer.echo("No fixtures found.")
+        return
+
+    typer.echo(f"\n{'Name':<30} {'Contexts':<30} {'Dependencies'}")
+    typer.echo("-" * 80)
+
+    for fixture in fixtures:
+        contexts = ", ".join(fixture.contexts)
+        deps = ", ".join(fixture.depends_on) if fixture.depends_on else "-"
+        typer.echo(f"{fixture.name:<30} {contexts:<30} {deps}")
+
+    typer.echo(f"\nTotal: {len(fixtures)} fixture(s)")
+
+
+@app.command("graph")
+def show_graph(
+    ctx: typer.Context,
+    fixture_name: Annotated[
+        str | None,
+        typer.Argument(help="Show dependencies for a specific fixture."),
+    ] = None,
+) -> None:
+    """Show fixture dependency graph."""
+    registry = _get_registry(ctx)
+
+    if fixture_name:
+        try:
+            order = registry.resolve_dependencies(fixture_name)
+            typer.echo(f"\nDependency chain for '{fixture_name}':\n")
+            for i, name in enumerate(order):
+                indent = "  " * i
+                arrow = "└─> " if i > 0 else ""
+                typer.echo(f"{indent}{arrow}{name}")
+        except KeyError:
+            typer.echo(f"Fixture '{fixture_name}' not found.", err=True)
+            raise typer.Exit(1)
+    else:
+        # Show full graph
+        fixtures = registry.get_all()
+
+        typer.echo("\nFixture Dependency Graph:\n")
+        for fixture in fixtures:
+            deps = (
+                f" -> [{', '.join(fixture.depends_on)}]" if fixture.depends_on else ""
+            )
+            typer.echo(f"  {fixture.name}{deps}")
+
+
+@app.command("load")
+def load(
+    ctx: typer.Context,
+    contexts: Annotated[
+        list[str] | None,
+        typer.Argument(
+            help="Contexts to load (base, production, development, testing)."
+        ),
+    ] = None,
+    strategy: Annotated[
+        str,
+        typer.Option(
+            "--strategy", "-s", help="Load strategy: merge, insert, skip_existing."
+        ),
+    ] = "merge",
+    dry_run: Annotated[
+        bool,
+        typer.Option(
+            "--dry-run", "-n", help="Show what would be loaded without loading."
+        ),
+    ] = False,
+) -> None:
+    """Load fixtures into the database."""
+    registry = _get_registry(ctx)
+    get_db_context = _get_db_context(ctx)
+
+    # Parse contexts
+    if contexts:
+        context_list = contexts
+    else:
+        context_list = [Context.BASE]
+
+    # Parse strategy
+    try:
+        load_strategy = LoadStrategy(strategy)
+    except ValueError:
+        typer.echo(
+            f"Invalid strategy: {strategy}. Use: merge, insert, skip_existing", err=True
+        )
+        raise typer.Exit(1)
+
+    # Resolve what will be loaded
+    ordered = registry.resolve_context_dependencies(*context_list)
+
+    if not ordered:
+        typer.echo("No fixtures to load for the specified context(s).")
+        return
+
+    typer.echo(f"\nFixtures to load ({load_strategy.value} strategy):")
+    for name in ordered:
+        fixture = registry.get(name)
+        instances = list(fixture.func())
+        model_name = type(instances[0]).__name__ if instances else "?"
+        typer.echo(f"  - {name}: {len(instances)} {model_name}(s)")
+
+    if dry_run:
+        typer.echo("\n[Dry run - no changes made]")
+        return
+
+    typer.echo("\nLoading...")
+
+    async def do_load():
+        async with get_db_context() as session:
+            result = await load_fixtures_by_context(
+                session, registry, *context_list, strategy=load_strategy
+            )
+            return result
+
+    result = asyncio.run(do_load())
+
+    total = sum(len(items) for items in result.values())
+    typer.echo(f"\nLoaded {total} record(s) successfully.")
+
+
+@app.command("show")
+def show_fixture(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Fixture name to show.")],
+) -> None:
+    """Show details of a specific fixture."""
+    registry = _get_registry(ctx)
+
+    try:
+        fixture = registry.get(name)
+    except KeyError:
+        typer.echo(f"Fixture '{name}' not found.", err=True)
+        raise typer.Exit(1)
+
+    typer.echo(f"\nFixture: {fixture.name}")
+    typer.echo(f"Contexts: {', '.join(fixture.contexts)}")
+    typer.echo(
+        f"Dependencies: {', '.join(fixture.depends_on) if fixture.depends_on else 'None'}"
+    )
+
+    # Show instances
+    instances = list(fixture.func())
+    if instances:
+        model_name = type(instances[0]).__name__
+        typer.echo(f"\nInstances ({len(instances)} {model_name}):")
+        for instance in instances[:10]:  # Limit to 10
+            typer.echo(f"  - {instance!r}")
+        if len(instances) > 10:
+            typer.echo(f"  ... and {len(instances) - 10} more")
+    else:
+        typer.echo("\nNo instances (empty fixture)")