> 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/automate-protect-and-extend/es/integraciones-y-api/python-sdk.md).

# SDK de VergeOS para Python (pyvergeos)

## Descripción general

pyvergeos es un SDK de Python para gestionar la infraestructura de VergeOS a través de la API REST. Proporciona una interfaz anotada de tipos y con estilo Python para automatizar el ciclo de vida de las VM, la red, el almacenamiento, las operaciones multiinquilino y los flujos de trabajo de recuperación ante desastres, lo que lo hace ideal para scripts de automatización, desarrollo de herramientas e integraciones.

## Características clave

* **Gestión de VM**: Creación, configuración, control de energía, clonación e instantáneas
* **Redes avanzadas**: Redes virtuales, reglas de firewall, DHCP, DNS, VPN IPSec y WireGuard
* **NAS y almacenamiento**: Administración de volúmenes, recursos compartidos CIFS/NFS y sincronización
* **Multitenencia**: Aprovisionamiento de inquilinos con aislamiento de recursos
* **Recuperación ante desastres**: Instantáneas en la nube, sincronización de sitios y flujos de trabajo de recuperación
* **Filtrado**: Compatibilidad con filtros OData mediante una API fluida de construcción de filtros
* **Anotaciones de tipos**: Pistas de tipo completas para el autocompletado del IDE y el análisis estático
* **Multiplataforma**: Compatibilidad con Windows, macOS y Linux

## Requisitos

* Python 3.9 o posterior
* VergeOS 26.0 o posterior

## Instalación

### Desde PyPI (recomendado)

```bash
pip install pyvergeos
```

### Usando uv

```bash
uv add pyvergeos
```

### Desde el código fuente

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

## Autenticación

El SDK admite múltiples métodos de autenticación:

### Nombre de usuario/contraseña

```python
from pyvergeos import VergeClient

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

{% hint style="info" %}
**Verificación de certificado SSL**

Establezca `verify_ssl=False` solo para entornos con certificados autofirmados. Para entornos de producción con certificados válidos, omita este parámetro o establézcalo en `True`.
{% endhint %}

### Token de API

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

### Variables de entorno

```bash
export VERGE_HOST=192.168.1.100
export VERGE_USERNAME=admin
export VERGE_PASSWORD=secret
```

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

{% hint style="success" %}
**Recomendado para producción**

Usar variables de entorno mantiene las credenciales fuera de su código fuente y facilita el uso de diferentes credenciales en distintos entornos.
{% endhint %}

### Gestor de contexto

```python
with VergeClient(host="192.168.1.100", token="api-token") as client:
    vms = client.vms.list()
```

{% hint style="success" %}
**Limpieza automática**

Usar el gestor de contexto (`with` instrucción) garantiza que la conexión se cierre correctamente, incluso si ocurre una excepción.
{% endhint %}

## Recursos disponibles

El SDK proporciona acceso a los siguientes recursos de VergeOS:

| Categoría               | Recursos                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------- |
| Máquinas virtuales      | VM, discos, NIC, instantáneas                                                         |
| Redes                   | Redes, reglas, DNS, DHCP, alias, hosts                                                |
| VPN                     | Conexiones IPSec, interfaces y pares de WireGuard                                     |
| NAS/Almacenamiento      | Servicios, volúmenes, recursos compartidos CIFS/NFS, sincronizaciones de volúmenes    |
| Inquilinos              | Administración de inquilinos, instantáneas, almacenamiento, bloques de red            |
| Usuarios y grupos       | Usuarios, grupos, permisos, claves API                                                |
| Sistema                 | Clusters, nodos, niveles de almacenamiento, certificados                              |
| Monitorización          | Alarmas, registros, tareas                                                            |
| Copia de seguridad y DR | Perfiles de instantáneas, instantáneas en la nube, sitios, sincronizaciones de sitios |

## Ejemplos de uso

### Administración de máquinas virtuales

```python
from pyvergeos import VergeClient

client = VergeClient(host="192.168.1.100", username="admin", password="secret")

# Listar todas las VM
for vm in client.vms.list():
    print(f"{vm.name}: {vm.ram}MB RAM, {vm.cpu_cores} cores")

# Obtener una VM específica
vm = client.vms.get(name="web-server")

# Crear una VM
new_vm = client.vms.create(
    name="test-vm",
    ram=2048,
    cpu_cores=2,
    os_family="linux"
)

# Operaciones de energía
vm.power_on()
vm.power_off()
vm.reset()

# Instantáneas
vm.snapshot(retention=86400, quiesce=True)

# Clonar una VM
clone = vm.clone(name="test-clone")

# Agregar discos y NIC
vm.drives.add(name="data", size=50*1024*1024*1024)
vm.nics.add(network=network.key)

client.disconnect()
```

### Creación y administración de redes

```python
# Crear una red virtual
network = client.networks.create(
    name="app-network",
    network_address="10.10.1.0/24",
    ip_address="10.10.1.1",
    dhcp_enabled=True
)

network.power_on()
network.apply_rules()

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

### Recursos de filtrado

El SDK admite múltiples enfoques de filtrado:

{% tabs %}
{% tab title="Argumentos de palabra clave" %}

```python
# Simple y legible para filtros básicos
vms = client.vms.list(status="running", name="prod-*")
```

{% endtab %}

{% tab title="Cadena de filtro OData" %}

```python
# Sintaxis completa de filtro OData para consultas complejas
vms = client.vms.list(filter="os_family eq 'linux' and ram gt 2048")
```

{% endtab %}

{% tab title="Constructor de filtros" %}

```python
# API fluida para construir filtros programáticamente
from pyvergeos import Filter

f = Filter().eq("os_family", "linux").and_().gt("ram", 2048)
vms = client.vms.list(filter=str(f))
```

{% endtab %}
{% endtabs %}

### Espera de tareas

Muchas operaciones en VergeOS se ejecutan de forma asíncrona. Use el administrador de tareas para esperar a que finalicen:

```python
result = vm.snapshot()
task = client.tasks.wait(result["task"], timeout=300)
```

{% hint style="info" %}
**Operaciones asíncronas**

Operaciones como instantáneas, clones y migraciones devuelven inmediatamente un ID de tarea. Use `client.tasks.wait()` para bloquear hasta que la operación se complete.
{% endhint %}

## Manejo de errores

El SDK proporciona tipos de excepción específicos para diferentes condiciones de error:

```python
from pyvergeos import NotFoundError, AuthenticationError, TaskTimeoutError

try:
    vm = client.vms.get(name="nonexistent")
except NotFoundError:
    print("VM no encontrada")

try:
    task = client.tasks.wait(task_id, timeout=60)
except TaskTimeoutError as e:
    print(f"Task {e.task_id} timed out")
```

{% hint style="info" %}
**Tipos de excepción disponibles**
{% endhint %}

| Excepción             | Descripción                                                               |
| --------------------- | ------------------------------------------------------------------------- |
| `VergeError`          | Excepción base para todos los errores del SDK                             |
| `AuthenticationError` | Credenciales no válidas o token expirado                                  |
| `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                                       |

## Casos de uso comunes

* **Automatización de infraestructura**: Aprovisione VMs, redes y almacenamiento mediante programación
* **Integración CI/CD**: Cree y destruya entornos de prueba en los pipelines
* **Monitorización e informes**: Consulte el estado de los recursos y genere informes de inventario
* **Automatización de copias de seguridad**: Programe y administre instantáneas y copias de seguridad en la nube
* **Aprovisionamiento multitenencia**: Automatice la creación de inquilinos y la asignación de recursos

## Documentación y recursos

Para obtener la documentación completa, incluidos todos los métodos disponibles y ejemplos de uso detallados, visite el repositorio oficial:

* [Repositorio de GitHub](https://github.com/verge-io/pyvergeos)
* [Paquete de PyPI](https://pypi.org/project/pyvergeos/)

## Soporte

Si encuentra problemas o tiene solicitudes de funciones, abra un issue en el repositorio de GitHub:

<https://github.com/verge-io/pyvergeos/issues>

## Recursos adicionales

* [Documentación de Python](https://docs.python.org/3/)
* [Documentación de la API de VergeOS](/knowledge-base/es/automation-api/verge-api-guide.md)
* [Módulo de PowerShell PSVergeOS](/automate-protect-and-extend/es/integraciones-y-api/powershell-module.md) - alternativa de PowerShell
* [Proveedor de Terraform](/automate-protect-and-extend/es/integraciones-y-api/terraform-provider.md) - infraestructura como código


---

# 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/automate-protect-and-extend/es/integraciones-y-api/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.