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

octostar/utils/workspace/delete_entities.py

@@ -0,0 +1,247 @@
+import asyncio as _asyncio
+import logging
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Dict, List
+from urllib.parse import quote
+
+import httpx
+
+_logger = logging.getLogger(__name__)
+
+from ...api.workspace_data import delete_entities
+from ..ontology import query_ontology
+from ...client import Client
+from ..exceptions import ApiConnectionError
+
+
+def _files_delete_url(client: Client, os_workspace: str, os_entity_uid: str) -> str:
+    base = client.get_base_url_v1()
+    return f"{base}/api/v1/files/delete-file/{quote(os_workspace, safe='')}/{quote(os_entity_uid, safe='')}"
+
+
+def _query_survivors_sync(os_entity_uids: List[str], client: Client) -> Dict[str, str]:
+    """Return {entity_uid: os_workspace} for every UID that still exists."""
+    uids_text = ", ".join(f"'{uid}'" for uid in os_entity_uids)
+    rows = (
+        query_ontology.sync(
+            f"SELECT `os_entity_uid`, `os_workspace` FROM `timbr`.`os_workspace_item` WHERE `os_entity_uid` IN ({uids_text})",
+            client=client,
+        )
+        or []
+    )
+    return {
+        row["os_entity_uid"]: row["os_workspace"]
+        for row in rows
+        if row.get("os_entity_uid") and row.get("os_workspace")
+    }
+
+
+async def _query_survivors_async(
+    os_entity_uids: List[str], client: Client
+) -> Dict[str, str]:
+    """Return {entity_uid: os_workspace} for every UID that still exists."""
+    uids_text = ", ".join(f"'{uid}'" for uid in os_entity_uids)
+    rows = (
+        await query_ontology.asyncio(
+            f"SELECT `os_entity_uid`, `os_workspace` FROM `timbr`.`os_workspace_item` WHERE `os_entity_uid` IN ({uids_text})",
+            client=client,
+        )
+        or []
+    )
+    return {
+        row["os_entity_uid"]: row["os_workspace"]
+        for row in rows
+        if row.get("os_entity_uid") and row.get("os_workspace")
+    }
+
+
+def _files_delete_one_sync(
+    os_workspace: str, os_entity_uid: str, client: Client
+) -> bool:
+    """DELETE /api/v1/files/delete-file/{os_workspace}/{entity_uid}. Returns True on 204, False on 404."""
+    url = _files_delete_url(client, os_workspace, os_entity_uid)
+    with httpx.Client(verify=client.verify_ssl) as httpx_client:
+        resp = httpx_client.delete(
+            url,
+            headers=client.get_headers(),
+            timeout=client.get_timeout(),
+            follow_redirects=client.follow_redirects,
+        )
+    if resp.status_code == 204:
+        return True
+    if resp.status_code == 404:
+        return False
+    raise ApiConnectionError("delete_entities (files fallback)", resp, client)
+
+
+async def _files_delete_one_async(
+    os_workspace: str, os_entity_uid: str, client: Client
+) -> bool:
+    """DELETE /api/v1/files/delete-file/{os_workspace}/{entity_uid}. Returns True on 204, False on 404."""
+    url = _files_delete_url(client, os_workspace, os_entity_uid)
+    async with httpx.AsyncClient(verify=client.verify_ssl) as httpx_client:
+        resp = await httpx_client.delete(
+            url,
+            headers=client.get_headers(),
+            timeout=client.get_timeout(),
+            follow_redirects=client.follow_redirects,
+        )
+    if resp.status_code == 204:
+        return True
+    if resp.status_code == 404:
+        return False
+    raise ApiConnectionError("delete_entities (files fallback)", resp, client)
+
+
+def sync(
+    os_entity_uids: List[str],
+    safe: bool = False,
+    raise_on_missing: bool = False,
+    client: Client = None,
+):
+    """
+    # Delete a list of local entities given their IDs
+
+    ## Arguments
+    - `os_entity_uids`: The list of IDs
+    - `safe`: Whether to raise a ValueError before removal if some entities in the list do not exist
+    - `raise_on_missing`: Whether to raise a ConnectionError if some of the entities could not be deleted
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used
+
+    ## Returns
+    The number of successfully deleted entities
+
+    ## Raises
+    - `ValueError`: If the list of IDs contain invalid entries (and safe is enabled)
+    - `ApiConnectionError`: If the request was unsuccessful on the server
+    - `ConnectionError`: If some of the entities could not be removed (and raise_on_missing is enabled)
+    """
+    assert len(os_entity_uids) > 0
+    if safe:
+        uids_text = ", ".join(f"'{uid}'" for uid in os_entity_uids)
+        uids = query_ontology.sync(
+            f"SELECT `os_entity_uid` FROM `timbr`.`os_thing` WHERE `os_entity_uid` IN ({uids_text})",
+            client=client,
+        )
+        if len(uids or []) < len(os_entity_uids):
+            raise ValueError("Attempting to remove an entity which does not exist!")
+
+    response = delete_entities.sync_detailed(json_body=os_entity_uids, client=client)
+    if response.status_code != 200:
+        raise ApiConnectionError("delete_entities", response, client)
+    deleted = response.parsed.additional_properties.get("deleted_count", 0)
+
+    if deleted >= len(os_entity_uids):
+        return deleted
+
+    # v1/entities/delete silently ignores certain entity types. Query for any survivors and fall back to the
+    # v1/files/delete-file endpoint in parallel, which handles the remaining entity types.
+    survivors = _query_survivors_sync(os_entity_uids, client)
+    if not survivors:
+        total = deleted
+        if total < len(os_entity_uids):
+            _logger.warning("Deleted only %d/%d entities", total, len(os_entity_uids))
+            if raise_on_missing:
+                raise ConnectionError(
+                    "Failed to delete some entities! (likely they did not exist prior to this call)"
+                )
+        return total
+
+    files_deleted = 0
+    max_workers = min(len(survivors), 10)
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        futures = {
+            executor.submit(_files_delete_one_sync, ws, uid, client): uid
+            for uid, ws in survivors.items()
+        }
+        for future in as_completed(futures):
+            uid = futures[future]
+            try:
+                if future.result():
+                    files_deleted += 1
+            except Exception as e:
+                _logger.error("files fallback delete failed for %s: %s", uid, e)
+
+    total = deleted + files_deleted
+    if total < len(os_entity_uids):
+        _logger.warning("Deleted only %d/%d entities", total, len(os_entity_uids))
+        if raise_on_missing:
+            raise ConnectionError(
+                "Failed to delete some entities! (likely they did not exist prior to this call)"
+            )
+    return total
+
+
+async def asyncio(
+    os_entity_uids: List[str],
+    safe: bool = False,
+    raise_on_missing: bool = False,
+    client: Client = None,
+):
+    """
+    # Delete asynchronously a list of local entities given their IDs
+
+    ## Arguments
+    (Same as sync function)
+
+    ## Returns
+    The number of successfully deleted entities
+
+    ## Raises
+    - `ValueError`: If the list of IDs contain invalid entries (and safe is enabled)
+    - `ApiConnectionError`: If the request was unsuccessful on the server
+    - `ConnectionError`: If some of the entities could not be removed (and raise_on_missing is enabled)
+    """
+    assert len(os_entity_uids) > 0
+    if safe:
+        uids_text = ", ".join(f"'{uid}'" for uid in os_entity_uids)
+        uids = await query_ontology.asyncio(
+            f"SELECT `os_entity_uid` FROM `timbr`.`os_thing` WHERE `os_entity_uid` IN ({uids_text})",
+            client=client,
+        )
+        if len(uids or []) < len(os_entity_uids):
+            raise ValueError("Attempting to remove an entity which does not exist!")
+
+    response = await delete_entities.asyncio_detailed(
+        json_body=os_entity_uids, client=client
+    )
+    if response.status_code != 200:
+        raise ApiConnectionError("delete_entities", response, client)
+    deleted = response.parsed.additional_properties.get("deleted_count", 0)
+
+    if deleted >= len(os_entity_uids):
+        return deleted
+
+    # v1/entities/delete silently ignores certain entity types. Query for any survivors and fall back to the
+    # v1/files/delete-file endpoint in parallel, which handles the remaining entity types.
+    survivors = await _query_survivors_async(os_entity_uids, client)
+    if not survivors:
+        total = deleted
+        if total < len(os_entity_uids):
+            _logger.warning("Deleted only %d/%d entities", total, len(os_entity_uids))
+            if raise_on_missing:
+                raise ConnectionError(
+                    "Failed to delete some entities! (likely they did not exist prior to this call)"
+                )
+        return total
+
+    results = await _asyncio.gather(
+        *[_files_delete_one_async(ws, uid, client) for uid, ws in survivors.items()],
+        return_exceptions=True,
+    )
+
+    files_deleted = 0
+    for uid, result in zip(survivors.keys(), results):
+        if isinstance(result, Exception):
+            _logger.error("files fallback delete failed for %s: %s", uid, result)
+        elif result:
+            files_deleted += 1
+
+    total = deleted + files_deleted
+    if total < len(os_entity_uids):
+        _logger.warning("Deleted only %d/%d entities", total, len(os_entity_uids))
+        if raise_on_missing:
+            raise ConnectionError(
+                "Failed to delete some entities! (likely they did not exist prior to this call)"
+            )
+    return total

octostar/utils/workspace/delete_entity.py

@@ -0,0 +1,81 @@
+import logging
+
+_logger = logging.getLogger(__name__)
+
+from ..ontology import query_ontology
+from ...client import Client
+from . import delete_entities as _delete_entities
+
+
+def sync(
+    os_entity_uid: str,
+    safe: bool = False,
+    raise_on_missing: bool = False,
+    client: Client = None,
+):
+    """
+    # Delete a local entity given its ID
+
+    ## Arguments
+    - `os_entity_uid`: The ID of the entity to delete
+    - `safe`: Whether to raise a ValueError before removal if the entity does not exist
+    - `raise_on_missing`: Whether to raise a ConnectionError if the entity could not be deleted
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used
+
+    ## Returns
+    True if the entity was successfully deleted, False if no entity was deleted
+
+    ## Raises
+    - `ValueError`: If the ID is not a valid entity ID (and safe is enabled)
+    - `ApiConnectionError`: If the request was unsuccessful on the server
+    - `ConnectionError`: If the entity could not be removed (and raise_on_missing is enabled)
+    """
+    if safe:
+        uids = query_ontology.sync(
+            f"SELECT `os_entity_uid` FROM `timbr`.`os_thing` WHERE `os_entity_uid`='{os_entity_uid}'",
+            client=client,
+        )
+        if not uids:
+            raise ValueError("Attempting to remove an entity which does not exist!")
+
+    deleted = _delete_entities.sync(
+        [os_entity_uid], raise_on_missing=raise_on_missing, client=client
+    )
+    return deleted >= 1
+
+
+async def asyncio(
+    os_entity_uid: str,
+    safe: bool = False,
+    raise_on_missing: bool = False,
+    client: Client = None,
+):
+    """
+    # Delete asynchronously a local entity given its ID
+
+    ## Arguments
+    - `os_entity_uid`: The ID of the entity to delete
+    - `safe`: Whether to raise a ValueError before removal if the entity does not exist
+    - `raise_on_missing`: Whether to raise a ConnectionError if the entity could not be deleted
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used
+
+    ## Returns
+    True if the entity was successfully deleted, False if no entity was deleted
+
+    ## Raises
+    - `ValueError`: If the ID is not a valid entity ID (and safe is enabled)
+    - `ApiConnectionError`: If the request was unsuccessful on the server
+    - `ConnectionError`: If the entity could not be removed (and raise_on_missing is enabled)
+    """
+    if safe:
+        uids = await query_ontology.asyncio(
+            f"SELECT `os_entity_uid` FROM `timbr`.`os_thing` WHERE `os_entity_uid`='{os_entity_uid}'",
+            client=client,
+        )
+        if not uids:
+            raise ValueError("Attempting to remove an entity which does not exist!")
+
+    deleted = await _delete_entities.asyncio(
+        [os_entity_uid], raise_on_missing=raise_on_missing, client=client
+    )
+    return deleted >= 1

octostar/utils/workspace/delete_relationship.py

@@ -0,0 +1,78 @@
+import logging
+
+_logger = logging.getLogger(__name__)
+
+from ..ontology import query_ontology
+from ...client import Client
+from . import delete_entities as _delete_entities
+
+
+def sync(
+    os_relationship_uid: str,
+    safe: bool = False,
+    raise_on_missing: bool = False,
+    client: Client = None,
+):
+    """
+    # Delete a local relationship between two entities given its ID
+
+    ## Arguments
+    - `os_relationship_uid`: The ID of the relationship to delete
+    - `safe`: Whether to raise a ValueError before removal if the relationship does not exist
+    - `raise_on_missing`: Whether to raise a ConnectionError if the relationship could not be deleted
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used
+
+    ## Returns
+    True if the relationship was successfully deleted, False if no relationship was deleted
+
+    ## Raises
+    - `ValueError`: If the ID is not a valid relationship ID (and safe is enabled)
+    - `ApiConnectionError`: If the request was unsuccessful on the server
+    - `ConnectionError`: If the relationship could not be removed (and raise_on_missing is enabled)
+    """
+    if safe:
+        uids = query_ontology.sync(
+            f"SELECT `os_entity_uid` FROM `timbr`.`os_relationship` WHERE `os_entity_uid`='{os_relationship_uid}'",
+            client=client,
+        )
+        if not uids:
+            raise ValueError("Attempting to remove an entity which does not exist!")
+
+    deleted = _delete_entities.sync(
+        [os_relationship_uid], raise_on_missing=raise_on_missing, client=client
+    )
+    return deleted >= 1
+
+
+async def asyncio(
+    os_relationship_uid: str,
+    safe: bool = False,
+    raise_on_missing: bool = False,
+    client: Client = None,
+):
+    """
+    # Delete asynchronously a local relationship between two entities given its ID
+
+    ## Arguments
+    (Same as sync function)
+
+    ## Returns
+    True if the relationship was successfully deleted, False if no relationship was deleted
+
+    ## Raises
+    - `ValueError`: If the ID is not a valid relationship ID (and safe is enabled)
+    - `ApiConnectionError`: If the request was unsuccessful on the server
+    - `ConnectionError`: If the relationship could not be removed (and raise_on_missing is enabled)
+    """
+    if safe:
+        uids = await query_ontology.asyncio(
+            f"SELECT `os_entity_uid` FROM `timbr`.`os_relationship` WHERE `os_entity_uid`='{os_relationship_uid}'",
+            client=client,
+        )
+        if not uids:
+            raise ValueError("Attempting to remove an entity which does not exist!")
+
+    deleted = await _delete_entities.asyncio(
+        [os_relationship_uid], raise_on_missing=raise_on_missing, client=client
+    )
+    return deleted >= 1

octostar/utils/workspace/delete_relationships.py

@@ -0,0 +1,85 @@
+import logging
+from typing import List
+
+_logger = logging.getLogger(__name__)
+
+from ..ontology import query_ontology
+from ...client import Client
+from . import delete_entities as _delete_entities
+
+
+def sync(
+    os_relationship_uids: List[str],
+    safe: bool = False,
+    raise_on_missing: bool = False,
+    client: Client = None,
+):
+    """
+    # Delete a list of local relationships given their IDs
+
+    ## Arguments
+    - `os_relationships_uids`: The list of IDs
+    - `safe`: Whether to raise a ValueError before removal if some relationships in the list do not exist
+    - `raise_on_missing`: Whether to raise a ConnectionError if some of the relationships could not be deleted
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used
+
+    ## Returns
+    The number of successfully deleted relationships
+
+    ## Raises
+    - `ValueError`: If the list of IDs contain invalid entries (and safe is enabled)
+    - `ApiConnectionError`: If the request was unsuccessful on the server
+    - `ConnectionError`: If some of the relationships could not be removed (and raise_on_missing is enabled)
+    """
+    assert len(os_relationship_uids) > 0
+    if safe:
+        uids_text = ", ".join(f"'{uid}'" for uid in os_relationship_uids)
+        uids = query_ontology.sync(
+            f"SELECT `os_entity_uid` FROM `timbr`.`os_relationship` WHERE `os_entity_uid` IN ({uids_text})",
+            client=client,
+        )
+        if len(uids or []) < len(os_relationship_uids):
+            raise ValueError(
+                "Attempting to remove a relationship which does not exist!"
+            )
+
+    return _delete_entities.sync(
+        os_relationship_uids, raise_on_missing=raise_on_missing, client=client
+    )
+
+
+async def asyncio(
+    os_relationship_uids: List[str],
+    safe: bool = False,
+    raise_on_missing: bool = False,
+    client: Client = None,
+):
+    """
+    # Delete asynchronously a list of local relationships given their IDs
+
+    ## Arguments
+    (Same as sync function)
+
+    ## Returns
+    The number of successfully deleted relationships
+
+    ## Raises
+    - `ValueError`: If the list of IDs contain invalid entries (and safe is enabled)
+    - `ApiConnectionError`: If the request was unsuccessful on the server
+    - `ConnectionError`: If some of the relationships could not be removed (and raise_on_missing is enabled)
+    """
+    assert len(os_relationship_uids) > 0
+    if safe:
+        uids_text = ", ".join(f"'{uid}'" for uid in os_relationship_uids)
+        uids = await query_ontology.asyncio(
+            f"SELECT `os_entity_uid` FROM `timbr`.`os_relationship` WHERE `os_entity_uid` IN ({uids_text})",
+            client=client,
+        )
+        if len(uids or []) < len(os_relationship_uids):
+            raise ValueError(
+                "Attempting to remove a relationship which does not exist!"
+            )
+
+    return await _delete_entities.asyncio(
+        os_relationship_uids, raise_on_missing=raise_on_missing, client=client
+    )

octostar/utils/workspace/delete_temporary_blob.py

@@ -0,0 +1,85 @@
+import logging
+import httpx
+
+_logger = logging.getLogger(__name__)
+
+from ...client import Client, get_default_client
+from ..commons import network_retry_strategy
+from ..exceptions import ApiConnectionError
+
+
+DEFAULT_TIMEOUT = 120
+
+
+def _delete_api_url(client: Client, filename: str) -> str:
+    """Build the blob delete API endpoint URL."""
+    base = client.get_base_url_v1()
+    return f"{base}/api/v1/files/delete-blob/{filename}"
+
+
+def sync(
+    filename: str,
+    client: Client = None,
+):
+    """
+    # Delete a temporary blob from the user's temp bucket
+
+    Permanently removes a file from the authenticated user's temporary S3 bucket.
+    Use this to clean up temporary files that are no longer needed.
+
+    ## Arguments
+    - `filename`: The name of the file in the temp bucket to delete
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used
+
+    ## Raises
+    - `ApiConnectionError`: If the deletion request failed
+    """
+    if not client:
+        client = get_default_client()
+
+    api_url = _delete_api_url(client, filename)
+    headers = dict(client.get_headers())
+
+    response = None
+    try:
+        for attempt in network_retry_strategy():
+            with attempt:
+                with httpx.Client(timeout=DEFAULT_TIMEOUT) as http_client:
+                    response = http_client.delete(api_url, headers=headers)
+                    response.raise_for_status()
+    except Exception:
+        raise ApiConnectionError("delete_temporary_blob", response, client)
+
+
+async def asyncio(
+    filename: str,
+    client: Client = None,
+):
+    """
+    # Delete a temporary blob from the user's temp bucket (async)
+
+    Permanently removes a file from the authenticated user's temporary S3 bucket.
+    Use this to clean up temporary files that are no longer needed.
+
+    ## Arguments
+    - `filename`: The name of the file in the temp bucket to delete
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used
+
+    ## Raises
+    - `ApiConnectionError`: If the deletion request failed
+    """
+    if not client:
+        client = get_default_client()
+
+    api_url = _delete_api_url(client, filename)
+    headers = dict(client.get_headers())
+
+    response = None
+    try:
+        for attempt in network_retry_strategy():
+            with attempt:
+                async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT) as http_client:
+                    response = await http_client.delete(api_url, headers=headers)
+                    response.raise_for_status()
+    except Exception:
+        raise ApiConnectionError("delete_temporary_blob", response, client)