mantatech-sdk 0.5b0.dev65__py3-none-any.whl

manta/apis/user_api.py

@@ -0,0 +1,1016 @@
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from manta_common.event_loop import EventLoopManager, call_async
+from .async_user_api import AsyncUserAPI
+from .module import Module
+from .results import Results
+from .swarm import Swarm
+
+
+class UserAPI:
+    """
+    User API
+
+    Parameters
+    ----------
+    token : str
+        The JWT token for the user
+    host : str
+        The host of the user servicer
+    port : int
+        The port of the user servicer
+    cert_folder : Optional[str], optional
+        The folder containing the certificates, by default None
+
+    See Also
+    --------
+    AsyncUserAPI : Asynchronous User API
+    """
+
+    __slots__ = ["async_api", "event_loop"]
+
+    def __init__(
+        self,
+        token: str,
+        host: str,
+        port: int,
+        cert_folder: Optional[str] = None,
+    ):
+        """Initialize the UserAPI."""
+        # Convert cert_folder to individual certificate files for AsyncUserAPI
+        # If cert_folder is provided, construct paths to individual cert files
+        cafile = None
+        certfile = None
+        keyfile = None
+
+        if cert_folder:
+            from pathlib import Path
+
+            cert_path = Path(cert_folder)
+            # Common certificate file names
+            cafile = (
+                str(cert_path / "ca.crt") if (cert_path / "ca.crt").exists() else None
+            )
+            certfile = (
+                str(cert_path / "client.crt")
+                if (cert_path / "client.crt").exists()
+                else None
+            )
+            keyfile = (
+                str(cert_path / "client.key")
+                if (cert_path / "client.key").exists()
+                else None
+            )
+
+        self.async_api = AsyncUserAPI(token, host, port, cafile, certfile, keyfile)
+        self.event_loop = EventLoopManager.get_instance()
+
+    @call_async
+    def is_available(self) -> bool:
+        """
+        Check if the User service is available.
+
+        Returns
+        -------
+        bool
+            Service availability status
+        """
+        pass
+
+    @call_async
+    def get_user(self) -> Dict[str, Any]:
+        """
+        Get the currently authenticated user's details.
+
+        Returns
+        -------
+        Dict[str, Any]
+            User details for the authenticated user.
+        """
+        pass
+
+    @call_async
+    def logout(self) -> str:
+        """
+        Logout the currently authenticated user (invalidate the JWT token).
+
+        Returns
+        -------
+        str
+            Success message
+        """
+        pass
+
+    @call_async
+    def list_cluster_ids(self) -> List[str]:
+        """
+        List all cluster IDs for the authenticated user.
+
+        Returns
+        -------
+        List[str]
+            List of cluster IDs
+        """
+        pass
+
+    @call_async
+    def stream_and_fetch_clusters(self) -> List[Dict[str, Any]]:
+        """
+        Stream all clusters for the authenticated user and fetch them.
+
+        Returns
+        -------
+        List[Dict[str, Any]]
+            List of cluster details
+        """
+        pass
+
+    def get_clusters(self) -> List[Dict[str, Any]]:
+        """
+        Get all clusters for the authenticated user.
+
+        Returns
+        -------
+        List[Dict[str, Any]]
+            List of cluster details
+
+        Notes
+        -----
+        This method is not recommended for large number of clusters.
+        Use :code:`stream_clusters` instead.
+        """
+        return self.stream_and_fetch_clusters()
+
+    @call_async
+    def get_cluster(self, cluster_id: str) -> dict:
+        """
+        Get cluster info
+
+        Parameters
+        ----------
+        cluster_id : str
+            ID of the cluster
+
+        Returns
+        -------
+        dict
+            Cluster Info
+        """
+        pass
+
+    @call_async
+    def create_cluster(self, name: Optional[str] = None) -> str:
+        """
+        Create a new cluster.
+
+        Parameters
+        ----------
+        name : Optional[str]
+            Name for the cluster. If not provided, a default name will be generated.
+
+        Returns
+        -------
+        str
+            The cluster ID of the newly created cluster
+        """
+        pass
+
+    @call_async
+    def start_cluster(self, cluster_id: str) -> Dict[str, Any]:
+        """
+        Start a cluster.
+
+        Parameters
+        ----------
+        cluster_id : str
+            ID of the cluster to start
+
+        Returns
+        -------
+        Dict[str, Any]
+            Cluster information including connection details (nodeHost, nodePort, jwtToken)
+        """
+        pass
+
+    @call_async
+    def stop_cluster(self, cluster_id: str) -> str:
+        """
+        Stop a cluster.
+
+        Parameters
+        ----------
+        cluster_id : str
+            ID of the cluster to stop
+
+        Returns
+        -------
+        str
+            Success message
+        """
+        pass
+
+    @call_async
+    def delete_cluster(self, cluster_id: str) -> str:
+        """
+        Delete a cluster.
+
+        Parameters
+        ----------
+        cluster_id : str
+            ID of the cluster to delete
+
+        Returns
+        -------
+        str
+            Success message
+        """
+        pass
+
+    @call_async
+    def list_module_ids(self) -> List[str]:
+        """
+        List all module IDs for the authenticated user.
+
+        Returns
+        -------
+        List[str]
+            List of module IDs
+        """
+        pass
+
+    @call_async
+    def stream_and_fetch_modules(self) -> List[Module]:
+        """
+        Stream all modules for the authenticated user and fetch them.
+
+        Returns
+        -------
+        List[Module]
+            List of Module objects
+        """
+        pass
+
+    def get_modules(self) -> List[Module]:
+        """
+        Get all modules for the authenticated user.
+
+        Returns
+        -------
+        List[Module]
+            List of Module objects
+
+        Notes
+        -----
+        This method is not recommended for large number of modules.
+        Use :code:`stream_modules` instead.
+        """
+        return self.stream_and_fetch_modules()
+
+    @call_async
+    def get_module(self, module_id: str) -> Module:
+        """
+        Get a module by its ID.
+
+        Parameters
+        ----------
+        module_id : str
+            ID of the module
+
+        Returns
+        -------
+        Module
+            Module object
+        """
+        pass
+
+    @call_async
+    def send_module(self, module: Module) -> str:
+        """
+        Send/create a new module.
+
+        Parameters
+        ----------
+        module : Module
+            Module object to create
+
+        Returns
+        -------
+        str
+            Module ID
+        """
+        pass
+
+    @call_async
+    def update_module(self, module: Module, module_id: str) -> str:
+        """
+        Update an existing module.
+
+        Parameters
+        ----------
+        module : Module
+            Module object with updated data
+        module_id : str
+            ID of the module to update
+
+        Returns
+        -------
+        str
+            Module ID
+        """
+        pass
+
+    @call_async
+    def remove_module(self, module_id: str) -> str:
+        """
+        Remove a module by its ID.
+
+        Parameters
+        ----------
+        module_id : str
+            ID of the module to remove
+
+        Returns
+        -------
+        str
+            Response message confirming removal
+        """
+        pass
+
+    @call_async
+    def list_swarm_ids(self) -> List[str]:
+        """
+        List all swarm IDs for the authenticated user.
+
+        Returns
+        -------
+        List[str]
+            List of swarm IDs
+        """
+        pass
+
+    @call_async
+    def stream_and_fetch_swarms(self) -> List[Dict[str, Any]]:
+        """
+        Stream all swarms for the authenticated user and fetch them.
+
+        Returns
+        -------
+        List[Dict[str, Any]]
+            List of swarm details
+        """
+        pass
+
+    def get_swarms(self) -> List[Dict[str, Any]]:
+        """
+        Get all swarms for the authenticated user.
+
+        Returns
+        -------
+        List[Dict[str, Any]]
+            List of swarm details
+        """
+        return self.stream_and_fetch_swarms()
+
+    @call_async
+    def get_swarm(self, swarm_id: str) -> Dict[str, Any]:
+        """
+        Get a swarm by its ID.
+
+        Parameters
+        ----------
+        swarm_id : str
+            ID of the swarm
+
+        Returns
+        -------
+        Dict[str, Any]
+            Swarm details
+        """
+        pass
+
+    @call_async
+    def stream_and_fetch_tasks(self, swarm_id: str) -> List[Dict[str, Any]]:
+        """
+        Get all tasks for a swarm by its ID.
+
+        Parameters
+        ----------
+        swarm_id : str
+            ID of the swarm
+
+        Returns
+        -------
+        List[Dict[str, Any]]
+            List of task details
+        """
+        pass
+
+    def get_tasks(self, swarm_id: str) -> List[Dict[str, Any]]:
+        """
+        Get all tasks for a swarm by its ID.
+
+        Parameters
+        ----------
+        swarm_id : str
+            ID of the swarm
+
+        Returns
+        -------
+        List[Dict[str, Any]]
+            List of task details
+        """
+        return self.stream_and_fetch_tasks(swarm_id)
+
+    @call_async
+    def send_swarm(self, cluster_id: str, swarm: Swarm) -> Dict[str, Any]:
+        """
+        Send a Swarm to the server to be inserted into its database
+
+        Parameters
+        ----------
+        cluster_id : str
+            Cluster ID
+        swarm : Swarm
+            Any class which inherit from the :code:`Swarm` class
+
+        Returns
+        -------
+        Dict[str, Any]
+            Swarm overview
+
+        Examples
+        --------
+
+        >>> swarm = FLSwarm()
+        >>> swarm_overview = user_api.send_swarm(cluster_id, swarm)
+        {'swarm_id': '9415dfd18edc45c9a6ffdf2055007bf9', 'status': 'ACTIVE', 'datetime': '2024-09-13 10:18:06'}
+
+        Notes
+        -----
+
+        The argument :code:`service` is managed by a decorator under the hood.
+        """
+        pass
+
+    @call_async
+    def start_swarm(self, swarm_id: str) -> str:
+        """
+        Start a Swarm given its ID if it is found in the database
+
+        Parameters
+        ----------
+        swarm_id : str
+            Swarm ID
+
+        Returns
+        -------
+        str
+            Response of the server
+
+        Examples
+        --------
+
+        >>> swarm_id = '9415dfd18edc45c9a6ffdf2055007bf9'
+        >>> user_api.start_swarm(swarm_id)
+        'Swarm 9415dfd18edc45c9a6ffdf2055007bf9 has started.'
+
+        Notes
+        -----
+
+        The argument :code:`service` is managed by a decorator under the hood.
+        """
+        pass
+
+    @call_async
+    def deploy_swarm(self, cluster_id: str, swarm: Swarm) -> Dict[str, Any]:
+        """
+        Deploy a Swarm
+
+        Parameters
+        ----------
+        cluster_id : str
+            Cluster ID
+        swarm : Swarm
+            Any class which inherit from the :code:`Swarm` class
+
+        Returns
+        -------
+        Dict[str, Any]
+            Swarm overview
+
+        Examples
+        --------
+
+        >>> swarm = FLSwarm()
+        >>> swarm_overview = user_api.deploy_swarm(cluster_id, swarm)
+        {'swarm_id': '9415dfd18edc45c9a6ffdf2055007bf9', 'status': 'ACTIVE', 'datetime': '2024-09-13 10:18:06'}
+
+        Notes
+        -----
+
+        The argument :code:`service` is managed by a decorator under the hood.
+        """
+        pass
+
+    @call_async
+    def stop_swarm(self, swarm_id: str, force: bool = False) -> str:
+        """
+        Stop a Swarm given its ID if it is found in the database
+
+        Parameters
+        ----------
+        swarm_id : str
+            Swarm ID
+        force : bool
+            Force the stop of all the running tasks
+
+        Returns
+        -------
+        str
+            Response of the server
+
+        Examples
+        --------
+
+        >>> swarm_id = '9415dfd18edc45c9a6ffdf2055007bf9'
+        >>> user_api.stop_swarm(swarm_id)
+        'Swarm 9415dfd18edc45c9a6ffdf2055007bf9 has stopped.'
+
+        Notes
+        -----
+
+        The argument :code:`service` is managed by a decorator under the hood.
+        """
+        pass
+
+    @call_async
+    def remove_swarm(self, swarm_id: str) -> str:
+        """
+        Remove a swarm on the cluster
+
+        Parameters
+        ----------
+        swarm_id : str
+            Id of the swarm
+
+        Returns
+        -------
+        str
+            Response of the server
+
+        Examples
+        --------
+
+        >>> swarm_id = '9415dfd18edc45c9a6ffdf2055007bf9'
+        >>> user_api.remove_swarm(swarm_id)
+        '9415dfd18edc45c9a6ffdf2055007bf9 deleted.'
+
+        Notes
+        -----
+
+        The argument :code:`service` is managed by a decorator under the hood.
+        """
+        pass
+
+    @call_async
+    def select_tasks(self, cluster_id: str, node_id: str) -> List[Dict[str, Any]]:
+        """
+        Select tasks given node ID.
+        Tasks are sorted by progression of the swarm from the end
+        to the beginning.
+
+        Parameters
+        ----------
+        cluster_id : str
+            Cluster ID
+        node_id : str
+            Node ID
+
+        Returns
+        -------
+        List[Dict[str, Any]]
+            List of several informations containing tasks
+
+        Examples
+        --------
+
+        >>> node_id = 'a2ff3abc76e045d7bb4a04a5ac416318'
+        >>> user_api.select_tasks(cluster_id, node_id)
+        [{'task_id': 'adcc83a14d8642bbb6413d196fb0b5b8', 'swarm_id': '435709c73c5344c5a3d5754c7eb2ab6d', 'status': ...}, ...]
+
+        .. warning::
+
+            The server is not returning the payloads in the response.
+            Ask the Manta team to add this feature.
+        """
+        pass
+
+    @call_async
+    def collect_errors(
+        self,
+        cluster_id: str,
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None,
+        limit: Optional[int] = None,
+        sort_order: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        """
+        Collect errors from a node
+
+        Parameters
+        ----------
+        cluster_id: str
+            Cluster ID
+        start_time : Optional[datetime]
+            Start time
+        end_time : Optional[datetime]
+            End time
+        limit : Optional[int]
+            Limit
+        sort_order : Optional[str]
+            Sort order
+
+        Returns
+        -------
+        List[Dict[str, Any]]
+            List of several informations containing errors
+
+        Examples
+        --------
+
+        >>> node_id = 'a2ff3abc76e045d7bb4a04a5ac416318'
+        >>> user_api.collect_errors(cluster_id, node_id)
+        [{'error_id': '1234567890', 'error_message': 'Error message', 'datetime': '2024-09-13 10:18:06'}, ...]
+        """
+        pass
+
+    @call_async
+    def stop_node(self, cluster_id: str, node_id: str) -> str:
+        """
+        Stop a node given its ID
+
+        Parameters
+        ----------
+        cluster_id: str
+            ID of the cluster
+        node_id : str
+            ID of the node to stop
+
+        Returns
+        -------
+        str
+            Response of the server
+
+        Examples
+        --------
+
+        >>> node_id = 'a2ff3abc76e045d7bb4a04a5ac416318'
+        >>> user_api.stop_node(cluster_id, node_id)
+        """
+        pass
+
+    @call_async
+    def remove_node(self, cluster_id: str, node_id: str) -> str:
+        """
+        Remove a node from the cluster
+
+        Parameters
+        ----------
+        cluster_id: str
+            ID of the cluster
+        node_id : str
+            ID of the node to remove
+
+        Returns
+        -------
+        str
+            Message of the server
+
+        Examples
+        --------
+
+        >>> node_id = 'a2ff3abc76e045d7bb4a04a5ac416318'
+        >>> user_api.remove_node(cluster_id, node_id)
+        'Node a2ff3abc76e045d7bb4a04a5ac416318 has been removed from the cluster.'
+        """
+        pass
+
+    @call_async
+    def list_node_ids(self, cluster_id: str, available: bool = False) -> List[str]:
+        """
+        Get node IDs
+
+        Parameters
+        ----------
+        cluster_id: str
+            ID of the cluster
+        available : bool
+            Get only available nodes
+
+        Returns
+        -------
+        List[str]
+            List of node IDs
+
+        Examples
+        --------
+
+        >>> user_api.list_node_ids(cluster_id, available=True)
+        ['a2ff3abc76e045d7bb4a04a5ac416318', 'f8a7c1d7f9d44f6b9d0d3d5d9c7b3c9d']
+        """
+        pass
+
+    @call_async
+    def list_available_node_ids(self, cluster_id: str) -> List[str]:
+        """
+        List all available (connected and ready) node IDs for a cluster.
+
+        Parameters
+        ----------
+        cluster_id : str
+            Cluster ID
+
+        Returns
+        -------
+        List[str]
+            List of available node IDs
+
+        Examples
+        --------
+        >>> user_api.list_available_node_ids(cluster_id)
+        ['node1', 'node2', 'node3']
+        """
+        pass
+
+    @call_async
+    def stream_and_fetch_nodes(self, cluster_id: str) -> List[Dict[str, Any]]:
+        """
+        Stream all nodes in the cluster and fetch their resources.
+
+        Parameters
+        ----------
+        cluster_id : str
+            Cluster ID
+
+        Returns
+        -------
+        List[Dict[str, Any]]
+            List of nodes
+
+        Examples
+        --------
+
+        >>> user_api.stream_and_fetch_nodes(cluster_id)
+        [{'node_id': 'a2ff3abc76e045d7bb4a04a5ac416318', 'resources': {'cpu': 1, 'memory': 1024, 'disk': 1024}, ...}, ...]
+        """
+        pass
+
+    def get_nodes(self, cluster_id: str) -> List[Dict[str, Any]]:
+        """
+        Stream all nodes in the cluster and fetch their resources.
+
+        Parameters
+        ----------
+        cluster_id : str
+            Cluster ID
+
+        Returns
+        -------
+        List[Dict[str, Any]]
+            List of nodes
+
+        Examples
+        --------
+
+        >>> user_api.get_nodes(cluster_id)
+        [{'node_id': 'a2ff3abc76e045d7bb4a04a5ac416318', 'resources': {'cpu': 1, 'memory': 1024, 'disk': 1024}, ...}, ...]
+        """
+        pass
+
+    @call_async
+    def get_node(self, cluster_id: str, node_id: str) -> Dict[str, Any]:
+        """
+        Get a node by its ID.
+
+        Parameters
+        ----------
+        cluster_id : str
+            Cluster ID
+        node_id : str
+            Node ID
+
+        Returns
+        -------
+        Dict[str, Any]
+            Node details
+
+        Examples
+        --------
+
+        >>> node_id = 'a2ff3abc76e045d7bb4a04a5ac416318'
+        >>> user_api.get_node(cluster_id, node_id)
+        {'node_id': 'a2ff3abc76e045d7bb4a04a5ac416318', 'resources': {'cpu': 1, 'memory': 1024, 'disk': 1024}, ...}
+        """
+        pass
+
+    @call_async
+    def get_node_resources(self, cluster_id: str, node_id: str) -> Dict[str, Any]:
+        """
+        Get node resources for a specific node.
+
+        Parameters
+        ----------
+        cluster_id : str
+            Cluster ID
+        node_id : str
+            Node ID
+
+        Returns
+        -------
+        Dict[str, Any]
+            Node resources
+
+        Examples
+        --------
+        >>> node_id = 'a2ff3abc76e045d7bb4a04a5ac416318'
+        >>> user_api.get_node_resources(cluster_id, node_id)
+        {'cpu': 1, 'memory': 1024, 'disk': 1024}
+        """
+        pass
+
+    @call_async
+    def select_results(self, swarm_id: str, tag: str) -> Dict[str, Results]:
+        """
+        Select results from the database given the queries
+
+        Parameters
+        ----------
+        swarm_id: str
+            Swarm ID
+        tag: str
+            Tag
+
+        Returns
+        -------
+        Dict[str, Results]
+            Dictionary of :code:`(swarm_id, results)`
+
+        Examples
+        --------
+
+        >>> swarm_id = '9415dfd18edc45c9a6ffdf2055007bf9'
+        >>> tags = ["accuracy", "loss"]
+        >>> user_api.select_results(swarm_id, tags)
+        {'9415dfd18edc45c9a6ffdf2055007bf9': Results(len(iteration)=10, len(nodes)=8, len(tags)=2)}
+
+        Notes
+        -----
+
+        The argument :code:`service` is managed by a decorator under the hood.
+        """
+        pass
+
+    @call_async
+    def delete_results(
+        self,
+        swarm_id: str,
+        tag: str,
+        node_id: Optional[str] = None,
+        task_id: Optional[str] = None,
+        iteration: Optional[int] = None,
+    ) -> str:
+        """
+        Delete results for a specific swarm and tag.
+
+        Parameters
+        ----------
+        swarm_id : str
+            Swarm ID
+        tag : str
+            Tag of the results to delete
+        node_id : str, optional
+            Filter by node ID
+        task_id : str, optional
+            Filter by task ID
+        iteration : int, optional
+            Filter by iteration number
+
+        Returns
+        -------
+        str
+            Deletion confirmation message
+        """
+        pass
+
+    @call_async
+    def collect_logs(
+        self,
+        swarm_id: str,
+        node_ids: Optional[List[str]] = None,
+        task_ids: Optional[List[str]] = None,
+        iteration: Optional[int] = None,
+        circular: Optional[int] = None,
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None,
+        severity: Optional[List[str]] = None,
+        limit: Optional[int] = None,
+        sort_order: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        """
+        Collect the logs stored in the :code:`Manager` database
+        with optional filtering parameters
+
+        Parameters
+        ----------
+        swarm_id : str
+            Swarm ID
+        node_ids : List[str]
+            Node IDs
+        task_ids : List[str]
+            Task IDs
+        iteration : int
+            Iteration
+        circular : int
+            Circular
+        start_time : int
+            Start time
+        end_time : int
+            End time
+        severity : List[str]
+            Severity
+        limit : int
+            Limit
+        sort_order : str
+            Sort order ("asc" or "desc")
+
+        Returns
+        -------
+        List[Dict[str, Any]]
+            List of several informations containing logs
+
+        Examples
+        --------
+
+        >>> swarm_id = '9415dfd18edc45c9a6ffdf2055007bf9'
+        >>> user_api.collect_logs(swarm_id)
+        [{'swarm_id': '9415dfd18edc45c9a6ffdf2055007bf9', 'task_id': 'a2ff3abc76e045d7bb4a04a5ac416318', 'message': ..., 'datetime': '2024-09-13 10:18:06', 'iteration': '1'}, ...]
+
+        Notes
+        -----
+        The argument :code:`service` is managed by a decorator under the hood.
+        """
+        pass
+
+    @call_async
+    def list_result_tags(self, swarm_id: str) -> Dict[str, Any]:
+        """
+        List result tags for a specific swarm.
+
+        Parameters
+        ----------
+        swarm_id : str
+            The swarm ID
+
+        Returns
+        -------
+        Dict[str, Any]
+            Tags with usage information
+        """
+        pass
+
+    @call_async
+    def list_global_tags(self, swarm_id: str) -> Dict[str, Any]:
+        """
+        List global tags for a specific swarm.
+
+        Parameters
+        ----------
+        swarm_id : str
+            The swarm ID
+
+        Returns
+        -------
+        Dict[str, Any]
+            Tags with usage information
+        """
+        pass
+
+    @call_async
+    def select_global(self, swarm_id: str, tag: str) -> List[Dict[str, Any]]:
+        """
+        Select global data for a specific swarm and tag.
+
+        Parameters
+        ----------
+        swarm_id : str
+            The swarm ID
+        tag : str
+            The tag
+
+        Returns
+        -------
+        List[Dict[str, Any]]
+            List of global data
+        """
+        pass