Skip to content

Commit a43355a

Browse files
jorwoodsjorwoods
authored
docs: docstrings for JobItem and Jobs endpoint (#1529)
Co-authored-by: Jordan Woods <13803242+jorwoods@users.noreply.github.com>
1 parent f9341a4 commit a43355a

File tree

2 files changed

+174
-0
lines changed

2 files changed

+174
-0
lines changed

‎tableauserverclient/models/job_item.py

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,71 @@
88

99

1010
class JobItem:
11+
"""
12+
Using the TSC library, you can get information about an asynchronous process
13+
(or job) on the server. These jobs can be created when Tableau runs certain
14+
tasks that could be long running, such as importing or synchronizing users
15+
from Active Directory, or running an extract refresh. For example, the REST
16+
API methods to create or update groups, to run an extract refresh task, or
17+
to publish workbooks can take an asJob parameter (asJob-true) that creates a
18+
background process (the job) to complete the call. Information about the
19+
asynchronous job is returned from the method.
20+
21+
If you have the identifier of the job, you can use the TSC library to find
22+
out the status of the asynchronous job.
23+
24+
The job properties are defined in the JobItem class. The class corresponds
25+
to the properties for jobs you can access using the Tableau Server REST API.
26+
The job methods are based upon the endpoints for jobs in the REST API and
27+
operate on the JobItem class.
28+
29+
Parameters
30+
----------
31+
id_ : str
32+
The identifier of the job.
33+
34+
job_type : str
35+
The type of job.
36+
37+
progress : str
38+
The progress of the job.
39+
40+
created_at : datetime.datetime
41+
The date and time the job was created.
42+
43+
started_at : Optional[datetime.datetime]
44+
The date and time the job was started.
45+
46+
completed_at : Optional[datetime.datetime]
47+
The date and time the job was completed.
48+
49+
finish_code : int
50+
The finish code of the job. 0 for success, 1 for failure, 2 for cancelled.
51+
52+
notes : Optional[list[str]]
53+
Contains detailed notes about the job.
54+
55+
mode : Optional[str]
56+
57+
workbook_id : Optional[str]
58+
The identifier of the workbook associated with the job.
59+
60+
datasource_id : Optional[str]
61+
The identifier of the datasource associated with the job.
62+
63+
flow_run : Optional[FlowRunItem]
64+
The flow run associated with the job.
65+
66+
updated_at : Optional[datetime.datetime]
67+
The date and time the job was last updated.
68+
69+
workbook_name : Optional[str]
70+
The name of the workbook associated with the job.
71+
72+
datasource_name : Optional[str]
73+
The name of the datasource associated with the job.
74+
"""
75+
1176
class FinishCode:
1277
"""
1378
Status codes as documented on

‎tableauserverclient/server/endpoint/jobs_endpoint.py

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,32 @@ def get(self: Self, job_id: None, req_options: Optional[RequestOptionsBase]) ->
3333

3434
@api(version="2.6")
3535
def get(self, job_id=None, req_options=None):
36+
"""
37+
Retrieve jobs for the site. Endpoint is paginated and will return a
38+
list of jobs and pagination information. If a job_id is provided, the
39+
method will return information about that specific job. Specifying a
40+
job_id is deprecated and will be removed in a future version.
41+
42+
REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#query_jobs
43+
44+
Parameters
45+
----------
46+
job_id : str or RequestOptionsBase
47+
The ID of the job to retrieve. If None, the method will return all
48+
jobs for the site. If a RequestOptions object is provided, the
49+
method will use the options to filter the jobs.
50+
51+
req_options : RequestOptionsBase
52+
The request options to filter the jobs. If None, the method will
53+
return all jobs for the site.
54+
55+
Returns
56+
-------
57+
tuple[list[BackgroundJobItem], PaginationItem] or JobItem
58+
If a job_id is provided, the method will return a JobItem. If no
59+
job_id is provided, the method will return a tuple containing a
60+
list of BackgroundJobItems and a PaginationItem.
61+
"""
3662
# Backwards Compatibility fix until we rev the major version
3763
if job_id is not None and isinstance(job_id, str):
3864
import warnings
@@ -50,6 +76,33 @@ def get(self, job_id=None, req_options=None):
5076

5177
@api(version="3.1")
5278
def cancel(self, job_id: Union[str, JobItem]):
79+
"""
80+
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.
81+
82+
The following jobs can be canceled using the Cancel Job method:
83+
84+
Full extract refresh
85+
Incremental extract refresh
86+
Subscription
87+
Flow Run
88+
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).)
89+
Bridge full extract refresh
90+
Bridge incremental extract refresh
91+
Queue upgrade Thumbnail (Job that puts the upgrade thumbnail job on the queue)
92+
Upgrade Thumbnail
93+
94+
REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#cancel_job
95+
96+
Parameters
97+
----------
98+
job_id : str or JobItem
99+
The ID of the job to cancel. If a JobItem is provided, the method
100+
will use the ID from the JobItem.
101+
102+
Returns
103+
-------
104+
None
105+
"""
53106
if isinstance(job_id, JobItem):
54107
job_id = job_id.id
55108
assert isinstance(job_id, str)
@@ -58,13 +111,69 @@ def cancel(self, job_id: Union[str, JobItem]):
58111

59112
@api(version="2.6")
60113
def get_by_id(self, job_id: str) -> JobItem:
114+
"""
115+
Returns status information about an asynchronous process that is tracked
116+
using a job. This method can be used to query jobs that are used to do
117+
the following:
118+
119+
Import users from Active Directory (the result of a call to Create Group).
120+
Synchronize an existing Tableau Server group with Active Directory (the result of a call to Update Group).
121+
Run extract refresh tasks (the result of a call to Run Extract Refresh Task).
122+
Publish a workbook asynchronously (the result of a call to Publish Workbook).
123+
Run workbook or view subscriptions (the result of a call to Create Subscription or Update Subscription)
124+
Run a flow task (the result of a call to Run Flow Task)
125+
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)
126+
Note: To query a site deletion job, the server administrator must be first signed into the default site (contentUrl=" ").
127+
128+
REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#query_job
129+
130+
Parameters
131+
----------
132+
job_id : str
133+
The ID of the job to retrieve.
134+
135+
Returns
136+
-------
137+
JobItem
138+
The JobItem object that contains information about the requested job.
139+
"""
61140
logger.info("Query for information about job " + job_id)
62141
url = f"{self.baseurl}/{job_id}"
63142
server_response = self.get_request(url)
64143
new_job = JobItem.from_response(server_response.content, self.parent_srv.namespace)[0]
65144
return new_job
66145

67146
def wait_for_job(self, job_id: Union[str, JobItem], *, timeout: Optional[float] = None) -> JobItem:
147+
"""
148+
Waits for a job to complete. The method will poll the server for the job
149+
status until the job is completed. If the job is successful, the method
150+
will return the JobItem. If the job fails, the method will raise a
151+
JobFailedException. If the job is cancelled, the method will raise a
152+
JobCancelledException.
153+
154+
Parameters
155+
----------
156+
job_id : str or JobItem
157+
The ID of the job to wait for. If a JobItem is provided, the method
158+
will use the ID from the JobItem.
159+
160+
timeout : float | None
161+
The maximum amount of time to wait for the job to complete. If None,
162+
the method will wait indefinitely.
163+
164+
Returns
165+
-------
166+
JobItem
167+
The JobItem object that contains information about the completed job.
168+
169+
Raises
170+
------
171+
JobFailedException
172+
If the job failed to complete.
173+
174+
JobCancelledException
175+
If the job was cancelled.
176+
"""
68177
if isinstance(job_id, JobItem):
69178
job_id = job_id.id
70179
assert isinstance(job_id, str)

0 commit comments

Comments
 (0)