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

octostar/utils/workspace/saved_searches/create_saved_search.py

@@ -0,0 +1,183 @@
+from typing import List, Optional, Any, Union, TypedDict
+import logging
+import uuid
+
+_logger = logging.getLogger(__name__)
+
+from .. import upsert_entity
+from ...ontology import fetch_ontology_data
+from ....client import Client
+
+
+class SupersetFilter(TypedDict):
+    pass
+
+
+class SimpleSupersetFilter(SupersetFilter):
+    """
+    # Represents a primitive superset filter using a (col, op, val) tuple.
+
+    ## Attributes:
+    - **col** (`str`): The timbr column involved in the filter as the first operand.
+    - **op** (`str`): The operator name, e.g. `"=="`, `"IN"`, `"LIKE"`.
+    - **val** (`Any`, `List[Any]`): The value (or values) involved in the filter as the second operand.
+    """
+
+    col: str
+    op: str
+    val: Union[Any, List[Any]]
+
+
+class ComplexSupersetFilter(SupersetFilter):
+    """
+    # Represents a nested superset filter combined via a logical boolean operator.
+
+    ## Attributes:
+    - **operator** (`str`): The SQL logical operator to apply to all operands, e.g. `AND`, `OR`.
+    - **operands** (`List[SupersetFilter]`): A list of superset filters onto which the logical operator is applied.
+    """
+
+    operator: str
+    operands: List[SupersetFilter]
+    operator: str
+    operands: List[SupersetFilter]
+
+
+def sync(
+    os_workspace: str,
+    name: str,
+    entity_type: str,
+    filter: List[SupersetFilter],
+    path: str = None,
+    os_entity_uid: Optional[str] = None,
+    fields: dict = {},
+    client: Optional[Client] = None,
+):
+    """
+    # Create or update a local saved search in a workspace
+
+    ## Arguments
+    - `os_workspace`: The workspace ID
+    - `name`: The name for the saved search
+    - `entity_type`: The entity type for which to apply the filter
+    - `filter`: The superset filter for the saved search
+    - `path`: The path to the saved search file in the workspace, excluding the saved search filename
+    - `os_entity_uid`: The unique identifier for the saved search
+    - `fields`: Additional fields to include in the entity record
+    - `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
+    - `ConnectionError`: If the operation was unsuccessful on the server
+    """
+    icon = None
+    if not os_entity_uid:
+        os_entity_uid = str(uuid.uuid4())
+    try:
+        ontology = fetch_ontology_data.sync(client=client)
+        curr_concept = ontology["concepts"][entity_type]
+        while not icon:
+            icon = curr_concept["tags"].get("icon")
+            if not icon:
+                curr_concept = ontology["concepts"][curr_concept["parents"][0]]
+    except Exception:
+        logging.warning("Warning: Could not assign icon to saved search!")
+    return upsert_entity.sync(
+        os_workspace=os_workspace,
+        os_entity_type="os_wsfs_object",
+        os_entity_uid=os_entity_uid,
+        fields={
+            **fields,
+            "os_item_content_type": "os_saved_search",
+            "os_item_name": name,
+            "os_icon": icon,
+            "os_item_content": {
+                "concept": entity_type,
+                "crossFilters": [
+                    {
+                        "id": str(uuid.uuid4()),
+                        "extraFormData": {
+                            "filters": filter,
+                        },
+                        "filterState": {},
+                        "ownState": {},
+                    }
+                ],
+                "filters": [],
+                "datasourcesInScope": {},
+            },
+            "os_parent_folder": os_workspace,
+            "#os_path": path or "",
+        },
+        client=client,
+    )
+
+
+async def asyncio(
+    os_workspace: str,
+    name: str,
+    entity_type: str,
+    filter: List[SupersetFilter],
+    path: str = None,
+    os_entity_uid: Optional[str] = None,
+    fields: dict = {},
+    client: Optional[Client] = None,
+):
+    """
+    # Create or update asynchronously a local saved search in a workspace
+
+    ## Arguments
+    (Same as sync function)
+
+    ## Returns
+    The created/updated entity record
+
+    ## Raises
+    - `NotImplementedError`: If the operation is not supported for the ontology
+    - `ConnectionError`: If the operation was unsuccessful on the server
+    """
+    icon = None
+    if not os_entity_uid:
+        os_entity_uid = str(uuid.uuid4())
+    try:
+        ontology = fetch_ontology_data.sync(client=client)
+        curr_concept = ontology["concepts"][entity_type]
+        while not icon:
+            icon = curr_concept["tags"].get("icon")
+            if not icon:
+                curr_concept = ontology["concepts"][curr_concept["parents"][0]]
+    except Exception:
+        logging.warning("Warning: Could not assign icon to saved search!")
+
+    return upsert_entity.sync(
+        os_workspace=os_workspace,
+        os_entity_type="os_wsfs_object",
+        os_entity_uid=os_entity_uid,
+        fields={
+            **fields,
+            "os_item_content_type": "os_saved_search",
+            "os_item_name": name,
+            "os_icon": icon,
+            "os_item_content": {
+                "concept": entity_type,
+                "crossFilters": [
+                    {
+                        "id": str(uuid.uuid4()),
+                        "extraFormData": {
+                            "filters": filter,
+                        },
+                        "filterState": {},
+                        "ownState": {},
+                    }
+                ],
+                "filters": [],
+                "datasourcesInScope": {},
+            },
+            "os_parent_folder": os_workspace,
+            "#os_path": path or "",
+        },
+        client=client,
+    )

octostar/utils/workspace/tags/delete_tag_from_entities.py

@@ -0,0 +1,96 @@
+from typing import Dict, TypedDict, Union, List, Any, Optional
+import os
+import uuid
+import logging
+
+_logger = logging.getLogger(__name__)
+
+from ....api.workspace_tags import delete_tag_from_entities
+from ....models.entity import Entity as TagEntity
+from ....client import Client, get_default_client
+from ....types import UNSET
+from ...exceptions import ApiConnectionError
+
+
+class Entity(TypedDict):
+    os_entity_uid: str
+    entity_type: str
+
+
+def sync(
+    os_workspace: str,
+    entities: List[Entity],
+    tag_uid: str,
+    ontology_name: str = None,
+    client: Client = None,
+):
+    """
+    # Remove a tag from a list of entities
+
+    ## Arguments
+    - `os_workspace`: The workspace ID of the tag
+    - `entities`: The entities to tag, as a list of dictionaries
+        Each dictionary must contain:
+        - `os_entity_uid`: The unique ID for the entity
+        - `entity_type`: The concept name for the entity
+    - `tag_uid`: The unique ID of the tag
+    - `ontology_name`: The name of the ontology
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used
+
+    ## Raises
+    - `NotImplementedError`: If the operation is not supported for the ontology
+    - `ApiConnectionError`: If the operation was unsuccessful on the server
+    """
+    assert len(entities) > 0
+    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!"
+        )
+    entities_to_untag = [
+        TagEntity(entity["os_entity_uid"], entity["entity_type"]) for entity in entities
+    ]
+    response = delete_tag_from_entities.sync_detailed(
+        os_workspace, tag_uid, json_body=entities_to_untag, client=client
+    )
+    if response.status_code != 200:
+        raise ApiConnectionError("delete_tag_from_entities", response, client)
+
+
+async def asyncio(
+    os_workspace: str,
+    entities: List[Entity],
+    tag_uid: str,
+    ontology_name: str = None,
+    client: Client = None,
+):
+    """
+    # Remove asynchronously a tag from a list of entities
+
+    ## Arguments
+    (Same as sync function)
+
+    ## Raises
+    - `NotImplementedError`: If the operation is not supported for the ontology
+    - `ApiConnectionError`: If the operation was unsuccessful on the server
+    """
+    assert len(entities) > 0
+    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!"
+        )
+    entities_to_untag = [
+        TagEntity(entity["os_entity_uid"], entity["entity_type"]) for entity in entities
+    ]
+    response = await delete_tag_from_entities.asyncio_detailed(
+        os_workspace, tag_uid, json_body=entities_to_untag, client=client
+    )
+    if response.status_code != 200:
+        raise ApiConnectionError("delete_tag_from_entities", response, client)

octostar/utils/workspace/tags/tag_entities.py

@@ -0,0 +1,175 @@
+from typing import TypedDict, List, Optional
+
+from ...ontology import query_ontology
+from ....api.workspace_tags import tag_entities
+from ....models.entity import Entity as TagEntity
+from ....client import Client, get_default_client
+from ....types import UNSET
+from ...exceptions import ApiConnectionError
+
+
+class Entity(TypedDict):
+    os_entity_uid: str
+    entity_type: str
+
+
+def sync(
+    os_workspace: str,
+    entities: List[Entity],
+    existing_tag_uid: Optional[str] = None,
+    tag_name: Optional[str] = None,
+    new_tag_color: Optional[str] = None,
+    tag_group: Optional[str] = None,
+    new_tag_order: Optional[int] = -1,
+    ontology_name: str = None,
+    client: Client = None,
+):
+    """
+    # Tag a list of entities with a tag
+
+    The tag can be a new tag or an existing one.
+
+    ## Arguments
+    - `os_workspace`: The workspace ID in which to write the tag relationships (and the tag itself, if a new one is created)
+    - `entities`: The entities to tag, as a list of dictionaries
+        Each dictionary must contain:
+        - `os_entity_uid`: The unique ID for the entity
+        - `entity_type`: The concept name for the entity
+    - `existing_tag_uid`: The unique ID of the tag, if an existing tag is used
+    - `tag_name`: A label for the tag. If no tag with this name and group pair exists, it is created
+    - `new_tag_color`: A color (in hex "#ffffff" format) for the tag, if a new tag is used
+    - `tag_group`: A label used to group the tag with other tags. If no tag with this name and group pair exists, it is created
+    - `new_tag_order`: The order of the tag within its group, if a new tag is used
+    - `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 tag record
+
+    ## Raises
+    - `NotImplementedError`: If the operation is not supported for the ontology
+    - `ApiConnectionError`: If the operation was unsuccessful on the server
+    - `ConnectionError`: If the tag returned from the response is ambiguous
+    """
+    assert len(entities) > 0
+    assert bool(existing_tag_uid) ^ bool(tag_name)  # xor
+    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!"
+        )
+    entities_to_tag = [
+        TagEntity(entity["os_entity_uid"], entity["entity_type"]) for entity in entities
+    ]
+    response = tag_entities.sync_detailed(
+        os_workspace,
+        tag=existing_tag_uid or tag_name,
+        json_body=entities_to_tag,
+        color=new_tag_color or UNSET,
+        group=tag_group or UNSET,
+        order=new_tag_order or UNSET,
+        client=client,
+    )
+    if response.status_code != 200 or (
+        response.parsed and response.parsed.get("status") != "success"
+    ):
+        raise ApiConnectionError("tag_entities", response, client)
+    assigned_tag = list(
+        {entity["os_entity_uid_to"] for entity in (response.parsed.get("data") or [])}
+    )
+    if not len(assigned_tag) == 1:
+        raise ConnectionError(
+            f"tag_entities failed, tag upsertion ambiguous or failed! Returned the following tags: "
+            + str(assigned_tag)
+        )
+    assigned_tag = assigned_tag[0]
+    full_assigned_tag = query_ontology.sync(
+        f"SELECT * FROM dtimbr.os_tag WHERE entity_id='{assigned_tag}'",
+        ontology_name=ontology_name,
+        client=client,
+    )
+    return full_assigned_tag[0]
+
+
+async def asyncio(
+    os_workspace: str,
+    entities: List[Entity],
+    existing_tag_uid: Optional[str] = None,
+    tag_name: Optional[str] = None,
+    new_tag_color: Optional[str] = None,
+    tag_group: Optional[str] = None,
+    new_tag_order: Optional[int] = -1,
+    ontology_name: str = None,
+    client: Client = None,
+):
+    """
+    # Tag asynchronously a list of entities with a tag
+
+    The tag can be a new tag or an existing one.
+
+    ## Arguments
+    - `os_workspace`: The workspace ID in which to write the tag relationships (and the tag itself, if a new one is created)
+    - `entities`: The entities to tag, as a list of dictionaries
+        Each dictionary must contain:
+        - `os_entity_uid`: The unique ID for the entity
+        - `entity_type`: The concept name for the entity
+    - `existing_tag_uid`: The unique ID of the tag, if an existing tag is used
+    - `tag_name`: A label for the tag. If no tag with this name and group pair exists, it is created
+    - `new_tag_color`: A color (in hex "#ffffff" format) for the tag, if a new tag is used
+    - `tag_group`: A label used to group the tag with other tags. If no tag with this name and group pair exists, it is created
+    - `new_tag_order`: The order of the tag within its group, if a new tag is used
+    - `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 tag record
+
+    ## Raises
+    - `NotImplementedError`: If the operation is not supported for the ontology
+    - `ApiConnectionError`: If the operation was unsuccessful on the server
+    - `ConnectionError`: If the tag returned from the response is ambiguous
+    """
+    assert len(entities) > 0
+    assert bool(existing_tag_uid) ^ bool(tag_name)  # xor
+    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!"
+        )
+    entities_to_tag = [
+        TagEntity(entity["os_entity_uid"], entity["entity_type"]) for entity in entities
+    ]
+    response = await tag_entities.asyncio_detailed(
+        os_workspace,
+        tag=existing_tag_uid or tag_name,
+        json_body=entities_to_tag,
+        color=new_tag_color or UNSET,
+        group=tag_group or UNSET,
+        order=new_tag_order or UNSET,
+        client=client,
+    )
+    if response.status_code != 200 or (
+        response.parsed and response.parsed.get("status") != "success"
+    ):
+        raise ApiConnectionError("tag_entities", response, client)
+    assigned_tag = list(
+        {entity["os_entity_uid_to"] for entity in (response.parsed.get("data") or [])}
+    )
+    if not len(assigned_tag) == 1:
+        raise ConnectionError(
+            f"tag_entities failed, tag upsertion ambiguous or failed! Returned the following tags: "
+            + str(assigned_tag)
+        )
+    assigned_tag = assigned_tag[0]
+    full_assigned_tag = await query_ontology.asyncio(
+        f"SELECT * FROM dtimbr.os_tag WHERE entity_id='{assigned_tag}'",
+        ontology_name=ontology_name,
+        client=client,
+    )
+    return full_assigned_tag[0]