مرجع
عميل Python
اقرأ مشاريع Holarch وابحث في العناصر واقترح تغييرات للمراجعة من برامج Python النصية باستخدام الحزمة المجانية holarch-api؛ التثبيت، وتسجيل الدخول، وكل دالة، والمقترحات، والأخطاء، والحدود.
في هذه الصفحة
نظرة عامة
holarch-api حزمة Python صغيرة لـ REST API الخاصة بـ Holarch. تقرأ المشاريع والعناصر والمستندات ونتائج الفحوص، وتبحث، وتقترح التغييرات. وهي مجانية؛ أما API نفسها فتأتي مع الخطط التي تتضمنها، وتستخدم الحزمة رمز الوصول الشخصي الخاص بك.
التغييرات المجراة عبر الحزمة هي دائمًا مقترحات: تتجمع على الخادم، ويراجعها مالكو المشروع ويطبّقونها في Holarch، تمامًا مثل التغييرات من عملاء الذكاء الاصطناعي، ويُلغي تراجع واحد كل مقترح مطبَّق. وليس في الحزمة أساليب تغيّر المشروع مباشرة. والبرامج النصية التي يجب أن تكتب مباشرة تستخدم استدعاءات الكتابة في REST API.
المفاهيم
- العميل: رمز واحد على خادم Holarch واحد. يرسل كل أسلوب طلبًا واحدًا (أو واحدًا لكل صفحة) ويعيد JSON الخاص بـ API بشكل قواميس وقوائم Python.
- الإجابات المنمَّطة: تحمل الحزمة معلومات الأنواع (أشكال
TypedDictمثلEntityوProjectSummary)، فتكمل المحررات أسماء الحقول وتفحصها مدققات الأنواع مثل mypy. والحقول التي يضيفها الخادم لاحقًا تظهر ببساطة في القواميس. - المقترح: مقترحك المفتوح في مشروع واحد. يضيف كل استدعاء تغييرًا واحدًا؛ ويسلّم
send()المقترح إلى مالكي المشروع للمراجعة. وللرمز الواحد مقترح مفتوح واحد على الأكثر لكل مشروع. - المراجع: الكيان المنشأ في مقترح لا يوجد بعد. ويعيد
create()مرجعًا (new:1،new:2، …) تستخدمه التغييرات اللاحقة في المقترح نفسه مكان المعرّف.
طريقة استخدامها
متى ولماذا
استخدم العميل للبرامج النصية حول مشروع: التقارير والتصديرات بصيغتك الخاصة، والفحوص في مهمة ليلية، والاستيرادات من أداة أخرى ينبغي أن يراجعها شخص قبل أن تصل. ولأن التغييرات تصل مقترحات، لا يفاجئ البرنامج النصي الفريق أبدًا: يرى المالكون كل تغيير قبل تطبيقه.
التثبيت وتسجيل الدخول
- ثبِّت Python 3.9 أو أحدث، ثم الحزمة:
python3 -m pip install holarch-api. ولا تحتاج إلى شيء غير Python. - في Holarch، افتح إعدادات الحساب ← رموز API وأنشئ رمزًا: للقراءة فقط للبرامج النصية التي تقرأ فقط، والقراءة والكتابة للبرامج النصية التي تقترح تغييرات. وقصره على المشاريع التي يحتاج إليها البرنامج النصي.
- ضع الرمز في متغير البيئة
HOLARCH_API_KEY. - تحقق من الاتصال:
from holarch_api import Client
c = Client()
print(c.me()["user"]["email"])
for p in c.projects():
print(p["id"], p["name"], p["role"])
قراءة مشروع
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 كل تطابق صفحةً صفحة؛ ويعيد entities صفحة واحدة (entities، total، offset، limit). ويعثر search(pid, "thermal") على الكيانات التي يحتوي اسمها أو رقمها أو وصفها أو فئتها على النص.
اقتراح التغييرات
- ابدأ مقترحًا:
p = c.proposal(pid). - أضف التغييرات. يفحص الخادم كل استدعاء فورًا ويفشل مع خطأ حين لا تكون الفئة أو العلاقة أو السمة موجودة:
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…")
- انظر إلى ما تجمّع:
p.get()["changes"]. لم يتغير المشروع. - أرسله:
view = p.send("Add a TVAC test", "Covers the two thermal requirements."). وview["review"]هو الرابط الذي يفتح المراجعة في Holarch.
يتلقى المالكون إشعارًا ويراجعون المقترح من قائمة ✦ الذكاء الاصطناعي ▾؛ انظر المقترحات من عملاء الذكاء الاصطناعي. ولإسقاط مقترح قبل إرساله، استدعِ p.discard(). وللمتابعة لاحقًا، يكون c.get_proposal(pid, view["id"])["status"] ready أو applied أو rejected أو expired.
مثال عملي: المشروع التوضيحي CubeSat EO-1
- أنشئ رمزًا للقراءة فقط لمشروع CubeSat واضبط
HOLARCH_API_KEY. - اسرد نتائج فحص المتطلبات في فحوص النموذج:
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")
- قيّم المتطلبات: يسرد
c.quality(pid)["results"]كل متطلب مع درجته ونتائجه. - برمز قراءة وكتابة، اقترح حالة اختبار لمتطلب ليست له واحدة، كما في اقتراح التغييرات، وأرسلها. وبعد أن يطبّقها مالك، لا تعود فحوص النموذج تسرد المتطلب.
مشاريع SysML v2
يقرأ العميل نفسه مشاريع SysML v2: model(pid) (الحزم والأعداد)، وelements(pid, q=…, type=…)، وelement(pid, "Vehicles::Engine")، وrequirements(pid)، وdiagnostics(pid) وsysml_text(pid, root="Vehicles"). ويفحص check_sysml(pid, text) النص دون اقتراحه. ولاقتراح تغيير، أرسل النص الجديد لحزمة بـ p.sysml_text(text, root="Vehicles")، أو تعديلات العناصر بـ p.sysml_edits([...])؛ ويفحص المحرك كل تغيير ويرفض الذي فيه أخطاء. انظر API وMCP في مشاريع SysML v2.
نصائح وممارسات جيدة
- اقرأ المخطط الهيكلي أولًا (
c.schema(pid)): يسرد أسماء الفئات والسمات والعلاقات التي يستخدمها المشروع. - أعطِ كل برنامج نصي رمزًا خاصًا به، للقراءة فقط حيث يقرأ فقط.
- اجمع التغييرات المترابطة في مقترح واحد وأرسله مع عنوان وملخص يقولان السبب: يرى المراجع التغيير كله دفعة واحدة.
- أبقِ الرموز خارج الملفات المصدرية؛ يقرأ العميل
HOLARCH_API_KEYلهذا السبب.
أخطاء شائعة
ApiErrorبالرمزread-only-token: الرمز للقراءة فقط؛ أنشئ رمز قراءة وكتابة للمقترحات.ApiErrorبالرمزnot-foundعلى مشروع تستطيع فتحه في Holarch: الرمز مقصور على مشاريع أخرى.- لا يمكن العثور على كيان منشأ بـ
entity(): إنه موجود في المقترح فقط حتى يطبّقه مالك.
مرجع
العميل
Client(token=None, server=None, timeout=30.0, retries=3). قيمة token الافتراضية HOLARCH_API_KEY، وقيمة server HOLARCH_SERVER أو https://app.holarch.app. ويجب أن يكون الخادم عنوان https.
| الطريقة | يُرجع |
|---|---|
me() | حساب الرمز ووصوله وانتهاء صلاحيته |
projects() | مشاريعك: المعرّف، والاسم، والدور، وعدد العناصر، واللغة، والرابط |
project(pid) | الاسم، والوصف، والدور، وعدد العناصر، والعناصر لكل فئة، وعدد المستندات |
schema(pid) | الفئات مع السمات والعلاقات المسموح بها؛ والعلاقات |
entities(pid, cls=None, label=None, q=None, limit=100, offset=0) | صفحة واحدة من الكيانات (500 على الأكثر) |
iter_entities(pid, cls=None, label=None, q=None, page_size=500) | كل كيان مطابق |
search(pid, text, cls=None, limit=100) | الكيانات التي يحتوي اسمها أو رقمها أو وصفها أو فئتها على النص |
entity(pid, id) | كيان واحد مع السمات والتسميات والعلاقات |
documents(pid) | المستندات مع النوع وعدد الأقسام |
document(pid, id) | مستند واحد مع أقسامه بالترتيب، مرقَّمة، بشكل نص عادي |
model_checks(pid, cls=None, rule=None, limit=500, offset=0) | نتائج فحوص النموذج مع ملخص |
quality(pid, ids=None) | فحص جودة المتطلبات، للمتطلبات المعطاة أو لكلها |
versions(pid) | الإصدارات المحفوظة التي تحتفظ بها خطة المشروع |
configurations(pid) | خط الإنتاج: الميزات والقواعد والتكوينات مع التحديد والحكم والسريان |
proposal(pid) | Proposal لمقترحك المفتوح في المشروع |
get_proposal(pid, proposal_id=None) | المقترح المفتوح، أو مقترح بمعرّفه، مع الحالة والتغييرات |
request(method, path, params=None, body=None) | أي استدعاء API آخر، نسبةً إلى /api/v1 |
تأخذ project وentities وiter_entities وsearch وentity وdocuments وdocument وmodel_checks وquality أيضًا configuration= (رقم تكوين أو اسمه أو معرّفه) وeffectivity= ("sn:23" أو "date:2027-03-01") لقراءة النموذج كما يعرضه تكوين واحد من خط إنتاج (خطوط الإنتاج).
المقترح
| الطريقة | ما يقترحه |
|---|---|
create(cls, name, number=None, description=None, labels=None, attributes=None, relationships=None) | كيان جديد؛ وrelationships بشكل أزواج (relation, target)؛ ويعيد مرجعه |
update(entity, name=None, number=None, description=None, labels=None, attributes=None) | الحقول المتغيرة؛ وتبقى الحقول المستبعدة، والسمة المضبوطة على None تفقد قيمتها |
delete(entity) | نقل الكيان إلى سلة محذوفات المشروع |
relate(source, relation, target, attributes=None) | علاقة جديدة، مسماة من جهة المصدر |
unrelate(relationship) | إزالة علاقة (معرّفها من entity()) |
get() | لا شيء: يعيد المقترح مع تغييراته |
send(title, summary="") | لا شيء إضافي: يرسل المقترح للمراجعة ويعيده مع رابط المراجعة |
discard() | لا شيء: يُسقط المقترح المفتوح |
تأخذ create وupdate أيضًا applies_to= ("F-3 and not F-5"؛ ويمسحه "") وeffectivity= ({"serials": "1-20, 25"}؛ ويمسحه {})، ويأخذ كل تغيير configuration= لاقتراحه تعديلًا في ذلك التكوين (خطوط الإنتاج).
الأخطاء
يرفع كل طلب مرفوض holarch_api.ApiError مع message (نص الخادم) وcode وstatus وbody. والرموز هي رموز REST API. والطلب المرفوض بـ 429 rate-limited يُعاد بعد الوقت الذي يذكره الخادم، حتى retries مرات، قبل أن يرفع الخطأ.
الحدود
- تنطبق حدود API (API وMCP): معدل الطلبات، و500 كيان على الأكثر لكل صفحة، وحد عناصر المشروع حين يُطبَّق مقترح.
- تنتهي صلاحية المقترح بعد 7 أيام من بدئه.
- يعمل العميل مع الخدمة المستضافة.