fastapi-toolsets 0.1.0__py3-none-any.whl

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/cli/__init__.py

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

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/cli/commands/__init__.py

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

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)")