Довідник
Клієнт 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, …), яке пізніші зміни в тій самій пропозиції використовують замість id.
Як користуватися
Коли й навіщо
Використовуйте клієнт для скриптів навколо проєкту: звіти й експорти у власному форматі, перевірки в нічному завданні, імпорти з іншого інструмента, які людина має переглянути до того, як вони потраплять у проєкт. Оскільки зміни надходять як пропозиції, скрипт ніколи не заскочить команду зненацька: власники бачать кожну зміну до її застосування.
Установлення та вхід
- Установіть 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() | Ваші проєкти: id, назва, роль, кількість елементів, мова, посилання |
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) | Відкрита пропозиція або одна за id зі статусом і змінами |
request(method, path, params=None, body=None) | Будь-який інший виклик API відносно /api/v1 |
project, entities, iter_entities, search, entity, documents, document, model_checks і quality також приймають configuration= (номер, назва чи id конфігурації) і 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) | Вилучення зв’язку (його id з 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 днів після початку.
- Клієнт працює з хостинговим сервісом.