Holarch

Довідник

Клієнт Python

Читайте проєкти Holarch, шукайте елементи та пропонуйте зміни на рецензування зі скриптів Python за допомогою безкоштовного пакета holarch-api; встановлення, вхід, кожен метод, пропозиції, помилки та ліміти.

Як цим користуватися →

На цій сторінці
  1. Огляд
  2. Поняття
  3. Як користуватися
    1. Коли й навіщо
    2. Установлення та вхід
    3. Читання проєкту
    4. Пропонування змін
    5. Робочий приклад: демопроєкт CubeSat EO-1
    6. Проєкти SysML v2
    7. Поради та добрі практики
    8. Типові помилки
  4. Довідник
    1. Клієнт
    2. Пропозиція
    3. Помилки
  5. Обмеження
  6. Пов’язані сторінки

Огляд

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.

Як користуватися

Коли й навіщо

Використовуйте клієнт для скриптів навколо проєкту: звіти й експорти у власному форматі, перевірки в нічному завданні, імпорти з іншого інструмента, які людина має переглянути до того, як вони потраплять у проєкт. Оскільки зміни надходять як пропозиції, скрипт ніколи не заскочить команду зненацька: власники бачать кожну зміну до її застосування.

Установлення та вхід

  1. Установіть Python 3.9 або новіший, потім пакет: python3 -m pip install holarch-api. Йому не потрібно нічого, крім Python.
  2. У Holarch відкрийте Налаштування облікового запису → Токени API і створіть токен: Лише читання для скриптів, що лише читають, Читання й запис для скриптів, що пропонують зміни. Обмежте його проєктами, потрібними скрипту.
  3. Помістіть токен у змінну середовища HOLARCH_API_KEY.
  4. Перевірте з’єднання:
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") знаходить сутності, назва, номер, опис чи клас яких містять текст.

Пропонування змін

  1. Почніть пропозицію: p = c.proposal(pid).
  2. Додайте зміни. Сервер одразу перевіряє кожен виклик, і той завершується помилкою, коли класу, відношення чи атрибута не існує:
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. Перегляньте, що зібрано: p.get()["changes"]. Проєкт не змінився.
  2. Надішліть її: 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

  1. Створіть токен лише для читання для проєкту CubeSat і задайте HOLARCH_API_KEY.
  2. Перелічіть зауваження перевірок моделі щодо вимог:
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. Оцініть вимоги: c.quality(pid)["results"] перелічує кожну вимогу з її оцінкою й зауваженнями.
  2. З токеном читання й запису запропонуйте тестовий випадок для вимоги, яка його не має, як у Пропонування змін, і надішліть пропозицію. Після того як власник її застосує, перевірки моделі більше не наводять цю вимогу.

Проєкти 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 днів після початку.
  • Клієнт працює з хостинговим сервісом.