Référence
Le client Python
Lisez des projets Holarch, recherchez des éléments et proposez des modifications à examiner depuis des scripts Python avec le package gratuit holarch-api ; installation, connexion, toutes les méthodes, propositions, erreurs et limites.
Sur cette page
Vue d'ensemble
holarch-api est un petit paquet Python pour l'API REST de Holarch. Il lit les projets, les éléments, les documents et les résultats de contrôle, effectue des recherches et propose des modifications. Il est gratuit ; l'API elle-même est fournie avec les offres qui l'incluent, et le paquet utilise votre jeton d'accès personnel.
Les modifications faites par le paquet sont toujours des propositions : elles s'accumulent sur le serveur, et les propriétaires du projet les examinent et les appliquent dans Holarch, exactement comme les modifications des clients d'IA, et une seule annulation défait chaque proposition appliquée. Le paquet n'a aucune méthode qui modifie directement un projet. Les scripts qui doivent écrire directement utilisent les appels d'écriture de l'API REST.
Concepts
- Client : un jeton sur un serveur Holarch. Chaque méthode envoie une requête (ou une par page) et renvoie le JSON de l'API sous forme de dict et de listes Python.
- Réponses typées : le paquet fournit des informations de type (des formes
TypedDicttelles queEntityetProjectSummary) : les éditeurs complètent donc les noms de champs et les vérificateurs de types comme mypy les contrôlent. Les champs que le serveur ajoute plus tard apparaissent simplement dans les dict. - Proposition : votre proposition ouverte dans un projet. Chaque appel ajoute une modification ;
send()remet la proposition aux propriétaires du projet pour revue. Un jeton a au plus une proposition ouverte par projet. - Références : une entité créée dans une proposition n'existe pas encore.
create()renvoie une référence (new:1,new:2, …) que les modifications suivantes de la même proposition utilisent à la place d'un id.
Mode d'emploi
Quand et pourquoi
Utilisez le client pour les scripts autour d'un projet : rapports et exportations dans votre propre format, contrôles dans une tâche nocturne, importations depuis un autre outil qu'une personne doit examiner avant leur arrivée. Comme les modifications arrivent sous forme de propositions, un script ne surprend jamais l'équipe : les propriétaires voient chaque modification avant qu'elle soit appliquée.
Installer et se connecter
- Installez Python 3.9 ou une version ultérieure, puis le paquet :
python3 -m pip install holarch-api. Il n'a besoin de rien d'autre que Python. - Dans Holarch, ouvrez Paramètres du compte → Jetons API et créez un jeton : Lecture seule pour les scripts qui ne font que lire, Lecture et écriture pour les scripts qui proposent des modifications. Limitez-le aux projets dont le script a besoin.
- Placez le jeton dans la variable d'environnement
HOLARCH_API_KEY. - Vérifiez la connexion :
from holarch_api import Client
c = Client()
print(c.me()["user"]["email"])
for p in c.projects():
print(p["id"], p["name"], p["role"])
Lire un projet
c = Client()
pid = "…" # the project id from c.projects()
info = c.project(pid) # name, description, items per class
for e in c.iter_entities(pid, cls="Requirement"):
print(e["number"], e["name"])
req = c.entity(pid, "…") # one entity with attributes and relationships
for r in req["relationships"]:
print(r["relation"], r["other"]["name"])
iter_entities récupère chaque correspondance une page à la fois ; entities renvoie une seule page (entities, total, offset, limit). search(pid, "thermal") trouve les entités dont le nom, le numéro, la description ou la classe contiennent le texte.
Proposer des modifications
- Commencez une proposition :
p = c.proposal(pid). - Ajoutez des modifications. Chaque appel est vérifié aussitôt par le serveur et échoue avec une erreur lorsque la classe, la relation ou l'attribut n'existe pas :
p = c.proposal(pid)
tc = p.create("Test Case", "Thermal vacuum test", description="Soak at -40 C for 8 hours.",
relationships=[("verifies", "…requirement id…")])
p.update("…", attributes={"Status": "Approved"})
p.relate(tc, "verifies", "…another requirement id…")
- Regardez ce qui a été rassemblé :
p.get()["changes"]. Le projet n'a pas changé. - Envoyez-la :
view = p.send("Add a TVAC test", "Covers the two thermal requirements.").view["review"]est le lien qui ouvre la revue dans Holarch.
Les propriétaires reçoivent une notification et examinent la proposition depuis le menu ✦ IA ▾ ; voir Propositions des clients d'IA. Pour abandonner une proposition avant son envoi, appelez p.discard(). Pour en suivre l'évolution plus tard, c.get_proposal(pid, view["id"])["status"] vaut ready, applied, rejected ou expired.
Exemple complet : la démo CubeSat EO-1
- Créez un jeton en lecture seule pour le projet CubeSat et définissez
HOLARCH_API_KEY. - Listez les constats des Contrôles du modèle sur les exigences :
c = Client()
pid = next(p["id"] for p in c.projects() if p["name"].startswith("CubeSat"))
checks = c.model_checks(pid, cls="Requirement")
print(checks["total"], "findings")
- Notez les exigences :
c.quality(pid)["results"]liste chaque exigence avec son score et ses constats. - Avec un jeton en lecture et écriture, proposez un cas de test pour une exigence qui n'en a pas, comme dans Proposer des modifications, et envoyez la proposition. Une fois qu'un propriétaire l'a appliquée, les Contrôles du modèle ne listent plus l'exigence.
Projets SysML v2
Le même client lit les projets SysML v2 : model(pid) (packages et décomptes), elements(pid, q=…, type=…), element(pid, "Vehicles::Engine"), requirements(pid), diagnostics(pid) et sysml_text(pid, root="Vehicles"). check_sysml(pid, text) vérifie un texte sans le proposer. Pour proposer une modification, envoyez le nouveau texte d'un package avec p.sysml_text(text, root="Vehicles"), ou des modifications d'éléments avec p.sysml_edits([...]) ; le moteur vérifie chaque modification et refuse celle qui comporte des erreurs. Voir L'API et MCP dans les projets SysML v2.
Conseils et bonnes pratiques
- Lisez d'abord le schéma (
c.schema(pid)) : il liste les noms de classes, d'attributs et de relations qu'utilise le projet. - Donnez à chaque script son propre jeton, en lecture seule là où il ne fait que lire.
- Rassemblez les modifications liées dans une seule proposition et envoyez-la avec un titre et un résumé qui en expliquent la raison : le relecteur voit toute la modification d'un coup.
- Gardez les jetons hors des fichiers source ; c'est pourquoi le client lit
HOLARCH_API_KEY.
Erreurs courantes
ApiErroravec le coderead-only-token: le jeton est en lecture seule ; créez un jeton en lecture et écriture pour les propositions.ApiErroravec le codenot-foundsur un projet que vous pouvez ouvrir dans Holarch : le jeton est limité à d'autres projets.- Une entité créée est introuvable avec
entity(): elle n'existe que dans la proposition jusqu'à ce qu'un propriétaire l'applique.
Référence
Client
Client(token=None, server=None, timeout=30.0, retries=3). token vaut par défaut HOLARCH_API_KEY, et server HOLARCH_SERVER ou https://app.holarch.app. Le serveur doit être une adresse https.
| Méthode | Renvoie |
|---|---|
me() | Le compte, l'accès et l'expiration du jeton |
projects() | Vos projets : id, nom, rôle, nombre d'éléments, langage, lien |
project(pid) | Nom, description, rôle, nombre d'éléments, éléments par classe, nombre de documents |
schema(pid) | Classes avec leurs attributs et leurs relations autorisées ; relations |
entities(pid, cls=None, label=None, q=None, limit=100, offset=0) | Une page d'entités (au plus 500) |
iter_entities(pid, cls=None, label=None, q=None, page_size=500) | Chaque entité correspondante |
search(pid, text, cls=None, limit=100) | Entités dont le nom, le numéro, la description ou la classe contiennent le texte |
entity(pid, id) | Une entité avec ses attributs, ses étiquettes et ses relations |
documents(pid) | Documents avec leur type et leur nombre de sections |
document(pid, id) | Un document avec ses sections dans l'ordre, numérotées, en texte brut |
model_checks(pid, cls=None, rule=None, limit=500, offset=0) | Constats des Contrôles du modèle avec un résumé |
quality(pid, ids=None) | Le contrôle de la qualité des exigences, pour les exigences données ou pour toutes |
versions(pid) | Les versions enregistrées que conserve l'offre du projet |
configurations(pid) | La ligne de produits : caractéristiques, règles et configurations avec leur sélection, leur verdict et leur applicabilité |
proposal(pid) | Un Proposal pour votre proposition ouverte dans le projet |
get_proposal(pid, proposal_id=None) | La proposition ouverte, ou une proposition par son id, avec son statut et ses modifications |
request(method, path, params=None, body=None) | Tout autre appel API, relatif à /api/v1 |
project, entities, iter_entities, search, entity, documents, document, model_checks et quality acceptent aussi configuration= (le numéro, le nom ou l'id d'une configuration) et effectivity= ("sn:23" ou "date:2027-03-01") pour lire le modèle tel qu'une configuration d'une ligne de produits le présente (Lignes de produits).
Proposition
| Méthode | Ce qu'il propose |
|---|---|
create(cls, name, number=None, description=None, labels=None, attributes=None, relationships=None) | Une nouvelle entité ; relationships sous forme de paires (relation, target) ; renvoie sa référence |
update(entity, name=None, number=None, description=None, labels=None, attributes=None) | Champs modifiés ; les champs omis restent inchangés, un attribut défini à None perd sa valeur |
delete(entity) | Placer l'entité dans la corbeille du projet |
relate(source, relation, target, attributes=None) | Une nouvelle relation, nommée depuis la source |
unrelate(relationship) | Retirer une relation (son id provenant de entity()) |
get() | Rien : renvoie la proposition avec ses modifications |
send(title, summary="") | Rien de plus : envoie la proposition pour revue et la renvoie avec le lien de revue |
discard() | Rien : abandonne la proposition ouverte |
create et update acceptent aussi applies_to= ("F-3 and not F-5" ; "" l'efface) et effectivity= ({"serials": "1-20, 25"} ; {} l'efface), et chaque modification accepte configuration= pour la proposer comme modification dans cette configuration (Lignes de produits).
Erreurs
Chaque requête refusée lève holarch_api.ApiError avec message (le texte du serveur), code, status et body. Les codes sont ceux de l'API REST. Une requête refusée avec 429 rate-limited est retentée après le délai indiqué par le serveur, jusqu'à retries fois, avant de lever l'erreur.
Limites
- Les limites de l'API s'appliquent (API et MCP) : fréquence des requêtes, au plus 500 entités par page, et limite d'éléments du projet lorsqu'une proposition est appliquée.
- Une proposition expire 7 jours après avoir été commencée.
- Le client fonctionne avec le service hébergé.