How hmarcuzzo/fastgear works
Project type and purpose
• FastGear is an open-source Python library for FastAPI that enhances SQLAlchemy (sync & async) and Redis (async) support, with built-in pagination, error handling, session management, and dynamic query building.
• It is not a standalone application but a reusable toolkit meant to be imported into FastAPI projects.
File structure
• Top-level fastgear/ package subdivided into:
• applications.py – entry-point helpers for wiring into FastAPI
• common/database – repository abstractions and concrete implementations (SQLAlchemy async/sync, Redis)
• common/schema – Pydantic schema bases and exception schemas
• constants – shared regex or other constants
• decorators – function-level wrappers for sessions, pagination, search
• handlers – HTTP exception handler
• middlewares – FastAPI middleware for DB session injection
• types – custom types, result wrappers, options objects
• utils – helper functions for enums, JSON, logging, pagination
• Support files: pyproject.toml, CI workflows, linting, test suite under tests/.
README for insights
• Confirms FastAPI orientation, dependencies on SQLAlchemy 2.0, Pydantic v2, Redis.
• Highlights features: async/sync DB ops, Redis caching, offset pagination, error handling, session context manager.
Main components
a. Library core modules:
• Applications module
• Database layer: AbstractRepository, AsyncBaseRepository (SQLAlchemy), SyncBaseRepository, Redis client
• Schema layer: BaseSchema, ExceptionResponseSchema
• Decorators & middleware: DB session decorator, pagination decorators, DB session middleware
• Handlers: HTTP exception handler
• Utilities & types
b. External dependencies:
• FastAPI framework (router & request lifecycle)
• SQL database (PostgreSQL, MySQL, …) via SQLAlchemy 2.0
• Redis instance for cache/other operations
c. Data flow & interactions:
• FastAPI receives request → middleware injects DB session
• Route handlers can use fastgear decorators for session management & pagination
• Handler invokes repository methods (async/sync) → SQLAlchemy session or Redis client
• Exceptions bubble up → fastgear exception handler serializes via Pydantic schemas
• Response serialized by Pydantic schemas and returned
d. Architectural patterns & design principles:
• Repository pattern (abstract + concrete)
• Decorator pattern for augmenting handlers
• Middleware for cross-cutting concerns (session management)
• Schema-first validation (Pydantic)
• Clear separation of concerns: data access, error handling, pagination, application wiring