Metadata-Version: 2.4
Name: essencia
Version: 1.11.0
Summary: A comprehensive Python framework for building secure medical and business applications with advanced security features and Flet integration
Project-URL: Homepage, https://github.com/arantesdv/essencia
Project-URL: Bug Tracker, https://github.com/arantesdv/essencia/issues
Project-URL: Documentation, https://github.com/arantesdv/essencia#readme
Author-email: Daniel Arantes <arantesdv@me.com>
License: MIT
License-File: LICENSE
Keywords: brazil,encryption,flet,framework,medical,mongodb
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: aiofiles>=23.2.1
Requires-Dist: aioredis>=2.0.1
Requires-Dist: bson>=0.5.10
Requires-Dist: cryptography>=44.0.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: flet[all]>=0.28.3
Requires-Dist: httpx>=0.27.0
Requires-Dist: itsdangerous>=2.0.0
Requires-Dist: motor>=3.7.1
Requires-Dist: numpy>=1.26.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pydantic[email]>=2.11.5
Requires-Dist: pyjwt>=2.8.0
Requires-Dist: pymongo>=4.13.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: redis>=6.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: starlette>=0.27.0
Requires-Dist: typer[all]>=0.12.0
Requires-Dist: unidecode>=1.3.8
Requires-Dist: uvicorn[standard]>=0.23.0
Provides-Extra: all
Requires-Dist: argon2-cffi>=23.0.0; extra == 'all'
Requires-Dist: asyncpg>=0.29.0; extra == 'all'
Requires-Dist: bcrypt>=4.0.0; extra == 'all'
Requires-Dist: factory-boy>=3.3.0; extra == 'all'
Requires-Dist: faker>=30.0.0; extra == 'all'
Requires-Dist: flet[all]>=0.28.3; extra == 'all'
Requires-Dist: httpx>=0.27.0; extra == 'all'
Requires-Dist: motor>=3.7.1; extra == 'all'
Requires-Dist: psycopg2-binary>=2.9.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'all'
Requires-Dist: pytest-cov>=5.0.0; extra == 'all'
Requires-Dist: pytest-mock>=3.14.0; extra == 'all'
Requires-Dist: pytest-timeout>=2.3.0; extra == 'all'
Requires-Dist: pytest-xdist>=3.6.0; extra == 'all'
Requires-Dist: pytest>=8.0.0; extra == 'all'
Requires-Dist: respx>=0.21.0; extra == 'all'
Requires-Dist: sqlalchemy[asyncio]>=2.0.0; extra == 'all'
Provides-Extra: async
Requires-Dist: motor>=3.7.1; extra == 'async'
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: flake8>=7.0.0; extra == 'dev'
Requires-Dist: isort>=5.13.0; extra == 'dev'
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Provides-Extra: flet
Requires-Dist: flet[all]>=0.28.3; extra == 'flet'
Provides-Extra: graphql
Requires-Dist: graphene>=3.3.0; extra == 'graphql'
Requires-Dist: strawberry-graphql[fastapi]>=0.235.0; extra == 'graphql'
Provides-Extra: mobile
Requires-Dist: aiofiles>=23.2.1; extra == 'mobile'
Requires-Dist: flet[all]>=0.28.3; extra == 'mobile'
Provides-Extra: monitoring
Requires-Dist: opentelemetry-api>=1.24.0; extra == 'monitoring'
Requires-Dist: opentelemetry-exporter-jaeger>=1.21.0; extra == 'monitoring'
Requires-Dist: opentelemetry-exporter-otlp>=1.24.0; extra == 'monitoring'
Requires-Dist: opentelemetry-exporter-zipkin>=1.24.0; extra == 'monitoring'
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.45b0; extra == 'monitoring'
Requires-Dist: opentelemetry-instrumentation-pymongo>=0.45b0; extra == 'monitoring'
Requires-Dist: opentelemetry-instrumentation-redis>=0.45b0; extra == 'monitoring'
Requires-Dist: opentelemetry-instrumentation-requests>=0.45b0; extra == 'monitoring'
Requires-Dist: opentelemetry-instrumentation>=0.45b0; extra == 'monitoring'
Requires-Dist: opentelemetry-sdk>=1.24.0; extra == 'monitoring'
Requires-Dist: prometheus-client>=0.20.0; extra == 'monitoring'
Provides-Extra: postgresql
Requires-Dist: asyncpg>=0.29.0; extra == 'postgresql'
Requires-Dist: psycopg2-binary>=2.9.0; extra == 'postgresql'
Requires-Dist: sqlalchemy[asyncio]>=2.0.0; extra == 'postgresql'
Provides-Extra: security
Requires-Dist: argon2-cffi>=23.0.0; extra == 'security'
Requires-Dist: bcrypt>=4.0.0; extra == 'security'
Provides-Extra: test
Requires-Dist: factory-boy>=3.3.0; extra == 'test'
Requires-Dist: faker>=30.0.0; extra == 'test'
Requires-Dist: httpx>=0.27.0; extra == 'test'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest-cov>=5.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.14.0; extra == 'test'
Requires-Dist: pytest-timeout>=2.3.0; extra == 'test'
Requires-Dist: pytest-xdist>=3.6.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Requires-Dist: respx>=0.21.0; extra == 'test'
Provides-Extra: websocket
Requires-Dist: python-socketio>=5.11.0; extra == 'websocket'
Requires-Dist: websockets>=12.0; extra == 'websocket'
Description-Content-Type: text/markdown

# 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)