octostar-python-client 0.1.759__py3-none-any.whl

octostar/utils/workspace/upsert_entities.py

@@ -0,0 +1,268 @@
+from types import SimpleNamespace
+from typing import Dict, TypedDict, Union, List, Any
+import uuid
+import httpx
+import logging
+
+_logger = logging.getLogger(__name__)
+
+from ..commons import network_retry_strategy
+from ...client import Client, get_default_client
+from ..exceptions import ApiConnectionError, ApiValidationError
+
+MAX_ERROR_DETAILS = 10
+
+
+class _EntityBaseRequired(TypedDict):
+    entity_type: str
+    fields: Dict[str, Any]
+
+
+class EntityBase(_EntityBaseRequired, total=False):
+    os_entity_uid: str
+
+
+def _raise_validation_error(
+    message,
+    client,
+    *,
+    entity_errors=None,
+    missing_entity_ids=None,
+    mismatched_keys=None,
+):
+    # status_code=200 mirrors the actual HTTP status — the server accepted
+    # the request and returned a structured per-entity breakdown; the
+    # failures were inside that response body, not at the transport layer.
+    raise ApiValidationError(
+        "upsert_entities",
+        SimpleNamespace(status_code=200, content=message),
+        client,
+        entity_errors=entity_errors,
+        missing_entity_ids=missing_entity_ids,
+        mismatched_keys=mismatched_keys,
+    )
+
+
+def _validate_response(body, entities, data, response, client):
+    expected_ids = {e["os_entity_uid"] for e in entities}
+    returned_ids = {e["entity_id"] for e in data.get("entities", [])}
+    errors_list = data.get("errors", [])
+    error_ids = {e["entity_id"] for e in errors_list}
+    accounted_ids = returned_ids | error_ids
+
+    missing_ids = expected_ids - accounted_ids
+    if missing_ids:
+        missing_entities = [e for e in body if e["entity_id"] in missing_ids]
+        _raise_validation_error(
+            f"Entities missing from response (neither in entities nor errors): "
+            f"{missing_ids}, payload: {missing_entities}",
+            client,
+            missing_entity_ids=missing_ids,
+        )
+
+    expected_keys = {(e["entity_id"], e["os_workspace"]) for e in body}
+    returned_keys = {
+        (e["entity_id"], e["os_workspace"]) for e in data.get("entities", [])
+    }
+    mismatched = returned_keys - expected_keys
+    if mismatched:
+        _raise_validation_error(
+            f"Returned entities have unexpected (entity_id, os_workspace) keys "
+            f"(possibly stale records): {mismatched}",
+            client,
+            mismatched_keys=list(mismatched),
+        )
+
+    if errors_list:
+        lines = [
+            f"  {e['entity_id']}: {e['error']}" for e in errors_list[:MAX_ERROR_DETAILS]
+        ]
+        if len(errors_list) > MAX_ERROR_DETAILS:
+            lines.append(f"  ... and {len(errors_list) - MAX_ERROR_DETAILS} more")
+        _raise_validation_error(
+            f"{len(errors_list)} entities failed to upsert:\n" + "\n".join(lines),
+            client,
+            entity_errors=errors_list,
+        )
+
+    return list({e["entity_id"]: e for e in data.get("entities", [])}.values())
+
+
+def sync(
+    os_workspace: Union[str, List[str]],
+    entities: List[EntityBase],
+    ontology_name: str = None,
+    client: Client = None,
+):
+    """
+    # Create or update a set of local entities in a workspace
+
+    ## Arguments
+    - `os_workspace`: The workspace ID, or a list of workspace IDs (one per entity)
+    - `entities`: The entities to update or create, as a list of dictionaries
+        Each dictionary must contain:
+        - `entity_type`: The concept name for the entity
+        - `fields`: A dictionary of fields for the entity, according to the concept definition in the ontology
+        Each dictionary can optionally contain:
+        - `os_entity_uid`: The ID for the entity. Only necessary in case of an update
+    - `ontology_name`: The name of the ontology
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used
+
+    ## Returns
+    The list of created/updated entity records
+
+    ## Raises
+    - `NotImplementedError`: If the operation is not supported for the ontology
+    - `ApiValidationError`: The server accepted the request but rejected
+        one or more entities. The per-entity breakdown is on the
+        exception as structured attributes (see the class docstring for
+        the shape of each):
+        - `entity_errors`: full per-entity error rows from the server
+          (``list[{"entity_id": str, "error": str}]``)
+        - `missing_entity_ids`: ``set[str]`` of IDs the server returned
+          no record for
+        - `mismatched_keys`: ``list[(entity_id, os_workspace)]`` of
+          entries returned under an unexpected workspace
+        - `invalid_fields`: ``dict[entity_id, list[field_name]]`` for
+          per-field rejections — drop these fields and re-upsert to
+          recover
+        - `reserved_keyword_entity_types`: ``set[str]`` of entity-type
+          tokens flagged as reserved keywords by the query parser
+        Subclass of `ApiConnectionError` for backward compatibility.
+    - `ApiConnectionError`: If the transport layer failed (network error,
+        non-2xx response from the upsert endpoint).
+    """
+    assert len(entities) > 0
+    for entity in entities:
+        entity["os_entity_uid"] = entity.get("os_entity_uid", None) or str(uuid.uuid4())
+        if "fields" not in entity:
+            entity["fields"] = dict()
+    if isinstance(os_workspace, str):
+        os_workspace = [os_workspace] * len(entities)
+    assert len(os_workspace) == len(entities)
+    if not ontology_name:
+        if not client:
+            client = get_default_client()
+        ontology_name = client.ontology
+    if ontology_name != client.ontology:
+        raise NotImplementedError(
+            "This operation is currently only supported on the current ontology!"
+        )
+    body = [
+        {
+            **entities[i]["fields"],
+            "entity_id": entities[i]["os_entity_uid"],
+            "entity_type": entities[i]["entity_type"],
+            "os_workspace": os_workspace[i],
+        }
+        for i in range(len(entities))
+    ]
+    endpoint_url = f"{client.get_base_url_v1()}/api/v1/entities/upsert"
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {client.token}",
+        "x-ontology": client.ontology,
+    }
+    response = None
+    try:
+        for attempt in network_retry_strategy():
+            with attempt:
+                with httpx.Client() as httpx_client:
+                    response = httpx_client.post(
+                        endpoint_url, json=body, headers=headers, timeout=120
+                    )
+                    response.raise_for_status()
+    except Exception:
+        raise ApiConnectionError("upsert_entities", response, client)
+
+    return _validate_response(body, entities, response.json(), response, client)
+
+
+async def asyncio(
+    os_workspace: Union[str, List[str]],
+    entities: List[EntityBase],
+    ontology_name: str = None,
+    client: Client = None,
+):
+    """
+    # Create or update asynchronously a set of local entities in a workspace
+
+    ## Arguments
+    - `os_workspace`: The workspace ID, or a list of workspace IDs (one per entity)
+    - `entities`: The entities to update or create, as a list of dictionaries
+        Each dictionary must contain:
+        - `entity_type`: The concept name for the entity
+        - `fields`: A dictionary of fields for the entity, according to the concept definition in the ontology
+        Each dictionary can optionally contain:
+        - `os_entity_uid`: The ID for the entity. Only necessary in case of an update
+    - `ontology_name`: The name of the ontology
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used
+
+    ## Returns
+    The list of created/updated entity records
+
+    ## Raises
+    - `NotImplementedError`: If the operation is not supported for the ontology
+    - `ApiValidationError`: The server accepted the request but rejected
+        one or more entities. The per-entity breakdown is on the
+        exception as structured attributes (see the class docstring for
+        the shape of each):
+        - `entity_errors`: full per-entity error rows from the server
+          (``list[{"entity_id": str, "error": str}]``)
+        - `missing_entity_ids`: ``set[str]`` of IDs the server returned
+          no record for
+        - `mismatched_keys`: ``list[(entity_id, os_workspace)]`` of
+          entries returned under an unexpected workspace
+        - `invalid_fields`: ``dict[entity_id, list[field_name]]`` for
+          per-field rejections — drop these fields and re-upsert to
+          recover
+        - `reserved_keyword_entity_types`: ``set[str]`` of entity-type
+          tokens flagged as reserved keywords by the query parser
+        Subclass of `ApiConnectionError` for backward compatibility.
+    - `ApiConnectionError`: If the transport layer failed (network error,
+        non-2xx response from the upsert endpoint).
+    """
+    assert len(entities) > 0
+    for entity in entities:
+        entity["os_entity_uid"] = entity.get("os_entity_uid", None) or str(uuid.uuid4())
+        if "fields" not in entity:
+            entity["fields"] = dict()
+    if isinstance(os_workspace, str):
+        os_workspace = [os_workspace] * len(entities)
+    assert len(os_workspace) == len(entities)
+    if not ontology_name:
+        if not client:
+            client = get_default_client()
+        ontology_name = client.ontology
+    if ontology_name != client.ontology:
+        raise NotImplementedError(
+            "This operation is currently only supported on the current ontology!"
+        )
+    body = [
+        {
+            **entities[i]["fields"],
+            "entity_id": entities[i]["os_entity_uid"],
+            "entity_type": entities[i]["entity_type"],
+            "os_workspace": os_workspace[i],
+        }
+        for i in range(len(entities))
+    ]
+    endpoint_url = f"{client.get_base_url_v1()}/api/v1/entities/upsert"
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {client.token}",
+        "x-ontology": client.ontology,
+    }
+    response = None
+    try:
+        for attempt in network_retry_strategy():
+            with attempt:
+                async with httpx.AsyncClient() as httpx_client:
+                    response = await httpx_client.post(
+                        endpoint_url, json=body, headers=headers, timeout=120
+                    )
+                    response.raise_for_status()
+    except Exception:
+        raise ApiConnectionError("upsert_entities", response, client)
+
+    return _validate_response(body, entities, response.json(), response, client)

octostar/utils/workspace/upsert_entity.py

@@ -0,0 +1,110 @@
+from typing import Dict, Union, Any
+import uuid
+import os
+
+from ...client import Client
+from . import upsert_entities
+
+
+def sync(
+    os_workspace: str,
+    os_entity_type: str,
+    fields: Dict[str, Any],
+    os_entity_uid: Union[str, None] = None,
+    ontology_name: str = None,
+    client: Client = None,
+):
+    """
+    # Create or update a local entity in a workspace
+
+    ## Arguments
+    - `os_workspace`: The workspace ID
+    - `os_entity_type`: The concept name for the entity
+    - `fields`: A dictionary of fields for the entity, according to the concept definition in the ontology
+    - `os_entity_uid`: The ID for the entity. Only necessary in case of an update
+    - `ontology_name`: The name of the ontology
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used
+
+    ## Returns
+    The created/updated entity record
+
+    ## Raises
+    - `NotImplementedError`: If the operation is not supported for the ontology
+    - `ApiValidationError`: The server rejected the entity. The
+        breakdown is exposed as structured attributes on the exception
+        (see the class docstring for the shape of each):
+        - `entity_errors`: ``list[{"entity_id": str, "error": str}]``
+        - `invalid_fields`: ``dict[entity_id, list[field_name]]`` —
+          drop these fields and re-upsert to recover
+        - `reserved_keyword_entity_types`: ``set[str]`` of entity-type
+          tokens flagged as reserved keywords
+        Subclass of `ApiConnectionError` for backward compatibility.
+    - `ApiConnectionError`: If the transport layer failed (network error,
+        non-2xx response).
+    """
+    result = upsert_entities.sync(
+        os_workspace,
+        [
+            {
+                "os_workspace": os_workspace,
+                "entity_type": os_entity_type,
+                "os_entity_uid": os_entity_uid,
+                "fields": fields,
+            }
+        ],
+        ontology_name=ontology_name,
+        client=client,
+    )
+    return result[0]
+
+
+async def asyncio(
+    os_workspace: str,
+    os_entity_type: str,
+    fields: Dict[str, Any],
+    os_entity_uid: Union[str, None] = None,
+    ontology_name: str = None,
+    client: Client = None,
+):
+    """
+    # Create or update asynchronously a local entity in a workspace
+
+    ## Arguments
+    - `os_workspace`: The workspace ID
+    - `os_entity_type`: The concept name for the entity
+    - `fields`: A dictionary of fields for the entity, according to the concept definition in the ontology
+    - `os_entity_uid`: The ID for the entity. Only necessary in case of an update
+    - `ontology_name`: The name of the ontology
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used
+
+    ## Returns
+    The created/updated entity record
+
+    ## Raises
+    - `NotImplementedError`: If the operation is not supported for the ontology
+    - `ApiValidationError`: The server rejected the entity. The
+        breakdown is exposed as structured attributes on the exception
+        (see the class docstring for the shape of each):
+        - `entity_errors`: ``list[{"entity_id": str, "error": str}]``
+        - `invalid_fields`: ``dict[entity_id, list[field_name]]`` —
+          drop these fields and re-upsert to recover
+        - `reserved_keyword_entity_types`: ``set[str]`` of entity-type
+          tokens flagged as reserved keywords
+        Subclass of `ApiConnectionError` for backward compatibility.
+    - `ApiConnectionError`: If the transport layer failed (network error,
+        non-2xx response).
+    """
+    result = await upsert_entities.asyncio(
+        os_workspace,
+        [
+            {
+                "os_workspace": os_workspace,
+                "entity_type": os_entity_type,
+                "os_entity_uid": os_entity_uid,
+                "fields": fields,
+            }
+        ],
+        ontology_name=ontology_name,
+        client=client,
+    )
+    return result[0]

octostar/utils/workspace/upsert_relationship.py

@@ -0,0 +1,128 @@
+from typing import Dict, Union, Any, Optional
+import uuid
+import os
+import logging
+
+_logger = logging.getLogger(__name__)
+
+from ..ontology import query_ontology
+from . import upsert_entities
+from ...types import Unset, UNSET
+from ...client import Client, get_default_client
+
+
+def sync(
+    os_entity_uid_from: str,
+    entity_type_from: str,
+    os_entity_uid_to: str,
+    entity_type_to: str,
+    os_relationship_name: str,
+    os_relationship_workspace: str,
+    relationship_fields: Dict[str, Any] = None,
+    os_relationship_uid: Optional[str] = None,
+    allow_multi_cardinality: bool = True,
+    ontology_name: str = None,
+    client: Client = None,
+):
+    """
+    # Create or update a local relationship between two entities, a source and a target
+
+    ## Arguments
+    - `os_entity_uid_from`: The source entity ID
+    - `entity_type_from`: The source entity concept name
+    - `os_entity_uid_to`: The target entity ID
+    - `entity_type_to`: The target entity concept name
+    - `os_relationship_name`: The name of the relationship, from source to target
+    - `os_relationship_workspace`: The workspace for the relationship
+    - `relationship_fields`: A dictionary of additional properties for the relationship
+    - `os_relationship_uid`: The ID for the relationship. Only necessary in case of an update
+    - `allow_multi_cardinality`: If True, allows multiple relationships from the same source, target, and relationship name. Otherwise, it updates them.
+        Note this uniqueness is only applied per-workspace
+    - `ontology_name`: The name of the ontology
+    - `client`: The Client with which to connect to Octostar
+
+    ## Returns
+    The created/updated relationship record
+
+    ## Raises
+    - `NotImplementedError`: If the operation is not supported for the ontology or for the given data
+    - `ApiValidationError`: The server rejected the relationship (the
+        underlying ``os_workspace_relationship`` record failed
+        validation, the endpoint entity_type is a reserved keyword,
+        etc.). The breakdown is exposed as structured attributes (see
+        the class docstring for the shape of each):
+        - `entity_errors`: ``list[{"entity_id": str, "error": str}]``
+        - `invalid_fields`: ``dict[entity_id, list[field_name]]`` —
+          drop these fields and re-upsert to recover
+        - `reserved_keyword_entity_types`: ``set[str]`` of entity-type
+          tokens flagged as reserved keywords
+        Subclass of `ApiConnectionError` for backward compatibility.
+    - `ApiConnectionError`: If the transport layer failed (network error,
+        non-2xx response).
+    - `ValueError`: If relationship uniqueness is enforced when the relationship is already not unique
+    """
+    if relationship_fields is None:
+        relationship_fields = {}
+    if not os_relationship_uid:
+        os_relationship_uid = str(uuid.uuid4())
+    if not client:
+        client = get_default_client()
+    if not ontology_name:
+        ontology_name = client.ontology
+    if ontology_name != client.ontology:
+        raise NotImplementedError(
+            "This operation is currently only supported on the current ontology!"
+        )
+    if not allow_multi_cardinality:
+        check_existence_query = f"""SELECT os_entity_uid FROM dtimbr.os_workspace_relationship
+            WHERE os_workspace='{os_relationship_workspace}' AND
+                  os_relationship_name='{os_relationship_name}' AND 
+                  os_entity_uid_from='{os_entity_uid_from}' AND 
+                  os_entity_type_from='{entity_type_from}' AND 
+                  os_entity_uid_to='{os_entity_uid_to}' AND
+                  os_entity_type_to='{entity_type_to}' """
+        result = query_ontology.sync(check_existence_query, client=client)
+        if result:
+            if len(result) > 1:
+                raise ValueError(
+                    "Cannot enforce cardinality = 1 when cardinality is already greater than 1!"
+                )
+            os_relationship_uid = result[0]["os_entity_uid"]
+    result = upsert_entities.sync(
+        os_relationship_workspace,
+        [
+            {
+                "entity_type": "os_workspace_relationship",
+                "os_entity_uid": os_relationship_uid,
+                "fields": {
+                    **relationship_fields,
+                    "os_entity_uid_from": os_entity_uid_from,
+                    "os_entity_type_from": entity_type_from,
+                    "os_entity_uid_to": os_entity_uid_to,
+                    "os_entity_type_to": entity_type_to,
+                    "os_relationship_name": os_relationship_name,
+                },
+            }
+        ],
+        client=client,
+    )
+    return result[0]
+
+
+async def asyncio(
+    os_workspace_from: str,
+    os_entity_uid_from: str,
+    entity_type_from: str,
+    os_workspace_to: Union[None, str],
+    os_entity_uid_to: str,
+    entity_type_to: str,
+    os_relationship_name: str,
+    relationship_fields: Dict[str, Any] = None,
+    os_relationship_uid: Union[str, Unset] = UNSET,
+    ontology_name: str = None,
+    client: Client = None,
+):
+    """
+    # NOT IMPLEMENTED
+    """
+    raise NotImplementedError()