> 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/de/modul-8-entwicklung-and-devops/02-python-sdk.md).

# Python SDK (pyvergeos)

Das **pyvergeos** Das SDK bietet eine Python-ähnliche, typannotierte Schnittstelle für die gesamte VergeOS-REST-API. Anstatt rohe HTTP-Anfragen zu erstellen, arbeiten Sie mit **Ressourcenmanagern** — `client.vms`, `client.networks`, `client.tenants` — die direkt auf VergeOS-Objekte abgebildet werden. Das SDK übernimmt Authentifizierung, Paginierung, Wiederholungsversuche und das Polling asynchroner Aufgaben, damit Ihre Automatisierungsskripte sauber und auf die Geschäftslogik fokussiert bleiben.

## Voraussetzungen & Installation

**Voraussetzungen:**

* **Python 3.9** oder höher
* **VergeOS 26.0** oder höher
* Läuft auf **Windows, macOS und Linux**

**Installation von PyPI (empfohlen):**

```bash
pip install pyvergeos
```

**Oder mit uv (schnellere Alternative):**

```bash
uv add pyvergeos
```

**Aus dem Quellcode (Entwicklung):**

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

## Authentifizierung

Das SDK unterstützt drei Authentifizierungsmethoden, die jeweils für unterschiedliche Umgebungen geeignet sind.

### Benutzername & Passwort

Der einfachste Ansatz für interaktive Skripte und die Entwicklung:

```python
from pyvergeos import VergeClient

client = VergeClient(
    host="192.168.1.100",
    username="admin",
    password="secret",
    verify_ssl=False  # Nur für selbstsignierte Zertifikate
)
```

### API-Token

Für Produktionsautomatisierung, wenn Sie einen vorab erzeugten API-Schlüssel haben:

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

### Umgebungsvariablen

Der empfohlene Ansatz für die Produktion — hält Zugangsdaten aus dem Quellcode heraus:

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

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

### Kontextmanager

Verwenden Sie in Produktionscode immer den Kontextmanager, um sicherzustellen, dass Verbindungen ordnungsgemäß geschlossen werden, auch wenn Ausnahmen auftreten:

```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 RAM")
# Verbindung wird hier automatisch geschlossen
```

## Ressourcenmanager

Jeder VergeOS-Ressourcentyp wird über einen **Ressourcenmanager** am Client-Objekt bereitgestellt. Jeder Manager bietet konsistente `list()`, `get()`, `create()`- und Aktionsmethoden.

### Virtuelle Maschinen

`client.vms` — VMs erstellen, konfigurieren, ein-/ausschalten, klonen, Snapshots erstellen und Laufwerke/NICs verwalten.

### Netzwerke

`client.networks` — Virtuelle Netzwerke, Firewall-Regeln, DHCP, DNS und Netzwerk-Energieverwaltung.

### Mandanten

`client.tenants` — Mandantenübergreifende Bereitstellung, Ressourcenisolierung, Snapshots, Speicher- und Netzwerkblöcke.

### NAS & Speicher

`client.nas` — NAS-Dienste, Volumes, CIFS/NFS-Freigaben und Volumesynchronisierung.

### Notfallwiederherstellung

`client.dr` — Cloud-Snapshots, Standort-Synchronisierung und Wiederherstellungs-Workflows.

### Benutzer & Gruppen

`client.users` — Benutzerkonten, Gruppen, Berechtigungen und API-Schlüsselverwaltung.

### Aufgaben & Monitoring

`client.tasks` — Verfolgung asynchroner Aufgaben, Warten, Timeouts. Außerdem: Alarme und Protokolle.

### System & GPU

`client.clusters`, `client.nodes`, `client.gpu` — Cluster-/Knoteninformationen, Speicherebenen, GPU-Geräteverwaltung.

### Vollständige Ressourcentabelle

| Kategorie               | Verfügbare Ressourcen                                                     |
| ----------------------- | ------------------------------------------------------------------------- |
| **Virtuelle Maschinen** | VMs, Laufwerke, NICs, Snapshots                                           |
| **Netzwerk**            | Netzwerke, Firewall-Regeln, DNS, DHCP, Aliase, Hosts                      |
| **VPN**                 | IPSec-Verbindungen, WireGuard-Schnittstellen und Peers                    |
| **NAS/Speicher**        | NAS-Dienste, Volumes, CIFS/NFS-Freigaben, Volumesynchronisierungen        |
| **Mandanten**           | Mandantenverwaltung, Snapshots, Speicherblöcke, Netzwerkblöcke            |
| **Benutzer & Gruppen**  | Benutzer, Gruppen, Berechtigungen, API-Schlüssel                          |
| **System**              | Cluster, Knoten, Speicherebenen, Zertifikate                              |
| **Überwachung**         | Alarme, Protokolle, Aufgaben                                              |
| **Backup & DR**         | Snapshot-Profile, Cloud-Snapshots, Standorte, Standort-Synchronisierungen |

## Ressourcen filtern

Das SDK bietet drei Ansätze zum Filtern von Ressourcen, von einfachen Schlüsselwortargumenten bis hin zu einem vollständigen OData-Filter-Builder.

### Schlüsselwortargumente

Der einfachste Ansatz für grundlegende Filter — Feldnamen direkt übergeben:

```python
# Alle laufenden Linux-VMs finden
vms = client.vms.list(status="running", os_family="linux")

# Platzhalterabgleich
vms = client.vms.list(name="prod-*")
```

### OData-Filterzeichenfolgen

Für komplexe Abfragen rohe OData-Filterausdrücke übergeben:

```python
# Bedingungen mit Operatoren kombinieren
vms = client.vms.list(filter="os_family eq 'linux' and ram gt 2048")
```

### Filter-Builder (Fluent API)

Filter programmgesteuert mit Typsicherheit und Autovervollständigung erstellen:

```python
from pyvergeos import Filter

# Fluentes Verkettung mit Operator-Methoden
f = Filter().eq("os_family", "linux").and_().gt("ram", 2048)
vms = client.vms.list(filter=str(f))
```

**Verfügbare Filteroperatoren:**

| Methode   | OData-Operator | Beispiel                              |
| --------- | -------------- | ------------------------------------- |
| `.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_()` | `und`          | Mehrere Bedingungen verketten         |
| `.or_()`  | `oder`         | Alternative Bedingungen kombinieren   |

## Asynchrone Aufgabenverarbeitung

Viele VergeOS-Operationen — Snapshots, Klone, Migrationen — laufen **asynchron** und geben sofort eine Aufgaben-ID zurück. Das SDK stellt einen Aufgabenmanager zum Abfragen des Abschlusses bereit:

```python
# Snapshot gibt einen Aufgabenverweis zurück
result = vm.snapshot(retention=86400, quiesce=True)

# Warten, bis der Snapshot abgeschlossen ist (blockiert bis zu 300 Sekunden)
task = client.tasks.wait(result["task"], timeout=300)
print(f"Snapshot abgeschlossen: {task}")
```

Wenn die Aufgabe innerhalb des Timeouts nicht abgeschlossen wird, wird ein `TaskTimeoutError` ausgelöst, mit der `task_id` -Eigenschaft, damit Sie den Status später prüfen können:

```python
from pyvergeos import TaskTimeoutError

try:
    task = client.tasks.wait(task_id, timeout=60)
except TaskTimeoutError as e:
    print(f"Aufgabe {e.task_id} läuft noch — später erneut prüfen")
```

## Fehlerbehandlung

Das SDK bietet eine strukturierte Ausnahmehierarchie, sodass Sie bestimmte Fehlermodi gezielt abfangen können:

| Exception             | Beschreibung                                             |
| --------------------- | -------------------------------------------------------- |
| `VergeError`          | Basisausnahme für alle SDK-Fehler                        |
| `AuthenticationError` | Ungültige Anmeldedaten oder abgelaufenes Token           |
| `NotFoundError`       | Angeforderte Ressource existiert nicht                   |
| `ConflictError`       | Konflikt im Ressourcenstatus (z. B. VM läuft bereits)    |
| `ValidationError`     | Ungültige Parameterwerte                                 |
| `TaskTimeoutError`    | Aufgabe wurde nicht innerhalb des Timeouts abgeschlossen |
| `TaskError`           | Aufgabe ist während der Ausführung fehlgeschlagen        |

```python
from pyvergeos import NotFoundError, AuthenticationError

try:
    vm = client.vms.get(name="nonexistent-vm")
except NotFoundError:
    print("VM nicht gefunden — Name überprüfen")
except AuthenticationError:
    print("Authentifizierung fehlgeschlagen — Zugangsdaten überprüfen")
```

## Retry-Konfiguration

Das SDK wiederholt vorübergehende Fehler automatisch (HTTP 429, 500, 502, 503, 504) mit exponentiellem Backoff:

```python
client = VergeClient(
    host="192.168.1.100",
    token="api-token",
    retry_total=5,            # Maximale Anzahl von Wiederholungsversuchen (Standard: 3)
    retry_backoff_factor=2,   # Backoff-Multiplikator (Standard: 1)
)
```

Setzen Sie `retry_total=0` um Wiederholungen für zeitkritische Vorgänge vollständig zu deaktivieren.

## Mandanten-Kontextwechsel

pyvergeos kann **in Mandantenkontexte verbinden** vom Host-System aus und ermöglicht zentrale Automatisierungsskripte, die Ressourcen über mehrere Mandanten hinweg verwalten:

```python
# Einen Mandanten aus dem Host-System abrufen
tenant = client.tenants.get(name="customer-a")

# In den Kontext des Mandanten verbinden
tenant_client = tenant.connect()

# Jetzt Ressourcen INNERHALB des Mandanten verwalten
tenant_vms = tenant_client.vms.list()
for vm in tenant_vms:
    print(f"Mandanten-VM: {vm.name}")

# Ein Netzwerk innerhalb des Mandanten erstellen
tenant_client.networks.create(
    name="tenant-app-net",
    network_address="10.50.1.0/24",
    ip_address="10.50.1.1",
    dhcp_enabled=True
)
```

Dies ist besonders wertvoll für **MSPs und Dienstanbieter** die die Bereitstellung über Dutzende oder Hunderte von Mandantenumgebungen mit einem einzigen Skript automatisieren müssen.

## Praktische Beispiele

### Verwaltung des VM-Lebenszyklus

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

    # Ein 50-GB-Datenlaufwerk hinzufügen
    vm.drives.add(name="data", size=50 * 1024 * 1024 * 1024)

    # Mit einem Netzwerk verbinden
    network = client.networks.get(name="app-network")
    vm.nics.add(network=network.key)

    # Einschalten
    vm.power_on()
    print(f"VM {vm.name} läuft")
```

### Netzwerk mit Firewall-Regeln

```python
with VergeClient.from_env() as client:
    # Ein Netzwerk erstellen
    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()

    # Firewall-Regeln hinzufügen
    network.rules.create(
        name="HTTPS zulassen",
        action="accept",
        protocol="tcp",
        dest_port=443
    )
    network.rules.create(
        name="SSH zulassen",
        action="accept",
        protocol="tcp",
        dest_port=22
    )
    network.apply_rules()
```

### Massenoperationen mit Filterung

```python
with VergeClient.from_env() as client:
    # Alle laufenden Produktions-VMs snapshotten
    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"Snapshot für {vm.name} erstellt")
```

### Mandantenübergreifender Inventarbericht

```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 RAM, {vm.cpu_cores} Kerne")
```

## Wichtige Hinweise

{% hint style="warning" %}
**Thread-Sicherheit**

Der pyvergeos-Client ist **nicht threadsicher**. Wenn Sie parallele Vorgänge benötigen, erstellen Sie separate `VergeClient` -Instanzen für jeden Thread. Für wirklich parallele Workloads sollten Sie das **govergeos** Go-SDK in Betracht ziehen, das für die gleichzeitige Nutzung mit Goroutinen ausgelegt ist.
{% endhint %}

{% hint style="info" %}
**Kommen Sie von VMware oder Nutanix?**

pyvergeos stellt drei Muster bereit, die Sie von Anfang an kennen sollten:

* **Filtern** — ein flüssiger `Filter()` -Builder erzeugt OData-ähnliche Ausdrücke (`.eq()`, `.gt()`, `.and_()`, `.or_()`), oder Sie können einen rohen OData-String an `list(filter=...)`.
* **Aufgaben-Polling** — asynchrone Vorgänge geben einen Aufgabenverweis zurück; `client.tasks.wait(task_id, timeout=...)` blockiert bis zum Abschluss und löst bei `TaskTimeoutError` ein Timeout aus.
* **Mandantenkontext** — `tenant.connect()` liefert einen Client, der innerhalb des Mandanten kontextgebunden ist, sodass dasselbe Skript das Host-System und jeden untergeordneten Mandanten steuern kann, ohne eine Verbindung zu einem anderen Endpunkt herzustellen.
  {% endhint %}

## Zusätzliche Ressourcen

* [GitHub-Repository](https://github.com/verge-io/pyvergeos) — Quellcode, Issues und Beiträge
* [PyPI-Paket](https://pypi.org/project/pyvergeos/) — Neueste Version und Versionsverlauf
* [VergeOS-API-Dokumentation](/knowledge-base/de/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/de/modul-8-entwicklung-and-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.