Referencja
Klient Python
Odczytuj projekty Holarch, przeszukuj elementy i proponuj zmiany do przeglądu ze skryptów Pythona za pomocą bezpłatnego pakietu holarch-api; instalacja, logowanie, każda metoda, propozycje, błędy i limity.
Na tej stronie
Przegląd
holarch-api to mały pakiet Python dla REST API Holarch. Odczytuje projekty, elementy, dokumenty i wyniki kontroli, wyszukuje i proponuje zmiany. Jest bezpłatny; samo API jest dostępne w planach, które je obejmują, a pakiet używa Twojego osobistego tokenu dostępu.
Zmiany wprowadzane przez pakiet są zawsze propozycjami: zbierają się na serwerze, a właściciele projektu przeglądają je i stosują w Holarch, dokładnie tak jak zmiany od klientów AI, a jedno polecenie Cofnij wycofuje każdą zastosowaną propozycję. Pakiet nie ma metod zmieniających projekt bezpośrednio. Skrypty, które muszą zapisywać bezpośrednio, używają wywołań zapisu REST API.
Pojęcia
- Klient: jeden token na jednym serwerze Holarch. Każda metoda wysyła jedno żądanie (lub jedno na stronę) i zwraca JSON z API jako słowniki i listy Python.
- Odpowiedzi z typami: pakiet zawiera informacje o typach (kształty
TypedDict, takie jakEntityiProjectSummary), więc edytory uzupełniają nazwy pól, a narzędzia sprawdzania typów, takie jak mypy, je sprawdzają. Pola dodane później przez serwer po prostu pojawiają się w słownikach. - Propozycja: Twoja otwarta propozycja w jednym projekcie. Każde wywołanie dodaje jedną zmianę;
send()przekazuje propozycję właścicielom projektu do przeglądu. Jeden token ma najwyżej jedną otwartą propozycję na projekt. - Odwołania: encja utworzona w propozycji jeszcze nie istnieje.
create()zwraca odwołanie (new:1,new:2, …), którego późniejsze zmiany w tej samej propozycji używają zamiast id.
Jak z niego korzystać
Kiedy i dlaczego
Używaj klienta do skryptów wokół projektu: raportów i eksportów we własnym formacie, kontroli w nocnym zadaniu, importów z innego narzędzia, które człowiek powinien przejrzeć przed ich wprowadzeniem. Ponieważ zmiany przychodzą jako propozycje, skrypt nigdy nie zaskakuje zespołu: właściciele widzą każdą zmianę przed jej zastosowaniem.
Instalacja i logowanie
- Zainstaluj Python 3.9 lub nowszy, a następnie pakiet:
python3 -m pip install holarch-api. Nie potrzebuje niczego poza Pythonem. - W Holarch otwórz Ustawienia konta → Tokeny API i utwórz token: Tylko do odczytu dla skryptów, które tylko odczytują, Odczyt i zapis dla skryptów proponujących zmiany. Ogranicz go do projektów potrzebnych skryptowi.
- Umieść token w zmiennej środowiskowej
HOLARCH_API_KEY. - Sprawdź połączenie:
from holarch_api import Client
c = Client()
print(c.me()["user"]["email"])
for p in c.projects():
print(p["id"], p["name"], p["role"])
Odczyt projektu
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 pobiera każde dopasowanie stronami; entities zwraca jedną stronę (entities, total, offset, limit). search(pid, "thermal") znajduje encje, których nazwa, numer, opis lub klasa zawierają tekst.
Proponowanie zmian
- Rozpocznij propozycję:
p = c.proposal(pid). - Dodaj zmiany. Każde wywołanie jest od razu sprawdzane przez serwer i kończy się błędem, gdy klasa, relacja lub atrybut nie istnieją:
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…")
- Zobacz, co zebrano:
p.get()["changes"]. Projekt się nie zmienił. - Wyślij ją:
view = p.send("Add a TVAC test", "Covers the two thermal requirements.").view["review"]to łącze otwierające przegląd w Holarch.
Właściciele otrzymują powiadomienie i przeglądają propozycję z menu ✦ AI ▾; zobacz Propozycje od klientów AI. Aby odrzucić propozycję przed jej wysłaniem, wywołaj p.discard(). Aby sprawdzić ją później, c.get_proposal(pid, view["id"])["status"] ma wartość ready, applied, rejected lub expired.
Przykład: demo CubeSat EO-1
- Utwórz token tylko do odczytu dla projektu CubeSat i ustaw
HOLARCH_API_KEY. - Wyświetl ustalenia kontroli modelu dotyczące wymagań:
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")
- Oceń wymagania:
c.quality(pid)["results"]wymienia każde wymaganie z jego oceną i ustaleniami. - Z tokenem do odczytu i zapisu zaproponuj przypadek testowy dla wymagania, które go nie ma, jak w sekcji Proponowanie zmian, i wyślij propozycję. Gdy właściciel ją zastosuje, kontrole modelu przestają wymieniać to wymaganie.
Projekty SysML v2
Ten sam klient odczytuje projekty SysML v2: model(pid) (pakiety i liczby), elements(pid, q=…, type=…), element(pid, "Vehicles::Engine"), requirements(pid), diagnostics(pid) i sysml_text(pid, root="Vehicles"). check_sysml(pid, text) sprawdza tekst bez proponowania go. Aby zaproponować zmianę, wyślij nowy tekst pakietu przez p.sysml_text(text, root="Vehicles") lub edycje obiektów przez p.sysml_edits([...]); silnik sprawdza każdą zmianę i odrzuca zmianę z błędami. Zobacz API i MCP w projektach SysML v2.
Wskazówki i dobre praktyki
- Najpierw odczytaj schemat (
c.schema(pid)): wymienia on nazwy klas, atrybutów i relacji używanych w projekcie. - Daj każdemu skryptowi własny token, tylko do odczytu tam, gdzie tylko odczytuje.
- Zbieraj powiązane zmiany w jednej propozycji i wysyłaj ją z tytułem i podsumowaniem wyjaśniającymi cel: recenzent widzi od razu całą zmianę.
- Nie umieszczaj tokenów w plikach źródłowych; dlatego klient odczytuje
HOLARCH_API_KEY.
Typowe błędy
ApiErrorz kodemread-only-token: token jest tylko do odczytu; dla propozycji utwórz token do odczytu i zapisu.ApiErrorz kodemnot-founddla projektu, który możesz otworzyć w Holarch: token jest ograniczony do innych projektów.- Utworzonej encji nie można znaleźć przez
entity(): istnieje ona tylko w propozycji, dopóki właściciel jej nie zastosuje.
Referencja
Klient
Client(token=None, server=None, timeout=30.0, retries=3). token ma domyślnie wartość HOLARCH_API_KEY, server wartość HOLARCH_SERVER lub https://app.holarch.app. Serwer musi mieć adres https.
| Metoda | Zwraca |
|---|---|
me() | Konto tokenu, dostęp i wygaśnięcie |
projects() | Twoje projekty: id, nazwa, rola, liczba elementów, język, łącze |
project(pid) | Nazwa, opis, rola, liczba elementów, elementy na klasę, liczba dokumentów |
schema(pid) | Klasy z atrybutami i dozwolonymi relacjami; relacje |
entities(pid, cls=None, label=None, q=None, limit=100, offset=0) | Jedna strona encji (najwyżej 500) |
iter_entities(pid, cls=None, label=None, q=None, page_size=500) | Każda pasująca encja |
search(pid, text, cls=None, limit=100) | Encje, których nazwa, numer, opis lub klasa zawierają tekst |
entity(pid, id) | Jedna encja z atrybutami, etykietami i relacjami |
documents(pid) | Dokumenty z typem i liczbą sekcji |
document(pid, id) | Jeden dokument z sekcjami w kolejności, numerowanymi, jako zwykły tekst |
model_checks(pid, cls=None, rule=None, limit=500, offset=0) | Ustalenia kontroli modelu z podsumowaniem |
quality(pid, ids=None) | Kontrola jakości wymagań, dla podanych wymagań lub wszystkich |
versions(pid) | Zapisane wersje przechowywane w ramach planu projektu |
configurations(pid) | Linia produktów: cechy, reguły i konfiguracje z wyborem, werdyktem i zakresem obowiązywania |
proposal(pid) | Proposal dla Twojej otwartej propozycji w projekcie |
get_proposal(pid, proposal_id=None) | Otwarta propozycja lub propozycja o danym id, ze statusem i zmianami |
request(method, path, params=None, body=None) | Dowolne inne wywołanie API, względem /api/v1 |
project, entities, iter_entities, search, entity, documents, document, model_checks i quality przyjmują też configuration= (numer, nazwa lub id konfiguracji) i effectivity= ("sn:23" lub "date:2027-03-01"), aby odczytać model tak, jak pokazuje go jedna konfiguracja linii produktów (Linie produktów).
Propozycja
| Metoda | Co proponuje |
|---|---|
create(cls, name, number=None, description=None, labels=None, attributes=None, relationships=None) | Nową encję; relationships jako pary (relation, target); zwraca jej odwołanie |
update(entity, name=None, number=None, description=None, labels=None, attributes=None) | Zmienione pola; pominięte pola pozostają, atrybut ustawiony na None traci wartość |
delete(entity) | Przeniesienie encji do kosza projektu |
relate(source, relation, target, attributes=None) | Nową relację, nazwaną od strony źródła |
unrelate(relationship) | Usunięcie relacji (jej id z entity()) |
get() | Nic: zwraca propozycję z jej zmianami |
send(title, summary="") | Nic więcej: wysyła propozycję do przeglądu i zwraca ją z łączem do przeglądu |
discard() | Nic: odrzuca otwartą propozycję |
create i update przyjmują też applies_to= ("F-3 and not F-5"; "" czyści) i effectivity= ({"serials": "1-20, 25"}; {} czyści), a każda zmiana przyjmuje configuration=, aby zaproponować ją jako edycję w tej konfiguracji (Linie produktów).
Błędy
Każde odrzucone żądanie zgłasza holarch_api.ApiError z message (tekst serwera), code, status i body. Kody są takie jak w REST API. Żądanie odrzucone z 429 rate-limited jest ponawiane po czasie podanym przez serwer, do retries razy, zanim zostanie zgłoszony błąd.
Limity
- Obowiązują limity API (API i MCP): szybkość żądań, najwyżej 500 encji na stronę i limit elementów projektu przy stosowaniu propozycji.
- Propozycja wygasa 7 dni po jej rozpoczęciu.
- Klient działa z usługą hostowaną.