utils-oci 0.1.0

Librería de utilidades para Oracle Cloud Infrastructure (OCI)

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:

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

Luego instala:

pip install -r requirements.txt

Opción B: Con pyproject.toml

Agrega esta línea en las dependencias de tu pyproject.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

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

🏷️ Instalación de Versiones Específicas

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

# 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

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

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

pip install -r requirements.txt

3. Usar en tu código 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

# 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

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:

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

   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)

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

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

# 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://[e-mail]/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.