> For the complete documentation index, see [llms.txt](https://cleyrop.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cleyrop.gitbook.io/docs/support-and-ressources/references-techniques-api-sdk/sdk-cleyrop-sdk.md).

# SDK cleyrop-sdk

Le SDK `cleyrop-sdk` est la librairie Python officielle pour interagir avec la plateforme Cleyrop depuis du code. Il permet de manipuler les ressources des Données de Travail d'un projet de manière programmatique pour automatiser des uploads, intégrer la gestion de fichiers dans un pipeline de traitement, ou accéder aux données depuis une App.

Il expose un client Python (synchrone et asynchrone) ainsi qu'une interface en ligne de commande (CLI) utilisable depuis le terminal d'un DevSpace.

## Installation & Utilisation 

Le SDK est pré-installé dans l'environnement du **Codelab** et dans les transformations Python / PySpark des Dataflows. L'authentification est automatique grâce au token injecté par la plateforme.

Seul le **DevSpace** nécessite une installation manuelle (voir ci-dessous).

### Installation DevSpace - Premiers pas

{% stepper %}
{% step %}

#### Installation

Une fois votre DevSpace connecté à votre IDE (VS Code, Cursor…), créez un dossier de travail et installez le SDK :

<pre class="language-shell" data-overflow="wrap"><code class="lang-shell"><strong>mkdir -p /home/cleyrop/projects/mon-projet &#x26;&#x26; cd /home/cleyrop/projects/mon-projet
</strong>uv venv
source .venv/bin/activate

uv pip install "cleyrop-sdk" --extra-index-url "https://gitlab.com/api/v4/projects/79823225/packages/pypi/simple"
</code></pre>

{% endstep %}

{% step %}

#### Authentification

Une fois le `cleyrop-sdk` installé, authentifiez-vous sur la plateforme avec la commande suivante :

```shell
cleyrop login
```

Le SDK ouvre votre navigateur et vous demande d'autoriser l'accès. Cliquez sur **Oui** pour valider.

<figure><img src="/files/eYU0DmRFbIOVnPLInh47" alt="" width="322"><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

## Utilisation - Exemple de code

Lister les fichiers présents et uploader un fichier dans les Données de Travail d'un projet.

{% tabs %}
{% tab title="Codelab" %}
{% code title="Codelab : Cleyrop sdk - folder content / upload file" expandable="true" %}

```python
import os, io
from cleyrop import CleyropClient, ClientConfig
from cleyrop.models import FileResponse, FolderResponse

sdk = CleyropClient(ClientConfig.from_env())

# Le projet associé au notebook
project = sdk.get_project_by_slug(os.environ["PROJECT_SLUG"])
print(f"Projet : {project.slug} (id={project.id})")

# Contenu du projet (direct, non récursif)
for item in sdk.iter_project_contents(project.id):
    kind = "📁" if isinstance(item, FolderResponse) else "📄"
    size = f" ({item.size}B)" if isinstance(item, FileResponse) else ""
    print(f"  {kind} {item.name}{size}")

# Uploader un fichier
buf = io.BytesIO(b"Hello depuis le Codelab\n")
resp = sdk.upload_file(buf, project_id=project.id, filename="depuis-codelab.txt")
print(f"Uploadé : {resp.name} (id={resp.id}, scan={resp.virus_scan_status})")
```

{% endcode %}
{% endtab %}

{% tab title="Dataflow " %}
{% code title="Dataflow - Cleyrop SDK - folder content / upload file" expandable="true" %}

```python

import os, io
from cleyrop import CleyropClient, ClientConfig
from cleyrop.models import FileResponse, FolderResponse

sdk = CleyropClient(ClientConfig.from_env())
sdk.login_client_credentials()   # obligatoire en Dataflow

# Le projet courant
project = sdk.get_project_by_slug(os.environ["PROJECT_SLUG"])
print(f"Projet : {project.slug} (id={project.id})")

# Lister les fichiers à la racine
for item in sdk.iter_project_contents(project.id):
    kind = "📁" if isinstance(item, FolderResponse) else "📄"
    size = f" ({item.size}B)" if isinstance(item, FileResponse) else ""
    print(f"  {kind} {item.name}{size}")

# Uploader un fichier
buf = io.BytesIO(b"Hello depuis le Dataflow\n")
resp = sdk.upload_file(buf, project_id=project.id, filename="depuis-dataflow.txt")
print(f"Uploadé : {resp.name} (id={resp.id}, scan={resp.virus_scan_status})")
```

{% endcode %}

{% hint style="info" %}
Dans un Dataflow, le code ci-dessus peut être intégré dans une transformation Python ou PySpark pour manipuler les Données de Travail en complément du traitement de données.
{% endhint %}

{% hint style="danger" %}

<pre><code><strong>sdk.login_client_credentials()   # obligatoire en Dataflow
</strong></code></pre>

{% endhint %}
{% endtab %}

{% tab title="DevSpace" %}
{% code title="DevSpace : Cleyrop sdk - folder content / upload file" overflow="wrap" %}

```py
import io
from cleyrop import CleyropClient, ClientConfig
from cleyrop.models import FileResponse, FolderResponse

with CleyropClient(ClientConfig.from_env()) as client:
    # Lister les projets
    for p in client.iter_projects():
        print(f"  {p.slug:20s} {p.id}")

    # Naviguer dans le contenu d'un projet
    project = client.get_project_by_slug("mon-projet")
    for item in client.iter_project_contents(project.id):
        kind = "📁" if isinstance(item, FolderResponse) else "📄"
        size = f" ({item.size}B)" if isinstance(item, FileResponse) else ""
        print(f"  {kind} {item.name}{size}")
    
    # Uploader un fichier présent dans le DevSpace
    resp = client.upload_file("chemin/vers/mon-fichier.csv", project_id=project.id)
    print(f"Uploadé : {resp.name} (id={resp.id})")
```

{% endcode %}
{% endtab %}

{% tab title="App" %}
{% code title="App : Cleyrop sdk - folder content / upload file" overflow="wrap" %}

```py
import os
from cleyrop import CleyropClient, ClientConfig


def get_client() -> CleyropClient:
    """Client Configuration & Authentification"""
    cfg = ClientConfig.internal(
            client_id=os.environ.get("CLEYROP_CLIENT_ID", "cleyrop-cli"),
            client_secret=os.environ.get("CLEYROP_CLIENT_SECRET"),
        )
    client = CleyropClient(cfg)
    client.login_client_credentials()
    return client


# Utilisation
with get_client() as client:
    project = client.get_project_by_slug("mon-projet")
    for item in client.iter_project_contents(project.id):
        print(item.name)
    # … toutes les autres méthodes du SDK fonctionnent ici
    # (upload_file, download_file_bytes, create_folder, search, etc.)
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Déployer une App avec le SDK

Pour utiliser le `cleyrop-sdk` dans une App déployée via la Fabrique, ajoutez les éléments suivants à votre Dockerfile.

{% hint style="success" %}
Pour **utiliser le SDK depuis une App** pour accéder aux fichiers des Données de travail d'un projet il faut avoir préalablement générer un **compte de service** pour l'instance et donner les accès nécéssaires (lecture, édition) aux projets souhaités&#x20;
{% endhint %}

```dockerfile
FROM python:3.13-slim
WORKDIR /app

# Installer le SDK (ajoutez ici les dépendances propres à votre app)
RUN pip install --no-cache-dir cleyrop-sdk \
    --extra-index-url "https://gitlab.com/api/v4/projects/79823225/packages/pypi/simple"

COPY app.py .

EXPOSE <port>
CMD ["python", "app.py"]
```

**Exemple de script**&#x20;

*Application web qui se connecte et renvoie la liste des projets accessibles :*

{% code title="Script python" overflow="wrap" %}

```py
import os
from fastapi import FastAPI
from cleyrop import CleyropClient, ClientConfig

app = FastAPI()

# Connexion (le compte de service attaché fournit les identifiants)
client = CleyropClient(ClientConfig.internal(
    client_id=os.environ.get("CLEYROP_CLIENT_ID"),
    client_secret=os.environ.get("CLEYROP_CLIENT_SECRET"),
))
client.login_client_credentials()

@app.get("/")
def home():
    return {"projets": [p.slug for p in client.iter_projects()]}
```

{% endcode %}

{% code title="" overflow="wrap" %}

```dockerfile
FROM python:3.13-slim
WORKDIR /app

RUN pip install --no-cache-dir cleyrop-sdk fastapi "uvicorn[standard]" \
    --extra-index-url "https://gitlab.com/api/v4/projects/79823225/packages/pypi/simple"

COPY app.py .

EXPOSE 8080
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8080"]
```

{% endcode %}

{% hint style="info" %}
Le port configuré dans la Fabrique doit être identique à celui exposé par l'app.
{% endhint %}

## Méthodes disponibles dans le SDK Cleyrop

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="262.1015625">Méthode</th><th>Description</th><th>Paramètres principaux</th><th>Sortie</th></tr></thead><tbody><tr><td><code>list_projects()</code></td><td>Lister tous les projets</td><td>—</td><td>Liste de projets</td></tr><tr><td><code>get_project(id)</code></td><td>Récupérer un projet par ID</td><td><code>id</code> : UUID du projet</td><td>ID du Projet</td></tr><tr><td><code>get_project_by_slug(slug)</code></td><td>Récupérer un projet par slug</td><td><code>slug</code> : identifiant texte</td><td>slug du Projet</td></tr><tr><td><code>iter_projects()</code></td><td>Parcourir tous les projets (pagination automatique)</td><td>—</td><td>Projet par projet</td></tr><tr><td><code>iter_project_contents(project_id)</code></td><td>Lister le contenu direct d'un projet ou dossier (non récursif)</td><td><code>project_id</code>, <code>folder_id</code>(optionnel)</td><td>Fichier ou dossier par élément</td></tr><tr><td><code>resolve_path(project_id, path)</code></td><td>Retrouver un fichier ou dossier à partir de son chemin</td><td><code>project_id</code>, <code>path</code></td><td>Fichier ou dossier trouvé</td></tr><tr><td><code>upload_file(source, project_id)</code></td><td>Uploader un fichier (chemin local ou buffer)</td><td><code>source</code>, <code>project_id</code>, <code>folder_id</code>(opt.), <code>filename</code>(opt.)</td><td>Fichier créé avec son ID et statut de scan</td></tr><tr><td><code>download_file(file_id, dest)</code></td><td>Télécharger un fichier sur disque</td><td><code>file_id</code>, <code>dest</code></td><td>Chemin du fichier sauvegardé</td></tr><tr><td><code>download_file_bytes(file_id)</code></td><td>Télécharger un fichier en mémoire</td><td><code>file_id</code></td><td>Contenu en bytes</td></tr><tr><td><code>get_file(file_id)</code></td><td>Récupérer les métadonnées d'un fichier</td><td><code>file_id</code></td><td>Nom, taille, statut de scan</td></tr><tr><td><code>rename_file(file_id, name)</code></td><td>Renommer un fichier</td><td><code>file_id</code>, <code>name</code></td><td>Fichier renommé</td></tr><tr><td><code>move_file(file_id, folder_id)</code></td><td>Déplacer un fichier</td><td><code>file_id</code>, <code>folder_id</code></td><td>Fichier déplacé</td></tr><tr><td><code>copy_file(file_id, name)</code></td><td>Copier un fichier</td><td><code>file_id</code>, <code>name</code> (opt.)</td><td>Copie créée avec nouvel ID</td></tr><tr><td><code>update_file(file_id, file_metadata)</code></td><td>Mettre à jour les métadonnées</td><td><code>file_id</code>, <code>file_metadata</code>(dict)</td><td>Fichier mis à jour</td></tr><tr><td><code>delete_file(file_id)</code></td><td>Envoyer un fichier en corbeille</td><td><code>file_id</code></td><td>—</td></tr><tr><td><code>restore_file(file_id)</code></td><td>Restaurer un fichier depuis la corbeille</td><td><code>file_id</code></td><td>Fichier restauré</td></tr><tr><td><code>delete_file_permanent(file_id)</code></td><td>Supprimer définitivement (irréversible)</td><td><code>file_id</code></td><td>—</td></tr><tr><td><code>create_folder(name, project_id)</code></td><td>Créer un dossier</td><td><code>name</code>, <code>project_id</code>, <code>parent_id</code> (opt.)</td><td>Dossier créé avec son ID</td></tr><tr><td><code>get_folder(folder_id)</code></td><td>Récupérer les métadonnées d'un dossier</td><td><code>folder_id</code></td><td>Nom, chemin</td></tr><tr><td><code>get_folder_contents(folder_id)</code></td><td>Lister le contenu d'un dossier</td><td><code>folder_id</code></td><td>Liste de fichiers et dossiers</td></tr><tr><td><code>rename_folder(folder_id, name)</code></td><td>Renommer un dossier</td><td><code>folder_id</code>, <code>name</code></td><td>Dossier renommé</td></tr><tr><td><code>move_folder(folder_id, parent_id)</code></td><td>Déplacer un dossier</td><td><code>folder_id</code>, <code>parent_id</code></td><td>Dossier déplacé</td></tr><tr><td><code>delete_folder(folder_id, recursive)</code></td><td>Envoyer un dossier en corbeille</td><td><code>folder_id</code>, <code>recursive</code>(bool)</td><td>—</td></tr><tr><td><code>restore_folder(folder_id, recursive)</code></td><td>Restaurer un dossier depuis la corbeille</td><td><code>folder_id</code>, <code>recursive</code>(bool)</td><td>Dossier restauré</td></tr><tr><td><code>search(query, project_id)</code></td><td>Rechercher dans les fichiers et dossiers</td><td><code>query</code>, <code>project_id</code>, <code>search_mode</code>("name" ou "fulltext")</td><td>Nombre de résultats + liste</td></tr><tr><td><code>list_trash(project_id)</code></td><td>Lister les éléments en corbeille</td><td><code>project_id</code></td><td>Nombre de fichiers et dossiers en corbeille</td></tr></tbody></table>

***

## CLI

Le SDK installe une commande `cleyrop` utilisable dans le terminal du DevSpace.

**Authentification**

| Commande         | Description                     |
| ---------------- | ------------------------------- |
| `cleyrop login`  | Connexion interactive           |
| `cleyrop logout` | Déconnexion                     |
| `cleyrop me`     | Afficher l'utilisateur connecté |

**Projets**

| Commande                                                    | Description                              |
| ----------------------------------------------------------- | ---------------------------------------- |
| `cleyrop projects list`                                     | Lister tous les projets                  |
| `cleyrop projects get <PROJECT_ID>`                         | Détails d'un projet                      |
| `cleyrop projects contents <PROJECT_ID> [--folder-id UUID]` | Lister le contenu d'un projet ou dossier |

**Fichiers**

| Commande                                                           | Description                   |
| ------------------------------------------------------------------ | ----------------------------- |
| `cleyrop files upload <FILE> --project-id UUID [--folder-id UUID]` | Uploader un fichier           |
| `cleyrop files download <FILE_ID> -o OUTPUT_PATH`                  | Télécharger un fichier        |
| `cleyrop files get <FILE_ID>`                                      | Métadonnées d'un fichier      |
| `cleyrop files rename <FILE_ID> <NAME>`                            | Renommer un fichier           |
| `cleyrop files copy <FILE_ID> [--folder-id UUID]`                  | Copier un fichier             |
| `cleyrop files move <FILE_ID> --folder-id UUID`                    | Déplacer un fichier           |
| `cleyrop files delete <FILE_ID>`                                   | Envoyer en corbeille          |
| `cleyrop files delete <FILE_ID> --permanent`                       | Supprimer définitivement      |
| `cleyrop files restore <FILE_ID>`                                  | Restaurer depuis la corbeille |

**Dossiers**

| Commande                                            | Description                    |
| --------------------------------------------------- | ------------------------------ |
| `cleyrop folders create <NAME> --project-id UUID`   | Créer un dossier               |
| `cleyrop folders list <FOLDER_ID>`                  | Lister le contenu d'un dossier |
| `cleyrop folders rename <FOLDER_ID> <NAME>`         | Renommer un dossier            |
| `cleyrop folders move <FOLDER_ID> --parent-id UUID` | Déplacer un dossier            |
| `cleyrop folders delete <FOLDER_ID>`                | Envoyer en corbeille           |
| `cleyrop folders restore <FOLDER_ID>`               | Restaurer depuis la corbeille  |

**Recherche de fichiers et corbeille**

| `cleyrop search <QUERY> --project-id UUID [--mode fulltext\|name]` | Rechercher des fichiers ou dossiers |
| ------------------------------------------------------------------ | ----------------------------------- |
| `cleyrop trash list <PROJECT_ID>`                                  | Lister les éléments en corbeille    |


---

# 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:

```
GET https://cleyrop.gitbook.io/docs/support-and-ressources/references-techniques-api-sdk/sdk-cleyrop-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.