From 5d8d69fddcf32df12505cbd8bb18d34ed6f4abfd Mon Sep 17 00:00:00 2001 From: Jordan Woods <13803242+jorwoods@users.noreply.github.com> Date: Sun, 10 Nov 2024 16:42:44 -0600 Subject: [PATCH] docs: docstrings for schedules and intervals --- tableauserverclient/models/interval_item.py | 40 ++++++ tableauserverclient/models/schedule_item.py | 57 +++++++++ .../server/endpoint/schedules_endpoint.py | 114 +++++++++++++++++- 3 files changed, 210 insertions(+), 1 deletion(-) diff --git a/tableauserverclient/models/interval_item.py b/tableauserverclient/models/interval_item.py index d7cf891c..14cec187 100644 --- a/tableauserverclient/models/interval_item.py +++ b/tableauserverclient/models/interval_item.py @@ -2,6 +2,13 @@ class IntervalItem: + """ + This class sets the frequency and start time of the scheduled item. This + class contains the classes for the hourly, daily, weekly, and monthly + intervals. This class mirrors the options you can set using the REST API and + the Tableau Server interface. + """ + class Frequency: Hourly = "Hourly" Daily = "Daily" @@ -26,6 +33,19 @@ class Day: class HourlyInterval: + """ + Runs scheduled item hourly. To set the hourly interval, you create an + instance of the HourlyInterval class and assign the following values: + start_time, end_time, and interval_value. To set the start_time and + end_time, assign the time value using this syntax: start_time=time(hour, minute) + and end_time=time(hour, minute). The hour is specified in 24 hour time. + The interval_value specifies how often the to run the task within the + start and end time. The options are expressed in hours. For example, + interval_value=.25 is every 15 minutes. The values are .25, .5, 1, 2, 4, 6, + 8, 12. Hourly schedules that run more frequently than every 60 minutes must + have start and end times that are on the hour. + """ + def __init__(self, start_time, end_time, interval_value): self.start_time = start_time self.end_time = end_time @@ -109,6 +129,12 @@ def _interval_type_pairs(self): class DailyInterval: + """ + Runs the scheduled item daily. To set the daily interval, you create an + instance of the DailyInterval and assign the start_time. The start time uses + the syntax start_time=time(hour, minute). + """ + def __init__(self, start_time, *interval_values): self.start_time = start_time self.interval = interval_values @@ -177,6 +203,15 @@ def _interval_type_pairs(self): class WeeklyInterval: + """ + Runs the scheduled item once a week. To set the weekly interval, you create + an instance of the WeeklyInterval and assign the start time and multiple + instances for the interval_value (days of week and start time). The start + time uses the syntax time(hour, minute). The interval_value is the day of + the week, expressed as a IntervalItem. For example + TSC.IntervalItem.Day.Monday for Monday. + """ + def __init__(self, start_time, *interval_values): self.start_time = start_time self.interval = interval_values @@ -214,6 +249,11 @@ def _interval_type_pairs(self): class MonthlyInterval: + """ + Runs the scheduled item once a month. To set the monthly interval, you + create an instance of the MonthlyInterval and assign the start time and day. + """ + def __init__(self, start_time, interval_value): self.start_time = start_time diff --git a/tableauserverclient/models/schedule_item.py b/tableauserverclient/models/schedule_item.py index e3904205..a2118e3d 100644 --- a/tableauserverclient/models/schedule_item.py +++ b/tableauserverclient/models/schedule_item.py @@ -20,6 +20,63 @@ class ScheduleItem: + """ + Using the TSC library, you can schedule extract refresh or subscription + tasks on Tableau Server. You can also get and update information about the + scheduled tasks, or delete scheduled tasks. + + If you have the identifier of the job, you can use the TSC library to find + out the status of the asynchronous job. + + The schedule properties are defined in the ScheduleItem class. The class + corresponds to the properties for schedules you can access in Tableau + Server or by using the Tableau Server REST API. The Schedule methods are + based upon the endpoints for jobs in the REST API and operate on the JobItem + class. + + Parameters + ---------- + name : str + The name of the schedule. + + priority : int + The priority of the schedule. Lower values represent higher priority, + with 0 indicating the highest priority. + + schedule_type : str + The type of task schedule. See ScheduleItem.Type for the possible values. + + execution_order : str + Specifies how the scheduled tasks should run. The choices are Parallel + which uses all avaiable background processes for a scheduled task, or + Serial, which limits the schedule to one background process. + + interval_item : Interval + Specifies the frequency that the scheduled task should run. The + interval_item is an instance of the IntervalItem class. The + interval_item has properties for frequency (hourly, daily, weekly, + monthly), and what time and date the scheduled item runs. You set this + value by declaring an IntervalItem object that is one of the following: + HourlyInterval, DailyInterval, WeeklyInterval, or MonthlyInterval. + + Attributes + ---------- + created_at : datetime + The date and time the schedule was created. + + end_schedule_at : datetime + The date and time the schedule ends. + + id : str + The unique identifier for the schedule. + + next_run_at : datetime + The date and time the schedule is next run. + + state : str + The state of the schedule. See ScheduleItem.State for the possible values. + """ + class Type: Extract = "Extract" Flow = "Flow" diff --git a/tableauserverclient/server/endpoint/schedules_endpoint.py b/tableauserverclient/server/endpoint/schedules_endpoint.py index eec4536f..8693d66c 100644 --- a/tableauserverclient/server/endpoint/schedules_endpoint.py +++ b/tableauserverclient/server/endpoint/schedules_endpoint.py @@ -30,6 +30,23 @@ def siteurl(self) -> str: @api(version="2.3") def get(self, req_options: Optional["RequestOptions"] = None) -> tuple[list[ScheduleItem], PaginationItem]: + """ + Returns a list of flows, extract, and subscription server schedules on + Tableau Server. For each schedule, the API returns name, frequency, + priority, and other information. + + REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#query_schedules + + Parameters + ---------- + req_options : Optional[RequestOptions] + Filtering and paginating options for request. + + Returns + ------- + Tuple[List[ScheduleItem], PaginationItem] + A tuple of list of ScheduleItem and PaginationItem + """ logger.info("Querying all schedules") url = self.baseurl server_response = self.get_request(url, req_options) @@ -38,7 +55,22 @@ def get(self, req_options: Optional["RequestOptions"] = None) -> tuple[list[Sche return all_schedule_items, pagination_item @api(version="3.8") - def get_by_id(self, schedule_id): + def get_by_id(self, schedule_id: str) -> ScheduleItem: + """ + Returns detailed information about the specified server schedule. + + REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#get-schedule + + Parameters + ---------- + schedule_id : str + The ID of the schedule to get information for. + + Returns + ------- + ScheduleItem + The schedule item that corresponds to the given ID. + """ if not schedule_id: error = "No Schedule ID provided" raise ValueError(error) @@ -49,6 +81,20 @@ def get_by_id(self, schedule_id): @api(version="2.3") def delete(self, schedule_id: str) -> None: + """ + Deletes the specified schedule from the server. + + REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#delete_schedule + + Parameters + ---------- + schedule_id : str + The ID of the schedule to delete. + + Returns + ------- + None + """ if not schedule_id: error = "Schedule ID undefined" raise ValueError(error) @@ -58,6 +104,23 @@ def delete(self, schedule_id: str) -> None: @api(version="2.3") def update(self, schedule_item: ScheduleItem) -> ScheduleItem: + """ + Modifies settings for the specified server schedule, including the name, + priority, and frequency details on Tableau Server. For Tableau Cloud, + see the tasks and subscritpions API. + + REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#update_schedule + + Parameters + ---------- + schedule_item : ScheduleItem + The schedule item to update. + + Returns + ------- + ScheduleItem + The updated schedule item. + """ if not schedule_item.id: error = "Schedule item missing ID." raise MissingRequiredFieldError(error) @@ -71,6 +134,20 @@ def update(self, schedule_item: ScheduleItem) -> ScheduleItem: @api(version="2.3") def create(self, schedule_item: ScheduleItem) -> ScheduleItem: + """ + Creates a new server schedule on Tableau Server. For Tableau Cloud, use + the tasks and subscriptions API. + + Parameters + ---------- + schedule_item : ScheduleItem + The schedule item to create. + + Returns + ------- + ScheduleItem + The newly created schedule. + """ if schedule_item.interval_item is None: error = "Interval item must be defined." raise MissingRequiredFieldError(error) @@ -92,6 +169,41 @@ def add_to_schedule( flow: Optional["FlowItem"] = None, task_type: Optional[str] = None, ) -> list[AddResponse]: + """ + Adds a workbook, datasource, or flow to a schedule on Tableau Server. + Only one of workbook, datasource, or flow can be passed in at a time. + + The task type is optional and will default to ExtractRefresh if a + workbook or datasource is passed in, and RunFlow if a flow is passed in. + + REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#add_workbook_to_schedule + REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#add_data_source_to_schedule + REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#add_flow_task_to_schedule + + Parameters + ---------- + schedule_id : str + The ID of the schedule to add the item to. + + workbook : Optional[WorkbookItem] + The workbook to add to the schedule. + + datasource : Optional[DatasourceItem] + The datasource to add to the schedule. + + flow : Optional[FlowItem] + The flow to add to the schedule. + + task_type : Optional[str] + The type of task to add to the schedule. If not provided, it will + default to ExtractRefresh if a workbook or datasource is passed in, + and RunFlow if a flow is passed in. + + Returns + ------- + list[AddResponse] + A list of responses for each item added to the schedule. + """ # There doesn't seem to be a good reason to allow one item of each type? if workbook and datasource: warnings.warn("Passing in multiple items for add_to_schedule will be deprecated", PendingDeprecationWarning)