Metadata-Version: 2.4
Name: dk-azure-services-dataknow
Version: 0.0.2
Summary: Paquete para facilitar la integración con servicios de Azure
Author-email: Leonar Santiago Castro <leonar.castro@dataknow.co>
License-Expression: MIT
Project-URL: Homepage, https://dev.azure.com/DataKnow/Dataknow%20-%20Repositorio%20General%20de%20Proyectos/_git/dk-azure-services
Project-URL: Documentation, https://dev.azure.com/DataKnow/Dataknow%20-%20Repositorio%20General%20de%20Proyectos/_wiki
Project-URL: Repository, https://dev.azure.com/DataKnow/Dataknow%20-%20Repositorio%20General%20de%20Proyectos/_git/dk-azure-services
Project-URL: Bug Tracker, https://dev.azure.com/DataKnow/Dataknow%20-%20Repositorio%20General%20de%20Proyectos/_workitems
Keywords: azure,cosmos,openai,storage,keyvault
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Database
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: azure-identity[aio]>=1.15.0
Requires-Dist: azure-cosmos>=4.5.0
Requires-Dist: azure-keyvault-secrets>=4.7.0
Requires-Dist: azure-storage-blob>=12.19.0
Requires-Dist: openai>=1.10.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: aiohttp>=3.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "docs"

# DK Azure Services Package

Paquete Python para facilitar la integración con servicios de Azure, proporcionando conectores seguros y fáciles de usar para los principales servicios de Azure.

## Servicios Soportados

- **Azure Cosmos DB** - Base de datos NoSQL distribuida globalmente
- **Azure OpenAI** - Servicios de inteligencia artificial (próximamente)
- **Azure Blob Storage** - Almacenamiento de objetos en la nube (próximamente)
- **Azure Key Vault** - Gestión segura de secretos y certificados

## Características Principales

✅ **Autenticación Centralizada** - Usa `DefaultAzureCredential` para autenticación segura  
✅ **Configuración por Entornos** - Soporte para múltiples entornos (dev, prod, etc.)  
✅ **Gestión de Secretos** - Integración automática con Azure Key Vault  
✅ **Manejo de Errores** - Excepciones personalizadas para mejor debugging  
✅ **Documentación Completa** - Docstrings en español  
✅ **Type Hints** - Compatibilidad completa con tipado estático  
🚀 **100% Asíncrono** - Operaciones concurrentes de alto rendimiento por defecto  
⚡ **Operaciones Bulk** - Procesamiento masivo optimizado (10-50x más rápido)  
🔧 **Context Managers** - Gestión automática de recursos  
🎯 **API Simple** - Una sola forma de hacer las cosas, bien hecha  

## Instalación

```bash
pip install dk-azure-services
```

### Instalación para Desarrollo

```bash
git clone https://github.com/yourusername/dk-azure-services.git
cd dk-azure-services
pip install -e .[dev]
```

## Uso Rápido

### Cliente Simplificado (AsyncCosmosDBClient)

```python
import asyncio
from dk_azure_services.cosmos import AsyncCosmosDBClient
from dotenv import load_dotenv

# Requieres tu archivo .env con la variable de entorno: KEY_VAULT_NAME=your-key-vault-name
# En tu Key Vault requieres los secretos:
# cosmos-uri="your-cosmos-uri"
# cosmos-key=your-cosmos-key


load_dotenv(override=True)

async def main():
    async with AsyncCosmosDBClient(partition_key_path="/partition_key") as client:
        # Crear una base de datos
        await client.create_database("mi_base_de_datos")

        # Crear un contenedor
        await client.create_container("mi_base_de_datos", "mi_contenedor", "/partition_key")

        # Crear un documento
        documento = {"id": "user123", "name": "Juan", "role": "Developer", "partition_key": "user123"}
        await client.create_document("mi_base_de_datos", "mi_contenedor", documento)

        # Leer un documento
        doc = await client.read_document("mi_base_de_datos", "mi_contenedor", "user123", partition_key="user123")
        print("Documento leído:", doc)

asyncio.run(main())
```

---

## Ejemplo Avanzado: Clientes Especializados

Puedes usar clientes especializados para un control más granular sobre bases de datos, contenedores y documentos.

```python
import asyncio
from dk_azure_services.cosmos.database_manager import AsyncDatabaseManager
from dk_azure_services.cosmos.container_manager import AsyncContainerManager
from dk_azure_services.cosmos.documents_manager import AsyncDocumentsManager

async def main():
    # Crear base de datos
    db_manager = AsyncDatabaseManager(environment="dev")
    await db_manager.create_database("ejemplo_db")

    # Crear contenedor
    container_manager = AsyncContainerManager(environment="dev")
    await container_manager.create_container_simple(
        database_name="ejemplo_db",
        container_name="ejemplo_contenedor",
        partition_key_path="/partition_key"
    )

    # Crear documento
    client = AsyncDocumentsManager(environment="dev")
    doc = {"id": "user1", "nombre": "Ana", "edad": 28, "partition_key": "user1"}
    await client.create_document(doc, "ejemplo_db", "ejemplo_contenedor", partition_key="user1")

    # Consultar documentos
    docs = await client.query_documents(
        "SELECT * FROM c WHERE c.edad >= @edad",
        [{"name": "@edad", "value": 18}],
        database_name="ejemplo_db",
        container_name="ejemplo_contenedor"
    )
    print("Documentos encontrados:", docs)

    # Cerrar conexiones
    await client.close()
    await container_manager.close()
    await db_manager.close()

asyncio.run(main())
```

> **Nota:** Puedes encontrar ejemplos completos y scripts de prueba en la carpeta `examples/02_cosmos` del repositorio.

---

## Configuración

### 🎯 **Variables Estandarizadas Entre Ambientes**

✅ **Mismos nombres** en DEV y PROD  
✅ **Solo cambian** valores y Key Vault  
✅ **Deployment simplificado**

El paquete busca la configuración en este orden:

1. **Variables de entorno** (ej: `COSMOS_URI`)
2. **Azure Key Vault** (ej: `cosmos-uri`)
3. **Valor por defecto**

### Variables de Entorno (Desarrollo Local)

#### Configuración Estándar:
```bash
# Variables sin prefijo de ambiente
COSMOS_URI=https://your-cosmos-dev.documents.azure.com:443/
COSMOS_KEY=your-cosmos-dev-key
COSMOS_DATABASE=myapp-dev
COSMOS_CONTAINER=documents
COSMOS_PARTITION=/id

# Configuración del entorno
APP_ENV=dev
KEY_VAULT_NAME=your-keyvault-dev
```

### Azure Key Vault (Producción)

#### Secretos por Ambiente:

**DESARROLLO** - Key Vault: `your-keyvault-dev`
- `cosmos-uri`
- `cosmos-key`
- `cosmos-database`
- `cosmos-container`

**PRODUCCIÓN** - Key Vault: `your-keyvault-prod`
- `cosmos-uri` (mismos nombres!)
- `cosmos-key`
- `cosmos-database`
- `cosmos-container`

> 🔄 **Para cambiar ambiente**: Solo actualiza `KEY_VAULT_NAME=your-keyvault-prod`

## Autenticación con Azure

El paquete utiliza `DefaultAzureCredential` que soporta múltiples métodos:

- ✅ Azure CLI (`az login`)
- ✅ Visual Studio Code
- ✅ Managed Identity (en Azure)
- ✅ Variables de entorno
- ✅ Interactive browser

### Configurar Azure CLI (Recomendado para desarrollo)

```bash
az login
```

## Estructura del Proyecto

```
dk_azure_services/
├── __init__.py              # Exportaciones principales
├── common/                  # Utilidades compartidas
│   ├── auth.py             # Autenticación centralizada
│   ├── config.py           # Gestión de configuración
│   └── exceptions.py       # Excepciones personalizadas
├── cosmos/                  # Azure Cosmos DB
│   ├── __init__.py
│   └── client.py           # Cliente principal
├── openai/                  # Azure OpenAI (próximamente)
├── storage/                 # Azure Blob Storage (próximamente)
└── keyvault/               # Azure Key Vault (próximamente)
```

## Ejemplos Avanzados

### Uso con ConfigManager Personalizado

```python
from dk_azure_services.common.config import ConfigManager
from dk_azure_services import CosmosDBClient

# Configuración personalizada
config = ConfigManager(environment="production", key_vault_name="my-vault")
client = CosmosDBClient(config_manager=config)
```

### Operaciones en Lote

```python
# Crear múltiples documentos
documentos = [
    {"id": "user1", "name": "Ana", "role": "Manager"},
    {"id": "user2", "name": "Carlos", "role": "Developer"},
    {"id": "user3", "name": "María", "role": "Designer"}
]

resultados = client.bulk_create_documents(documentos)
print(f"Creados {len(resultados)} documentos")
```

### Información del Contenedor

```python
info = client.get_container_info()
print(f"Entorno: {info['environment']}")
print(f"Base de datos: {info['database_name']}")
print(f"Contenedor: {info['container_name']}")
```

## Desarrollo

### Configurar Entorno de Desarrollo

```bash
# Clonar el repositorio
git clone https://github.com/yourusername/dk-azure-services.git
cd dk-azure-services

# Instalar dependencias de desarrollo
pip install -e .[dev]

# Configurar pre-commit hooks
pre-commit install
```

### Ejecutar Tests

```bash
pytest
```

### Formatear Código

```bash
black dk_azure_services/
isort dk_azure_services/
```

### Verificar Tipado

```bash
mypy dk_azure_services/
```

## ¿Por qué 100% Asíncrono? 🤔

Este paquete fue diseñado desde cero para ser **completamente asíncrono** por estas razones:

### **🎯 Rendimiento Superior**
- **10-50x más rápido** para operaciones en lote
- **Concurrencia nativa** - múltiples operaciones simultáneas
- **Eficiencia de recursos** - menos uso de CPU y memoria

### **🚀 Ideal para Servicios de Azure**
- **Azure Cosmos DB** - Base de datos distribuida (I/O intensivo)
- **Azure OpenAI** - Llamadas a LLMs con alta latencia
- **Azure Blob Storage** - Transferencia de archivos grandes
- **Azure Key Vault** - Operaciones de red para secretos

### **📱 Perfecto para Apps Modernas**
- **FastAPI** - Framework asíncrono por excelencia  
- **Starlette** - Base asíncrona sólida
- **Microservicios** - Escalabilidad superior
- **APIs REST** - Mejor throughput

### **🧠 API Más Simple**
- **Una sola forma** de hacer las cosas (bien hecha)
- **Context managers** automáticos
- **Menos decisiones** que tomar al desarrollar

> 💡 **Tip**: Si necesitas compatibilidad síncrona, puedes usar `asyncio.run()` o bibliotecas como `asgiref.sync.sync_to_async()`.

## Roadmap

- [x] Azure Cosmos DB - Cliente asíncrono completo
- [ ] Azure OpenAI - Cliente para chat y embeddings
- [ ] Azure Blob Storage - Cliente para almacenamiento
- [ ] Azure Key Vault - Cliente extendido
- [ ] Azure Service Bus - Mensajería
- [ ] Ejemplos con FastAPI
- [ ] Template de Docker
- [ ] CI/CD con GitHub Actions

## Contribuir

Las contribuciones son bienvenidas. Por favor:

1. Fork el proyecto
2. Crea una branch para tu feature (`git checkout -b feature/amazing-feature`)
3. Commit tus cambios (`git commit -m 'feat: add amazing feature'`)
4. Push a la branch (`git push origin feature/amazing-feature`)
5. Abre un Pull Request

## Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo `LICENSE` para más detalles.

## Autor

**Leonar Santiago Castro** - *Desarrollo inicial* - [GitHub](https://github.com/yourusername)

## Agradecimientos

- Equipo de Azure SDK para Python
- Comunidad de desarrolladores de Azure
- Contribuidores del proyecto 
