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

octostar/utils/workspace/linkcharts/create_linkchart.py

@@ -0,0 +1,241 @@
+import json
+import uuid
+from typing import List, Optional, TypedDict
+
+from ....client import Client, get_default_client
+from ..write_attachment import _create_entity_async, _create_entity_sync
+
+# Linkcharts are stored as os_file entities whose attachment body holds the
+# graph settings JSON; this MIME type tells the linkchart how to read it.
+LINKCHART_CONTENT_TYPE = "application/octostar-linkchart-settings+json"
+
+
+def _normalize_nodes(nodes: List["Node"]) -> List[dict]:
+    return [
+        {
+            **{
+                k: v
+                for k, v in node.items()
+                if k not in ["entity_type", "entity_label", "entity_id"]
+            },
+            "entity_type": node["entity_type"],
+            "entity_label": node["entity_label"],
+            "entity_id": node["entity_id"],
+        }
+        for node in nodes
+    ]
+
+
+def _linkchart_v1_content(
+    nodes: Optional[List["Node"]], edges: Optional[List["Edge"]]
+) -> str:
+    """Serialize nodes/edges into the LinkChart V1 saved-state the chart reads natively.
+
+    Nodes become the top-level entity list; each edge resolves its endpoints to those
+    entities and carries the label as a relationship. Duplicate nodes and edges are
+    collapsed so the graph never receives colliding element ids.
+    """
+    normalized = _normalize_nodes(nodes) if nodes else []
+
+    v1_nodes: List[dict] = []
+    nodes_by_id: dict = {}
+    # Key by entity_id alone so dedup matches the edge-endpoint lookup below.
+    for node in normalized:
+        entity_id = node["entity_id"]
+        if entity_id in nodes_by_id:
+            continue
+        nodes_by_id[entity_id] = node
+        v1_nodes.append(node)
+
+    v1_edges: List[dict] = []
+    seen_edges = set()
+    for edge in edges or []:
+        source = nodes_by_id.get(edge["from_node"])
+        target = nodes_by_id.get(edge["to_node"])
+        if source is None or target is None:
+            continue
+        relationship_name = edge["label"]
+        key = (
+            source["entity_type"],
+            source["entity_id"],
+            relationship_name,
+            target["entity_type"],
+            target["entity_id"],
+        )
+        if key in seen_edges:
+            continue
+        seen_edges.add(key)
+        extras = {
+            k: v for k, v in edge.items() if k not in ("from_node", "to_node", "label")
+        }
+        v1_edges.append(
+            {
+                **extras,
+                "from": source,
+                "to": target,
+                "relationship": {"relationship_name": relationship_name},
+            }
+        )
+
+    return json.dumps(
+        {
+            "format": "LinkChart V1",
+            "nodes": v1_nodes,
+            "edges": v1_edges,
+        }
+    )
+
+
+def _linkchart_entity_fields(
+    os_workspace: str,
+    os_entity_uid: str,
+    name: Optional[str],
+    path: Optional[str],
+    fields: dict,
+) -> dict:
+    return {
+        **fields,
+        "entity_id": os_entity_uid,
+        "entity_type": "os_file",
+        "entity_label": name,
+        "os_item_name": name,
+        "os_item_type": "os_file",
+        "os_item_content_type": LINKCHART_CONTENT_TYPE,
+        "os_parent_folder": os_workspace,
+        "#os_path": path,
+    }
+
+
+class _NodeRequired(TypedDict):
+    entity_type: str
+    entity_label: str
+    entity_id: str
+
+
+class Node(_NodeRequired, total=False):
+    """
+    # Represents an Entity in the Linkchart
+
+    ## Attributes:
+        - `entity_type` (str): The type of the entity.
+        - `entity_label` (str): The label of the entity.
+        - `entity_id` (str): The unique identifier for the entity.
+        - `**kwargs`: Any additional fields for the entity. Note that if this entity's ID exists in the data,
+          the ontology fields will be fetched by the linkchart regardless of this attribute.
+    """
+
+    pass  # this allows further kwargs
+
+
+class _EdgeRequired(TypedDict):
+    from_node: str
+    to_node: str
+    label: str
+
+
+class Edge(_EdgeRequired, total=False):
+    """
+    # Represents a Relationship between Two Entities in the Linkchart
+
+    ## Attributes:
+        - `from_node` (str): The unique identifier (entity_id) of the source node.
+        - `to_node` (str): The unique identifier (entity_id) of the target node.
+        - `label` (str): The label describing the relationship.
+        - `**kwargs`: Any additional fields for the relationship. Note that if this relationship's ID exists in the data,
+          the ontology fields will be fetched by the linkchart regardless of this attribute.
+    """
+
+    pass  # this allows further kwargs
+
+
+def sync(
+    os_workspace: str,
+    name: Optional[str] = None,
+    nodes: Optional[List[Node]] = None,
+    edges: Optional[List[Edge]] = None,
+    path: Optional[str] = None,
+    os_entity_uid: Optional[str] = None,
+    fields: dict = {},
+    client: Optional[Client] = None,
+):
+    """
+    # Create or update a local linkchart in a workspace
+
+    ## Arguments
+    - `os_workspace`: The workspace ID.
+    - `name`: The name for the linkchart.
+    - `nodes`: A list of entities to add to the linkchart.
+    - `edges`: A list of edges to add to the linkchart.
+    - `path`: The path to the linkchart file in the workspace, excluding the linkchart filename.
+    - `os_entity_uid`: The entity ID for the linkchart. Only necessary in case of an update to the linkchart.
+    - `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.
+    """
+    if not client:
+        client = get_default_client()
+    if not os_entity_uid:
+        os_entity_uid = str(uuid.uuid4())
+
+    content = _linkchart_v1_content(nodes, edges)
+    return _create_entity_sync(
+        os_workspace=os_workspace,
+        entity_fields=_linkchart_entity_fields(
+            os_workspace, os_entity_uid, name, path, fields
+        ),
+        file=content.encode("utf-8"),
+        content_type=LINKCHART_CONTENT_TYPE,
+        client=client,
+    )
+
+
+async def asyncio(
+    os_workspace: str,
+    name: Optional[str] = None,
+    nodes: Optional[List[Node]] = None,
+    edges: Optional[List[Edge]] = None,
+    path: Optional[str] = None,
+    os_entity_uid: Optional[str] = None,
+    fields: dict = {},
+    client: Optional[Client] = None,
+):
+    """
+    Create or update asynchronously a local linkchart in a workspace.
+
+    Args:
+        os_workspace: The workspace ID.
+        name: The name for the linkchart.
+        nodes: A list of entities to add to the linkchart.
+        edges: A list of edges to add to the linkchart.
+        path: The path to the linkchart file in the workspace, excluding the linkchart filename.
+        os_entity_uid: The entity ID for the linkchart. Only necessary in case of an update to the linkchart.
+        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.
+    """
+    if not client:
+        client = get_default_client()
+    if not os_entity_uid:
+        os_entity_uid = str(uuid.uuid4())
+
+    content = _linkchart_v1_content(nodes, edges)
+    return await _create_entity_async(
+        os_workspace=os_workspace,
+        entity_fields=_linkchart_entity_fields(
+            os_workspace, os_entity_uid, name, path, fields
+        ),
+        file=content.encode("utf-8"),
+        content_type=LINKCHART_CONTENT_TYPE,
+        client=client,
+    )

octostar/utils/workspace/permissions/PermissionLevel.py

@@ -0,0 +1,8 @@
+from enum import IntEnum
+
+
+class PermissionLevel(IntEnum):
+    NONE = 0
+    READ = 1
+    WRITE = 2
+    ADMIN = 4

octostar/utils/workspace/permissions/__init__.py

@@ -0,0 +1 @@
+from .PermissionLevel import PermissionLevel

octostar/utils/workspace/permissions/get_permissions.py

@@ -0,0 +1,81 @@
+import logging
+from typing import List, Union
+
+logger = logging.getLogger(__name__)
+
+from .PermissionLevel import PermissionLevel
+from ....api.workspace_permissions import get_permissions
+from ....client import Client
+from ...exceptions import ApiConnectionError
+
+
+def _parse_permissions_response(response, client):
+    """Parse the permissions response."""
+    if response.status_code != 200:
+        raise ApiConnectionError("get_permissions", response, client)
+
+    parsed = response.parsed
+    if parsed is None:
+        raise ApiConnectionError("get_permissions", response, client)
+
+    permissions_list = getattr(parsed, "additional_properties", {}).get("permissions")
+    if permissions_list is None:
+        raise ApiConnectionError("get_permissions", response, client)
+
+    return {
+        p["workspace"]: PermissionLevel(p["permission_level"])
+        for p in permissions_list
+        if "workspace" in p and "permission_level" in p
+    }
+
+
+def sync(os_workspace: Union[List[str], str], client: Client = None):
+    """
+    # Get permissions for workspaces
+
+    Get the permissions for one or more workspaces.
+
+    ## Arguments
+    - `os_workspace`: The ID (or list of IDs) of the workspaces to find permissions for.
+    - `client`: The Client with which to connect to Octostar, which is also the user for
+                which the permissions are given. If None, the default one is used.
+
+    ## Returns
+    A dictionary, where each key is a workspace ID and each value is the permission
+    level for that workspace.
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    if not isinstance(os_workspace, list):
+        os_workspace = [os_workspace]
+    response = get_permissions.sync_detailed(
+        os_workspaces=",".join(os_workspace), client=client
+    )
+    return _parse_permissions_response(response, client)
+
+
+async def asyncio(os_workspace: Union[List[str], str], client: Client = None):
+    """
+    # Get permissions for workspaces asynchronously
+
+    Get asynchronously the permissions for one or more workspaces.
+
+    ## Arguments
+    - `os_workspace`: The ID (or list of IDs) of the workspaces to find permissions for.
+    - `client`: The Client with which to connect to Octostar, which is also the user for
+                which the permissions are given. If None, the default one is used.
+
+    ## Returns
+    A dictionary, where each key is a workspace ID and each value is the permission
+    level for that workspace.
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    if not isinstance(os_workspace, list):
+        os_workspace = [os_workspace]
+    response = await get_permissions.asyncio_detailed(
+        os_workspaces=",".join(os_workspace), client=client
+    )
+    return _parse_permissions_response(response, client)

octostar/utils/workspace/read_attachment.py

@@ -0,0 +1,284 @@
+import logging
+import codecs
+import httpx
+from typing import Dict, Optional, Tuple
+from urllib.parse import quote
+
+_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 _attachment_url(client: Client, os_workspace: str, os_entity_uid: str) -> str:
+    """Build the attachment endpoint URL."""
+    base = client.get_base_url_v1()
+    return f"{base}/api/v2/entities/{quote(os_workspace, safe='')}/{quote(os_entity_uid, safe='')}/attachment"
+
+
+def _build_headers(
+    client: Client,
+    byte_range: Optional[Tuple[int, Optional[int]]] = None,
+) -> dict:
+    """Build request headers including auth and optional Range."""
+    headers = dict(client.get_headers())
+    if byte_range is not None:
+        start, end = byte_range
+        if end is not None:
+            headers["Range"] = f"bytes={start}-{end}"
+        else:
+            headers["Range"] = f"bytes={start}-"
+    return headers
+
+
+def _head_sync(url: str, headers: dict, client: Client) -> Dict[str, str]:
+    """Send a HEAD request and return the response headers as a dict."""
+    response = None
+    try:
+        for attempt in network_retry_strategy():
+            with attempt:
+                with httpx.Client(timeout=DEFAULT_TIMEOUT) as http_client:
+                    response = http_client.head(url, headers=headers)
+                    response.raise_for_status()
+    except Exception:
+        raise ApiConnectionError("read_attachment", response, client)
+    return dict(response.headers)
+
+
+async def _head_async(url: str, headers: dict, client: Client) -> Dict[str, str]:
+    """Send a HEAD request and return the response headers as a dict (async)."""
+    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.head(url, headers=headers)
+                    response.raise_for_status()
+    except Exception:
+        raise ApiConnectionError("read_attachment", response, client)
+    return dict(response.headers)
+
+
+def _decode_iter(chunks, encoding="utf-8", errors="strict"):
+    decoder = codecs.getincrementaldecoder(encoding)(errors=errors)
+    for chunk in chunks:
+        text = decoder.decode(chunk)
+        if text or not chunk:
+            yield text
+    tail = decoder.decode(b"", final=True)
+    if tail:
+        yield tail
+
+
+async def _decode_iter_async(chunks, encoding="utf-8", errors="strict"):
+    decoder = codecs.getincrementaldecoder(encoding)(errors=errors)
+    async for chunk in chunks:
+        text = decoder.decode(chunk)
+        if text or not chunk:
+            yield text
+    tail = decoder.decode(b"", final=True)
+    if tail:
+        yield tail
+
+
+def _iter_lines(chunks_iter):
+    pending = b""
+    for chunk in chunks_iter:
+        data = pending + chunk
+        pending = b""
+        lines = data.splitlines(keepends=True)
+        if not lines:
+            continue
+        if not lines[-1].endswith(b"\n"):
+            pending = lines.pop()
+        for line in lines:
+            yield line.rstrip(b"\r\n")
+    if pending:
+        yield pending.rstrip(b"\r\n")
+
+
+async def _iter_lines_async(chunks_iter):
+    pending = b""
+    async for chunk in chunks_iter:
+        data = pending + chunk
+        pending = b""
+        lines = data.splitlines(keepends=True)
+        if not lines:
+            continue
+        if not lines[-1].endswith(b"\n"):
+            pending = lines.pop()
+        for line in lines:
+            yield line.rstrip(b"\r\n")
+    if pending:
+        yield pending.rstrip(b"\r\n")
+
+
+def sync(
+    os_workspace: str,
+    os_entity_uid: str,
+    decode: bool = True,
+    stream: bool = False,
+    stream_lines: bool = False,
+    stream_chunk_size: int = 65_536,
+    byte_range: Optional[Tuple[int, Optional[int]]] = None,
+    headers_only: bool = False,
+    client: Client = None,
+):
+    """
+    # Read the content of an attachment from its workspace ID and object ID
+
+    Note that querying the ontology for the same entry will only provide metadata
+    information about the entity, not the attachment contents themselves.
+
+    ## Arguments
+    - `os_workspace`: The workspace ID the object belongs to
+    - `os_entity_uid`: The object ID
+    - `decode`: Whether to decode the contents to UTF-8
+    - `stream`: Whether to return the contents in chunks. Overrides stream_lines and stream_chunk_size if False
+    - `stream_lines`: Whether to chunk the contents per line. Overrides stream_chunk_size if set
+    - `stream_chunk_size`: How many bytes each chunk should be
+    - `byte_range`: Optional (start, end) tuple for Range requests. end can be None for open-ended ranges.
+        Example: (0, 1023) fetches the first 1024 bytes; (1024, None) fetches from byte 1024 onwards.
+    - `headers_only`: If True, send a HEAD request and return the response headers as a dict
+        instead of downloading the body.  Useful for inspecting content-type, content-length,
+        etag, or last-modified without fetching the full attachment.
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used
+
+    ## Returns
+    - When `headers_only=True`: a ``dict[str, str]`` of response headers.
+    - Otherwise: a string or bytes representation of the object file contents.
+
+    ## Raises
+    - `ApiConnectionError`: If the operation was unsuccessful on the server
+    - `ValueError`: If the object has no associated file
+    """
+    if not client:
+        client = get_default_client()
+
+    url = _attachment_url(client, os_workspace, os_entity_uid)
+    headers = _build_headers(client, byte_range)
+
+    if headers_only:
+        return _head_sync(url, headers, client)
+
+    if not stream:
+        response = None
+        try:
+            for attempt in network_retry_strategy():
+                with attempt:
+                    with httpx.Client(timeout=DEFAULT_TIMEOUT) as http_client:
+                        response = http_client.get(url, headers=headers)
+                        response.raise_for_status()
+        except Exception:
+            raise ApiConnectionError("read_attachment", response, client)
+        attachment = response.content
+        if decode:
+            attachment = attachment.decode()
+        return attachment
+
+    # Streaming mode — return a generator that keeps the connection alive
+    def _stream_chunks():
+        with httpx.Client(timeout=DEFAULT_TIMEOUT) as http_client:
+            with http_client.stream("GET", url, headers=headers) as response:
+                if response.status_code >= 400:
+                    raise ApiConnectionError("read_attachment", response, client)
+                for chunk in response.iter_bytes(chunk_size=stream_chunk_size):
+                    yield chunk
+
+    if stream_lines:
+        result = _iter_lines(_stream_chunks())
+    else:
+        result = _stream_chunks()
+
+    if decode:
+        result = _decode_iter(result)
+    return result
+
+
+async def asyncio(
+    os_workspace: str,
+    os_entity_uid: str,
+    decode: bool = True,
+    stream: bool = False,
+    stream_lines: bool = False,
+    stream_chunk_size: int = 65_536,
+    byte_range: Optional[Tuple[int, Optional[int]]] = None,
+    headers_only: bool = False,
+    client: Client = None,
+):
+    """
+    # Read the content of an attachment from its workspace ID and object ID (async)
+
+    Note that querying the ontology for the same entry will only provide metadata
+    information about the entity, not the attachment contents themselves.
+
+    ## Arguments
+    - `os_workspace`: The workspace ID the object belongs to
+    - `os_entity_uid`: The object ID
+    - `decode`: Whether to decode the contents to UTF-8
+    - `stream`: Whether to return the contents in chunks. Overrides stream_lines and stream_chunk_size if False
+    - `stream_lines`: Whether to chunk the contents per line. Overrides stream_chunk_size if set
+    - `stream_chunk_size`: How many bytes each chunk should be
+    - `byte_range`: Optional (start, end) tuple for Range requests. end can be None for open-ended ranges.
+        Example: (0, 1023) fetches the first 1024 bytes; (1024, None) fetches from byte 1024 onwards.
+    - `headers_only`: If True, send a HEAD request and return the response headers as a dict
+        instead of downloading the body.  Useful for inspecting content-type, content-length,
+        etag, or last-modified without fetching the full attachment.
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used
+
+    ## Returns
+    - When `headers_only=True`: a ``dict[str, str]`` of response headers.
+    - Otherwise: a string or bytes representation of the object file contents,
+      or an async generator when streaming.
+
+    ## Raises
+    - `ApiConnectionError`: If the operation was unsuccessful on the server
+    - `ValueError`: If the object has no associated file
+    """
+    if not client:
+        client = get_default_client()
+
+    url = _attachment_url(client, os_workspace, os_entity_uid)
+    headers = _build_headers(client, byte_range)
+
+    if headers_only:
+        return await _head_async(url, headers, client)
+
+    if not stream:
+        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.get(url, headers=headers)
+                        response.raise_for_status()
+        except Exception:
+            raise ApiConnectionError("read_attachment", response, client)
+        attachment = response.content
+        if decode:
+            attachment = attachment.decode()
+        return attachment
+
+    # Streaming mode — return an async generator
+    async def _stream_chunks():
+        async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT) as http_client:
+            async with http_client.stream("GET", url, headers=headers) as response:
+                if response.status_code >= 400:
+                    raise ApiConnectionError("read_attachment", response, client)
+                async for chunk in response.aiter_bytes(chunk_size=stream_chunk_size):
+                    yield chunk
+
+    if stream_lines:
+        result = _iter_lines_async(_stream_chunks())
+    else:
+        result = _stream_chunks()
+
+    if decode:
+        result = _decode_iter_async(result)
+    return result