Справочник
Клиент Python
Чтение проектов Holarch, поиск элементов и предложение изменений на рецензирование из скриптов Python с помощью бесплатного пакета holarch-api; установка, вход, все методы, предложения, ошибки и ограничения.
На этой странице
Обзор
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.
Как использовать
Когда и зачем
Используйте клиент для скриптов вокруг проекта: отчётов и экспорта в собственном формате, проверок в ночном задании, импорта из другого инструмента, который человек должен просмотреть, прежде чем данные попадут в проект. Поскольку изменения приходят как предложения, скрипт никогда не застаёт команду врасплох: владельцы видят каждое изменение до его применения.
Установка и вход
- Установите 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
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 дней после начала.
- Клиент работает с размещённым сервисом.