docs: docstrings for JobItem and Jobs endpoint

tableauserverclient/models/job_item.py

@@ -8,6 +8,71 @@
 
 
 class JobItem:
+    """
+    Using the TSC library, you can get information about an asynchronous process
+    (or job) on the server. These jobs can be created when Tableau runs certain
+    tasks that could be long running, such as importing or synchronizing users
+    from Active Directory, or running an extract refresh. For example, the REST
+    API methods to create or update groups, to run an extract refresh task, or
+    to publish workbooks can take an asJob parameter (asJob-true) that creates a
+    background process (the job) to complete the call. Information about the
+    asynchronous job is returned from the method.
+
+    If you have the identifier of the job, you can use the TSC library to find
+    out the status of the asynchronous job.
+
+    The job properties are defined in the JobItem class. The class corresponds
+    to the properties for jobs you can access using the Tableau Server REST API.
+    The job methods are based upon the endpoints for jobs in the REST API and
+    operate on the JobItem class.
+
+    Parameters
+    ----------
+    id_ : str
+        The identifier of the job.
+
+    job_type : str
+        The type of job.
+
+    progress : str
+        The progress of the job.
+
+    created_at : datetime.datetime
+        The date and time the job was created.
+
+    started_at : Optional[datetime.datetime]
+        The date and time the job was started.
+
+    completed_at : Optional[datetime.datetime]
+        The date and time the job was completed.
+
+    finish_code : int
+        The finish code of the job. 0 for success, 1 for failure, 2 for cancelled.
+
+    notes : Optional[list[str]]
+        Contains detailed notes about the job.
+
+    mode : Optional[str]
+
+    workbook_id : Optional[str]
+        The identifier of the workbook associated with the job.
+
+    datasource_id : Optional[str]
+        The identifier of the datasource associated with the job.
+
+    flow_run : Optional[FlowRunItem]
+        The flow run associated with the job.
+
+    updated_at : Optional[datetime.datetime]
+        The date and time the job was last updated.
+
+    workbook_name : Optional[str]
+        The name of the workbook associated with the job.
+
+    datasource_name : Optional[str]
+        The name of the datasource associated with the job.
+    """
+
     class FinishCode:
         """
         Status codes as documented on

tableauserverclient/server/endpoint/jobs_endpoint.py

@@ -33,6 +33,32 @@ def get(self: Self, job_id: None, req_options: Optional[RequestOptionsBase]) ->
 
     @api(version="2.6")
     def get(self, job_id=None, req_options=None):
+        """
+        Retrieve jobs for the site. Endpoint is paginated and will return a
+        list of jobs and pagination information. If a job_id is provided, the
+        method will return information about that specific job. Specifying a
+        job_id is deprecated and will be removed in a future version.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#query_jobs
+
+        Parameters
+        ----------
+        job_id : str or RequestOptionsBase
+            The ID of the job to retrieve. If None, the method will return all
+            jobs for the site. If a RequestOptions object is provided, the
+            method will use the options to filter the jobs.
+
+        req_options : RequestOptionsBase
+            The request options to filter the jobs. If None, the method will
+            return all jobs for the site.
+
+        Returns
+        -------
+        tuple[list[BackgroundJobItem], PaginationItem] or JobItem
+            If a job_id is provided, the method will return a JobItem. If no
+            job_id is provided, the method will return a tuple containing a
+            list of BackgroundJobItems and a PaginationItem.
+        """
         # Backwards Compatibility fix until we rev the major version
         if job_id is not None and isinstance(job_id, str):
             import warnings
@@ -50,6 +76,33 @@ def get(self, job_id=None, req_options=None):
 
     @api(version="3.1")
     def cancel(self, job_id: Union[str, JobItem]):
+        """
+        Cancels a job specified by job ID. To get a list of job IDs for jobs that are currently queued or in-progress, use the Query Jobs method.
+
+        The following jobs can be canceled using the Cancel Job method:
+
+        Full extract refresh
+        Incremental extract refresh
+        Subscription
+        Flow Run
+        Data Acceleration (Data acceleration is not available in Tableau Server 2022.1 (API 3.16) and later. See View Acceleration(Link opens in a new window).)
+        Bridge full extract refresh
+        Bridge incremental extract refresh
+        Queue upgrade Thumbnail (Job that puts the upgrade thumbnail job on the queue)
+        Upgrade Thumbnail
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#cancel_job
+
+        Parameters
+        ----------
+        job_id : str or JobItem
+            The ID of the job to cancel. If a JobItem is provided, the method
+            will use the ID from the JobItem.
+
+        Returns
+        -------
+        None
+        """
         if isinstance(job_id, JobItem):
             job_id = job_id.id
         assert isinstance(job_id, str)
@@ -58,13 +111,69 @@ def cancel(self, job_id: Union[str, JobItem]):
 
     @api(version="2.6")
     def get_by_id(self, job_id: str) -> JobItem:
+        """
+        Returns status information about an asynchronous process that is tracked
+        using a job. This method can be used to query jobs that are used to do
+        the following:
+
+        Import users from Active Directory (the result of a call to Create Group).
+        Synchronize an existing Tableau Server group with Active Directory (the result of a call to Update Group).
+        Run extract refresh tasks (the result of a call to Run Extract Refresh Task).
+        Publish a workbook asynchronously (the result of a call to Publish Workbook).
+        Run workbook or view subscriptions (the result of a call to Create Subscription or Update Subscription)
+        Run a flow task (the result of a call to Run Flow Task)
+        Status of Tableau Server site deletion (the result of a call to asynchronous Delete Site(Link opens in a new window) beginning API 3.18)
+        Note: To query a site deletion job, the server administrator must be first signed into the default site (contentUrl=" ").
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#query_job
+
+        Parameters
+        ----------
+        job_id : str
+            The ID of the job to retrieve.
+
+        Returns
+        -------
+        JobItem
+            The JobItem object that contains information about the requested job.
+        """
         logger.info("Query for information about job " + job_id)
         url = f"{self.baseurl}/{job_id}"
         server_response = self.get_request(url)
         new_job = JobItem.from_response(server_response.content, self.parent_srv.namespace)[0]
         return new_job
 
     def wait_for_job(self, job_id: Union[str, JobItem], *, timeout: Optional[float] = None) -> JobItem:
+        """
+        Waits for a job to complete. The method will poll the server for the job
+        status until the job is completed. If the job is successful, the method
+        will return the JobItem. If the job fails, the method will raise a
+        JobFailedException. If the job is cancelled, the method will raise a
+        JobCancelledException.
+
+        Parameters
+        ----------
+        job_id : str or JobItem
+            The ID of the job to wait for. If a JobItem is provided, the method
+            will use the ID from the JobItem.
+
+        timeout : float | None
+            The maximum amount of time to wait for the job to complete. If None,
+            the method will wait indefinitely.
+
+        Returns
+        -------
+        JobItem
+            The JobItem object that contains information about the completed job.
+
+        Raises
+        ------
+        JobFailedException
+            If the job failed to complete.
+
+        JobCancelledException
+            If the job was cancelled.
+        """
         if isinstance(job_id, JobItem):
             job_id = job_id.id
         assert isinstance(job_id, str)