Metadata-Version: 2.4
Name: fk_util_tools
Version: 0.1.31
Summary: This repository provides utility tools and common functions for FK projects, including helpers for configuration, logging, middleware, AWS integration, and OpenTelemetry instrumentation for Python web frameworks.
License: MIT
License-File: LICENSE
Author: Steven Santacruz Garcia
Author-email: steven.santacruz@finkargo.com
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Dist: boto3 (>=1.40.26,<2.0.0)
Requires-Dist: opentelemetry-api (>=1.36.0,<2.0.0)
Requires-Dist: opentelemetry-exporter-jaeger (>=1.21.0,<2.0.0)
Requires-Dist: opentelemetry-exporter-otlp (>=1.11,<2.0.0)
Requires-Dist: opentelemetry-instrumentation-aws-lambda (>=0.57b0,<0.58)
Requires-Dist: opentelemetry-instrumentation-botocore (>=0.57b0,<0.58)
Requires-Dist: opentelemetry-instrumentation-django (>=0.57b0,<0.58)
Requires-Dist: opentelemetry-instrumentation-fastapi (>=0.57b0,<0.58)
Requires-Dist: opentelemetry-instrumentation-flask (>=0.57b0,<0.58)
Requires-Dist: opentelemetry-instrumentation-logging (>=0.57b0,<0.58)
Requires-Dist: opentelemetry-instrumentation-psycopg2 (>=0.57b0,<0.58)
Requires-Dist: opentelemetry-instrumentation-requests (>=0.57b0,<0.58)
Requires-Dist: opentelemetry-instrumentation-sqlalchemy (>=0.57b0,<0.58)
Requires-Dist: opentelemetry-sdk (>=1.36.0,<2.0.0)
Requires-Dist: protobuf (==3.20.3)
Requires-Dist: psycopg2-binary (>=2.9.10,<3.0.0)
Requires-Dist: starlette (>=1.3.1,<2.0.0)
Description-Content-Type: text/markdown

# fk-util-tools

Utility tools and shared functions for FK projects: centralized configuration, logging, middlewares, AWS integration, and OpenTelemetry tracing for Python web frameworks.

## Installation

```bash
pip install fk-util-tools
```

## Main Features

- **Centralized Configuration**: `Config` class for global settings management.
- **Cache**: Redis integration.
- **Environment Variables & AWS**: Access to AWS Parameter Store and Secrets Manager.
- **Custom Exceptions**: HTTP error handling with custom codes.
- **Structured Logging**: Logging for FastAPI and other frameworks.
- **Middlewares**: SQL Printer, error handling, internationalization, and language support for Flask, Django, and FastAPI.
- **OpenTelemetry Tracing**: Instrumentation for Flask, Django, FastAPI, and AWS Lambda.
- **Type Hints**: PEP 561 support.

## Usage Examples

### Configuration

```python
from fk_utils import SETTINGS
print(SETTINGS.ENV)
```

### Structured Logging in FastAPI

```python
from fastapi import FastAPI
from fk_utils.logging.fastapi.logging import setup_logging

app = FastAPI()
setup_logging(app)
```

### SQL Printer Middleware

#### Flask

```python
from flask import Flask
from fk_utils.middlewares.flask.sql_middleware import SqlPrintingMiddleware

app = Flask(__name__)
app.config['DEBUG'] = True
SqlPrintingMiddleware(app)
```

#### Django

```python
from fk_utils.middlewares.django.sql_middleware import SqlPrintingMiddleware

SqlPrintingMiddleware()
```

#### FastAPI

```python
from fk_utils.middlewares.fastapi.sql_middleware import SqlPrintingMiddleware

app = FastAPI()
SqlPrintingMiddleware(app)
```

### OpenTelemetry Instrumentation

```python
from fk_utils.traces.opentelemetry.fastapi.trace import instrument_app

app = FastAPI()
instrument_app(app)
```

### AWS Lambda Instrumentation

```python
from fk_utils.traces.opentelemetry.fastapi.aws_lambda.trace import instrument_app

app = FastAPI()
is_lambda = instrument_app(app, instrument_lambda=True)
print("Lambda instrumented:", is_lambda)
```

### Health check endpoint

`fk_utils.health` expone un `/health` estandarizado para Django, FastAPI y Flask:

```python
from fk_utils.health.django import DjangoHealthCheck
from fk_utils.health import DjangoPostgreSQLCheck, MongoDBCheck

health = DjangoHealthCheck(
    environment=settings.ENV,
    country="CO",
    version=settings.VERSION,
    checks=[DjangoPostgreSQLCheck(), MongoDBCheck(mongo_client)],
)
urlpatterns = [path("health", health.view)]
```

Respuesta: `{"status": "healthy|unhealthy", "environment", "country", "version", "databases": {"postgresql": "healthy", "mongodb": "unhealthy: ..."}}`.

Los checks corren en paralelo y la respuesta está acotada en tiempo (2 s por defecto). Si una
dependencia se cuelga (p. ej. pymongo reintentando autenticación durante 20 s), el check se reporta
como `unhealthy: timeout after 2s` y el endpoint igual responde: los probes de Kubernetes y el
blackbox de monitoreo nunca ven un timeout HTTP por culpa de una dependencia. El presupuesto se
ajusta con el parámetro `timeout=` o la variable `FK_HEALTH_CHECK_TIMEOUT`; `timeout=0` vuelve al
comportamiento secuencial sin límite.

Checks propios: subclasear `fk_utils.health.base.HealthCheck` (ver docstring).

## License

MIT

