Holarch

Referenz

Der Python-Client

Lesen Sie Holarch-Projekte, durchsuchen Sie Elemente und schlagen Sie Änderungen zur Prüfung vor, aus Python-Skripten mit dem kostenlosen Paket holarch-api; Installation, Anmeldung, jede Methode, Vorschläge, Fehler und Grenzen.

So gehen Sie vor →

Auf dieser Seite
  1. Überblick
  2. Konzepte
  3. So setzen Sie es ein
    1. Wann und warum
    2. Installieren und anmelden
    3. Ein Projekt lesen
    4. Änderungen vorschlagen
    5. Durchgehendes Beispiel: die CubeSat-EO-1-Demo
    6. SysML-v2-Projekte
    7. Tipps und bewährte Vorgehensweisen
    8. Häufige Fehler
  4. Referenz
    1. Client
    2. Vorschlag
    3. Fehler
  5. Grenzen
  6. Verwandte Seiten

Überblick

holarch-api ist ein kleines Python-Paket für die REST-API von Holarch. Es liest Projekte, Elemente, Dokumente und Prüfergebnisse, sucht und schlägt Änderungen vor. Es ist kostenlos; die API selbst gehört zu den Tarifen, die sie enthalten, und das Paket verwendet Ihr persönliches Zugriffstoken.

Über das Paket vorgenommene Änderungen sind immer Vorschläge: Sie sammeln sich auf dem Server, und die Eigentümer des Projekts prüfen und wenden sie in Holarch an, genau wie Änderungen von KI-Clients, und ein einziges Rückgängigmachen nimmt jeden angewendeten Vorschlag zurück. Das Paket hat keine Methoden, die ein Projekt direkt ändern. Skripte, die direkt schreiben müssen, verwenden die Schreibaufrufe der REST-API.

Konzepte

  • Client: ein Token auf einem Holarch-Server. Jede Methode sendet eine Anfrage (oder eine pro Seite) und gibt das JSON der API als Python-Dicts und -Listen zurück.
  • Typisierte Antworten: Das Paket bringt Typinformationen mit (TypedDict-Formen wie Entity und ProjectSummary), sodass Editoren Feldnamen vervollständigen und Typprüfer wie mypy sie prüfen. Felder, die der Server später hinzufügt, erscheinen einfach in den Dicts.
  • Vorschlag: Ihr offener Vorschlag in einem Projekt. Jeder Aufruf fügt eine Änderung hinzu; send() übergibt den Vorschlag den Eigentümern des Projekts zur Prüfung. Ein Token hat höchstens einen offenen Vorschlag pro Projekt.
  • Verweise: Eine in einem Vorschlag erstellte Entität existiert noch nicht. create() gibt einen Verweis zurück (new:1, new:2, …), den spätere Änderungen im selben Vorschlag anstelle einer ID verwenden.

So setzen Sie es ein

Wann und warum

Verwenden Sie den Client für Skripte rund um ein Projekt: Berichte und Exporte in Ihrem eigenen Format, Prüfungen in einem nächtlichen Auftrag, Importe aus einem anderen Werkzeug, die eine Person prüfen soll, bevor sie übernommen werden. Weil Änderungen als Vorschläge ankommen, überrascht ein Skript das Team nie: Die Eigentümer sehen jede Änderung, bevor sie angewendet wird.

Installieren und anmelden

  1. Installieren Sie Python 3.9 oder neuer, dann das Paket: python3 -m pip install holarch-api. Es braucht nichts außer Python.
  2. Öffnen Sie in Holarch Kontoeinstellungen → API-Token und erstellen Sie ein Token: Nur lesen für Skripte, die nur lesen, Lesen und schreiben für Skripte, die Änderungen vorschlagen. Beschränken Sie es auf die Projekte, die das Skript braucht.
  3. Legen Sie das Token in der Umgebungsvariablen HOLARCH_API_KEY ab.
  4. Prüfen Sie die Verbindung:
from holarch_api import Client

c = Client()
print(c.me()["user"]["email"])
for p in c.projects():
    print(p["id"], p["name"], p["role"])

Ein Projekt lesen

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 holt jeden Treffer seitenweise; entities gibt eine Seite zurück (entities, total, offset, limit). search(pid, "thermal") findet Entitäten, deren Name, Nummer, Beschreibung oder Klasse den Text enthält.

Änderungen vorschlagen

  1. Beginnen Sie einen Vorschlag: p = c.proposal(pid).
  2. Fügen Sie Änderungen hinzu. Jeder Aufruf wird sofort vom Server geprüft und schlägt mit einem Fehler fehl, wenn die Klasse, Relation oder das Attribut nicht existiert:
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…")
  1. Sehen Sie sich an, was gesammelt ist: p.get()["changes"]. Das Projekt hat sich nicht geändert.
  2. Senden Sie ihn: view = p.send("Add a TVAC test", "Covers the two thermal requirements."). view["review"] ist der Link, der das Review in Holarch öffnet.

Die Eigentümer erhalten eine Benachrichtigung und prüfen den Vorschlag über das Menü ✦ KI ▾; siehe Vorschläge von KI-Clients. Um einen Vorschlag zu verwerfen, bevor er gesendet wird, rufen Sie p.discard() auf. Um später nachzuverfolgen: c.get_proposal(pid, view["id"])["status"] ist ready, applied, rejected oder expired.

Durchgehendes Beispiel: die CubeSat-EO-1-Demo

  1. Erstellen Sie ein Token mit Nur-Lesen-Zugriff für das CubeSat-Projekt und setzen Sie HOLARCH_API_KEY.
  2. Listen Sie die Befunde der Modellprüfungen zu Anforderungen auf:
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")
  1. Bewerten Sie die Anforderungen: c.quality(pid)["results"] listet jede Anforderung mit ihrer Bewertung und ihren Befunden.
  2. Schlagen Sie mit einem Token zum Lesen und Schreiben einen Testfall für eine Anforderung vor, die keinen hat, wie unter Änderungen vorschlagen, und senden Sie ihn. Nachdem ein Eigentümer ihn angewendet hat, listen die Modellprüfungen die Anforderung nicht mehr.

SysML-v2-Projekte

Derselbe Client liest SysML v2-Projekte: model(pid) (Packages und Anzahlen), elements(pid, q=…, type=…), element(pid, "Vehicles::Engine"), requirements(pid), diagnostics(pid) und sysml_text(pid, root="Vehicles"). check_sysml(pid, text) prüft Text, ohne ihn vorzuschlagen. Um eine Änderung vorzuschlagen, senden Sie den neuen Text eines Package mit p.sysml_text(text, root="Vehicles") oder Elementbearbeitungen mit p.sysml_edits([...]); die Engine prüft jede Änderung und lehnt eine mit Fehlern ab. Siehe API und MCP in SysML v2-Projekten.

Tipps und bewährte Vorgehensweisen

  • Lesen Sie zuerst das Schema (c.schema(pid)): Es listet die Klassen-, Attribut- und Relationsnamen, die das Projekt verwendet.
  • Geben Sie jedem Skript ein eigenes Token, mit Nur-Lesen-Zugriff, wo es nur liest.
  • Sammeln Sie zusammengehörige Änderungen in einem Vorschlag und senden Sie ihn mit einem Titel und einer Zusammenfassung, die sagen, warum: Der Prüfer sieht die ganze Änderung auf einmal.
  • Halten Sie Token aus Quelldateien heraus; der Client liest aus diesem Grund HOLARCH_API_KEY.

Häufige Fehler

  • ApiError mit Code read-only-token: Das Token hat nur Lesezugriff; erstellen Sie für Vorschläge ein Token zum Lesen und Schreiben.
  • ApiError mit Code not-found bei einem Projekt, das Sie in Holarch öffnen können: Das Token ist auf andere Projekte beschränkt.
  • Eine erstellte Entität lässt sich mit entity() nicht finden: Sie existiert nur im Vorschlag, bis ein Eigentümer ihn anwendet.

Referenz

Client

Client(token=None, server=None, timeout=30.0, retries=3). token ist standardmäßig HOLARCH_API_KEY, server standardmäßig HOLARCH_SERVER oder https://app.holarch.app. Der Server muss eine https-Adresse sein.

MethodeLiefert
me()Konto, Zugriff und Ablauf des Tokens
projects()Ihre Projekte: ID, Name, Rolle, Elementanzahl, Sprache, Link
project(pid)Name, Beschreibung, Rolle, Elementanzahl, Elemente pro Klasse, Anzahl der Dokumente
schema(pid)Klassen mit Attributen und erlaubten Relationen; Relationen
entities(pid, cls=None, label=None, q=None, limit=100, offset=0)Eine Seite mit Entitäten (höchstens 500)
iter_entities(pid, cls=None, label=None, q=None, page_size=500)Jede passende Entität
search(pid, text, cls=None, limit=100)Entitäten, deren Name, Nummer, Beschreibung oder Klasse den Text enthält
entity(pid, id)Eine Entität mit Attributen, Labels und Beziehungen
documents(pid)Dokumente mit Typ und Anzahl der Abschnitte
document(pid, id)Ein Dokument mit seinen Abschnitten in Reihenfolge, nummeriert, als Nur-Text
model_checks(pid, cls=None, rule=None, limit=500, offset=0)Befunde der Modellprüfungen mit einer Zusammenfassung
quality(pid, ids=None)Die Qualitätsprüfung von Anforderungen, für die angegebenen Anforderungen oder alle
versions(pid)Gespeicherte Versionen, die der Tarif des Projekts aufbewahrt
configurations(pid)Die Produktlinie: Features, Regeln und Konfigurationen mit Auswahl, Urteil und Gültigkeit
proposal(pid)Ein Proposal für Ihren offenen Vorschlag im Projekt
get_proposal(pid, proposal_id=None)Der offene Vorschlag oder einer nach ID, mit Status und Änderungen
request(method, path, params=None, body=None)Jeder andere API-Aufruf, relativ zu /api/v1

project, entities, iter_entities, search, entity, documents, document, model_checks und quality nehmen außerdem configuration= (Nummer, Name oder ID einer Konfiguration) und effectivity= ("sn:23" oder "date:2027-03-01") an, um das Modell so zu lesen, wie eine Konfiguration einer Produktlinie es zeigt (Produktlinien).

Vorschlag

MethodeWas es vorschlägt
create(cls, name, number=None, description=None, labels=None, attributes=None, relationships=None)Eine neue Entität; relationships als Paare (relation, target); gibt ihren Verweis zurück
update(entity, name=None, number=None, description=None, labels=None, attributes=None)Geänderte Felder; ausgelassene Felder bleiben, ein auf None gesetztes Attribut verliert seinen Wert
delete(entity)Das Verschieben der Entität in den Papierkorb des Projekts
relate(source, relation, target, attributes=None)Eine neue Beziehung, von der Quelle aus benannt
unrelate(relationship)Das Entfernen einer Beziehung (ihre ID aus entity())
get()Nichts: gibt den Vorschlag mit seinen Änderungen zurück
send(title, summary="")Nichts weiter: sendet den Vorschlag zur Prüfung und gibt ihn mit dem Link zum Review zurück
discard()Nichts: verwirft den offenen Vorschlag

create und update nehmen außerdem applies_to= ("F-3 and not F-5"; "" leert es) und effectivity= ({"serials": "1-20, 25"}; {} leert es) an, und jede Änderung nimmt configuration= an, um sie als Bearbeitung in dieser Konfiguration vorzuschlagen (Produktlinien).

Fehler

Jede abgelehnte Anfrage löst holarch_api.ApiError mit message (dem Text des Servers), code, status und body aus. Die Codes sind die der REST-API. Eine mit 429 rate-limited abgelehnte Anfrage wird nach der vom Server genannten Zeit bis zu retries-mal wiederholt, bevor der Fehler ausgelöst wird.

Grenzen

  • Es gelten die Grenzen der API (API und MCP): Anfragerate, höchstens 500 Entitäten pro Seite und die Elementgrenze des Projekts, wenn ein Vorschlag angewendet wird.
  • Ein Vorschlag läuft 7 Tage nach seinem Beginn ab.
  • Der Client funktioniert mit dem gehosteten Dienst.