# util-rpa

Librería de utilidades corporativas en Python orientada a automatización operativa (RPA), procesos batch y pipelines backend.

Incluye módulos para:

* 📧 Envío de correos SMTP
* 🗄️ Conexión a SQL Server
* 📜 Configuración de logging centralizado

> Diseñado para entornos productivos: scripts backend, ETLs, servicios batch y jobs automatizados.

---

## ✨ Objetivos

* Simplificar tareas repetitivas en proyectos Python empresariales
* Reducir boilerplate en envío de correos o ejecución SQL
* Mantener estandarización y buenas prácticas
* Facilitar adopción por equipos heterogéneos

---

# 🚀 Instalación

```bash
pip install util-rpa
```

> Requiere Python **>= 3.9 y < 3.13**

---

# 📁 Estructura del paquete

```
util_rpa/
│
├── mail/
│   ├── models.py
│   ├── smtp.py
│   ├── template.py
│
├── sql/
│   ├── sqlserver.py
│
├── logging_utils.py
├── __init__.py
└── bin/
    └── mail.exe  (legacy)
```

---

# ✉️ Módulo Mail

Este módulo provee un cliente SMTP estándar y opcionalmente plantillas simples.

### Ejemplo: envío básico

```python
from util_rpa.mail.models import EmailMessage
from util_rpa.mail.smtp import SMTPClient

msg = EmailMessage(
    sender="noreply@empresa.com",
    to=["usuario@empresa.com"],
    subject="Proceso completado",
    body_html="<b>OK</b>"
)

client = SMTPClient(host="10.10.1.12", port=25)
client.send(msg)
```

---

### Ejemplo: uso de plantilla

```python
from util_rpa.mail.template import EmailTemplate

tpl = EmailTemplate(
    subject="Reporte ${fecha}",
    body="""
        <h3>Hola ${usuario}</h3>
        Resultado: ${estado}
    """
)

subject, body = tpl.render(
    fecha="2025-01-01",
    usuario="Jonathan",
    estado="OK"
)

msg = EmailMessage(
    sender="noreply@empresa.com",
    to=["usuario@empresa.com"],
    subject=subject,
    body_html=body
)
```

> La plantilla sigue sintaxis estándar de `string.Template`.

---

# 🗄️ Módulo SQLServer

Cliente simple basado en `pyodbc`, ideal para consultas rápidas y pipelines.

### Ejemplo: consulta

```python
from util_rpa.sql.sqlserver import SQLServer

db = SQLServer(
    host="10.0.0.5",
    database="DATA",
    user="robot",
    password="***"
)

df = db.query("SELECT TOP 10 * FROM tabla")
print(df)
```

---

### Ejecución de comandos

```python
affected = db.execute(
    "UPDATE tabla SET estado = ? WHERE id = ?",
    ["OK", 1234]
)

print("Registros actualizados:", affected)
```

---

# 📝 Logging

Inicializa logger raíz reutilizable.

```python
from util_rpa.logging_utils import init_logging

log = init_logging(
    level="INFO",
    log_file="process.log",
    max_bytes=10*1024*1024,
    backup_count=3
)
```

Ahora puedes usar:

```python
log.info("Iniciando proceso")
log.error("Error crítico", exc_info=True)
```

> Logging rotativo para procesos batch/cron grandes.

---

# ⚠️ Sobre `mail.exe` (legacy)

`util_rpa/bin/mail.exe` es un envío SMTP alternativo para entornos Windows sin relay o TLS.

* Úsalo solo como fallback
* No recomendado en Linux ni Docker
* No recomendado en entornos CI/CD

---

# 📦 Requerimientos

Dependencias mínimas:

```
pandas>=2.0,<3.0
pyodbc>=5.1,<6.0
python-dateutil>=2.8,<3.0
```

---

# 🏛️ Versionamiento

> El paquete sigue **Semantic Versioning (SemVer)**.

* **2.0.0** → Primera versión modular (breaking changes respecto a 1.x)
* **2.1.x** → Nuevas funcionalidades sin romper compatibilidad
* **2.1.1** → Hotfix

---

# 🧪 Desarrollo

Instalar dependencias de desarrollo:

```bash
pip install .[dev]
```

Correr tests:

```bash
pytest -q
```

---

# 📌 Buenas prácticas recomendadas

* Inicializa logging una sola vez en `main.py`
* Gestiona conexiones SQL con `with`
* Usa plantillas para correos en vez de concatenación manual
* No expongas credenciales en código
* No uses `mail.exe` si tienes SMTP normal

---

# 📜 Licencia

MIT — Uso libre con atribución.

---

# ✉️ Contacto / Autor

* **Jonathan Bolo**
* Especialista en ingeniería, Python, automatización corporativa
* Perú

---

## 🚀 Roadmap

* 🔐 Módulo SFTP basado en Paramiko (async/transferencias masivas/retry)
* 📦 Zip/Tar inteligente (archivos grandes)
* 🧯 Manejo de excepciones estandarizado
* 📊 Integración de logging estructurado (JSON) para Splunk/ELK

---

# 📎 Ejemplos listos para copiar

> Puedes crear un script `main.py`:

```python
from util_rpa.logging_utils import init_logging
from util_rpa.mail.smtp import SMTPClient
from util_rpa.sql.sqlserver import SQLServer

log = init_logging()

# SQL
db = SQLServer("10.0.0.2", "PRD", "robot", "passwd")
df = db.query("SELECT COUNT(*) registros FROM ventas")
log.info(df)

# Notificación
smtp = SMTPClient("10.10.10.1", port=25)
smtp.send(...)
```

---

# 🛡️ Disclaimer

`util-rpa` es una librería **técnica**.
No se recomienda para UI, web frameworks o interfaces HMI.
Diseñada para **backend operativo, batch y automatización con RPAs**.