Metadata-Version: 2.4
Name: csctracker-py-core
Version: 26.7.7
Summary: A base library for microservices with Flask, JSON logging, and Prometheus telemetry.
Home-page: https://github.com/krlsedu/CscTrackerPyCore
Author: Carlos Eduardo
License: MIT
Project-URL: Bug Tracker, https://github.com/krlsedu/CscTrackerPyCore/issues
Project-URL: Source Code, https://github.com/krlsedu/CscTrackerPyCore
Keywords: microservices,flask,json-logging,prometheus,telemetry,swagger,openapi,background-jobs,scheduler,observability,http-client,middleware
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: csctracker-queue-scheduler==24.6.1
Requires-Dist: flask~=3.0.0
Requires-Dist: python-json-logger
Requires-Dist: python-dotenv~=1.0.0
Requires-Dist: requests~=2.32.0
Requires-Dist: beautifulsoup4==4.10.0
Requires-Dist: flask-cors~=3.0.7
Requires-Dist: prometheus-flask-exporter==0.22.4
Requires-Dist: flask-swagger-init==23.52.4
Requires-Dist: pytz~=2023.3.post1
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# CscTrackerPyCore

[![PyPI version](https://img.shields.io/pypi/v/csctracker-py-core.svg)](https://pypi.org/project/csctracker-py-core/)
[![Python versions](https://img.shields.io/pypi/pyversions/csctracker-py-core.svg)](https://pypi.org/project/csctracker-py-core/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

CscTrackerPyCore é uma biblioteca Python base desenvolvida para padronizar e acelerar o desenvolvimento de microserviços. Ela oferece integração nativa com Flask, fornecendo recursos essenciais como logging estruturado em JSON, telemetria com Prometheus, documentação automática via Swagger e gerenciamento de tarefas agendadas.

## Principais Funcionalidades

- **Starter Facilitado**: Inicialização rápida de aplicações Flask com suporte a CORS e tratamento de variáveis de ambiente.
- **Logging Estruturado**: Formatação automática de logs em JSON com inclusão de `requestId`, `appName` e `appVersion` para melhor rastreabilidade.
- **Observabilidade**:
    - Integração nativa com **Prometheus** para coleta de métricas de endpoints.
    - **Interceptor de Requisições**: Registro detalhado de chamadas HTTP (método, path, status, duração) com opção de persistência remota para auditoria.
- **Documentação Automática**: Geração de especificação **Swagger (OpenAPI)** simplificada.
- **Processamento em Background**: Integração com `csctracker-queue-scheduler` para execução de tarefas assíncronas e agendadas.
- **Repositórios Remotos**: Abstração para comunicação entre serviços via HTTP com tratamento de headers e correlação.

## Requisitos

- Python 3.9+
- Flask
- Flask-CORS
- Prometheus Flask Exporter
- Flask Swagger Generator
- Python JSON Logger
- Python Dotenv

## Instalação

As dependências podem ser instaladas via `pip`:

```bash
pip install csctracker-py-core
```

Ou via `requirements.txt`:

```bash
pip install -r requirements.txt
```

## Configuração

A biblioteca é configurada principalmente via variáveis de ambiente, suportando arquivos `.env` localizados na pasta `config/` (ex: `config/dev.env`).

### Variáveis de Ambiente Suportadas

| Variável | Descrição | Exemplo |
| :--- | :--- | :--- |
| `PROFILE` | Perfil de configuração (define o arquivo .env) | `dev` |
| `PORT` | Porta de execução do servidor Flask | `5000` |
| `LOG_LEVEL` | Nível de detalhamento do log | `INFO`, `DEBUG` |
| `LOG_REQUEST_BODY` | Se `True`, inclui o corpo da requisição nos logs | `True` |
| `LOG_RESPONSE_BODY` | Se `True`, inclui o corpo da resposta nos logs | `False` |
| `URL_BFF` | URL base para persistência de logs de requisição | `http://api-gateway/` |
| `API_TOKEN` | Token de autorização para chamadas externas | `seu_token_aqui` |
| `DEBUG` | Ativa o modo debug do Flask se definido como `1` | `0` |

## Uso Didático

### 1. Inicialização do `Starter`

A classe `Starter` centraliza a configuração do Flask.

```python
from csctracker_py_core.starter import Starter

# Inicializa o starter (static_folder define a pasta de arquivos estáticos)
# save_request=True ativa a persistência remota de logs de requisição
starter = Starter(save_request=False)

# Obtém a instância do Flask configurada
app = starter.get_app()

@app.route('/')
def hello():
    return {"message": "CscTrackerPyCore is running!"}

if __name__ == '__main__':
    starter.start()
```

### 2. Logging e Interceptação

Uma vez iniciado o `Starter`, todos os logs do sistema usarão o formato JSON e as requisições serão interceptadas automaticamente para gerar telemetria.

### 3. Acesso aos Repositórios

```python
# Acesso ao repositório HTTP para chamadas externas padronizadas
http_repo = starter.get_http_repository()
```

## Estrutura do Projeto

- `Starter`: Orquestrador principal que configura Flask, CORS, Métricas e Swagger.
- `Configs`: Gerencia o carregamento de variáveis de ambiente e a configuração do logger JSON.
- `Interceptor`: Middleware Flask que captura dados de performance e logs de entrada/saída.
- `HttpRepository`: Facilita requisições HTTP externas com injeção de headers de segurança e rastreio.
- `RequestInfo`: Utilitário para gerenciar IDs de correlação (Correlation IDs) entre threads.

## Licença

Este projeto está sob a licença MIT. Consulte o arquivo `LICENSE` para mais detalhes.
