feat: Add client for SystemLink jobs API

docs/api_reference.rst

@@ -14,6 +14,7 @@ API Reference
    api_reference/dataframe
    api_reference/spec
    api_reference/file
+   api_reference/system
 
 Indices and tables
 ------------------

docs/api_reference/system.rst

@@ -0,0 +1,18 @@
+.. _api_tag_page:
+
+nisystemlink.clients.system
+======================
+
+.. autoclass:: nisystemlink.clients.system.SystemClient
+   :exclude-members: __init__
+
+   .. automethod:: __init__
+   .. automethod:: list_jobs
+   .. automethod:: create_job
+   .. automethod:: get_job_summary
+   .. automethod:: query_jobs
+   .. automethod:: cancel_jobs
+
+.. automodule:: nisystemlink.clients.system.models
+   :members:
+   :imported-members:

docs/getting_started.rst

@@ -210,5 +210,33 @@ Examples
 Get the metadata of a File using its Id and download it.
 
 .. literalinclude:: ../examples/file/download_file.py
+   :language: python
+   :linenos:
+
+
+System API
+-------
+
+Overview
+~~~~~~~~
+
+The :class:`.SystemClient` class is the primary entry point of the System API.
+
+When constructing a :class:`.SystemClient`, you can pass an
+:class:`.HttpConfiguration` (like one retrieved from the
+:class:`.HttpConfigurationManager`), or let :class:`.SystemClient` use the
+default connection. The default connection depends on your environment.
+
+With a :class:`.SystemClient` object, you can:
+
+* Create, get, query, and cancel jobs
+* Get the summary of a jobs
+
+Examples
+~~~~~~~~
+
+Create, get, query, and cancel jobs
+
+.. literalinclude:: ../examples/system/system.py
    :language: python
    :linenos:

examples/system/job.py

@@ -0,0 +1,63 @@
+from nisystemlink.clients.core import HttpConfiguration
+from nisystemlink.clients.system import SystemClient
+from nisystemlink.clients.system.models import (
+    CancelJobRequest,
+    CreateJobRequest,
+    JobField,
+    JobState,
+    QueryJobsRequest,
+)
+
+# Setup the server configuration to point to your instance of SystemLink Enterprise
+server_configuration = HttpConfiguration(
+    server_uri="https://yourserver.yourcompany.com",
+    api_key="YourAPIKeyGeneratedFromSystemLink",
+)
+client = SystemClient(configuration=server_configuration)
+
+# Get all jobs that have succeeded
+jobs = client.list_jobs(
+    system_id="system_id",
+    job_id="jid",
+    state=JobState.SUCCEEDED,
+    function="function",
+    skip=0,
+    take=10,
+)
+
+# Create a job
+arguments = [["A description"]]
+target_systems = [
+    "HVM_domU--SN-ec200972-eeca-062e-5bf5-017a25451b39--MAC-0A-E1-20-D6-96-2B"
+]
+functions = ["system.set_computer_desc"]
+metadata = {"queued": True, "refresh_minion_cache": {"grains": True}}
+job = CreateJobRequest(
+    arguments=arguments,
+    target_systems=target_systems,
+    functions=functions,
+    metadata=metadata,
+)
+
+create_job_response = client.create_job(job)
+
+# Get job summary
+job_summary = client.get_job_summary()
+
+# Query jobs
+query_job = QueryJobsRequest(
+    skip=0,
+    take=1000,
+    filter="result.success.Contains(false)",
+    projection=[JobField.ID, JobField.SYSTEM_ID, "metadata.queued"],
+    orderBy=JobField.CREATED_TIMESTAMP,
+    descending=True,
+)
+query_jobs_response = client.query_jobs(query_job)
+
+
+# Cancel a job
+cancel_job_request = CancelJobRequest(
+    id=create_job_response.id, system_id=target_systems[0]
+)
+cancel_job_response = client.cancel_jobs([cancel_job_request])

nisystemlink/clients/core/_uplink/_methods.py

@@ -17,6 +17,7 @@ def get(path: str, args: Optional[Sequence[Any]] = None) -> Callable[[F], F]:
     """Annotation for a GET request."""
 
     def decorator(func: F) -> F:
+        print("get decorator", func)
         return commands.get(path, args=args)(func)  # type: ignore
 
     return decorator

nisystemlink/clients/system/__init__.py

@@ -0,0 +1,3 @@
+from ._system_client import SystemClient
+
+# flake8: noqa

nisystemlink/clients/system/_system_client.py

@@ -0,0 +1,194 @@
+import json
+from typing import List, Optional, Union
+
+from nisystemlink.clients import core
+from nisystemlink.clients.core import ApiError
+from nisystemlink.clients.core._uplink._base_client import BaseClient
+from nisystemlink.clients.core._uplink._methods import get, post, response_handler
+from requests.models import Response
+from uplink import Query
+
+from . import models
+
+
+def _cancel_job_response_handler(response: Response) -> Union[ApiError, None]:
+    """Response handler for Cancel Job response."""
+    if response is None:
+        return None
+
+    try:
+        cancel_response = response.json()
+    except json.JSONDecodeError:
+        return None
+
+    return cancel_response.get("error")
+
+
+def _list_jobs_response_handler(response: Response) -> List[models.Job]:
+    """Response handler for List Jobs response."""
+    if response is None:
+        return []
+
+    jobs = response.json()
+
+    return jobs
+
+
+class SystemClient(BaseClient):
+    def __init__(self, configuration: Optional[core.HttpConfiguration] = None):
+        """Initialize an instance.
+
+        Args:
+            configuration: Defines the web server to connect to and information about
+                how to connect. If not provided, the
+                :class:`HttpConfigurationManager <nisystemlink.clients.core.HttpConfigurationManager>`
+                is used to obtain the configuration.
+
+        Raises:
+            ApiException: if unable to communicate with the ``/nisysmgmt`` Service.
+        """
+        if configuration is None:
+            configuration = core.HttpConfigurationManager.get_configuration()
+
+        super().__init__(configuration, "/nisysmgmt/v1/")
+
+    @response_handler(_list_jobs_response_handler)
+    @get(
+        "jobs",
+        args=[
+            Query("systemId"),
+            Query("jid"),
+            Query("state"),
+            Query("function"),
+            Query("skip"),
+            Query("take"),
+        ],
+    )
+    def list_jobs(
+        self,
+        system_id: Optional[str] = None,
+        job_id: Optional[str] = None,
+        state: Optional[models.JobState] = None,
+        function: Optional[str] = None,
+        skip: Optional[int] = None,
+        take: Optional[int] = None,
+    ) -> List[models.Job]:
+        """List the jobs that matched the criteria.
+
+        Args:
+            system_id: The ID of the system to that the jobs belong.
+            jid: The ID of the job.
+            state: The state of the jobs.
+            function: The salt function to run on the client.
+            skip: The number of jobs to skip.
+            take: The number of jobs to return.
+
+        Returns:
+            The list of jobs that matched the criteria.
+
+        Raises:
+            ApiException: if unable to communicate with the ``/nisysmgmt`` Service
+                or provided an invalid argument.
+        """
+        ...
+
+    @post("jobs")
+    def create_job(self, job: models.CreateJobRequest) -> models.CreateJobResponse:
+        """Create a job.
+
+        Args:
+            job: The request to create the job.
+
+        Returns:
+            The job that was created.
+
+        Raises:
+            ApiException: if unable to communicate with the ``/nisysmgmt`` Service
+                or provided an invalid argument.
+        """
+        ...
+
+    @get("get-jobs-summary")
+    def get_job_summary(self) -> models.JobSummaryResponse:
+        """Get a summary of the jobs.
+
+        Returns:
+            An instance of a JobsSummaryResponse.
+
+        Raises:
+            ApiException: if unable to communicate with the ``/nisysmgmt`` Service
+                or provided an invalid argument.
+        """
+        ...
+
+    @post("query-jobs")
+    def _query_jobs(self, query: models._QueryJobsRequest) -> models.QueryJobsResponse:
+        """Query the jobs.
+
+        Args:
+            query: The request to query the jobs.
+
+        Returns:
+            An instance of QueryJobsRequest.
+
+        Raises:
+            ApiException: if unable to communicate with the ``/nisysmgmt`` Service
+                or provided an invalid argument.
+        """
+        ...
+
+    def query_jobs(self, query: models.QueryJobsRequest) -> models.QueryJobsResponse:
+        """Query the jobs.
+
+        Args:
+            query: The request to query the jobs.
+
+        Returns:
+            An instance of QueryJobsRequest.
+
+        Raises:
+            ApiException: if unable to communicate with the ``/nisysmgmt`` Service
+                or provided an invalid argument.
+        """
+        projection = f"new({','.join(query.projection)})" if query.projection else None
+
+        order_by = (
+            f"{query.order_by.value} {'descending' if query.descending else 'ascending'}"
+            if query.order_by
+            else None
+        )
+
+        query_params = {
+            "skip": query.skip,
+            "take": query.take,
+            "filter": query.filter,
+            "projection": projection,
+            "order_by": order_by,
+        }
+
+        # Clean the query_params to remove any keys with None values
+        query_params = {k: v for k, v in query_params.items() if v is not None}
+
+        # Create the query request with the cleaned parameters
+        query_request = models._QueryJobsRequest(**query_params)
+
+        return self._query_jobs(query_request)
+
+    @response_handler(_cancel_job_response_handler)
+    @post("cancel-jobs")
+    def cancel_jobs(
+        self, job_ids: List[models.CancelJobRequest]
+    ) -> Union[ApiError, None]:
+        """Cancel the jobs.
+
+        Args:
+            job_ids: List of CancelJobRequest.
+
+        Returns:
+            The errors that appear while attempting the operation.
+
+        Raises:
+            ApiException: if unable to communicate with the ``/nisysmgmt`` Service
+                or provided an invalid argument.
+        """
+        ...

nisystemlink/clients/system/models/__init__.py

@@ -0,0 +1,9 @@
+from ._job import Job, JobState, JobConfig, JobResult
+from ._create_job_request import CreateJobRequest
+from ._create_job_response import CreateJobResponse
+from ._job_summary_response import JobSummaryResponse
+from ._query_jobs_request import QueryJobsRequest, _QueryJobsRequest, JobField
+from ._query_jobs_response import QueryJobsResponse, QueryJob, QueryJobConfig
+from ._cancel_job_request import CancelJobRequest
+
+# flake8: noqa

nisystemlink/clients/system/models/_cancel_job_request.py

@@ -0,0 +1,12 @@
+from nisystemlink.clients.core._uplink._json_model import JsonModel
+from pydantic import Field
+
+
+class CancelJobRequest(JsonModel):
+    """Model for cancel job request."""
+
+    id: str = Field(alias="jid")
+    """The ID of the job to cancel."""
+
+    system_id: str
+    """The system ID that the job to cancel targets."""

nisystemlink/clients/system/models/_create_job_request.py

@@ -0,0 +1,20 @@
+from typing import Any, Dict, List, Optional
+
+from nisystemlink.clients.core._uplink._json_model import JsonModel
+from pydantic import Field
+
+
+class CreateJobRequest(JsonModel):
+    """Model for create job request."""
+
+    arguments: Optional[List[List[Any]]] = Field(None, alias="arg")
+    """List of arguments to the functions specified in the "fun" property."""
+
+    target_systems: List[str] = Field(alias="tgt")
+    """List of system IDs on which to run the job."""
+
+    functions: List[str] = Field(alias="fun")
+    """Functions contained in the job."""
+
+    metadata: Optional[Dict[str, Any]] = None
+    """Additional information of the job."""

nisystemlink/clients/system/models/_create_job_response.py

@@ -0,0 +1,16 @@
+from typing import Optional
+
+from nisystemlink.clients.core import ApiError
+from pydantic import Field
+
+from ._create_job_request import CreateJobRequest
+
+
+class CreateJobResponse(CreateJobRequest):
+    """Model for response of create job request."""
+
+    error: Optional[ApiError] = None
+    """Represents the standard error structure."""
+
+    id: str = Field(alias="jid")
+    """The job ID."""