Başvuru
Python istemcisi
Ücretsiz holarch-api paketiyle Python betiklerinden Holarch projelerini okuyun, öğe arayın ve inceleme için değişiklik önerin; kurulum, oturum açma, her yöntem, öneriler, hatalar ve sınırlar.
Bu sayfada
Genel bakış
holarch-api, Holarch REST API için küçük bir Python paketidir. Projeleri, öğeleri, belgeleri ve denetim sonuçlarını okur, arama yapar ve değişiklikler önerir. Ücretsizdir; API'nin kendisi onu içeren planlarla gelir ve paket kişisel erişim belirtecinizi kullanır.
Paket üzerinden yapılan değişiklikler her zaman önerilerdir: sunucuda toplanırlar ve projenin sahipleri onları, YZ istemcilerinden gelen değişiklikler gibi, Holarch'ta inceler ve uygular; uygulanan her öneri tek bir Geri al ile geri alınır. Paketin bir projeyi doğrudan değiştiren yöntemi yoktur. Doğrudan yazması gereken betikler REST API'nin yazma çağrılarını kullanır.
Kavramlar
- Client: tek bir Holarch sunucusunda tek bir belirteç. Her yöntem bir istek (veya sayfa başına bir istek) gönderir ve API'nin JSON'unu Python sözlükleri ve listeleri olarak döndürür.
- Türlendirilmiş yanıtlar: paket tür bilgisi taşır (
EntityveProjectSummarygibiTypedDictşekilleri), böylece düzenleyiciler alan adlarını tamamlar ve mypy gibi tür denetleyicileri onları denetler. Sunucunun daha sonra eklediği alanlar sözlüklerde basitçe görünür. - Proposal: bir projedeki açık öneriniz. Her çağrı bir değişiklik ekler;
send()öneriyi inceleme için projenin sahiplerine verir. Bir belirtecin proje başına en çok bir açık önerisi olur. - Başvurular: bir öneride oluşturulan bir nesne henüz yoktur.
create(), aynı önerideki sonraki değişikliklerin kimlik yerine kullandığı bir başvuru (new:1,new:2, …) döndürür.
Nasıl kullanılır
Ne zaman ve neden
İstemciyi bir proje etrafındaki betikler için kullanın: kendi biçiminizde raporlar ve dışa aktarmalar, gece çalışan bir işte denetimler, girmeden önce bir kişinin incelemesi gereken başka bir araçtan içe aktarmalar. Değişiklikler öneri olarak geldiği için bir betik ekibi asla şaşırtmaz: sahipler her değişikliği uygulanmadan önce görür.
Kurma ve oturum açma
- Python 3.9 veya sonrasını, ardından paketi kurun:
python3 -m pip install holarch-api. Python dışında hiçbir şey gerektirmez. - Holarch'ta Hesap ayarları → API belirteçleri açın ve bir belirteç oluşturun: yalnızca okuyan betikler için Salt okunur, değişiklik öneren betikler için Okuma ve yazma. Onu betiğin ihtiyaç duyduğu projelerle sınırlayın.
- Belirteci
HOLARCH_API_KEYortam değişkenine koyun. - Bağlantıyı denetleyin:
from holarch_api import Client
c = Client()
print(c.me()["user"]["email"])
for p in c.projects():
print(p["id"], p["name"], p["role"])
Bir projeyi okuma
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 her eşleşmeyi sayfa sayfa getirir; entities bir sayfa döndürür (entities, total, offset, limit). search(pid, "thermal"), adı, numarası, açıklaması veya sınıfı metni içeren nesneleri bulur.
Değişiklik önerme
- Bir öneri başlatın:
p = c.proposal(pid). - Değişiklikler ekleyin. Her çağrı sunucu tarafından hemen denetlenir ve sınıf, ilişki veya öznitelik yoksa bir hatayla başarısız olur:
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…")
- Toplananlara bakın:
p.get()["changes"]. Proje değişmedi. - Gönderin:
view = p.send("Add a TVAC test", "Covers the two thermal requirements.").view["review"], incelemeyi Holarch'ta açan bağlantıdır.
Sahipler bir bildirim alır ve öneriyi ✦ YZ ▾ menüsünden inceler; bkz. YZ istemcilerinden gelen öneriler. Bir öneriyi gönderilmeden önce bırakmak için p.discard() çağırın. Daha sonra takip etmek için c.get_proposal(pid, view["id"])["status"] değeri ready, applied, rejected veya expired olur.
Uygulamalı örnek: CubeSat EO-1 demosu
- CubeSat projesi için salt okunur bir belirteç oluşturun ve
HOLARCH_API_KEYayarlayın. - Model denetimlerinin gereksinim bulgularını listeleyin:
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")
- Gereksinimleri puanlayın:
c.quality(pid)["results"]her gereksinimi puanı ve bulgularıyla listeler. - Okuma ve yazma belirteciyle, hiç test senaryosu olmayan bir gereksinim için Değişiklik önerme bölümündeki gibi bir test senaryosu önerin ve gönderin. Bir sahip onu uyguladıktan sonra model denetimleri gereksinimi artık listelemez.
SysML v2 projeleri
Aynı istemci SysML v2 projelerini okur: model(pid) (paketler ve sayılar), elements(pid, q=…, type=…), element(pid, "Vehicles::Engine"), requirements(pid), diagnostics(pid) ve sysml_text(pid, root="Vehicles"). check_sysml(pid, text) metni önermeden denetler. Bir değişiklik önermek için bir paketin yeni metnini p.sysml_text(text, root="Vehicles") ile veya öğe düzenlemelerini p.sysml_edits([...]) ile gönderin; motor her değişikliği denetler ve hatalı olanı reddeder. Bkz. SysML v2 projelerinde API ve MCP.
İpuçları ve iyi uygulamalar
- Önce şemayı okuyun (
c.schema(pid)): projenin kullandığı sınıf, öznitelik ve ilişki adlarını listeler. - Her betiğe kendi belirtecini verin; yalnızca okuyorsa salt okunur olsun.
- İlgili değişiklikleri tek bir öneride toplayın ve nedenini söyleyen bir başlık ve özetle gönderin: inceleyen tüm değişikliği bir kerede görür.
- Belirteçleri kaynak dosyaların dışında tutun; istemci bu nedenle
HOLARCH_API_KEYokur.
Yaygın hatalar
read-only-tokenkodluApiError: belirteç salt okunur; öneriler için okuma ve yazma belirteci oluşturun.- Holarch'ta açabildiğiniz bir projede
not-foundkodluApiError: belirteç başka projelerle sınırlı. - Oluşturulan bir nesne
entity()ile bulunamıyor: bir sahip onu uygulayana kadar yalnızca öneride vardır.
Başvuru
Client
Client(token=None, server=None, timeout=30.0, retries=3). token varsayılan olarak HOLARCH_API_KEY, server ise HOLARCH_SERVER veya https://app.holarch.app olur. Sunucu bir https adresi olmalıdır.
| Yöntem | Döndürdüğü |
|---|---|
me() | Belirtecin hesabı, erişimi ve süre sonu |
projects() | Projeleriniz: kimlik, ad, rol, öğe sayısı, dil, bağlantı |
project(pid) | Ad, açıklama, rol, öğe sayısı, sınıf başına öğeler, belge sayısı |
schema(pid) | Öznitelikleri ve izin verilen ilişkileriyle sınıflar; ilişkiler |
entities(pid, cls=None, label=None, q=None, limit=100, offset=0) | Bir nesne sayfası (en çok 500) |
iter_entities(pid, cls=None, label=None, q=None, page_size=500) | Eşleşen her nesne |
search(pid, text, cls=None, limit=100) | Adı, numarası, açıklaması veya sınıfı metni içeren nesneler |
entity(pid, id) | Öznitelikleri, etiketleri ve ilişkileriyle bir nesne |
documents(pid) | Türü ve bölüm sayısıyla belgeler |
document(pid, id) | Bölümleri sırayla, numaralı ve düz metin olarak bir belge |
model_checks(pid, cls=None, rule=None, limit=500, offset=0) | Bir özetle model denetimi bulguları |
quality(pid, ids=None) | Verilen gereksinimler veya tümü için gereksinim kalite denetimi |
versions(pid) | Projenin planının tuttuğu kaydedilmiş sürümler |
configurations(pid) | Ürün hattı: seçim, karar ve geçerlilikle birlikte özellikler, kurallar ve konfigürasyonlar |
proposal(pid) | Projedeki açık öneriniz için bir Proposal |
get_proposal(pid, proposal_id=None) | Durum ve değişikliklerle birlikte açık öneri veya kimliğe göre bir öneri |
request(method, path, params=None, body=None) | /api/v1 adresine göreli diğer herhangi bir API çağrısı |
project, entities, iter_entities, search, entity, documents, document, model_checks ve quality, modeli bir ürün hattının bir konfigürasyonunun gösterdiği haliyle okumak için configuration= (bir konfigürasyonun numarası, adı veya kimliği) ve effectivity= ("sn:23" veya "date:2027-03-01") de alır (Ürün hatları).
Proposal
| Yöntem | Önerdiği |
|---|---|
create(cls, name, number=None, description=None, labels=None, attributes=None, relationships=None) | Yeni bir nesne; (relation, target) çiftleri olarak relationships; başvurusunu döndürür |
update(entity, name=None, number=None, description=None, labels=None, attributes=None) | Değişen alanlar; dışarıda bırakılan alanlar kalır, None olarak ayarlanan bir öznitelik değerini kaybeder |
delete(entity) | Nesneyi projenin Çöp kutusuna taşıma |
relate(source, relation, target, attributes=None) | Kaynaktan adlandırılan yeni bir ilişki |
unrelate(relationship) | Bir ilişkiyi kaldırma (entity() içinden kimliği) |
get() | Hiçbir şey: öneriyi değişiklikleriyle döndürür |
send(title, summary="") | Başka bir şey yok: öneriyi incelemeye gönderir ve inceleme bağlantısıyla döndürür |
discard() | Hiçbir şey: açık öneriyi bırakır |
create ve update ayrıca applies_to= ("F-3 and not F-5"; "" onu temizler) ve effectivity= ({"serials": "1-20, 25"}; {} onu temizler) alır ve her değişiklik onu o konfigürasyonda bir düzenleme olarak önermek için configuration= alır (Ürün hatları).
Hatalar
Reddedilen her istek message (sunucunun metni), code, status ve body ile holarch_api.ApiError oluşturur. Kodlar REST API kodlarıdır. 429 rate-limited ile reddedilen bir istek, hata oluşturmadan önce sunucunun belirttiği süreden sonra retries kez yeniden denenir.
Sınırlar
- API'nin sınırları geçerlidir (API ve MCP): istek hızı, sayfa başına en çok 500 nesne ve bir öneri uygulandığında projenin öğe sınırı.
- Bir önerinin süresi başlatılmasından 7 gün sonra dolar.
- İstemci barındırılan hizmetle çalışır.