essencia 1.13.0
A comprehensive Python framework for building secure medical and business applications with advanced security features and Flet integration
License: MIT
Requires Python: >=3.12
Keywords: brazil, encryption, flet, framework, medical, mongodb

# Essencia

A comprehensive Python framework for building secure medical and business applications with Brazilian market support.

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- **Security First**: Field-level encryption, XSS protection, rate limiting, CSRF tokens
- **Medical Ready**: Encrypted medical fields, LGPD compliance features
- **Brazilian Support**: CPF/CNPJ validators, phone formatting, Portuguese error messages  
- **Multi-Database**: MongoDB and PostgreSQL support with consistent API
- **Smart Caching**: Redis-based intelligent caching with fallback
- **Modern UI**: Built on Flet (Flutter for Python)
- **Type Safe**: Full type hints and Pydantic validation
- **Laboratory System**: Import, store and analyze lab test results with encryption

## Installation

```bash
# Basic installation
pip install essencia

# With security extras (bcrypt, argon2)
pip install essencia[security]

# With PostgreSQL support
pip install essencia[postgresql]

# All features
pip install essencia[all]
```

## Quick Start

### Environment Setup

Create a `.env` file:

```bash
# Required for encryption features
ESSENCIA_ENCRYPTION_KEY="your-base64-encoded-32-byte-key"

# Database connections (optional, defaults to localhost)
MONGODB_URL="mongodb://localhost:27017"
REDIS_URL="redis://localhost:6379"
```

Generate an encryption key:
```bash
python -c "import secrets; import base64; print(base64.b64encode(secrets.token_bytes(32)).decode())"
```

### Basic Usage

```python
from essencia import MongoModel, CPFValidator, EncryptedCPF
from essencia.fields import DefaultDateTime

# Define a model with encrypted fields
class Patient(MongoModel):
    COLLECTION_NAME = "patients"
    
    name: str
    cpf: EncryptedCPF  # Automatically encrypted/decrypted
    created_at: DefaultDateTime
    
# Validate Brazilian data
try:
    CPFValidator.validate("123.456.789-09")
except ValidationError as e:
    print(f"Invalid CPF: {e}")

# Use the model
patient = Patient(name="João Silva", cpf="123.456.789-09")
patient.save_self()  # CPF is encrypted in database
```

### Security Features

```python
from essencia.security import sanitize_input, RateLimiter
from essencia.cache import IntelligentCache

# Input sanitization
clean_html = sanitize_input("<script>alert('xss')</script>Hello")
# Result: "Hello"

# Rate limiting
rate_limiter = RateLimiter()
if rate_limiter.is_allowed("user-123", "login"):
    # Process login
    pass

# Intelligent caching
cache = IntelligentCache()
cache.set("user:123", user_data, ttl=3600)
```

### Service Pattern

```python
from essencia.services import EnhancedBaseService

class PatientService(EnhancedBaseService):
    model_class = Patient
    collection_name = "patients"
    
    async def find_by_cpf(self, cpf: str):
        # CPF is automatically encrypted for search
        return await self.find_one({"cpf": cpf})
```

### Laboratory Data Management

```python
from essencia.models import LabTest, LabTestAnalyzer
from essencia.utils import LabCSVImporter

# Import lab results from CSV
importer = LabCSVImporter(patient_key="patient_123", doctor_key="dr_smith")
success_count, errors = importer.import_csv("lab_results.csv")

# Analyze test trends
glucose_trend = LabTestAnalyzer.get_test_trend("patient_123", "Glicemia Jejum")
print(f"Latest: {glucose_trend['latest']} mg/dL, Trend: {glucose_trend['trend']}")

# Get abnormal results
abnormal = LabTestAnalyzer.get_abnormal_results("patient_123")
```

## Components

### Models
- `MongoModel` - Base model for MongoDB with sync operations
- `BaseModel` - Async base model using Motor
- Built-in field types: `MongoId`, `ObjectReferenceId`, `StrEnum`

### Security
- **Sanitization**: HTML/Markdown sanitizers for XSS prevention
- **Session Management**: Secure sessions with CSRF protection
- **Authorization**: Role-based access control (RBAC)
- **Rate Limiting**: Multiple strategies (sliding window, token bucket)
- **Encryption**: Field-level encryption for sensitive data

### Validators
- `CPFValidator` - Brazilian CPF validation and formatting
- `CNPJValidator` - Brazilian CNPJ validation
- `PhoneValidator` - Brazilian phone numbers
- `EmailValidator` - Email validation
- `MoneyValidator` - Brazilian currency formatting
- `DateValidator` - Date validation with business rules

### Fields
- `EncryptedCPF`, `EncryptedRG` - Encrypted Brazilian documents
- `EncryptedMedicalData` - For medical records
- `EncryptedLabResults` - For laboratory test results
- `DefaultDate`, `DefaultDateTime` - Auto-populated timestamps

### Laboratory System
- `LabTestType` - Catalog of test types with reference ranges
- `LabTest` - Individual test results with encryption
- `LabTestBatch` - Import tracking and auditing
- `LabTestAnalyzer` - Trend analysis and reporting
- `LabCSVImporter` - CSV import utility

## Documentation

- [Security Policy](SECURITY.md) - Security features and reporting
- [Migration Guide](MIGRATION.md) - Migrating from previous versions
- [Publishing Guide](PUBLISHING.md) - PyPI publication checklist
- [Laboratory System](docs/laboratory_system.md) - Lab data management guide

## Requirements

- Python 3.12+
- MongoDB 4.0+
- Redis 6.0+ (optional, for caching)

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

- Create an issue for bug reports or feature requests
- For security issues, see [SECURITY.md](SECURITY.md)