fastapi-toolsets 0.1.0__py3-none-any.whl

fastapi_toolsets/fixtures/pytest_plugin.py

@@ -0,0 +1,204 @@
+"""Pytest plugin for using FixtureRegistry fixtures in tests.
+
+This module provides utilities to automatically generate pytest fixtures
+from your FixtureRegistry, with proper dependency resolution.
+
+Example:
+    # conftest.py
+    import pytest
+    from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+
+    from app.fixtures import fixtures  # Your FixtureRegistry
+    from app.models import Base
+    from fastapi_toolsets.pytest_plugin import register_fixtures
+
+    DATABASE_URL = "postgresql+asyncpg://postgres:postgres@localhost:5432/test_db"
+
+    @pytest.fixture
+    async def engine():
+        engine = create_async_engine(DATABASE_URL)
+        yield engine
+        await engine.dispose()
+
+    @pytest.fixture
+    async def db_session(engine):
+        async with engine.begin() as conn:
+            await conn.run_sync(Base.metadata.create_all)
+
+        session_factory = async_sessionmaker(engine, expire_on_commit=False)
+        session = session_factory()
+
+        try:
+            yield session
+        finally:
+            await session.close()
+            async with engine.begin() as conn:
+                await conn.run_sync(Base.metadata.drop_all)
+
+    # Automatically generate pytest fixtures from registry
+    # Creates: fixture_roles, fixture_users, fixture_posts, etc.
+    register_fixtures(fixtures, globals())
+
+Usage in tests:
+    # test_users.py
+    async def test_user_count(db_session, fixture_users):
+        # fixture_users automatically loads fixture_roles first (if dependency)
+        # and returns the list of User models
+        assert len(fixture_users) > 0
+
+    async def test_user_role(db_session, fixture_users):
+        user = fixture_users[0]
+        assert user.role_id is not None
+"""
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+import pytest
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import DeclarativeBase
+
+from ..db import get_transaction
+from .fixtures import FixtureRegistry, LoadStrategy
+
+
+def register_fixtures(
+    registry: FixtureRegistry,
+    namespace: dict[str, Any],
+    *,
+    prefix: str = "fixture_",
+    session_fixture: str = "db_session",
+    strategy: LoadStrategy = LoadStrategy.MERGE,
+) -> list[str]:
+    """Register pytest fixtures from a FixtureRegistry.
+
+    Automatically creates pytest fixtures for each fixture in the registry.
+    Dependencies are resolved via pytest fixture dependencies.
+
+    Args:
+        registry: The FixtureRegistry containing fixtures
+        namespace: The module's globals() dict to add fixtures to
+        prefix: Prefix for generated fixture names (default: "fixture_")
+        session_fixture: Name of the db session fixture (default: "db_session")
+        strategy: Loading strategy for fixtures (default: MERGE)
+
+    Returns:
+        List of created fixture names
+
+    Example:
+        # conftest.py
+        from app.fixtures import fixtures
+        from fastapi_toolsets.pytest_plugin import register_fixtures
+
+        register_fixtures(fixtures, globals())
+
+        # Creates fixtures like:
+        # - fixture_roles
+        # - fixture_users (depends on fixture_roles if users depends on roles)
+        # - fixture_posts (depends on fixture_users if posts depends on users)
+    """
+    created_fixtures: list[str] = []
+
+    for fixture in registry.get_all():
+        fixture_name = f"{prefix}{fixture.name}"
+
+        # Build list of pytest fixture dependencies
+        pytest_deps = [session_fixture]
+        for dep in fixture.depends_on:
+            pytest_deps.append(f"{prefix}{dep}")
+
+        # Create the fixture function
+        fixture_func = _create_fixture_function(
+            registry=registry,
+            fixture_name=fixture.name,
+            dependencies=pytest_deps,
+            strategy=strategy,
+        )
+
+        # Apply pytest.fixture decorator
+        decorated = pytest.fixture(fixture_func)
+
+        # Add to namespace
+        namespace[fixture_name] = decorated
+        created_fixtures.append(fixture_name)
+
+    return created_fixtures
+
+
+def _create_fixture_function(
+    registry: FixtureRegistry,
+    fixture_name: str,
+    dependencies: list[str],
+    strategy: LoadStrategy,
+) -> Callable[..., Any]:
+    """Create a fixture function with the correct signature.
+
+    The function signature must include all dependencies as parameters
+    for pytest to resolve them correctly.
+    """
+    # Get the fixture definition
+    fixture_def = registry.get(fixture_name)
+
+    # Build the function dynamically with correct parameters
+    # We need the session as first param, then all dependencies
+    async def fixture_func(**kwargs: Any) -> Sequence[DeclarativeBase]:
+        # Get session from kwargs (first dependency)
+        session: AsyncSession = kwargs[dependencies[0]]
+
+        # Load the fixture data
+        instances = list(fixture_def.func())
+
+        if not instances:
+            return []
+
+        loaded: list[DeclarativeBase] = []
+
+        async with get_transaction(session):
+            for instance in instances:
+                if strategy == LoadStrategy.INSERT:
+                    session.add(instance)
+                    loaded.append(instance)
+                elif strategy == LoadStrategy.MERGE:
+                    merged = await session.merge(instance)
+                    loaded.append(merged)
+                elif strategy == LoadStrategy.SKIP_EXISTING:
+                    pk = _get_primary_key(instance)
+                    if pk is not None:
+                        existing = await session.get(type(instance), pk)
+                        if existing is None:
+                            session.add(instance)
+                            loaded.append(instance)
+                        else:
+                            loaded.append(existing)
+                    else:
+                        session.add(instance)
+                        loaded.append(instance)
+
+        return loaded
+
+    # Update function signature to include dependencies
+    # This is needed for pytest to inject the right fixtures
+    params = ", ".join(dependencies)
+    code = f"async def {fixture_name}_fixture({params}):\n    return await _impl({', '.join(f'{d}={d}' for d in dependencies)})"
+
+    local_ns: dict[str, Any] = {"_impl": fixture_func}
+    exec(code, local_ns)  # noqa: S102
+
+    created_func = local_ns[f"{fixture_name}_fixture"]
+    created_func.__doc__ = f"Load {fixture_name} fixture data."
+
+    return created_func
+
+
+def _get_primary_key(instance: DeclarativeBase) -> Any | None:
+    """Get the primary key value of a model instance."""
+    mapper = instance.__class__.__mapper__
+    pk_cols = mapper.primary_key
+
+    if len(pk_cols) == 1:
+        return getattr(instance, pk_cols[0].name, None)
+
+    pk_values = tuple(getattr(instance, col.name, None) for col in pk_cols)
+    if all(v is not None for v in pk_values):
+        return pk_values
+    return None

fastapi_toolsets/schemas.py

@@ -0,0 +1,116 @@
+"""Base Pydantic schemas for API responses."""
+
+from enum import Enum
+from typing import ClassVar, Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict
+
+__all__ = [
+    "ApiError",
+    "ErrorResponse",
+    "Pagination",
+    "PaginatedResponse",
+    "Response",
+    "ResponseStatus",
+]
+
+DataT = TypeVar("DataT")
+
+
+class PydanticBase(BaseModel):
+    """Base class for all Pydantic models with common configuration."""
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(
+        from_attributes=True,
+        validate_assignment=True,
+    )
+
+
+class ResponseStatus(str, Enum):
+    """Standard API response status."""
+
+    SUCCESS = "SUCCESS"
+    FAIL = "FAIL"
+
+
+class ApiError(PydanticBase):
+    """Structured API error definition.
+
+    Used to define standard error responses with consistent format.
+
+    Attributes:
+        code: HTTP status code
+        msg: Short error message
+        desc: Detailed error description
+        err_code: Application-specific error code (e.g., "AUTH-401")
+    """
+
+    code: int
+    msg: str
+    desc: str
+    err_code: str
+
+
+class BaseResponse(PydanticBase):
+    """Base response structure for all API responses.
+
+    Attributes:
+        status: SUCCESS or FAIL
+        message: Human-readable message
+        error_code: Error code if status is FAIL, None otherwise
+    """
+
+    status: ResponseStatus = ResponseStatus.SUCCESS
+    message: str = "Success"
+    error_code: str | None = None
+
+
+class Response(BaseResponse, Generic[DataT]):
+    """Generic API response with data payload.
+
+    Example:
+        Response[UserRead](data=user, message="User retrieved")
+    """
+
+    data: DataT | None = None
+
+
+class ErrorResponse(BaseResponse):
+    """Error response with additional description field.
+
+    Used for error responses that need more context.
+    """
+
+    status: ResponseStatus = ResponseStatus.FAIL
+    description: str | None = None
+    data: None = None
+
+
+class Pagination(PydanticBase):
+    """Pagination metadata for list responses.
+
+    Attributes:
+        total_count: Total number of items across all pages
+        items_per_page: Number of items per page
+        page: Current page number (1-indexed)
+        has_more: Whether there are more pages
+    """
+
+    total_count: int
+    items_per_page: int
+    page: int
+    has_more: bool
+
+
+class PaginatedResponse(BaseResponse, Generic[DataT]):
+    """Paginated API response for list endpoints.
+
+    Example:
+        PaginatedResponse[UserRead](
+            data=users,
+            pagination=Pagination(total_count=100, items_per_page=10, page=1, has_more=True)
+        )
+    """
+
+    data: list[DataT]
+    pagination: Pagination

fastapi_toolsets-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,20 @@
+fastapi_toolsets/__init__.py,sha256=bLVbdgVNhQdN9LhAvb4FPNrgoIqHUjLx9TvgJzm46Jc,820
+fastapi_toolsets/cli/__init__.py,sha256=QAcrenphE7D5toid_Kn777Cy1icSOWiEBjSE_oCuU4o,111
+fastapi_toolsets/cli/app.py,sha256=G3y3PNN3biHs8GtiiGsrX2X8nXNjkrsUhHLXQo2-MXc,2588
+fastapi_toolsets/cli/commands/__init__.py,sha256=BogehmsY6olwLdfIBzviuppXP1LLl9znnxtmji3eLwI,29
+fastapi_toolsets/cli/commands/fixtures.py,sha256=qiC2dcrJ_Rb1PRzx6EycTFQQXwa_GQUVoptpx4chf9k,6679
+fastapi_toolsets/crud.py,sha256=pD26V91y0Z5f9ft0I6ggY1EJ-Oh-QATgANgzEyj4EHU,11370
+fastapi_toolsets/db.py,sha256=YUj5CrxCnREg7AqpJLNrLR2RDIOCS7stQCNOSS3cRho,5619
+fastapi_toolsets/exceptions/__init__.py,sha256=PDiTg4NpEUhGi5p9Sfvn1FtxdlD9-Y4OPhWCQz6fW9g,391
+fastapi_toolsets/exceptions/exceptions.py,sha256=O6fqDbPfEFSj1oi_vo3-gnES7RPpSf-l_yXh4fTCBjg,4470
+fastapi_toolsets/exceptions/handler.py,sha256=IXfKiIr_LPo-11PRpOIrNRAXBkeQ5TdLcu3Gy-r6ChU,5916
+fastapi_toolsets/fixtures/__init__.py,sha256=EWODe3vwjyrnZ_4jEpDdQ4NFLmYvdFqvvvrRaKq6Bsk,323
+fastapi_toolsets/fixtures/fixtures.py,sha256=RB073yojMQoRCxP_-pvZWSW_viPQsD3RRJ5NhEZ2wZQ,9720
+fastapi_toolsets/fixtures/pytest_plugin.py,sha256=J2PjasekQUxzurk7_MVncQRcIZ1AIawsO6OlqKqKYT8,6891
+fastapi_toolsets/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastapi_toolsets/schemas.py,sha256=LBzrq4s5VWYeQqlUfOEvWDtpFdO8scgY0LRypk9KUAE,2639
+fastapi_toolsets-0.1.0.dist-info/licenses/LICENSE,sha256=V2jCjI-VPB-veGY2Ktb0sU4vT_TldRciZ9lCE98bMoE,1063
+fastapi_toolsets-0.1.0.dist-info/WHEEL,sha256=XV0cjMrO7zXhVAIyyc8aFf1VjZ33Fen4IiJk5zFlC3g,80
+fastapi_toolsets-0.1.0.dist-info/entry_points.txt,sha256=pNU38Nn_DXBgYd-nLZCizMvrrdaPhHmkRwouDoBqvzw,63
+fastapi_toolsets-0.1.0.dist-info/METADATA,sha256=fRrFRvKtO4m2lbF0pq6qgbHxrHTPitfMSVkD6WlknXU,4170
+fastapi_toolsets-0.1.0.dist-info/RECORD,,

fastapi_toolsets-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.26
+Root-Is-Purelib: true
+Tag: py3-none-any

fastapi_toolsets-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+fastapi-toolsets = fastapi_toolsets.cli:app
+

fastapi_toolsets-0.1.0.dist-info/licenses/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.