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

octostar/utils/jobs/get_job_logs.py

@@ -0,0 +1,113 @@
+import os
+import logging
+import re
+
+_logger = logging.getLogger(__name__)
+
+from ...api.apps import get_job_logs
+from ...client import Client
+from ..exceptions import ApiConnectionError
+
+
+def sync(
+    job_id: str = os.getenv("OS_JOB_ID"),
+    since_seconds: int = None,
+    tail_lines: int = None,
+    client: Client = None,
+):
+    """
+    # Get Job Logs
+
+    Retrieves the logs of a running job given its ID.
+
+    ## Arguments
+    - `job_id`: The running job ID.
+    - `since_seconds`: The maximum amount of seconds prior to now to get logs for.
+    - `tail_lines`: The maximum amount of log lines to retrieve.
+
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    An UTF-8 string with the job logs, or in bytes if they could not be decoded.
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    response = get_job_logs.sync_detailed(
+        job_id=job_id,
+        since_seconds=since_seconds,
+        tail_lines=tail_lines,
+        client=client,
+    )
+    if response.status_code != 200:
+        raise ApiConnectionError("get_job_logs", response, client)
+    logs = response.content
+    try:
+        escaped_logs = logs.decode("utf-8", "replace")
+        escaped_logs = re.sub(
+            r"\\.",
+            lambda x: {
+                "\\n": "\n",
+                "\\t": "\t",
+                "\\r": "\r",
+                '\\"': '"',
+                "\\'": "'",
+            }.get(x[0], x[0]),
+            escaped_logs,
+        )
+        return escaped_logs
+    except Exception:
+        _logger.warning("Could not decode logs! Returning raw bytes")
+        return logs
+
+
+async def asyncio(
+    job_id: str = os.getenv("OS_JOB_ID"),
+    since_seconds: int = None,
+    tail_lines: int = None,
+    client: Client = None,
+):
+    """
+    # Get Job Logs Asynchronously
+
+    Asynchronously retrieves the logs of a running job given its ID.
+
+    ## Arguments
+    - `job_id`: The running job ID.
+    - `since_seconds`: The maximum amount of seconds prior to now to get logs for.
+    - `tail_lines`: The maximum amount of log lines to retrieve.
+
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    An UTF-8 string with the job logs, or in bytes if they could not be decoded.
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    response = await get_job_logs.asyncio_detailed(
+        job_id=job_id,
+        since_seconds=since_seconds,
+        tail_lines=tail_lines,
+        client=client,
+    )
+    if response.status_code != 200:
+        raise ApiConnectionError("get_job_logs", response, client)
+    logs = response.content
+    try:
+        escaped_logs = logs.decode("utf-8", "replace")
+        escaped_logs = re.sub(
+            r"\\.",
+            lambda x: {
+                "\\n": "\n",
+                "\\t": "\t",
+                "\\r": "\r",
+                '\\"': '"',
+                "\\'": "'",
+            }.get(x[0], x[0]),
+            escaped_logs,
+        )
+        return escaped_logs
+    except Exception:
+        _logger.warning("Could not decode logs! Returning raw bytes")
+        return logs

octostar/utils/jobs/get_job_progress.py

@@ -0,0 +1,76 @@
+import os
+import logging
+
+_logger = logging.getLogger(__name__)
+
+from ...api.apps import get_job_progress
+from ...client import Client
+from ..exceptions import ApiConnectionError
+
+
+def _format_progress_response(content: dict) -> str:
+    """Format the new API response as a progress string for backward compatibility.
+
+    The new API returns: {job_id, progress (float 0-1), status, message}
+    The old API returned: a string message with the progress.
+
+    Returns the message if set, otherwise formats the progress as a percentage.
+    """
+    if content.get("message"):
+        return content["message"]
+    progress = content.get("progress")
+    if progress is not None:
+        return f"{int(progress * 100)}%"
+    return content.get("status", "unknown")
+
+
+def sync(job_id: str = os.getenv("OS_JOB_ID"), client: Client = None):
+    """
+    # Get Job Progress
+
+    Get the progress status of a job. Note the progress status is determined by the job
+    and its behavior is dependant on the implementation of the job itself.
+
+    ## Arguments
+    - `job_id`: The running job ID.
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    A string containing the progress status (usually containing some percentage value).
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    response = get_job_progress.sync_detailed(job_id=job_id, client=client)
+    if response.status_code != 200:
+        raise ApiConnectionError("get_job_progress", response, client)
+    content = response.parsed
+    if not content:
+        raise ApiConnectionError("get_job_progress", response, client)
+    return _format_progress_response(content)
+
+
+async def asyncio(job_id: str = os.getenv("OS_JOB_ID"), client: Client = None):
+    """
+    # Get Job Progress Asynchronously
+
+    Get asynchronously the progress status of a job. Note the progress status is determined by the job
+    and its behavior is dependant on the implementation of the job itself.
+
+    ## Arguments
+    - `job_id`: The running app/job ID.
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    A string containing the progress status (usually containing some percentage value).
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    response = await get_job_progress.asyncio_detailed(job_id=job_id, client=client)
+    if response.status_code != 200:
+        raise ApiConnectionError("get_job_progress", response, client)
+    content = response.parsed
+    if not content:
+        raise ApiConnectionError("get_job_progress", response, client)
+    return _format_progress_response(content)

octostar/utils/jobs/kill_job.py

@@ -0,0 +1,47 @@
+import logging
+
+_logger = logging.getLogger(__name__)
+
+from ...api.apps import kill_job
+from ...client import Client
+from ..exceptions import ApiConnectionError
+
+
+def sync(job_id: str, client: Client = None):
+    """
+    # Cancel a currently running job
+
+    ## Arguments
+    - `job_id`: The unique job ID to cancel.
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    An acknowledgment.
+
+    ## Raises
+    - `ApiConnectionError`: If the operation was unsuccessful on the server.
+    """
+    response = kill_job.sync_detailed(job_id=job_id, client=client)
+    if response.status_code != 200:
+        raise ApiConnectionError("kill_job", response, client)
+    return response.parsed
+
+
+async def asyncio(job_id: str, client: Client = None):
+    """
+    # Cancel asynchronously a currently running job
+
+    ## Arguments
+    - `job_id`: The job ID to cancel.
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    An acknowledgment.
+
+    ## Raises
+    - `ApiConnectionError`: If the operation was unsuccessful on the server.
+    """
+    response = await kill_job.asyncio_detailed(job_id=job_id, client=client)
+    if response.status_code != 200:
+        raise ApiConnectionError("kill_job", response, client)
+    return response.parsed

octostar/utils/jobs/set_job_progress.py

@@ -0,0 +1,67 @@
+import os
+import logging
+
+_logger = logging.getLogger(__name__)
+
+from ...api.apps import set_job_progress
+from ...client import Client
+from ...models.progress_request import ProgressRequest
+from ..exceptions import ApiConnectionError
+
+
+def sync(
+    progress_string: str, job_id: str = os.getenv("OS_JOB_ID"), client: Client = None
+):
+    """
+    # Set Job Progress
+
+    Set or update the progress status of a job.
+
+    ## Arguments
+    - `progress_string`: A string indicative of the progress status.
+    - `job_id`: The running job ID.
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    `True` if progress update was successful.
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    response = set_job_progress.sync_detailed(
+        job_id=job_id,
+        json_body=ProgressRequest(progress=progress_string),
+        client=client,
+    )
+    if response.status_code != 200:
+        raise ApiConnectionError("set_job_progress", response, client)
+    return True
+
+
+async def asyncio(
+    progress_string: str, job_id: str = os.getenv("OS_JOB_ID"), client: Client = None
+):
+    """
+    # Set Job Progress Asynchronously
+
+    Set or update asynchronously the progress status of a job.
+
+    ## Arguments
+    - `progress_string`: A string indicative of the progress status.
+    - `job_id`: The running job ID.
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    `True` if progress update was successful.
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    response = await set_job_progress.asyncio_detailed(
+        job_id=job_id,
+        json_body=ProgressRequest(progress=progress_string),
+        client=client,
+    )
+    if response.status_code != 200:
+        raise ApiConnectionError("set_job_progress", response, client)
+    return True

octostar/utils/meta/get_version.py

@@ -0,0 +1,30 @@
+import os
+
+from ...api.metadata import get_version
+
+
+def sync(client):
+    """
+    # Get the current Octostar version
+
+    ## Arguments
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    The octostar version as a string.
+    """
+    return get_version.sync_detailed(client=client).parsed
+
+
+async def asyncio(client):
+    """
+    # Get asynchronously the current Octostar version
+
+    ## Arguments
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    A dictionary containing the username, its signed JWT and a few other info.
+    """
+    out = get_version.asyncio_detailed(client=client)
+    return (await out).parsed

octostar/utils/meta/get_whoami.py

@@ -0,0 +1,30 @@
+import os
+
+from ...api.metadata import get_whoami
+
+
+def sync(client):
+    """
+    # Get information about the user
+
+    ## Arguments
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    A dictionary containing the username, its signed JWT and a few other info.
+    """
+    return get_whoami.sync_detailed(client=client).parsed
+
+
+async def asyncio(client):
+    """
+    # Get asynchronously information about the user
+
+    ## Arguments
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    A dictionary containing the username, its signed JWT and a few other info.
+    """
+    out = get_whoami.asyncio_detailed(client=client)
+    return (await out).parsed

octostar/utils/notifications/delete_stream.py

@@ -0,0 +1,58 @@
+import os
+import logging
+
+_logger = logging.getLogger(__name__)
+
+from ...api.notifications import delete_stream
+from ...client import Client
+from ..exceptions import ApiConnectionError
+
+
+def sync(stream_id: str, client: Client = None):
+    """
+    # Delete Event Stream
+
+    Deletes an event stream.
+
+    ## Arguments
+    - `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 stream has been deleted successfully.
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    response = delete_stream.sync_detailed(stream_id=stream_id, client=client)
+    if response.status_code != 200 or (
+        "status" in response.parsed.additional_properties
+        and response.parsed.additional_properties["status"] != "success"
+    ):
+        raise ApiConnectionError("delete_stream", response, client)
+    return True
+
+
+async def asyncio(stream_id: str, client: Client = None):
+    """
+    # Delete Event Stream Asynchronously
+
+    Asynchronously deletes an event stream.
+
+    ## Arguments
+    - `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 stream has been deleted successfully.
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    response = await delete_stream.asyncio_detailed(stream_id=stream_id, client=client)
+    if response.status_code != 200 or (
+        "status" in response.parsed.additional_properties
+        and response.parsed.additional_properties["status"] != "success"
+    ):
+        raise ApiConnectionError("delete_stream", response, client)
+    return True

octostar/utils/notifications/get_my_subscriptions.py

@@ -0,0 +1,49 @@
+import logging
+
+_logger = logging.getLogger(__name__)
+
+from ...api.notifications import get_subscriptions
+from ...client import Client
+from ..exceptions import ApiConnectionError
+
+
+def sync(client: Client = None):
+    """
+    # Get User Subscriptions
+
+    Retrieves the subscriptions the user is listening to.
+
+    ## Arguments
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    A list of subscription IDs.
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    response = get_subscriptions.sync_detailed(client=client)
+    if response.status_code != 200:
+        raise ApiConnectionError("get_my_subscriptions", response, client)
+    return response.parsed
+
+
+async def asyncio(client: Client = None):
+    """
+    # Get User Subscriptions Asynchronously
+
+    Asynchronously retrieves the subscriptions the user is listening to.
+
+    ## Arguments
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    A list of subscription IDs.
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    response = await get_subscriptions.asyncio_detailed(client=client)
+    if response.status_code != 200:
+        raise ApiConnectionError("get_my_subscriptions", response, client)
+    return response.parsed

octostar/utils/notifications/publish_notification.py

@@ -0,0 +1,73 @@
+from typing import List, Dict, Any, Union
+import logging
+
+_logger = logging.getLogger(__name__)
+
+from ...api.notifications import publish_notification as api_publish_notification
+from ...models.os_notification import OsNotification
+from ...client import Client
+from ..exceptions import ApiConnectionError
+
+
+def sync(
+    notification: Union[Dict[str, Any], List[Dict[str, Any]]], client: Client = None
+):
+    """
+    # Publishes desktop notifications to specified channels (users).
+
+    ## Arguments
+    - `notification`: One or more notification dictionaries. Each notification should contain:
+        - `channel`: Username or channel to send the notification to (required)
+        - `title`: Notification title (required)
+        - `body`: Notification body text (required)
+        - `workspace_id`: Workspace ID related to the notification (optional)
+        - `type`: Notification type, e.g., "octostar:desktop:builtins:wso:update" (optional)
+        - `expires_at`: ISO 8601 timestamp when notification expires (optional)
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    if not isinstance(notification, list):
+        notification = [notification]
+    default_fields = {"type": "octostar:desktop:builtins:wso:update"}
+    notification_objects = [
+        OsNotification.from_dict({**default_fields, **notif}) for notif in notification
+    ]
+    response = api_publish_notification.sync_detailed(
+        json_body=notification_objects, client=client
+    )
+    if response.status_code != 201:
+        raise ApiConnectionError("publish_notification", response, client)
+
+
+async def asyncio(
+    notification: Union[Dict[str, Any], List[Dict[str, Any]]], client: Client = None
+):
+    """
+    # Publishes asynchronously desktop notifications to specified channels (users).
+
+    ## Arguments
+    - `notification`: One or more notification dictionaries. Each notification should contain:
+        - `channel`: Username or channel to send the notification to (required)
+        - `title`: Notification title (required)
+        - `body`: Notification body text (required)
+        - `workspace_id`: Workspace ID related to the notification (optional)
+        - `type`: Notification type, e.g., "octostar:desktop:builtins:wso:update" (optional)
+        - `expires_at`: ISO 8601 timestamp when notification expires (optional)
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    if not isinstance(notification, list):
+        notification = [notification]
+    default_fields = {"type": "octostar:desktop:builtins:wso:update"}
+    notification_objects = [
+        OsNotification.from_dict({**default_fields, **notif}) for notif in notification
+    ]
+    response = await api_publish_notification.asyncio_detailed(
+        json_body=notification_objects, client=client
+    )
+    if response.status_code != 201:
+        raise ApiConnectionError("publish_notification", response, client)

octostar/utils/notifications/pull_event_from_stream.py

@@ -0,0 +1,63 @@
+import logging
+
+_logger = logging.getLogger(__name__)
+
+from ...api.notifications import pull_events_from_stream
+from ...client import Client
+from ..exceptions import ApiConnectionError
+
+
+def sync(stream_id: str, client: Client = None):
+    """
+    # Get Latest Event from Stream
+
+    Retrieves the latest event in a stream.
+
+    ## Arguments
+    - `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
+    An Octostar event instance (containing the event info and contents).
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    response = pull_events_from_stream.sync_detailed(
+        stream_id=stream_id, count=1, client=client
+    )
+    if response.status_code != 200:
+        raise ApiConnectionError("pull_event_from_stream", response, client)
+    events = response.parsed
+    if events:
+        return events[0]
+    else:
+        return events
+
+
+async def asyncio(stream_id: str, client: Client = None):
+    """
+    # Get Latest Event from Stream Asynchronously
+
+    Asynchronously retrieves the latest event in a stream.
+
+    ## Arguments
+    - `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
+    An Octostar event instance (containing the event info and contents).
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    response = await pull_events_from_stream.asyncio_detailed(
+        stream_id=stream_id, count=1, client=client
+    )
+    if response.status_code != 200:
+        raise ApiConnectionError("pull_event_from_stream", response, client)
+    events = response.parsed
+    if events:
+        return events[0]
+    else:
+        return events

octostar/utils/notifications/pull_events_from_stream.py

@@ -0,0 +1,64 @@
+import logging
+
+_logger = logging.getLogger(__name__)
+
+from ...api.notifications import pull_events_from_stream
+from ...client import Client
+
+
+def sync(stream_id: str, count: int = 10, client: Client = None):
+    """
+    # Get Latest Events from Stream
+
+    Retrieves the N latest events in a stream. Events are returned in LIFO order.
+
+    ## Arguments
+    - `stream_id`: The unique ID for the event stream.
+    - `count`: The number of events to fetch.
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    A list of Octostar event instances (containing the event info and contents).
+
+    ## Raises
+    - `ConnectionError`: If the request was unsuccessful on the server.
+    """
+    response = pull_events_from_stream.sync_detailed(
+        stream_id=stream_id, count=count, client=client
+    )
+    if response.status_code != 200:
+        logger.error(response.content)
+        raise ConnectionError(
+            "pull_events_from_stream failed with status code "
+            + str(response.status_code)
+        )
+    return response.parsed
+
+
+async def asyncio(stream_id: str, count: int = 10, client: Client = None):
+    """
+    # Get Latest Events from Stream Asynchronously
+
+    Asynchronously retrieves the N latest events in a stream. Events are returned in LIFO order.
+
+    ## Arguments
+    - `stream_id`: The unique ID for the event stream.
+    - `count`: The number of events to fetch.
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    A list of Octostar event instances (containing the event info and contents).
+
+    ## Raises
+    - `ConnectionError`: If the request was unsuccessful on the server.
+    """
+    response = await pull_events_from_stream.asyncio_detailed(
+        stream_id=stream_id, count=count, client=client
+    )
+    if response.status_code != 200:
+        logger.error(response.content)
+        raise ConnectionError(
+            "pull_events_from_stream failed with status code "
+            + str(response.status_code)
+        )
+    return response.parsed