Referencia
El cliente de Python
Lea proyectos de Holarch, busque elementos y proponga cambios para su revisión desde scripts de Python con el paquete gratuito holarch-api; instalación, inicio de sesión, todos los métodos, propuestas, errores y límites.
En esta página
Resumen
holarch-api es un pequeño paquete de Python para la API REST de Holarch. Lee proyectos, elementos, documentos y resultados de comprobaciones, busca y propone cambios. Es gratuito; la API en sí viene con los planes que la incluyen, y el paquete usa su token de acceso personal.
Los cambios hechos mediante el paquete son siempre propuestas: se reúnen en el servidor, y los propietarios del proyecto los revisan y aplican en Holarch, exactamente como los cambios de los clientes de IA, y un solo Deshacer revierte cada propuesta aplicada. El paquete no tiene métodos que cambien un proyecto directamente. Los scripts que deben escribir directamente usan las llamadas de escritura de la API REST.
Conceptos
- Cliente: un token en un servidor de Holarch. Cada método envía una solicitud (o una por página) y devuelve el JSON de la API como diccionarios y listas de Python.
- Respuestas tipadas: el paquete incluye información de tipos (formas
TypedDictcomoEntityyProjectSummary), de modo que los editores completan los nombres de campo y los comprobadores de tipos como mypy los comprueban. Los campos que el servidor añada más adelante aparecen sin más en los diccionarios. - Propuesta: su propuesta abierta en un proyecto. Cada llamada añade un cambio;
send()entrega la propuesta a los propietarios del proyecto para su revisión. Un token tiene como máximo una propuesta abierta por proyecto. - Referencias: una entidad creada en una propuesta todavía no existe.
create()devuelve una referencia (new:1,new:2, …) que los cambios posteriores de la misma propuesta usan en lugar de un id.
Cómo usarlo
Cuándo y por qué
Use el cliente para scripts en torno a un proyecto: informes y exportaciones en su propio formato, comprobaciones en un trabajo nocturno, importaciones desde otra herramienta que una persona deba revisar antes de que entren. Como los cambios llegan como propuestas, un script nunca sorprende al equipo: los propietarios ven cada cambio antes de que se aplique.
Instalar e iniciar sesión
- Instale Python 3.9 o posterior y después el paquete:
python3 -m pip install holarch-api. No necesita nada más que Python. - En Holarch, abra Ajustes de la cuenta → Tokens de API y cree un token: Solo lectura para scripts que solo leen, Lectura y escritura para scripts que proponen cambios. Limítelo a los proyectos que el script necesita.
- Ponga el token en la variable de entorno
HOLARCH_API_KEY. - Compruebe la conexión:
from holarch_api import Client
c = Client()
print(c.me()["user"]["email"])
for p in c.projects():
print(p["id"], p["name"], p["role"])
Leer un proyecto
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 obtiene todas las coincidencias, una página cada vez; entities devuelve una página (entities, total, offset, limit). search(pid, "thermal") encuentra las entidades cuyo nombre, número, descripción o clase contienen el texto.
Proponer cambios
- Inicie una propuesta:
p = c.proposal(pid). - Añada cambios. El servidor comprueba cada llamada en el acto, y esta falla con un error cuando la clase, la relación o el atributo no existe:
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…")
- Mire lo que se ha reunido:
p.get()["changes"]. El proyecto no ha cambiado. - Envíela:
view = p.send("Add a TVAC test", "Covers the two thermal requirements.").view["review"]es el enlace que abre la revisión en Holarch.
Los propietarios reciben una notificación y revisan la propuesta desde el menú ✦ IA ▾; consulte Propuestas de clientes de IA. Para descartar una propuesta antes de enviarla, llame a p.discard(). Para hacer el seguimiento más tarde, c.get_proposal(pid, view["id"])["status"] es ready, applied, rejected o expired.
Ejemplo práctico: la demostración CubeSat EO-1
- Cree un token de solo lectura para el proyecto CubeSat y establezca
HOLARCH_API_KEY. - Enumere los hallazgos de requisitos de las comprobaciones del modelo:
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")
- Puntúe los requisitos:
c.quality(pid)["results"]enumera cada requisito con su puntuación y sus hallazgos. - Con un token de lectura y escritura, proponga un caso de prueba para un requisito que no tiene ninguno, como en Proponer cambios, y envíelo. Después de que un propietario lo aplique, las comprobaciones del modelo ya no enumeran el requisito.
Proyectos SysML v2
El mismo cliente lee proyectos SysML v2: model(pid) (paquetes y recuentos), elements(pid, q=…, type=…), element(pid, "Vehicles::Engine"), requirements(pid), diagnostics(pid) y sysml_text(pid, root="Vehicles"). check_sysml(pid, text) comprueba texto sin proponerlo. Para proponer un cambio, envíe el texto nuevo de un paquete con p.sysml_text(text, root="Vehicles"), o ediciones de elementos con p.sysml_edits([...]); el motor comprueba cada cambio y rechaza los que tienen errores. Consulte La API y MCP en proyectos SysML v2.
Consejos y buenas prácticas
- Lea primero el esquema (
c.schema(pid)): enumera los nombres de clases, atributos y relaciones que usa el proyecto. - Dé a cada script su propio token, de solo lectura donde solo lee.
- Reúna los cambios relacionados en una propuesta y envíela con un título y un resumen que digan por qué: el revisor ve todo el cambio a la vez.
- Mantenga los tokens fuera de los archivos de código fuente; por ese motivo, el cliente lee
HOLARCH_API_KEY.
Errores habituales
ApiErrorcon el códigoread-only-token: el token es de solo lectura; cree un token de lectura y escritura para las propuestas.ApiErrorcon el códigonot-founden un proyecto que puede abrir en Holarch: el token está limitado a otros proyectos.- Una entidad creada no se encuentra con
entity(): solo existe en la propuesta hasta que un propietario la aplica.
Referencia
Cliente
Client(token=None, server=None, timeout=30.0, retries=3). token toma de forma predeterminada HOLARCH_API_KEY, y server, HOLARCH_SERVER o https://app.holarch.app. El servidor debe ser una dirección https.
| Método | Devuelve |
|---|---|
me() | La cuenta, el acceso y la caducidad del token |
projects() | Sus proyectos: id, nombre, rol, número de elementos, idioma, enlace |
project(pid) | Nombre, descripción, rol, número de elementos, elementos por clase, número de documentos |
schema(pid) | Clases con atributos y relaciones permitidas; relaciones |
entities(pid, cls=None, label=None, q=None, limit=100, offset=0) | Una página de entidades (como máximo 500) |
iter_entities(pid, cls=None, label=None, q=None, page_size=500) | Todas las entidades que coinciden |
search(pid, text, cls=None, limit=100) | Entidades cuyo nombre, número, descripción o clase contienen el texto |
entity(pid, id) | Una entidad con atributos, etiquetas y relaciones |
documents(pid) | Documentos con tipo y número de secciones |
document(pid, id) | Un documento con sus secciones en orden, numeradas, como texto sin formato |
model_checks(pid, cls=None, rule=None, limit=500, offset=0) | Hallazgos de las comprobaciones del modelo con un resumen |
quality(pid, ids=None) | La comprobación de calidad de los requisitos, para los requisitos indicados o para todos |
versions(pid) | Las versiones guardadas que conserva el plan del proyecto |
configurations(pid) | La línea de productos: características, reglas y configuraciones con selección, veredicto y aplicabilidad |
proposal(pid) | Un Proposal para su propuesta abierta en el proyecto |
get_proposal(pid, proposal_id=None) | La propuesta abierta, o una por id, con estado y cambios |
request(method, path, params=None, body=None) | Cualquier otra llamada a la API, relativa a /api/v1 |
project, entities, iter_entities, search, entity, documents, document, model_checks y quality también aceptan configuration= (el número, el nombre o el id de una configuración) y effectivity= ("sn:23" o "date:2027-03-01") para leer el modelo tal como lo muestra una configuración de una línea de productos (Líneas de productos).
Propuesta
| Método | Qué propone |
|---|---|
create(cls, name, number=None, description=None, labels=None, attributes=None, relationships=None) | Una entidad nueva; relationships como pares (relation, target); devuelve su referencia |
update(entity, name=None, number=None, description=None, labels=None, attributes=None) | Campos cambiados; los campos omitidos se mantienen, y un atributo establecido en None pierde su valor |
delete(entity) | Mover la entidad a la Papelera del proyecto |
relate(source, relation, target, attributes=None) | Una relación nueva, nombrada desde el origen |
unrelate(relationship) | Quitar una relación (su id de entity()) |
get() | Nada: devuelve la propuesta con sus cambios |
send(title, summary="") | Nada más: envía la propuesta a revisión y la devuelve con el enlace de revisión |
discard() | Nada: descarta la propuesta abierta |
create y update también aceptan applies_to= ("F-3 and not F-5"; "" lo borra) y effectivity= ({"serials": "1-20, 25"}; {} la borra), y todo cambio acepta configuration= para proponerlo como edición en esa configuración (Líneas de productos).
Errores
Toda solicitud rechazada lanza holarch_api.ApiError con message (el texto del servidor), code, status y body. Los códigos son los de la API REST. Una solicitud rechazada con 429 rate-limited se reintenta después del tiempo que indica el servidor, hasta retries veces, antes de lanzar el error.
Límites
- Se aplican los límites de la API (API y MCP): la frecuencia de solicitudes, como máximo 500 entidades por página y el límite de elementos del proyecto cuando se aplica una propuesta.
- Una propuesta caduca 7 días después de iniciarse.
- El cliente funciona con el servicio alojado.