Metadata-Version: 2.4
Name: utils-oci
Version: 0.1.0
Summary: Librería de utilidades para Oracle Cloud Infrastructure (OCI)
Project-URL: Homepage, https://bitbucket.org/entel_fuentes/utils_oci_lib
Project-URL: Repository, https://bitbucket.org/entel_fuentes/utils_oci_lib
Project-URL: Issues, https://bitbucket.org/entel_fuentes/utils_oci_lib/issues
Author-email: Rodolfo Núñez <rununez@entel.cl>, Christian Cómena <christian.comena@entel.pe>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: black>=24.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# Utils OCI - Librería de Utilidades para Oracle Cloud Infrastructure

Una librería Python con funciones utilitarias para trabajar con Oracle Cloud Infrastructure (OCI), incluyendo conexiones, SQL endpoints, y más.

## 🚀 Instalación

### 📦 Método 1: Instalación Directa desde Git (Recomendado)

La forma más sencilla de usar esta librería en tus proyectos es instalarla directamente desde el repositorio Git.

#### Opción A: Con `requirements.txt`

Agrega esta línea a tu archivo `requirements.txt`:

```txt
git+https://bitbucket.org/entel_fuentes/utils_oci_lib.git
```

Luego instala:
```bash
pip install -r requirements.txt
```

#### Opción B: Con `pyproject.toml`

Agrega esta línea en las dependencias de tu `pyproject.toml`:

```toml
[project]
dependencies = [
    "utils-oci @ git+https://bitbucket.org/entel_fuentes/utils_oci_lib.git",
    # ... otras dependencias
]
```

#### Opción C: Instalación Directa con pip

```bash
pip install git+https://bitbucket.org/entel_fuentes/utils_oci_lib.git
```

#### 🏷️ Instalación de Versiones Específicas

```bash
# Versión específica (tag)
pip install git+https://bitbucket.org/entel_fuentes/utils_oci_lib.git@v0.1.0

# Rama específica
pip install git+https://bitbucket.org/entel_fuentes/utils_oci_lib.git@main

# Commit específico
pip install git+https://bitbucket.org/entel_fuentes/utils_oci_lib.git@abc1234

# Al hacer pruebas con la versión de desarrollo y forzando reinstalacion para eviar problemas con cache
pip install --upgrade --force-reinstall --no-cache-dir git+https://bitbucket.org/entel_fuentes/utils_oci_lib.git@dev
```

### 🛠️ Método 2: Instalación Local de Desarrollo

Para desarrollo local o si tienes problemas con pip:

```bash
# Clonar el repositorio
git clone https://bitbucket.org/entel_fuentes/utils_oci_lib.git
cd utils-oci-lib

# Opción A: Instalación estándar
pip install -e .

# Opción B: Si hay problemas con pip (Windows)
python install_library.py
```

## 📖 Uso Básico

### Importar y Usar

```python
# Importar la librería
from utils_oci import hello_world
from utils_oci.core import get_version

# Función de prueba
result = hello_world()
print(result)  # ¡Hola! Utils OCI está funcionando correctamente 🚀

# Verificar versión
version = get_version()
print(f"Versión: {version}")  # Versión: 0.1.0
```

### Ejemplo Completo en Otro Proyecto

1. **Crear `requirements.txt` en tu proyecto:**
```txt
# requirements.txt
requests>=2.25.0
pandas>=1.3.0
git+https://bitbucket.org/entel_fuentes/utils_oci_lib.git
python-dotenv>=0.19.0
```

2. **Instalar dependencias:**
```bash
pip install -r requirements.txt
```

3. **Usar en tu código Python:**
```python
# main.py
from utils_oci import hello_world

def main():
    # Usar funciones de la librería
    result = hello_world()
    print(result)
    
    # Aquí irán tus funciones de OCI
    # connection = oci_connect()
    # endpoint = start_sql_endpoint()

if __name__ == "__main__":
    main()
```

## 🧪 Verificar Instalación

### Script de Prueba Rápida

```python
# test_install.py
try:
    from utils_oci import hello_world
    print("✅ Importación exitosa")
    
    result = hello_world()
    print(f"✅ Función ejecutada: {result}")
    
    print("🎉 ¡Instalación completamente funcional!")
    
except ImportError as e:
    print(f"❌ Error de importación: {e}")
except Exception as e:
    print(f"❌ Error general: {e}")
```

## 📁 Estructura del Proyecto


utils_oci_lib/
├── setup.py                    # Configuración del paquete (legacy)
├── pyproject.toml              # Configuración moderna de Python  
├── requirements.txt            # Dependencias del proyecto
├── LICENSE                     # Licencia MIT
├── MANIFEST.in                 # Archivos a incluir en el paquete
├── README.md                   # Esta documentación
├── Dockerfile                  # Imagen Docker para testing
├── .gitignore                  # Archivos a ignorar en Git
├── bitbucket-pipelines.yml     # CI/CD configuration
│
├── utils_oci/                  # 📦 Librería principal
│   ├── __init__.py             # Hace que sea un paquete importable
│   ├── core.py                 # Funciones principales y versión
│   ├── auth.py                 # 🔐 Autenticación OCI (Config/Instance/Resource Principal)
│   ├── clients.py              # 🔌 Clientes OCI (DataFlow, Object Storage, etc.)
│   ├── compartments.py         # 🗂️  Gestión de compartments
│   ├── container_instances.py  # 🐳 Gestión de Container Instances
│   ├── sqle.py                 # 💾 SQL Endpoints y conexiones JDBC
│   └── logger_config.py        # 📝 Configuración de logging
│
├── tests/                      # 🧪 Tests unitarios e integración
│   ├── __init__.py
│   ├── test_basic.py           # Tests básicos de importación
│   ├── test_auth_*.py          # Tests de autenticación
│   ├── test_logger_*.py        # Tests de logging
│   ├── test_connect_sqle.py    # Tests de conexión SQL Endpoint
│   ├── test_integration.py     # Tests de integración
│   ├── test_git_install.py     # Tests de instalación desde Git
│   └── test_from_outside.py    # Tests externos
│
├── docs/                       # 📚 Documentación adicional
│   └── EJEMPLO_CONNECT_SQLE.md # Ejemplos de conexión SQLE
│
├── archivos_de_ejemplo/        # 📋 Ejemplos de uso
│   ├── example_usage.py
│   ├── pyproject_example.toml
│   └── requirements_example.txt
│
├── airflow_dags/               # ✈️ DAGs de ejemplo para Airflow
│   └── test_DAG_airflow.py
│
├── test_de_libreria_en_CI/     # 🔬 Testing en CI/CD
│   ├── build_docker.sh
│   ├── requirements.txt
│   └── test_utils_oci.py
│
└── sandbox/                    # 🏖️ Archivos de desarrollo
    ├── install_library.py      # Instalación manual (fallback)
    └── setup.py                # Setup alternativo
```

### 📦 Módulos Principales

#### 🔐 `auth.py`
- Autenticación multi-método (Config file, Instance Principal, Resource Principal)
- Detección automática del método de autenticación
- Signers para diferentes contextos de ejecución

#### 🔌 `clients.py`
- Factory de clientes OCI pre-configurados
- `get_dataflow_client()`: Cliente para DataFlow y SQL Endpoints
- `get_object_storage_client()`: Cliente para Object Storage (buckets)
- Gestión automática de autenticación

#### 🗂️ `compartments.py`
- Validación de compartments
- Gestión de recursos por compartment

#### 🐳 `container_instances.py`
- Gestión de Container Instances
- Ejecución de jobs en contenedores
- Monitoreo de logs en tiempo real

#### 💾 `sqle.py`
- Gestión de SQL Endpoints (start, stop, status)
- Conexión JDBC a SQL Endpoints
- Soporte automático para Resource/Instance Principal

#### 📝 `logger_config.py`
- Configuración centralizada de logging
- Formateo consistente de logs
- Integración con sistemas de logging externos

## 🔄 Actualización de la Librería

### Actualizar a la Última Versión

```bash
# Desinstalar versión actual
pip uninstall utils-oci

# Reinstalar última versión
pip install git+https://bitbucket.org/entel_fuentes/utils_oci_lib.git
```

### Actualizar con pip

```bash
pip install --upgrade git+https://bitbucket.org/entel_fuentes/utils_oci_lib.git
```

## 🔧 CI/CD con Bitbucket Pipelines

### ¿Qué es bitbucket-pipelines.yml?

El archivo `bitbucket-pipelines.yml` configura la integración y despliegue continuo (CI/CD) para tu librería en Bitbucket. Automatiza las siguientes tareas:

- ✅ **Pruebas automáticas** en cada push y pull request
- ✅ **Verificación de instalación** desde Git
- ✅ **Testing en múltiples versiones de Python** (3.8, 3.9, 3.10, 3.11)
- ✅ **Validación de código** con herramientas de calidad

### Cómo Funciona

1. **Activación automática**: Se ejecuta en cada `git push` y pull request
2. **Testing paralelo**: Prueba en diferentes versiones de Python simultáneamente
3. **Instalación**: Verifica que la librería se instale correctamente desde Git
4. **Pruebas**: Ejecuta todos los tests en la carpeta `tests/`

### Configuración en Bitbucket

Para habilitar Bitbucket Pipelines en tu repositorio:

1. **Ir a tu repositorio en Bitbucket**
2. **Navegar a**: `Repository settings` → `Pipelines` → `Settings`
3. **Habilitar**: "Enable Pipelines"
4. **Confirmar**: El archivo `bitbucket-pipelines.yml` se detectará automáticamente

### Estados del Pipeline

- 🟢 **Verde (Éxito)**: Todas las pruebas pasan, librería lista para usar
- 🔴 **Rojo (Fallo)**: Hay errores que necesitan corrección
- 🟡 **Amarillo (En progreso)**: Pipeline ejecutándose

### Ver Resultados

- **En Bitbucket**: Ve a `Pipelines` en la barra lateral de tu repositorio
- **En commits**: Verás el estado del pipeline junto a cada commit
- **En Pull Requests**: El estado aparece antes de hacer merge

### Beneficios

✅ **Detección temprana**: Encuentra errores antes de que lleguen a producción  
✅ **Calidad garantizada**: Solo código que pasa pruebas llega a main  
✅ **Colaboración segura**: Pull requests se validan automáticamente  
✅ **Documentación viva**: Los tests sirven como ejemplos de uso

### Personalizar el Pipeline

Para modificar el comportamiento, edita `bitbucket-pipelines.yml`:

```yaml
# Agregar más versiones de Python
- step:
    name: Test Python 3.12
    image: python:3.12
    
# Agregar herramientas de análisis
- pip install black flake8
- black --check .
- flake8 .

# Agregar tests de integración
- python tests/integration_tests.py
```

## 🔧 Para Desarrolladores

### Configuración del Repositorio

1. **Actualiza información del autor:**
   - Edita `setup.py` y `pyproject.toml`
   - Cambia "Tu Nombre" y email por tu información real

2. **Publica en GitHub:**
   ```bash
   git init
   git add .
   git commit -m "Initial commit: Utils OCI library"
   git remote add origin https://bitbucket.org/entel_fuentes/utils_oci_lib.git
   git push -u origin main
   ```

### Crear Nuevas Versiones (Tags)

```bash
# Crear tag para nueva versión
git tag v0.1.0
git push origin v0.1.0

# Los usuarios podrán instalar esta versión específica:
# pip install git+https://bitbucket.org/entel_fuentes/utils_oci_lib.git@v0.1.0
```

## 🐛 Solución de Problemas

### Error: "No module named 'utils_oci'"

**Causa:** La librería no se instaló correctamente desde Git.

**Solución:**
```bash
# Verificar instalación
pip list | grep utils-oci

# Si no aparece, reinstalar
pip install git+https://bitbucket.org/entel_fuentes/utils_oci_lib.git
```

### Error: "Permission denied" en Git

**Causa:** Problemas de autenticación con GitHub.

**Solución:**
```bash
# Usar HTTPS en lugar de SSH
pip install git+https://bitbucket.org/entel_fuentes/utils_oci_lib.git

# Si el repositorio es privado, usar token personal:
pip install git+https://TOKEN@github.com/entel_fuentes/utils_oci_lib.git
```

### Error: "Could not find a version"

**Causa:** URL del repositorio incorrecta o repositorio no existe.

**Solución:**
1. Verificar que el repositorio existe en GitHub
2. Comprobar que la URL es correcta
3. Verificar que el repositorio es público o tienes acceso

## 🎯 Ventajas de Este Método

✅ **Una sola línea**: Solo agregar al `requirements.txt` o `pyproject.toml`  
✅ **Actualización automática**: `pip install --upgrade` funciona  
✅ **Compatible con pipenv, poetry, conda**: Funciona con todos los gestores  
✅ **Versionado**: Puedes especificar tags, ramas o commits específicos  
✅ **CI/CD friendly**: Funciona en contenedores y pipelines  
✅ **Sin configuración extra**: No requiere configuración adicional en proyectos

## 📝 Próximas Funciones

- ✅ Función hello_world (implementada)
- ✅ Instalación desde Git (implementada)
- 🔄 Conexiones a OCI
- 🔄 Manejo de SQL endpoints
- 🔄 Funciones de autenticación
- 🔄 Utilidades de configuración

---

**¿Problemas?** Consulta la sección "Solución de Problemas" o crea un issue en el repositorio.