> 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/fr/module-8-developpeur-et-devops/02-python-sdk.md).

# SDK Python (pyvergeos)

Le **pyvergeos** Le SDK fournit une interface typée, de style Python, pour l’ensemble de l’API REST VergeOS. Plutôt que de créer des requêtes HTTP brutes, vous travaillez avec **des gestionnaires de ressources** — `client.vms`, `client.networks`, `client.tenants` — qui correspondent directement aux objets VergeOS. Le SDK gère l’authentification, la pagination, les nouvelles tentatives et le sondage des tâches asynchrones afin que vos scripts d’automatisation restent propres et centrés sur la logique métier.

## Prérequis et installation

**Prérequis :**

* **Python 3.9** ou version ultérieure
* **VergeOS 26.0** ou version ultérieure
* Fonctionne sur **Windows, macOS et Linux**

**Installer depuis PyPI (recommandé) :**

```bash
pip install pyvergeos
```

**Ou avec uv (alternative plus rapide) :**

```bash
uv add pyvergeos
```

**Depuis les sources (développement) :**

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

## Authentification

Le SDK prend en charge trois méthodes d’authentification, chacune adaptée à des environnements différents.

### Nom d’utilisateur et mot de passe

L’approche la plus simple pour les scripts interactifs et le développement :

```python
from pyvergeos import VergeClient

client = VergeClient(
    host="192.168.1.100",
    username="admin",
    password="secret",
    verify_ssl=False  # Uniquement pour les certificats auto-signés
)
```

### Jeton API

Pour l’automatisation en production, lorsque vous disposez d’une clé API pré-générée :

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

### Variables d’environnement

L’approche recommandée pour la production — elle garde les identifiants hors du code स्रोत :

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

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

### Gestionnaire de contexte

Utilisez toujours le gestionnaire de contexte dans le code de production afin de garantir que les connexions sont correctement fermées, même lorsque des exceptions se produisent :

```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")
# Connexion automatiquement fermée ici
```

## Gestionnaires de ressources

Chaque type de ressource VergeOS est exposé via un **gestionnaire de ressources** sur l’objet client. Chaque gestionnaire fournit des méthodes cohérentes `list()`, `get()`, `create()`, et des méthodes d’action.

### Machines virtuelles

`client.vms` — Crée, configure, contrôle l’alimentation, clone, prend des instantanés et gère les disques/cartes réseau des VM.

### Réseaux

`client.networks` — Réseaux virtuels, règles de pare-feu, DHCP, DNS et gestion de l’alimentation du réseau.

### Locataires

`client.tenants` — Provisioning multi-locataire, isolement des ressources, instantanés, blocs de stockage et blocs réseau.

### NAS et stockage

`client.nas` — Services NAS, volumes, partages CIFS/NFS et synchronisation des volumes.

### Récupération après sinistre

`client.dr` — Instantanés cloud, synchronisation des sites et workflows de récupération.

### Utilisateurs et groupes

`client.users` — Comptes utilisateurs, groupes, permissions et gestion des clés API.

### Tâches et supervision

`client.tasks` — Suivi asynchrone des tâches, attente, délais d’expiration. Aussi : alarmes et journaux.

### Système et GPU

`client.clusters`, `client.nodes`, `client.gpu` — Informations sur les clusters/nœuds, niveaux de stockage, gestion des périphériques GPU.

### Table complète des ressources

| Catégorie                                | Ressources disponibles                                                     |
| ---------------------------------------- | -------------------------------------------------------------------------- |
| **Machines virtuelles**                  | VM, disques, cartes réseau, instantanés                                    |
| **Réseau**                               | Réseaux, règles de pare-feu, DNS, DHCP, alias, hôtes                       |
| **VPN**                                  | Connexions IPSec, interfaces et pairs WireGuard                            |
| **NAS/Stockage**                         | Services NAS, volumes, partages CIFS/NFS, synchronisations de volumes      |
| **Locataires**                           | Gestion des locataires, instantanés, blocs de stockage, blocs réseau       |
| **Utilisateurs et groupes**              | Utilisateurs, groupes, permissions, clés API                               |
| **Système**                              | Clusters, nœuds, niveaux de stockage, certificats                          |
| **Surveillance**                         | Alarmes, journaux, tâches                                                  |
| **Sauvegarde et reprise après sinistre** | Profils d’instantanés, instantanés cloud, sites, synchronisations de sites |

## Filtrage des ressources

Le SDK propose trois approches pour filtrer les ressources, des simples arguments de mot-clé à un constructeur de filtres OData complet.

### Arguments de mots-clés

L’approche la plus simple pour les filtres de base — passez directement les noms de champs :

```python
# Trouver toutes les VM Linux en cours d’exécution
vms = client.vms.list(status="running", os_family="linux")

# Correspondance avec jokers
vms = client.vms.list(name="prod-*")
```

### Chaînes de filtre OData

Pour les requêtes complexes, passez des expressions de filtre OData brutes :

```python
# Combiner des conditions avec des opérateurs
vms = client.vms.list(filter="os_family eq 'linux' and ram gt 2048")
```

### Constructeur de filtres (API fluide)

Construisez des filtres par programme avec sécurité de type et auto-complétion :

```python
from pyvergeos import Filter

# Enchaînement fluide avec des méthodes d’opérateur
f = Filter().eq("os_family", "linux").and_().gt("ram", 2048)
vms = client.vms.list(filter=str(f))
```

**Opérateurs de filtre disponibles :**

| Méthode   | Opérateur OData | Exemple                               |
| --------- | --------------- | ------------------------------------- |
| `.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_()` | `et`            | Enchaîner plusieurs conditions        |
| `.or_()`  | `ou`            | Combiner des conditions alternatives  |

## Gestion des tâches asynchrones

De nombreuses opérations VergeOS — instantanés, clones, migrations — s’exécutent **de manière asynchrone** et renvoient immédiatement un ID de tâche. Le SDK fournit un gestionnaire de tâches pour interroger l’achèvement :

```python
# L’instantané renvoie une référence de tâche
result = vm.snapshot(retention=86400, quiesce=True)

# Attendre la fin de l’instantané (bloque jusqu’à 300 secondes)
task = client.tasks.wait(result["task"], timeout=300)
print(f"Instantané terminé : {task}")
```

Si la tâche ne se termine pas avant l’expiration du délai, une `TaskTimeoutError` est levée avec la `task_id` propriété afin que vous puissiez vérifier l’état plus tard :

```python
from pyvergeos import TaskTimeoutError

try:
    task = client.tasks.wait(task_id, timeout=60)
except TaskTimeoutError as e:
    print(f"La tâche {e.task_id} est toujours en cours — revenez plus tard")
```

## Gestion des erreurs

Le SDK fournit une hiérarchie structurée d’exceptions afin que vous puissiez intercepter des modes d’échec spécifiques :

| Exception             | Description                                                            |
| --------------------- | ---------------------------------------------------------------------- |
| `VergeError`          | Exception de base pour toutes les erreurs du SDK                       |
| `AuthenticationError` | Identifiants invalides ou jeton expiré                                 |
| `NotFoundError`       | La ressource demandée n’existe pas                                     |
| `ConflictError`       | Conflit d’état de la ressource (par ex., VM déjà en cours d’exécution) |
| `ValidationError`     | Valeurs de paramètres invalides                                        |
| `TaskTimeoutError`    | La tâche ne s’est pas terminée avant l’expiration du délai             |
| `TaskError`           | La tâche a échoué pendant l’exécution                                  |

```python
from pyvergeos import NotFoundError, AuthenticationError

try:
    vm = client.vms.get(name="nonexistent-vm")
except NotFoundError:
    print("VM introuvable — vérifiez le nom")
except AuthenticationError:
    print("Échec de l’authentification — vérifiez les identifiants")
```

## Configuration des nouvelles tentatives

Le SDK réessaie automatiquement les erreurs transitoires (HTTP 429, 500, 502, 503, 504) avec une temporisation exponentielle :

```python
client = VergeClient(
    host="192.168.1.100",
    token="api-token",
    retry_total=5,            # Nombre maximal de tentatives (par défaut : 3)
    retry_backoff_factor=2,   # Multiplicateur de temporisation (par défaut : 1)
)
```

Définissez `retry_total=0` pour désactiver complètement les nouvelles tentatives pour les opérations sensibles au temps.

## Changement de contexte de locataire

pyvergeos peut **se connecter dans des contextes de locataire** depuis le système hôte, ce qui permet des scripts d’automatisation centralisés qui gèrent des ressources sur plusieurs locataires :

```python
# Récupérer un locataire depuis le système hôte
tenant = client.tenants.get(name="customer-a")

# Se connecter dans le contexte du locataire
tenant_client = tenant.connect()

# Gérer maintenant des ressources À L’INTÉRIEUR du locataire
tenant_vms = tenant_client.vms.list()
for vm in tenant_vms:
    print(f"VM du locataire : {vm.name}")

# Créer un réseau à l’intérieur du locataire
tenant_client.networks.create(
    name="tenant-app-net",
    network_address="10.50.1.0/24",
    ip_address="10.50.1.1",
    dhcp_enabled=True
)
```

C’est particulièrement utile pour **Les MSP et les fournisseurs de services** qui doivent automatiser le provisioning sur des dizaines ou des centaines d’environnements locataires à partir d’un seul script.

## Exemples pratiques

### Gestion du cycle de vie des VM

```python
with VergeClient.from_env() as client:
    # Créer une nouvelle VM
    vm = client.vms.create(
        name="web-server-01",
        ram=4096,
        cpu_cores=2,
        os_family="linux"
    )

    # Ajouter un disque de données de 50 Go
    vm.drives.add(name="data", size=50 * 1024 * 1024 * 1024)

    # Rattacher à un réseau
    network = client.networks.get(name="app-network")
    vm.nics.add(network=network.key)

    # Mise sous tension
    vm.power_on()
    print(f"La VM {vm.name} est en cours d’exécution")
```

### Réseau avec règles de pare-feu

```python
with VergeClient.from_env() as client:
    # Créer un réseau
    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()

    # Ajouter des règles de pare-feu
    network.rules.create(
        name="Autoriser HTTPS",
        action="accept",
        protocol="tcp",
        dest_port=443
    )
    network.rules.create(
        name="Autoriser SSH",
        action="accept",
        protocol="tcp",
        dest_port=22
    )
    network.apply_rules()
```

### Opérations en masse avec filtrage

```python
with VergeClient.from_env() as client:
    # Créer un instantané de toutes les VM de production en cours d’exécution
    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"Instantané créé pour {vm.name}")
```

### Rapport d’inventaire multi-locataire

```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} cœurs")
```

## Remarques importantes

{% hint style="warning" %}
**Sécurité des threads**

Le client pyvergeos n’est **pas sûr pour les threads**. Si vous avez besoin d’opérations concurrentes, créez des `VergeClient` instances séparées pour chaque thread. Pour de véritables charges de travail parallèles, envisagez le SDK Go **govergeos** qui est conçu pour une utilisation concurrente avec des goroutines.
{% endhint %}

{% hint style="info" %}
**Vous venez de VMware ou de Nutanix ?**

pyvergeos expose trois modèles qu’il vaut la peine de connaître dès le départ :

* **Filtrage** — un `Filter()` constructeur fluide produit des expressions de style OData (`.eq()`, `.gt()`, `.and_()`, `.or_()`), ou vous pouvez transmettre une chaîne OData brute à `list(filter=...)`.
* **Interrogation des tâches** — les opérations asynchrones renvoient une référence de tâche ; `client.tasks.wait(task_id, timeout=...)` bloque jusqu’à l’achèvement et lève `TaskTimeoutError` en cas d’expiration du délai.
* **Contexte du locataire** — `tenant.connect()` renvoie un client limité au locataire, de sorte que le même script peut piloter le système hôte et n’importe quel locataire enfant sans se reconnecter à un autre point de terminaison.
  {% endhint %}

## Ressources supplémentaires

* [Dépôt GitHub](https://github.com/verge-io/pyvergeos) — code source, problèmes et contributions
* [Paquet PyPI](https://pypi.org/project/pyvergeos/) — dernière version publiée et historique des versions
* [Documentation de l’API VergeOS](/knowledge-base/fr/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/fr/module-8-developpeur-et-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.