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

octostar/utils/notifications/push_event_to_stream.py

@@ -0,0 +1,109 @@
+import os
+import logging
+from typing import Union
+
+_logger = logging.getLogger(__name__)
+
+from ...api.notifications import push_event_to_stream
+from ...models.octostar_event import OctostarEvent
+from ...models.octostar_event_octostar_payload import OctostarEventOctostarPayload
+from ...models.octostar_event_octostar_payload_level import (
+    OctostarEventOctostarPayloadLevel,
+)
+from ...client import Client
+from ...types import UNSET
+from ..exceptions import ApiConnectionError
+
+
+def sync(
+    message: str,
+    description: Union[str, None] = None,
+    level: Union[str, None] = None,
+    channel: str = "octostar:desktop:builtins:showToast",
+    stream_id: str = os.getenv("OS_JOB_ID") or os.getenv("OS_APP_ID"),
+    client: Client = None,
+):
+    """
+    # Add Event to Stream
+
+    Adds a new event to an event stream.
+
+    ## Arguments
+    - `message`: The main content to write to the event.
+    - `description`: The secondary content to write to the event.
+    - `level`: A string detailing the event level. Can be "debug", "error", "info" or "warning".
+    - `channel`: The event channel. See OsMessageType for its possible values.
+    - `stream_id`: The unique ID for the event stream.
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    `True` if the event was added successfully to the stream.
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    response = push_event_to_stream.sync_detailed(
+        stream_id=stream_id,
+        client=client,
+        json_body=OctostarEvent(
+            octostar_stream=channel,
+            octostar_payload=OctostarEventOctostarPayload(
+                message=message,
+                description=description if description else UNSET,
+                level=OctostarEventOctostarPayloadLevel(level) if level else UNSET,
+            ),
+        ),
+    )
+    if response.status_code not in (200, 201) or (
+        "status" in response.parsed.additional_properties
+        and response.parsed.additional_properties["status"] != "success"
+    ):
+        raise ApiConnectionError("push_event_from_stream", response, client)
+    return True
+
+
+async def asyncio(
+    message: str,
+    description: Union[str, None] = None,
+    level: Union[str, None] = None,
+    channel: str = "octostar:desktop:builtins:showToast",
+    stream_id: str = os.getenv("OS_JOB_ID") or os.getenv("OS_APP_ID"),
+    client: Client = None,
+):
+    """
+    # Add Event to Stream Asynchronously
+
+    Asynchronously adds a new event to an event stream.
+
+    ## Arguments
+    - `message`: The main content to write to the event.
+    - `description`: The secondary content to write to the event.
+    - `level`: A string detailing the event level. Can be "debug", "error", "info" or "warning".
+    - `channel`: The event channel. See OsMessageType for its possible values.
+    - `stream_id`: The unique ID for the event stream.
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    `True` if the event was added successfully to the stream.
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    response = await push_event_to_stream.asyncio_detailed(
+        stream_id=stream_id,
+        client=client,
+        json_body=OctostarEvent(
+            octostar_stream=channel,
+            octostar_payload=OctostarEventOctostarPayload(
+                message=message,
+                description=description if description else UNSET,
+                level=OctostarEventOctostarPayloadLevel(level) if level else UNSET,
+            ),
+        ),
+    )
+    if response.status_code not in (200, 201) or (
+        "status" in response.parsed.additional_properties
+        and response.parsed.additional_properties["status"] != "success"
+    ):
+        raise ApiConnectionError("push_event_from_stream", response, client)
+    return True

octostar/utils/notifications/push_events_to_stream.py

@@ -0,0 +1,137 @@
+import os
+import logging
+from typing import TypedDict, List
+
+_logger = logging.getLogger(__name__)
+
+from ...api.notifications import push_event_to_stream
+from ...models.octostar_event import OctostarEvent
+from ...models.octostar_event_octostar_payload import OctostarEventOctostarPayload
+from ...models.octostar_event_octostar_payload_level import (
+    OctostarEventOctostarPayloadLevel,
+)
+from ...client import Client
+from ...types import UNSET
+from ..exceptions import ApiConnectionError
+
+
+class __PushEvent(TypedDict, total=False):
+    message: str
+    description: str
+    level: str
+
+
+def sync(
+    events: List[__PushEvent],
+    channel: str = "octostar:desktop:builtins:showToast",
+    stream_id: str = os.getenv("OS_JOB_ID") or os.getenv("OS_APP_ID"),
+    client: Client = None,
+):
+    """
+    # Add Multiple Events to Stream
+
+    Adds N new events to an event stream, in order. Note that, when pulling from a stream,
+    events are returned in LIFO order.
+
+    ## Arguments
+    - `events`: A list of dictionaries, one per event to add.
+        Each dictionary must contain:
+        - `message`: The main content to write to the event.
+        - `description`: The secondary content to write to the event.
+        - `level`: A string detailing the event level. Can be "debug", "error", "info" or "warning".
+    - `channel`: The event channel. See OsMessageType for its possible values.
+    - `stream_id`: The unique ID for the event stream.
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    The number of events successfully pushed to the stream.
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    for i in range(len(events)):
+        event = events[i]
+        response = push_event_to_stream.sync_detailed(
+            stream_id=stream_id,
+            client=client,
+            json_body=OctostarEvent(
+                octostar_channel=channel,
+                octostar_payload=OctostarEventOctostarPayload(
+                    message=event["message"],
+                    description=(
+                        UNSET
+                        if "description" not in event or not event["description"]
+                        else event["description"]
+                    ),
+                    level=(
+                        UNSET
+                        if "level" not in event or not event["level"]
+                        else OctostarEventOctostarPayloadLevel(event["level"])
+                    ),
+                ),
+            ),
+        )
+        if response.status_code not in (200, 201) or (
+            "status" in response.parsed.additional_properties
+            and response.parsed.additional_properties["status"] != "success"
+        ):
+            raise ApiConnectionError("push_events_to_stream", response, client)
+    return i
+
+
+async def asyncio(
+    events: List[__PushEvent],
+    channel: str = "octostar:desktop:builtins:showToast",
+    stream_id: str = os.getenv("OS_APP_ID"),
+    client: Client = None,
+):
+    """
+    # Add Multiple Events to Stream Asynchronously
+
+    Asynchronously adds N new events to an event stream, in order. Note that, when pulling from a stream,
+    events are returned in LIFO order.
+
+    ## Arguments
+    - `events`: A list of dictionaries, one per event to add.
+        Each dictionary must contain:
+        - `message`: The main content to write to the event.
+        - `description`: The secondary content to write to the event.
+        - `level`: A string detailing the event level. Can be "debug", "error", "info" or "warning".
+    - `channel`: The event channel. See OsMessageType for its possible values.
+    - `stream_id`: The unique ID for the event stream.
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    The number of events successfully pushed to the stream.
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    for i in range(len(events)):
+        event = events[i]
+        response = await push_event_to_stream.asyncio_detailed(
+            stream_id=stream_id,
+            client=client,
+            json_body=OctostarEvent(
+                octostar_channel=channel,
+                octostar_payload=OctostarEventOctostarPayload(
+                    message=event["message"],
+                    description=(
+                        UNSET
+                        if "description" not in event or not event["description"]
+                        else event["description"]
+                    ),
+                    level=(
+                        UNSET
+                        if "level" not in event or not event["level"]
+                        else event["level"]
+                    ),
+                ),
+            ),
+        )
+        if response.status_code not in (200, 201) or (
+            "status" in response.parsed.additional_properties
+            and response.parsed.additional_properties["status"] != "success"
+        ):
+            raise ApiConnectionError("push_events_to_stream", response, client)
+    return i

octostar/utils/notifications/toast.py

@@ -0,0 +1,92 @@
+from typing import Union
+import logging
+
+_logger = logging.getLogger(__name__)
+
+from ...api.notifications import toast
+from ...types import UNSET
+from ...client import Client
+from ...models.octostar_event_octostar_payload_level import (
+    OctostarEventOctostarPayloadLevel,
+)
+from ..exceptions import ApiConnectionError
+
+
+def sync(
+    message: str,
+    description: Union[str, None] = None,
+    level: Union[str, None] = None,
+    client: Client = None,
+):
+    """
+    # Send Browser Notification
+
+    Sends a simple notification to the user in the browser.
+
+    ## Arguments
+    - `message`: The main string in the notification.
+    - `description`: The secondary string in the notification.
+    - `level`: A string detailing the icon to show in the notification. Can be "debug", "error", "info" or "warning".
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    `True` if the operation was successful.
+
+    ## Raises
+    - `AttributeError`: If the level string is invalid.
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    if level and level not in ["debug", "error", "info", "warning"]:
+        raise AttributeError("Invalid level!")
+    response = toast.sync_detailed(
+        message=message,
+        description=UNSET if not description else description,
+        level=OctostarEventOctostarPayloadLevel(level) if level else UNSET,
+        client=client,
+    )
+    if response.status_code not in (200, 201) or (
+        "status" in response.parsed.additional_properties
+        and response.parsed.additional_properties["status"] != "success"
+    ):
+        raise ApiConnectionError("toast", response, client)
+    return True
+
+
+async def asyncio(
+    message: str,
+    description: Union[str, None] = None,
+    level: Union[str, None] = None,
+    client: Client = None,
+):
+    """
+    # Send Browser Notification Asynchronously
+
+    Asynchronously sends a simple notification to the user in the browser.
+
+    ## Arguments
+    - `message`: The main string in the notification.
+    - `description`: The secondary string in the notification.
+    - `level`: A string detailing the icon to show in the notification. Can be "debug", "error", "info" or "warning".
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    `True` if the operation was successful.
+
+    ## Raises
+    - `AttributeError`: If the level string is invalid.
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    if level and level not in ["debug", "error", "info", "warning"]:
+        raise AttributeError("Invalid level!")
+    response = await toast.asyncio_detailed(
+        message=message,
+        description=UNSET if not description else description,
+        level=OctostarEventOctostarPayloadLevel(level) if level else UNSET,
+        client=client,
+    )
+    if response.status_code not in (200, 201) or (
+        "status" in response.parsed.additional_properties
+        and response.parsed.additional_properties["status"] != "success"
+    ):
+        raise ApiConnectionError("toast", response, client)
+    return True

octostar/utils/ontology/__init__.py

@@ -0,0 +1,10 @@
+"""
+# General SQL queries on one ontology
+Use this to query your ontology for entities or data. The syntax is based on timbr/SQL. For more information, see the "fusion centre" documentation.
+
+Example of a query:
+```sql
+SELECT * FROM os_thing WHERE os_workspace = 'my_workspace';
+```
+
+"""

octostar/utils/ontology/fetch_ontology_data.py

@@ -0,0 +1,141 @@
+from typing import Optional
+import logging
+
+_logger = logging.getLogger(__name__)
+
+from ...api.ontology import fetch_ontology_data
+from ...client import Client, get_default_client
+from ..exceptions import ApiConnectionError
+
+
+def _align_ontology(ontology):
+    """Convert the optimized API format into the established SDK format.
+
+    The API now returns an optimized structure with three top-level dicts
+    (concepts, relationships, properties).  SDK consumers expect the legacy
+    shape with:
+      - concepts keyed by name, each with parents (self at [0]),
+        primaryKeys, labelKeys, inheritanceLevel, allProperties (list of
+        dicts), properties (direct-only list of dicts), tags, relationships
+      - relationships as a flat list of dicts
+    """
+    opt_properties = ontology.get("properties", {})
+
+    # ── Convert concepts ──────────────────────────────────────────────────
+    for concept_name, concept_dict in ontology.get("concepts", {}).items():
+        # parents: insert self at index 0 (legacy SDK convention)
+        concept_dict["parents"].insert(0, concept_name)
+
+        # Rename / synthesise legacy fields
+        concept_dict["labelKeys"] = concept_dict.get("label_keys", [])
+        concept_dict["inheritanceLevel"] = concept_dict.get("inheritance_level", 0)
+
+        # allProperties: full inherited list as dicts
+        concept_dict["allProperties"] = [
+            {
+                "property_name": pname,
+                "property_type": opt_properties[pname]["property_type"],
+            }
+            for pname in concept_dict.get("properties", [])
+            if pname in opt_properties
+        ]
+
+        # properties: direct-only as dicts
+        concept_dict["properties"] = [
+            {
+                "property_name": pname,
+                "property_type": opt_properties[pname]["property_type"],
+            }
+            for pname in concept_dict.get("direct_properties", [])
+            if pname in opt_properties
+        ]
+
+    # ── Convert relationships dict → flat list ────────
+    relationships_list = []
+    for rname, rdata in ontology.get("relationships", {}).items():
+        relationships_list.append(
+            {
+                "relationship_name": rname,
+                "is_mtm": rdata.get("is_mtm", False),
+                "concept": rdata.get("source_concept", ""),
+                "source_concept": rdata.get("source_concept", ""),
+                "target_concept": rdata.get("target_concept", ""),
+                "source_properties": ",".join(rdata.get("source_properties", [])),
+                "target_properties": ",".join(rdata.get("target_properties", [])),
+                "inverse_name": rdata.get("inverse_name"),
+                "inverse": rdata.get("is_inverse", False),
+            }
+        )
+    ontology["relationships"] = relationships_list
+
+    return ontology
+
+
+def sync(ontology_name: Optional[str] = None, client: Optional[Client] = None):
+    """
+    # Query Ontology Structure
+
+    Retrieves the structure of an ontology.
+
+    ## Arguments
+    - `ontology_name`: The name of the ontology.
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    A dictionary containing a list of concepts and a list of relationships.
+    Each of these entries is in itself a dictionary.
+
+    ## Raises
+    - `NotImplementedError`: If the operation is not supported for the ontology.
+    - `ApiConnectionError`: If the query was unsuccessful.
+    """
+    if not client:
+        client = get_default_client()
+    if not ontology_name:
+        ontology_name = client.ontology
+    if ontology_name != client.ontology:
+        raise NotImplementedError(
+            "Only the client ontology is currently supported for this method!"
+        )
+    response = fetch_ontology_data.sync_detailed(client=client)
+    if response.status_code != 200:
+        raise ApiConnectionError("fetch_ontology_data", response, client)
+    if response.parsed is None:
+        raise ApiConnectionError("fetch_ontology_data", response, client)
+    ontology = response.parsed.additional_properties
+    return _align_ontology(ontology)
+
+
+async def asyncio(ontology_name: Optional[str] = None, client: Optional[Client] = None):
+    """
+    # Query Ontology Structure Asynchronously
+
+    Asynchronously retrieves the structure of an ontology.
+
+    ## Arguments
+    - `ontology_name`: The name of the ontology.
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    A dictionary containing a list of concepts and a list of relationships.
+    Each of these entries is in itself a dictionary.
+
+    ## Raises
+    - `NotImplementedError`: If the operation is not supported for the ontology.
+    - `ApiConnectionError`: If the query was unsuccessful.
+    """
+    if not client:
+        client = get_default_client()
+    if not ontology_name:
+        ontology_name = client.ontology
+    if ontology_name != client.ontology:
+        raise NotImplementedError(
+            "Only the active ontology is currently supported for this method!"
+        )
+    response = await fetch_ontology_data.asyncio_detailed(client=client)
+    if response.status_code != 200:
+        raise ApiConnectionError("fetch_ontology_data", response, client)
+    if response.parsed is None:
+        raise ApiConnectionError("fetch_ontology_data", response, client)
+    ontology = response.parsed.additional_properties
+    return _align_ontology(ontology)

octostar/utils/ontology/get_ontologies.py

@@ -0,0 +1,55 @@
+import logging
+
+_logger = logging.getLogger(__name__)
+
+from ...api.ontology import get_ontologies
+from ...client import Client
+from ..exceptions import ApiConnectionError
+
+
+def sync(client: Client = None):
+    """
+    # Query Ontology List
+
+    Retrieves the list of ontologies.
+
+    ## Arguments
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    A list of strings, the names of the ontologies.
+
+    ## Raises
+    - `ApiConnectionError`: If the query was unsuccessful.
+    """
+    response = get_ontologies.sync_detailed(client=client)
+    if response.status_code != 200:
+        raise ApiConnectionError("get_ontologies", response, client)
+    content = response.parsed
+    if "status" in content and content["status"] != "success":
+        raise ApiConnectionError("get_ontologies", response, client)
+    return response.parsed["data"]
+
+
+async def asyncio(client: Client = None):
+    """
+    # Query Ontology List Asynchronously
+
+    Asynchronously retrieves the list of ontologies.
+
+    ## Arguments
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    A list of strings, the names of the ontologies.
+
+    ## Raises
+    - `ApiConnectionError`: If the query was unsuccessful.
+    """
+    response = await get_ontologies.asyncio_detailed(client=client)
+    if response.status_code != 200:
+        raise ApiConnectionError("get_ontologies", response, client)
+    content = response.parsed
+    if "status" in content and content["status"] != "success":
+        raise ApiConnectionError("get_ontologies", response, client)
+    return response.parsed["data"]