{"id":34847805,"url":"https://github.com/deerhide/fastapi_factory_utilities","last_synced_at":"2026-04-18T10:20:14.335Z","repository":{"id":322898456,"uuid":"1091347712","full_name":"DeerHide/fastapi_factory_utilities","owner":"DeerHide","description":"Extend FastAPI with tooling to create microservices easily","archived":false,"fork":false,"pushed_at":"2026-02-23T15:02:43.000Z","size":831,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-23T21:35:34.134Z","etag":null,"topics":["library","public","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DeerHide.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-06T22:32:53.000Z","updated_at":"2026-02-23T15:02:57.000Z","dependencies_parsed_at":"2025-12-06T09:06:19.386Z","dependency_job_id":"5dcdb4d7-4ffd-4766-8019-b967fd21522d","html_url":"https://github.com/DeerHide/fastapi_factory_utilities","commit_stats":null,"previous_names":["deerhide/fastapi_factory_utilities"],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/DeerHide/fastapi_factory_utilities","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeerHide%2Ffastapi_factory_utilities","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeerHide%2Ffastapi_factory_utilities/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeerHide%2Ffastapi_factory_utilities/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeerHide%2Ffastapi_factory_utilities/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DeerHide","download_url":"https://codeload.github.com/DeerHide/fastapi_factory_utilities/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeerHide%2Ffastapi_factory_utilities/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29860109,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T08:51:08.701Z","status":"ssl_error","status_checked_at":"2026-02-26T08:50:19.607Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["library","public","python"],"created_at":"2025-12-25T18:53:55.933Z","updated_at":"2026-02-26T13:01:35.558Z","avatar_url":"https://github.com/DeerHide.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FastAPI Factory Utilities\n\n[![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Development Status](https://img.shields.io/badge/status-alpha-orange.svg)](https://github.com/DeerHide/fastapi_factory_utilities)\n\n**A comprehensive library to build production-ready microservices with FastAPI, Beanie, Taskiq, AioPika, and OpenTelemetry.**\n\nThis library consolidates common patterns, plugins, and utilities for creating modern Python microservices with observability, security, and message-driven architectures built-in from the start.\n\n---\n\n## 📚 Documentation\n\n| Document | Description |\n|----------|-------------|\n| **[Documentation Index](docs/knowledge/index.md)** | Master navigation for all documentation |\n| [Project Overview](docs/knowledge/project-overview.md) | Executive summary and tech stack |\n| [Architecture](docs/knowledge/architecture.md) | Technical architecture reference with diagrams |\n| [Architecture Decisions](docs/planning-artifacts/architecture.md) | Formal architectural decisions and implementation patterns |\n| [Source Tree](docs/knowledge/source-tree-analysis.md) | Annotated directory structure |\n| [Development Guide](docs/knowledge/development-guide.md) | Setup, testing, and contribution guide |\n\n---\n\n## Features\n\n### 🏗️ Application Framework\n- **Abstract Application Builder** with plugin architecture for composable microservices\n- **Configuration Management** using YAML files and environment variables\n- **Environment-aware** configuration (development, staging, production)\n- **Lifecycle Management** with startup/shutdown hooks\n\n\u003e 📖 See [Architecture Documentation](docs/knowledge/architecture.md#core-components) for detailed component design.\n\n### 🔐 Security \u0026 Authentication\n- **JWT Bearer Authentication** with token verification and decoding\n- **Ory Kratos Integration** for identity and user management\n- **Ory Hydra Integration** for OAuth2 and OpenID Connect flows\n- **Flexible Authentication** with custom JWT verifiers and JWK stores\n\n\u003e 📖 See [Security Architecture](docs/knowledge/architecture.md#security-architecture) for authentication flows.\n\n### 🗄️ Database \u0026 ODM\n- **Beanie ODM Plugin** for MongoDB with async operations\n- **Document Models** with Pydantic v2 validation\n- **Repository Pattern** support for clean architecture\n\n\u003e 📖 See [Data Architecture](docs/knowledge/architecture.md#data-architecture) for repository patterns.\n\n### 📨 Message Broker \u0026 Task Queue\n- **AioPika Plugin** for RabbitMQ message broker integration\n- **Taskiq Plugin** for distributed task queue with Redis backend\n- **Message-Driven Architecture** support with async consumers/producers\n\n\u003e 📖 See [Plugin Architecture](docs/knowledge/architecture.md#plugin-architecture) for plugin details.\n\n### 📊 Observability \u0026 Monitoring\n- **OpenTelemetry Plugin** with automatic instrumentation for:\n  - FastAPI endpoints\n  - MongoDB operations\n  - HTTP client requests (aiohttp)\n  - RabbitMQ messaging (AioPika)\n- **Distributed Tracing** with OTLP exporters (HTTP/gRPC)\n- **Structured Logging** with structlog integration\n- **Status Endpoint** for health checks and monitoring\n\n\u003e 📖 See [Observability Architecture](docs/knowledge/architecture.md#observability-architecture) for tracing setup.\n\n### 🌐 HTTP Client\n- **AioHttp Plugin** with OpenTelemetry instrumentation\n- **Async HTTP operations** with connection pooling\n- **Automatic tracing** of outbound HTTP requests\n\n### 🛠️ Services\n- **Status Service** - Health check endpoints with reactive monitoring\n- **Audit Service** - Event auditing capabilities\n- **Kratos Service** - Identity management operations\n- **Hydra Service** - OAuth2/OIDC operations\n\n\u003e 📖 See [Service Layer](docs/knowledge/architecture.md#service-layer) for service details.\n\n---\n\n## Requirements\n\n- **Python:** \u003e= 3.12\n- **Key Dependencies:**\n  - FastAPI \u003e= 0.115.13\n  - Beanie ^2.0.0\n  - Taskiq with Redis backend\n  - AioPika ^9.5.7\n  - OpenTelemetry SDK ^1.26.0\n  - Pydantic ^2.8.2\n  - Structlog \u003e= 24.1\n\n\u003e 📖 See [Project Overview](docs/knowledge/project-overview.md#technology-stack-summary) for complete dependency list.\n\n---\n\n## Installation\n\n### Using pip\n\n```bash\npip install fastapi-factory-utilities\n```\n\n### Using Poetry\n\n```bash\npoetry add fastapi-factory-utilities\n```\n\n---\n\n## Quick Start\n\nHere's a minimal example to create a microservice with MongoDB and OpenTelemetry:\n\n```python\nfrom typing import ClassVar\nfrom beanie import Document\nfrom fastapi_factory_utilities.core.app import (\n    ApplicationAbstract,\n    ApplicationGenericBuilder,\n    RootConfig,\n)\nfrom fastapi_factory_utilities.core.plugins import PluginAbstract\nfrom fastapi_factory_utilities.core.plugins.odm_plugin import ODMPlugin\nfrom fastapi_factory_utilities.core.plugins.opentelemetry_plugin import OpenTelemetryPlugin\n\n\nclass MyAppConfig(RootConfig):\n    \"\"\"Custom application configuration.\"\"\"\n    pass\n\n\nclass MyApp(ApplicationAbstract):\n    \"\"\"Your microservice application.\"\"\"\n\n    CONFIG_CLASS: ClassVar[type[RootConfig]] = MyAppConfig\n    PACKAGE_NAME: ClassVar[str] = \"my_app\"\n    ODM_DOCUMENT_MODELS: ClassVar[list[type[Document]]] = []\n\n    def configure(self) -\u003e None:\n        \"\"\"Configure your application routes and middleware.\"\"\"\n        # Add your API routers here\n        pass\n\n    async def on_startup(self) -\u003e None:\n        \"\"\"Actions to perform on application startup.\"\"\"\n        pass\n\n    async def on_shutdown(self) -\u003e None:\n        \"\"\"Actions to perform on application shutdown.\"\"\"\n        pass\n\n\nclass MyAppBuilder(ApplicationGenericBuilder[MyApp]):\n    \"\"\"Application builder.\"\"\"\n\n    def get_default_plugins(self) -\u003e list[PluginAbstract]:\n        \"\"\"Get the default plugins.\"\"\"\n        return [\n            ODMPlugin(),\n            OpenTelemetryPlugin(),\n        ]\n\n    def __init__(self, plugins: list[PluginAbstract] | None = None) -\u003e None:\n        \"\"\"Initialize the builder.\"\"\"\n        if plugins is None:\n            plugins = self.get_default_plugins()\n        super().__init__(plugins=plugins)\n\n\n# Build and run your application\nif __name__ == \"__main__\":\n    MyAppBuilder().build_and_serve()\n```\n\nCreate an `application.yaml` configuration file in your package:\n\n```yaml\napplication:\n  service_namespace: \"my-company\"\n  service_name: \"my-app\"\n  description: \"My awesome microservice\"\n  version: \"1.0.0\"\n  environment: \"development\"\n\nserver:\n  host: \"0.0.0.0\"\n  port: 8000\n\ncors:\n  allow_origins: [\"*\"]\n  allow_credentials: true\n  allow_methods: [\"*\"]\n  allow_headers: [\"*\"]\n```\n\n\u003e 📖 See [Architecture - Configuration System](docs/knowledge/architecture.md#configuration-system) for complete configuration options.\n\n---\n\n## Core Components\n\n### Application Framework\n\nThe `ApplicationAbstract` class provides the foundation for your microservice:\n\n- **Plugin System**: Extend functionality through composable plugins\n- **Configuration**: Type-safe configuration with Pydantic models\n- **Lifecycle Management**: Control startup and shutdown behavior\n- **FastAPI Integration**: Built-in FastAPI application with customizable routes\n\nThe `ApplicationGenericBuilder` handles:\n- Configuration loading from YAML files\n- Plugin initialization and registration\n- FastAPI application setup\n- Uvicorn server management\n\n\u003e 📖 See [Architecture - Core Components](docs/knowledge/architecture.md#core-components) for detailed class documentation.\n\n### Available Plugins\n\nEach plugin extends your application with specific capabilities:\n\n| Plugin | Purpose | Documentation |\n|--------|---------|---------------|\n| **`ODMPlugin`** | MongoDB operations with Beanie ODM | [Plugin Details](docs/knowledge/architecture.md#plugin-implementation-example-odmplugin) |\n| **`OpenTelemetryPlugin`** | Distributed tracing and metrics | [Observability](docs/knowledge/architecture.md#observability-architecture) |\n| **`TaskiqPlugin`** | Background task processing with Redis | [Plugin Architecture](docs/knowledge/architecture.md#available-plugins) |\n| **`AioPikaPlugin`** | RabbitMQ messaging capabilities | [Plugin Architecture](docs/knowledge/architecture.md#available-plugins) |\n| **`AioHttpPlugin`** | Instrumented HTTP client | [Plugin Architecture](docs/knowledge/architecture.md#available-plugins) |\n\nPlugins follow a consistent lifecycle:\n1. `on_load()` - Initial setup when plugin is registered\n2. `on_startup()` - Async initialization during application startup\n3. `on_shutdown()` - Cleanup during application shutdown\n\n\u003e 📖 See [Plugin Lifecycle](docs/knowledge/architecture.md#plugin-lifecycle) for detailed flow.\n\n### Security \u0026 Authentication\n\n#### JWT Authentication\n\n```python\nfrom fastapi_factory_utilities.core.security.jwt import (\n    JWTAuthenticationService,\n    JWTBearerAuthenticationConfig,\n)\n\n# Configure JWT authentication\njwt_config = JWTBearerAuthenticationConfig(\n    issuer=\"https://your-auth-server.com\",\n    audience=\"your-api\",\n)\n\n# Use in FastAPI dependencies\nfrom fastapi import Depends\n\nasync def get_current_user(\n    token: str = Depends(JWTAuthenticationService),\n):\n    # Token is automatically verified\n    return token.sub\n```\n\n#### Ory Kratos Integration\n\n```python\nfrom fastapi_factory_utilities.core.services.kratos import (\n    KratosIdentityGenericService,\n    KratosGenericWhoamiService,\n)\n\n# Identity management\nkratos_service = KratosIdentityGenericService(base_url=\"http://kratos:4434\")\nidentity = await kratos_service.get_identity(identity_id=\"...\")\n\n# Session validation\nwhoami_service = KratosGenericWhoamiService(base_url=\"http://kratos:4433\")\nsession = await whoami_service.whoami(cookie=\"...\")\n```\n\n\u003e 📖 See [Security Architecture](docs/knowledge/architecture.md#security-architecture) for complete authentication flows.\n\n### Configuration System\n\nThe configuration system supports:\n\n- **YAML Files**: Store configuration in `application.yaml`\n- **Environment Variables**: Override values via environment variables\n- **Type Safety**: Pydantic models ensure type correctness\n- **Environment-Specific**: Different configs for dev/staging/production\n- **Frozen Models**: Immutable configuration prevents accidental changes\n\n```python\nfrom fastapi_factory_utilities.core.app.config import (\n    RootConfig,\n    BaseApplicationConfig,\n)\nfrom pydantic import Field\n\nclass MyCustomConfig(BaseModel):\n    \"\"\"Custom configuration section.\"\"\"\n    api_key: str = Field(description=\"External API key\")\n    timeout: int = Field(default=30, description=\"Request timeout\")\n\nclass MyAppConfig(RootConfig):\n    \"\"\"Extended application configuration.\"\"\"\n    my_custom: MyCustomConfig = Field(description=\"Custom configuration\")\n```\n\n\u003e 📖 See [Configuration Hierarchy](docs/knowledge/architecture.md#configuration-system) for all configuration options.\n\n---\n\n## Example Application\n\nThis library includes a complete example application demonstrating key features:\n\n```bash\n# Run the example application\nfastapi_factory_utilities-example\n```\n\nThe example shows:\n- Application structure with plugins\n- Configuration management\n- API router organization\n- Document models with Beanie\n- OpenTelemetry instrumentation\n\nSource code: [`src/fastapi_factory_utilities/example/`](src/fastapi_factory_utilities/example/)\n\n\u003e 📖 See [Source Tree Analysis](docs/knowledge/source-tree-analysis.md) for complete directory structure.\n\n---\n\n## Development\n\n### Prerequisites\n\n- Python 3.12+\n- Poetry for dependency management\n- Docker (optional, for containerized development)\n\n### Setup Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/DeerHide/fastapi_factory_utilities.git\ncd fastapi_factory_utilities\n\n# Run the setup script\n./scripts/setup_dev_env.sh\n\n# Or manually:\npoetry install --with test\npoetry run pre-commit install\n```\n\n\u003e 📖 See [Development Guide](docs/knowledge/development-guide.md) for complete setup instructions.\n\n### Running Tests\n\n```bash\n# Run all tests with coverage\npoetry run pytest --cov=src --cov-report=html --cov-report=term\n\n# Run specific tests\npoetry run pytest tests/units/test_exceptions.py\n\n# Run tests in parallel\npoetry run pytest -n auto\n```\n\n\u003e 📖 See [Development Guide - Testing](docs/knowledge/development-guide.md#running-tests) for testing patterns.\n\n### Code Quality\n\n```bash\n# Run all pre-commit hooks\npoetry run pre-commit run --all-files\n\n# Format code\npoetry run ruff format src tests\npoetry run ruff check --fix src tests\n\n# Type checking\npoetry run mypy\n```\n\n\u003e 📖 See [Development Guide - Code Style](docs/knowledge/development-guide.md#code-style-guidelines) for conventions.\n\n### Docker Development\n\n```bash\n# Build and run in container\n./scripts/dev-in-container.sh\n```\n\n\u003e 📖 See [Development Guide - Docker](docs/knowledge/development-guide.md#docker-development) for container setup.\n\n---\n\n## Architecture\n\n```mermaid\ngraph TB\n    App[ApplicationAbstract]\n    Builder[ApplicationGenericBuilder]\n    FastAPI[FastAPI Instance]\n\n    Builder --\u003e|builds| App\n    App --\u003e|provides| FastAPI\n\n    subgraph Plugins\n        ODM[ODM Plugin\u003cbr/\u003eMongoDB/Beanie]\n        OTel[OpenTelemetry Plugin\u003cbr/\u003eTracing]\n        Taskiq[Taskiq Plugin\u003cbr/\u003eTask Queue]\n        AioPika[AioPika Plugin\u003cbr/\u003eRabbitMQ]\n        Http[AioHttp Plugin\u003cbr/\u003eHTTP Client]\n    end\n\n    App --\u003e|registers| Plugins\n\n    subgraph Services\n        Status[Status Service]\n        Audit[Audit Service]\n        Kratos[Kratos Service]\n        Hydra[Hydra Service]\n    end\n\n    App --\u003e|provides| Services\n```\n\n\u003e 📖 See [Architecture Documentation](docs/knowledge/architecture.md) for detailed architecture diagrams and patterns.\n\n---\n\n## Project Structure\n\n```\nfastapi_factory_utilities/\n├── src/fastapi_factory_utilities/\n│   ├── core/           # 🎯 Main library code\n│   │   ├── app/        # Application framework\n│   │   ├── plugins/    # Plugin implementations\n│   │   ├── security/   # Authentication/authorization\n│   │   ├── services/   # Business services\n│   │   └── utils/      # Utility functions\n│   └── example/        # 📚 Usage example\n├── tests/              # Test suite\n├── docs/knowledge/     # 📖 Detailed documentation\n└── docker/             # Docker configurations\n```\n\n\u003e 📖 See [Source Tree Analysis](docs/knowledge/source-tree-analysis.md) for complete annotated structure.\n\n---\n\n## Contributing\n\nContributions are welcome! This project follows clean architecture principles and emphasizes:\n\n- Type safety with comprehensive type annotations\n- Async/await patterns for I/O operations\n- Plugin-based extensibility\n- Comprehensive testing\n- Clean code with proper documentation\n\nPlease ensure:\n- All tests pass (`poetry run pytest`)\n- Code is properly formatted (`poetry run ruff format`)\n- Type checking passes (`poetry run mypy`)\n- Pre-commit hooks pass (`poetry run pre-commit run --all-files`)\n\n\u003e 📖 See [Development Guide](docs/knowledge/development-guide.md) for complete contribution workflow.\n\n---\n\n## Security\n\nFor security concerns, please review our [Security Policy](SECURITY.md).\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n**Copyright (c) 2024 VANROYE Victorien**\n\n---\n\n## Resources\n\n- **Repository**: [https://github.com/DeerHide/fastapi_factory_utilities](https://github.com/DeerHide/fastapi_factory_utilities)\n- **Issues**: [https://github.com/DeerHide/fastapi_factory_utilities/issues](https://github.com/DeerHide/fastapi_factory_utilities/issues)\n- **PyPI**: [https://pypi.org/project/fastapi-factory-utilities/](https://pypi.org/project/fastapi-factory-utilities/)\n- **Documentation**: [docs/knowledge/index.md](docs/knowledge/index.md)\n\n### Related Projects\n\n- [FastAPI](https://fastapi.tiangolo.com/) - Modern web framework\n- [Beanie](https://beanie-odm.dev/) - MongoDB ODM\n- [Taskiq](https://taskiq-python.github.io/) - Distributed task queue\n- [AioPika](https://aio-pika.readthedocs.io/) - RabbitMQ client\n- [OpenTelemetry](https://opentelemetry.io/) - Observability framework\n- [Ory](https://www.ory.sh/) - Identity \u0026 access management\n\n---\n\n**Built with ❤️ for modern Python microservices**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeerhide%2Ffastapi_factory_utilities","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeerhide%2Ffastapi_factory_utilities","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeerhide%2Ffastapi_factory_utilities/lists"}