Holarch

Справочник

Клиент Python

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

Как использовать →

На этой странице
  1. Обзор
  2. Понятия
  3. Как использовать
    1. Когда и зачем
    2. Установка и вход
    3. Чтение проекта
    4. Предложение изменений
    5. Рабочий пример: демо CubeSat EO-1
    6. Проекты SysML v2
    7. Советы и рекомендации
    8. Типичные ошибки
  4. Справочник
    1. Client
    2. Proposal
    3. Ошибки
  5. Ограничения
  6. Связанные страницы

Обзор

holarch-api — небольшой пакет Python для REST API Holarch. Он читает проекты, элементы, документы и результаты проверок, выполняет поиск и предлагает изменения. Он бесплатен; сам API входит в тарифы, которые его включают, а пакет использует ваш персональный токен доступа.

Изменения через пакет всегда являются предложениями: они собираются на сервере, а владельцы проекта рецензируют и применяют их в Holarch точно так же, как изменения от клиентов ИИ, и каждое применённое предложение отменяется одним нажатием “Отменить”. В пакете нет методов, изменяющих проект напрямую. Скрипты, которые должны писать напрямую, используют вызовы записи REST API.

Понятия

  • Client: один токен на одном сервере Holarch. Каждый метод отправляет один запрос (или по одному на страницу) и возвращает JSON API в виде словарей и списков Python.
  • Типизированные ответы: пакет содержит сведения о типах (формы TypedDict, такие как Entity и ProjectSummary), поэтому редакторы дополняют имена полей, а средства проверки типов, такие как mypy, их проверяют. Поля, которые сервер добавит позже, просто появятся в словарях.
  • Proposal: ваше открытое предложение в одном проекте. Каждый вызов добавляет одно изменение; 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

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"), чтобы прочитать модель такой, какой её показывает одна конфигурация линейки продуктов (Линейки продуктов).

Proposal

МетодЧто предлагает
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 дней после начала.
  • Клиент работает с размещённым сервисом.