Holarch

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.

Nasıl kullanılır →

Bu sayfada
  1. Genel bakış
  2. Kavramlar
  3. Nasıl kullanılır
    1. Ne zaman ve neden
    2. Kurma ve oturum açma
    3. Bir projeyi okuma
    4. Değişiklik önerme
    5. Uygulamalı örnek: CubeSat EO-1 demosu
    6. SysML v2 projeleri
    7. İpuçları ve iyi uygulamalar
    8. Yaygın hatalar
  4. Başvuru
    1. Client
    2. Proposal
    3. Hatalar
  5. Sınırlar
  6. İlgili sayfalar

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 (Entity ve ProjectSummary gibi TypedDict ş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

  1. Python 3.9 veya sonrasını, ardından paketi kurun: python3 -m pip install holarch-api. Python dışında hiçbir şey gerektirmez.
  2. 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.
  3. Belirteci HOLARCH_API_KEY ortam değişkenine koyun.
  4. 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

  1. Bir öneri başlatın: p = c.proposal(pid).
  2. 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…")
  1. Toplananlara bakın: p.get()["changes"]. Proje değişmedi.
  2. 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

  1. CubeSat projesi için salt okunur bir belirteç oluşturun ve HOLARCH_API_KEY ayarlayın.
  2. 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")
  1. Gereksinimleri puanlayın: c.quality(pid)["results"] her gereksinimi puanı ve bulgularıyla listeler.
  2. 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_KEY okur.

Yaygın hatalar

  • read-only-token kodlu ApiError: belirteç salt okunur; öneriler için okuma ve yazma belirteci oluşturun.
  • Holarch'ta açabildiğiniz bir projede not-found kodlu ApiError: 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öntemDö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.