fastapi-armor-lib 0.1.0__tar.gz

fastapi_armor_lib-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: fastapi-armor-lib
+Version: 0.1.0
+Summary: Production-ready error handling, logging, and monitoring for FastAPI apps
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: sentry-sdk[fastapi]>=1.40.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+Requires-Dist: uvicorn; extra == "dev"
+
+# fastapi-armor 🛡️
+
+> Production-ready error handling, logging, and Sentry monitoring for FastAPI — in one line.
+
+[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-009688.svg)](https://fastapi.tiangolo.com/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-armor.svg)](https://pypi.org/project/fastapi-armor/)
+
+---
+
+## Why fastapi-armor?
+
+Every production FastAPI app needs the same boilerplate: structured logging, clean error responses, and error monitoring. **fastapi-armor** wires all of that up automatically — no copy-pasting, no missing edge cases.
+
+**Before:**
+```python
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import JSONResponse
+import logging, logging.handlers, sentry_sdk
+# ... 60+ lines of setup code
+
+app = FastAPI()
+```
+
+**After:**
+```python
+from fastapi import FastAPI
+from fastapi_armor import Armor
+
+app = FastAPI()
+Armor(app)  # ✅ Done.
+```
+
+---
+
+## Installation
+
+```bash
+pip install fastapi-armor
+```
+
+---
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+from fastapi_armor import Armor
+
+app = FastAPI()
+
+Armor(
+    app,
+    log_file="logs/app.log",
+    sentry_dsn="https://your-dsn@sentry.io/123",  # optional
+    environment="production",
+)
+
+@app.get("/")
+def root():
+    return {"status": "running"}
+```
+
+That's it. Your app now has:
+- ✅ Rotating file logs + console output
+- ✅ Clean JSON error responses for all exception types
+- ✅ Sentry integration (if DSN is provided)
+
+---
+
+## What It Does
+
+### 🔴 Error Handling
+
+| Exception Type | Response |
+|---|---|
+| `HTTPException` | `{"detail": "..."}` with original status code |
+| `RequestValidationError` | `{"error": "Validation failed", "detail": [...]}` with 422 |
+| Any other `Exception` | `{"error": "Internal server error"}` with 500 (full traceback logged internally) |
+
+All responses use `Content-Type: application/json; charset=utf-8`.
+
+### 📋 Logging
+
+- **Rotating file logs** — auto-creates the `logs/` directory
+- **Console output** — for local development
+- **Format:** `2024-01-01 12:00:00 | ERROR | Traceback (most recent call last): ...`
+- Named logger: `fastapi_armor`
+
+### 🔍 Sentry (optional)
+
+Initializes `sentry_sdk` with `FastApiIntegration` and `StarletteIntegration` when a DSN is provided. Private data is not sent by default.
+
+---
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `app` | `FastAPI` | required | Your FastAPI application instance |
+| `log_file` | `str` | `"logs/app.log"` | Path to the rotating log file |
+| `log_max_bytes` | `int` | `5_000_000` | Max size per log file (5 MB) |
+| `log_backup_count` | `int` | `3` | Number of backup log files to keep |
+| `sentry_dsn` | `str` | `""` | Sentry DSN — leave empty to disable |
+| `environment` | `str` | `"development"` | Environment tag sent to Sentry |
+
+---
+
+## Requirements
+
+- Python 3.9+
+- FastAPI 0.100+
+- sentry-sdk 1.40+ *(installed automatically)*
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/raghadalb-tech/fastapi-armor.git
+cd fastapi-armor
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+Test output:

fastapi_armor_lib-0.1.0/README.md

@@ -0,0 +1,127 @@
+# fastapi-armor 🛡️
+
+> Production-ready error handling, logging, and Sentry monitoring for FastAPI — in one line.
+
+[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-009688.svg)](https://fastapi.tiangolo.com/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-armor.svg)](https://pypi.org/project/fastapi-armor/)
+
+---
+
+## Why fastapi-armor?
+
+Every production FastAPI app needs the same boilerplate: structured logging, clean error responses, and error monitoring. **fastapi-armor** wires all of that up automatically — no copy-pasting, no missing edge cases.
+
+**Before:**
+```python
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import JSONResponse
+import logging, logging.handlers, sentry_sdk
+# ... 60+ lines of setup code
+
+app = FastAPI()
+```
+
+**After:**
+```python
+from fastapi import FastAPI
+from fastapi_armor import Armor
+
+app = FastAPI()
+Armor(app)  # ✅ Done.
+```
+
+---
+
+## Installation
+
+```bash
+pip install fastapi-armor
+```
+
+---
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+from fastapi_armor import Armor
+
+app = FastAPI()
+
+Armor(
+    app,
+    log_file="logs/app.log",
+    sentry_dsn="https://your-dsn@sentry.io/123",  # optional
+    environment="production",
+)
+
+@app.get("/")
+def root():
+    return {"status": "running"}
+```
+
+That's it. Your app now has:
+- ✅ Rotating file logs + console output
+- ✅ Clean JSON error responses for all exception types
+- ✅ Sentry integration (if DSN is provided)
+
+---
+
+## What It Does
+
+### 🔴 Error Handling
+
+| Exception Type | Response |
+|---|---|
+| `HTTPException` | `{"detail": "..."}` with original status code |
+| `RequestValidationError` | `{"error": "Validation failed", "detail": [...]}` with 422 |
+| Any other `Exception` | `{"error": "Internal server error"}` with 500 (full traceback logged internally) |
+
+All responses use `Content-Type: application/json; charset=utf-8`.
+
+### 📋 Logging
+
+- **Rotating file logs** — auto-creates the `logs/` directory
+- **Console output** — for local development
+- **Format:** `2024-01-01 12:00:00 | ERROR | Traceback (most recent call last): ...`
+- Named logger: `fastapi_armor`
+
+### 🔍 Sentry (optional)
+
+Initializes `sentry_sdk` with `FastApiIntegration` and `StarletteIntegration` when a DSN is provided. Private data is not sent by default.
+
+---
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `app` | `FastAPI` | required | Your FastAPI application instance |
+| `log_file` | `str` | `"logs/app.log"` | Path to the rotating log file |
+| `log_max_bytes` | `int` | `5_000_000` | Max size per log file (5 MB) |
+| `log_backup_count` | `int` | `3` | Number of backup log files to keep |
+| `sentry_dsn` | `str` | `""` | Sentry DSN — leave empty to disable |
+| `environment` | `str` | `"development"` | Environment tag sent to Sentry |
+
+---
+
+## Requirements
+
+- Python 3.9+
+- FastAPI 0.100+
+- sentry-sdk 1.40+ *(installed automatically)*
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/raghadalb-tech/fastapi-armor.git
+cd fastapi-armor
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+Test output:

fastapi_armor_lib-0.1.0/fastapi_armor/__init__.py

@@ -0,0 +1,3 @@
+from .armor import Armor
+
+__all__ = ["Armor"]

fastapi_armor_lib-0.1.0/fastapi_armor/armor.py

@@ -0,0 +1,27 @@
+from fastapi import FastAPI
+
+from .error_handler import add_exception_handlers
+from .logger import setup_logger
+from .sentry import init_sentry
+
+
+class Armor:
+    def __init__(
+        self,
+        app: FastAPI,
+        log_file: str = "logs/app.log",
+        log_max_bytes: int = 5_000_000,
+        log_backup_count: int = 3,
+        sentry_dsn: str = "",
+        environment: str = "development",
+    ):
+        self.app = app
+        self.logger = setup_logger(
+            log_file=log_file,
+            max_bytes=log_max_bytes,
+            backup_count=log_backup_count,
+        )
+        add_exception_handlers(app=self.app, logger=self.logger)
+
+        if sentry_dsn:
+            init_sentry(dsn=sentry_dsn, environment=environment)

fastapi_armor_lib-0.1.0/fastapi_armor/error_handler.py

@@ -0,0 +1,36 @@
+import logging
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+
+JSON_MEDIA_TYPE = "application/json; charset=utf-8"
+
+
+def add_exception_handlers(app: FastAPI, logger: logging.Logger) -> None:
+    @app.exception_handler(HTTPException)
+    async def http_exception_handler(_: Request, exc: HTTPException) -> JSONResponse:
+        return JSONResponse(
+            status_code=exc.status_code,
+            content={"detail": exc.detail},
+            media_type=JSON_MEDIA_TYPE,
+        )
+
+    @app.exception_handler(RequestValidationError)
+    async def validation_exception_handler(
+        _: Request, exc: RequestValidationError
+    ) -> JSONResponse:
+        return JSONResponse(
+            status_code=422,
+            content={"error": "Validation failed", "detail": exc.errors()},
+            media_type=JSON_MEDIA_TYPE,
+        )
+
+    @app.exception_handler(Exception)
+    async def generic_exception_handler(_: Request, exc: Exception) -> JSONResponse:
+        logger.exception("Unhandled exception occurred", exc_info=exc)
+        return JSONResponse(
+            status_code=500,
+            content={"error": "Internal server error"},
+            media_type=JSON_MEDIA_TYPE,
+        )

fastapi_armor_lib-0.1.0/fastapi_armor/logger.py

@@ -0,0 +1,37 @@
+import logging
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+
+def setup_logger(
+    log_file: str = "logs/app.log",
+    max_bytes: int = 5_000_000,
+    backup_count: int = 3,
+) -> logging.Logger:
+    logger = logging.getLogger("fastapi_armor")
+    logger.setLevel(logging.INFO)
+
+    if logger.handlers:
+        return logger
+
+    log_path = Path(log_file)
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+
+    formatter = logging.Formatter("%(asctime)s | %(levelname)s | %(message)s")
+
+    file_handler = RotatingFileHandler(
+        filename=log_path,
+        maxBytes=max_bytes,
+        backupCount=backup_count,
+        encoding="utf-8",
+    )
+    file_handler.setFormatter(formatter)
+
+    console_handler = logging.StreamHandler()
+    console_handler.setFormatter(formatter)
+
+    logger.addHandler(file_handler)
+    logger.addHandler(console_handler)
+    logger.propagate = False
+
+    return logger

fastapi_armor_lib-0.1.0/fastapi_armor/sentry.py

@@ -0,0 +1,19 @@
+from typing import Optional
+
+import sentry_sdk
+from sentry_sdk.integrations.fastapi import FastApiIntegration
+from sentry_sdk.integrations.starlette import StarletteIntegration
+
+
+def init_sentry(dsn: str, environment: str = "development") -> Optional[None]:
+    if not dsn:
+        return None
+
+    sentry_sdk.init(
+        dsn=dsn,
+        environment=environment,
+        integrations=[FastApiIntegration(), StarletteIntegration()],
+        traces_sample_rate=1.0,
+        send_default_pii=False,
+    )
+    return None

fastapi_armor_lib-0.1.0/fastapi_armor_lib.egg-info/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: fastapi-armor-lib
+Version: 0.1.0
+Summary: Production-ready error handling, logging, and monitoring for FastAPI apps
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: sentry-sdk[fastapi]>=1.40.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+Requires-Dist: uvicorn; extra == "dev"
+
+# fastapi-armor 🛡️
+
+> Production-ready error handling, logging, and Sentry monitoring for FastAPI — in one line.
+
+[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-009688.svg)](https://fastapi.tiangolo.com/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-armor.svg)](https://pypi.org/project/fastapi-armor/)
+
+---
+
+## Why fastapi-armor?
+
+Every production FastAPI app needs the same boilerplate: structured logging, clean error responses, and error monitoring. **fastapi-armor** wires all of that up automatically — no copy-pasting, no missing edge cases.
+
+**Before:**
+```python
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import JSONResponse
+import logging, logging.handlers, sentry_sdk
+# ... 60+ lines of setup code
+
+app = FastAPI()
+```
+
+**After:**
+```python
+from fastapi import FastAPI
+from fastapi_armor import Armor
+
+app = FastAPI()
+Armor(app)  # ✅ Done.
+```
+
+---
+
+## Installation
+
+```bash
+pip install fastapi-armor
+```
+
+---
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+from fastapi_armor import Armor
+
+app = FastAPI()
+
+Armor(
+    app,
+    log_file="logs/app.log",
+    sentry_dsn="https://your-dsn@sentry.io/123",  # optional
+    environment="production",
+)
+
+@app.get("/")
+def root():
+    return {"status": "running"}
+```
+
+That's it. Your app now has:
+- ✅ Rotating file logs + console output
+- ✅ Clean JSON error responses for all exception types
+- ✅ Sentry integration (if DSN is provided)
+
+---
+
+## What It Does
+
+### 🔴 Error Handling
+
+| Exception Type | Response |
+|---|---|
+| `HTTPException` | `{"detail": "..."}` with original status code |
+| `RequestValidationError` | `{"error": "Validation failed", "detail": [...]}` with 422 |
+| Any other `Exception` | `{"error": "Internal server error"}` with 500 (full traceback logged internally) |
+
+All responses use `Content-Type: application/json; charset=utf-8`.
+
+### 📋 Logging
+
+- **Rotating file logs** — auto-creates the `logs/` directory
+- **Console output** — for local development
+- **Format:** `2024-01-01 12:00:00 | ERROR | Traceback (most recent call last): ...`
+- Named logger: `fastapi_armor`
+
+### 🔍 Sentry (optional)
+
+Initializes `sentry_sdk` with `FastApiIntegration` and `StarletteIntegration` when a DSN is provided. Private data is not sent by default.
+
+---
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `app` | `FastAPI` | required | Your FastAPI application instance |
+| `log_file` | `str` | `"logs/app.log"` | Path to the rotating log file |
+| `log_max_bytes` | `int` | `5_000_000` | Max size per log file (5 MB) |
+| `log_backup_count` | `int` | `3` | Number of backup log files to keep |
+| `sentry_dsn` | `str` | `""` | Sentry DSN — leave empty to disable |
+| `environment` | `str` | `"development"` | Environment tag sent to Sentry |
+
+---
+
+## Requirements
+
+- Python 3.9+
+- FastAPI 0.100+
+- sentry-sdk 1.40+ *(installed automatically)*
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/raghadalb-tech/fastapi-armor.git
+cd fastapi-armor
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+Test output:

fastapi_armor_lib-0.1.0/fastapi_armor_lib.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+fastapi_armor/__init__.py
+fastapi_armor/armor.py
+fastapi_armor/error_handler.py
+fastapi_armor/logger.py
+fastapi_armor/sentry.py
+fastapi_armor_lib.egg-info/PKG-INFO
+fastapi_armor_lib.egg-info/SOURCES.txt
+fastapi_armor_lib.egg-info/dependency_links.txt
+fastapi_armor_lib.egg-info/requires.txt
+fastapi_armor_lib.egg-info/top_level.txt
+tests/test_armor.py

fastapi_armor_lib-0.1.0/fastapi_armor_lib.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fastapi_armor_lib-0.1.0/fastapi_armor_lib.egg-info/requires.txt

@@ -0,0 +1,7 @@
+fastapi>=0.100.0
+sentry-sdk[fastapi]>=1.40.0
+
+[dev]
+pytest
+httpx
+uvicorn

fastapi_armor_lib-0.1.0/fastapi_armor_lib.egg-info/top_level.txt

@@ -0,0 +1 @@
+fastapi_armor

fastapi_armor_lib-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fastapi-armor-lib"
+version = "0.1.0"
+description = "Production-ready error handling, logging, and monitoring for FastAPI apps"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "fastapi>=0.100.0",
+    "sentry-sdk[fastapi]>=1.40.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "httpx", "uvicorn"]
+
+[tool.setuptools.packages.find]
+include = ["fastapi_armor*"]

fastapi_armor_lib-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fastapi_armor_lib-0.1.0/tests/test_armor.py

@@ -0,0 +1,63 @@
+import asyncio
+
+from fastapi import FastAPI, HTTPException
+from httpx import ASGITransport, AsyncClient
+
+from fastapi_armor import Armor
+
+
+def _request(app: FastAPI, method: str, path: str):
+    async def _run():
+        transport = ASGITransport(app=app, raise_app_exceptions=False)
+        async with AsyncClient(transport=transport, base_url="http://test") as client:
+            return await client.request(method, path)
+
+    return asyncio.run(_run())
+
+
+def test_armor_initializes_without_errors():
+    app = FastAPI()
+    armor = Armor(app)
+    assert armor.app is app
+    assert armor.logger.name == "fastapi_armor"
+
+
+def test_http_exception_returns_clean_json():
+    app = FastAPI()
+    Armor(app)
+
+    @app.get("/http-error")
+    async def raise_http_error():
+        raise HTTPException(status_code=404, detail="Not found")
+
+    response = _request(app, "GET", "/http-error")
+    assert response.status_code == 404
+    assert response.json() == {"detail": "Not found"}
+
+
+def test_unhandled_exception_returns_internal_server_error():
+    app = FastAPI()
+    Armor(app)
+
+    @app.get("/boom")
+    async def raise_runtime_error():
+        raise RuntimeError("unexpected")
+
+    response = _request(app, "GET", "/boom")
+    assert response.status_code == 500
+    assert response.json() == {"error": "Internal server error"}
+
+
+def test_validation_error_returns_validation_failed():
+    app = FastAPI()
+    Armor(app)
+
+    @app.get("/items/{item_id}")
+    async def get_item(item_id: int):
+        return {"item_id": item_id}
+
+    response = _request(app, "GET", "/items/not-an-int")
+    assert response.status_code == 422
+    body = response.json()
+    assert body["error"] == "Validation failed"
+    assert isinstance(body["detail"], list)