> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/learn-the-platform/es/modulo-8-desarrollador-y-devops/02-python-sdk.md).

# SDK de Python (pyvergeos)

La **pyvergeos** El SDK proporciona una interfaz de estilo Python, con anotaciones de tipo, para toda la API REST de VergeOS. En lugar de crear solicitudes HTTP en bruto, trabajas con **gestores de recursos** — `client.vms`, `client.networks`, `client.tenants` — que se asignan directamente a objetos de VergeOS. El SDK se encarga de la autenticación, la paginación, los reintentos y el sondeo de tareas asíncronas para que tus scripts de automatización se mantengan limpios y centrados en la lógica de negocio.

## Requisitos e instalación

**Requisitos previos:**

* **Python 3.9** o superior
* **VergeOS 26.0** o superior
* Funciona en **Windows, macOS y Linux**

**Instalar desde PyPI (recomendado):**

```bash
pip install pyvergeos
```

**O con uv (alternativa más rápida):**

```bash
uv add pyvergeos
```

**Desde el código fuente (desarrollo):**

```bash
git clone https://github.com/verge-io/pyvergeos.git
cd pyvergeos
pip install .
```

## Autenticación

El SDK admite tres métodos de autenticación, cada uno adecuado para distintos entornos.

### Nombre de usuario y contraseña

La forma más simple para scripts interactivos y desarrollo:

```python
from pyvergeos import VergeClient

client = VergeClient(
    host="192.168.1.100",
    username="admin",
    password="secret",
    verify_ssl=False  # Solo para certificados autofirmados
)
```

### Token de API

Para automatización en producción cuando ya tienes una clave API generada previamente:

```python
client = VergeClient(
    host="192.168.1.100",
    token="your-api-token"
)
```

### Variables de entorno

La forma recomendada para producción — mantiene las credenciales fuera del código fuente:

```bash
export VERGE_HOST=192.168.1.100
export VERGE_USERNAME=admin
export VERGE_PASSWORD=secret
export VERGE_VERIFY_SSL=false      # Opcional
export VERGE_TIMEOUT=30            # Opcional
export VERGE_RETRY_TOTAL=3         # Opcional
export VERGE_RETRY_BACKOFF=1       # Opcional
```

```python
client = VergeClient.from_env()
```

### Gestor de contexto

Usa siempre el gestor de contexto en el código de producción para garantizar que las conexiones se cierren correctamente, incluso cuando ocurran excepciones:

```python
with VergeClient(host="192.168.1.100", token="api-token") as client:
    vms = client.vms.list()
    for vm in vms:
        print(f"{vm.name}: {vm.ram} MB de RAM")
# La conexión se cierra automáticamente aquí
```

## Gestores de recursos

Cada tipo de recurso de VergeOS se expone a través de un **gestor de recursos** en el objeto cliente. Cada gestor proporciona métodos coherentes `list()`, `get()`, `create()`y métodos de acción.

### Máquinas virtuales

`client.vms` — Crea, configura, controla la energía, clona, toma instantáneas y administra discos/NICs para las VM.

### Redes

`client.networks` — Redes virtuales, reglas de firewall, DHCP, DNS y control de energía de la red.

### Inquilinos

`client.tenants` — Aprovisionamiento multi-tenant, aislamiento de recursos, instantáneas, bloques de almacenamiento y bloques de red.

### NAS y almacenamiento

`client.nas` — Servicios NAS, volúmenes, comparticiones CIFS/NFS y sincronización de volúmenes.

### Recuperación ante desastres

`client.dr` — Instantáneas en la nube, sincronización de sitios y flujos de recuperación.

### Usuarios y grupos

`client.users` — Cuentas de usuario, grupos, permisos y gestión de claves API.

### Tareas y monitorización

`client.tasks` — Seguimiento asíncrono de tareas, espera y tiempos de espera. También: alarmas y registros.

### Sistema y GPU

`client.clusters`, `client.nodes`, `client.gpu` — Información de clústeres/nodos, niveles de almacenamiento y gestión de dispositivos GPU.

### Tabla completa de recursos

| Categoría                                             | Recursos disponibles                                                                  |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------- |
| **Máquinas virtuales**                                | VM, discos, NIC, instantáneas                                                         |
| **Redes**                                             | Redes, reglas de firewall, DNS, DHCP, alias, hosts                                    |
| **VPN**                                               | Conexiones IPSec, interfaces WireGuard y peers                                        |
| **NAS/Almacenamiento**                                | Servicios NAS, volúmenes, comparticiones CIFS/NFS, sincronizaciones de volúmenes      |
| **Inquilinos**                                        | Gestión de tenants, instantáneas, bloques de almacenamiento, bloques de red           |
| **Usuarios y grupos**                                 | Usuarios, grupos, permisos, claves API                                                |
| **Sistema**                                           | Clústeres, nodos, niveles de almacenamiento, certificados                             |
| **Supervisión**                                       | Alarmas, registros, tareas                                                            |
| **Copias de seguridad y recuperación ante desastres** | Perfiles de instantáneas, instantáneas en la nube, sitios, sincronizaciones de sitios |

## Filtrado de recursos

El SDK ofrece tres enfoques para filtrar recursos, desde argumentos de palabra clave simples hasta un generador completo de filtros OData.

### Argumentos de palabra clave

La forma más simple para filtros básicos: pasa directamente los nombres de los campos:

```python
# Encontrar todas las VM Linux en ejecución
vms = client.vms.list(status="running", os_family="linux")

# Coincidencia con comodines
vms = client.vms.list(name="prod-*")
```

### Cadenas de filtro OData

Para consultas complejas, pasa expresiones de filtro OData en bruto:

```python
# Combinar condiciones con operadores
vms = client.vms.list(filter="os_family eq 'linux' and ram gt 2048")
```

### Generador de filtros (API fluida)

Construye filtros programáticamente con seguridad de tipos y autocompletado:

```python
from pyvergeos import Filter

# Encadenamiento fluido con métodos de operador
f = Filter().eq("os_family", "linux").and_().gt("ram", 2048)
vms = client.vms.list(filter=str(f))
```

**Operadores de filtro disponibles:**

| Método    | Operador OData | Ejemplo                               |
| --------- | -------------- | ------------------------------------- |
| `.eq()`   | `eq`           | `Filter().eq("status", "running")`    |
| `.ne()`   | `ne`           | `Filter().ne("os_family", "windows")` |
| `.gt()`   | `gt`           | `Filter().gt("ram", 4096)`            |
| `.lt()`   | `lt`           | `Filter().lt("cpu_cores", 8)`         |
| `.ge()`   | `ge`           | `Filter().ge("ram", 2048)`            |
| `.le()`   | `le`           | `Filter().le("ram", 8192)`            |
| `.and_()` | `y`            | Encadena varias condiciones           |
| `.or_()`  | `o`            | Combina condiciones alternativas      |

## Gestión de tareas asíncronas

Muchas operaciones de VergeOS — instantáneas, clones, migraciones — se ejecutan **asíncronamente** y devuelven un ID de tarea de inmediato. El SDK proporciona un gestor de tareas para consultar la finalización:

```python
# La instantánea devuelve una referencia de tarea
result = vm.snapshot(retention=86400, quiesce=True)

# Esperar a que la instantánea se complete (bloquea hasta 300 segundos)
task = client.tasks.wait(result["task"], timeout=300)
print(f"Instantánea completada: {task}")
```

Si la tarea no se completa dentro del tiempo de espera, se `TaskTimeoutError` lanza con la `task_id` propiedad para que puedas comprobar el estado más tarde:

```python
from pyvergeos import TaskTimeoutError

try:
    task = client.tasks.wait(task_id, timeout=60)
except TaskTimeoutError as e:
    print(f"La tarea {e.task_id} sigue en ejecución — compruébalo más tarde")
```

## Manejo de errores

El SDK proporciona una jerarquía estructurada de excepciones para que puedas capturar modos de fallo específicos:

| Excepción             | Descripción                                                               |
| --------------------- | ------------------------------------------------------------------------- |
| `VergeError`          | Excepción base para todos los errores del SDK                             |
| `AuthenticationError` | Credenciales inválidas o token caducado                                   |
| `NotFoundError`       | El recurso solicitado no existe                                           |
| `ConflictError`       | Conflicto de estado del recurso (por ejemplo, la VM ya está en ejecución) |
| `ValidationError`     | Valores de parámetros no válidos                                          |
| `TaskTimeoutError`    | La tarea no se completó dentro del tiempo de espera                       |
| `TaskError`           | La tarea falló durante la ejecución                                       |

```python
from pyvergeos import NotFoundError, AuthenticationError

try:
    vm = client.vms.get(name="nonexistent-vm")
except NotFoundError:
    print("VM no encontrada — comprueba el nombre")
except AuthenticationError:
    print("La autenticación falló — verifica las credenciales")
```

## Configuración de reintentos

El SDK reintenta automáticamente los errores transitorios (HTTP 429, 500, 502, 503, 504) con retroceso exponencial:

```python
client = VergeClient(
    host="192.168.1.100",
    token="api-token",
    retry_total=5,            # Máximo de intentos de reintento (predeterminado: 3)
    retry_backoff_factor=2,   # Multiplicador de retroceso (predeterminado: 1)
)
```

Establece `retry_total=0` para desactivar por completo los reintentos en operaciones sensibles al tiempo.

## Cambio de contexto de tenant

pyvergeos puede **conectarse a contextos de tenant** desde el sistema anfitrión, lo que permite scripts de automatización centralizados que gestionan recursos en varios tenants:

```python
# Obtener un tenant desde el sistema anfitrión
tenant = client.tenants.get(name="customer-a")

# Conectarse al contexto del tenant
tenant_client = tenant.connect()

# Ahora administrar recursos DENTRO del tenant
tenant_vms = tenant_client.vms.list()
for vm in tenant_vms:
    print(f"VM del tenant: {vm.name}")

# Crear una red dentro del tenant
tenant_client.networks.create(
    name="tenant-app-net",
    network_address="10.50.1.0/24",
    ip_address="10.50.1.1",
    dhcp_enabled=True
)
```

Esto es especialmente valioso para **MSPs y proveedores de servicios** que necesitan automatizar el aprovisionamiento en docenas o cientos de entornos de tenant desde un único script.

## Ejemplos prácticos

### Gestión del ciclo de vida de las VM

```python
with VergeClient.from_env() as client:
    # Crear una nueva VM
    vm = client.vms.create(
        name="web-server-01",
        ram=4096,
        cpu_cores=2,
        os_family="linux"
    )

    # Añadir una unidad de datos de 50 GB
    vm.drives.add(name="data", size=50 * 1024 * 1024 * 1024)

    # Conectar a una red
    network = client.networks.get(name="app-network")
    vm.nics.add(network=network.key)

    # Encender
    vm.power_on()
    print(f"La VM {vm.name} está en ejecución")
```

### Red con reglas de firewall

```python
with VergeClient.from_env() as client:
    # Crear una red
    network = client.networks.create(
        name="web-tier",
        network_address="10.20.1.0/24",
        ip_address="10.20.1.1",
        dhcp_enabled=True
    )
    network.power_on()

    # Agregar reglas de firewall
    network.rules.create(
        name="Permitir HTTPS",
        action="accept",
        protocol="tcp",
        dest_port=443
    )
    network.rules.create(
        name="Permitir SSH",
        action="accept",
        protocol="tcp",
        dest_port=22
    )
    network.apply_rules()
```

### Operaciones masivas con filtrado

```python
with VergeClient.from_env() as client:
    # Crear una instantánea de todas las VM de producción en ejecución
    prod_vms = client.vms.list(name="prod-*", status="running")

    for vm in prod_vms:
        result = vm.snapshot(retention=86400, quiesce=True)
        task = client.tasks.wait(result["task"], timeout=300)
        print(f"Se creó una instantánea de {vm.name}")
```

### Informe de inventario multi-tenant

```python
with VergeClient.from_env() as client:
    for tenant in client.tenants.list():
        tenant_client = tenant.connect()
        vms = tenant_client.vms.list()
        print(f"\n--- {tenant.name} ---")
        for vm in vms:
            print(f"  {vm.name}: {vm.ram} MB de RAM, {vm.cpu_cores} núcleos")
```

## Notas importantes

{% hint style="warning" %}
**Seguridad en subprocesos**

El cliente pyvergeos **no es seguro para subprocesos**. Si necesitas operaciones concurrentes, crea instancias separadas de `VergeClient` para cada subproceso. Para cargas de trabajo verdaderamente paralelas, considera el **govergeos** SDK de Go, diseñado para su uso concurrente con goroutines.
{% endhint %}

{% hint style="info" %}
**¿Vienes de VMware o Nutanix?**

pyvergeos expone tres patrones que conviene conocer de entrada:

* **Filtrado** — un `Filter()` fluido genera expresiones de estilo OData (`.eq()`, `.gt()`, `.and_()`, `.or_()`), o puedes pasar una cadena OData en bruto a `list(filter=...)`.
* **Sondeo de tareas** — las operaciones asíncronas devuelven una referencia de tarea; `client.tasks.wait(task_id, timeout=...)` bloquea hasta completarse y lanza `TaskTimeoutError` si se agota el tiempo.
* **Contexto de tenant** — `tenant.connect()` devuelve un cliente con ámbito dentro del tenant, de modo que el mismo script pueda controlar el sistema anfitrión y cualquier tenant hijo sin volver a conectarse a otro extremo.
  {% endhint %}

## Recursos adicionales

* [Repositorio de GitHub](https://github.com/verge-io/pyvergeos) — Código fuente, incidencias y contribuciones
* [Paquete de PyPI](https://pypi.org/project/pyvergeos/) — Última versión e historial de versiones
* [Documentación de la API de VergeOS](/knowledge-base/es/automation-api/verge-api-guide.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/learn-the-platform/es/modulo-8-desarrollador-y-devops/02-python-sdk.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.