docs: docstrings for schedules and intervals

jorwoods · jorwoods · commit 5d8d69fddcf3 · 2024-11-10T16:42:44.000-06:00
diff --git 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
@@ -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
@@ -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)
