tableauserverclient 0.33__py3-none-any.whl → 0.35__py3-none-any.whl

tableauserverclient/server/filter.py

@@ -1,7 +1,7 @@
 from .request_options import RequestOptions
 
 
-class Filter(object):
+class Filter:
     def __init__(self, field, operator, value):
         self.field = field
         self.operator = operator
@@ -16,7 +16,7 @@ class Filter(object):
             # to [<string1>,<string2>]
             # so effectively, remove any spaces between "," and "'" and then remove all "'"
             value_string = value_string.replace(", '", ",'").replace("'", "")
-        return "{0}:{1}:{2}".format(self.field, self.operator, value_string)
+        return f"{self.field}:{self.operator}:{value_string}"
 
     @property
     def value(self):

tableauserverclient/server/pager.py

@@ -1,6 +1,7 @@
 import copy
 from functools import partial
-from typing import Iterable, Iterator, List, Optional, Protocol, Tuple, TypeVar, Union, runtime_checkable
+from typing import Optional, Protocol, TypeVar, Union, runtime_checkable
+from collections.abc import Iterable, Iterator
 
 from tableauserverclient.models.pagination_item import PaginationItem
 from tableauserverclient.server.request_options import RequestOptions
@@ -11,14 +12,12 @@ T = TypeVar("T")
 
 @runtime_checkable
 class Endpoint(Protocol[T]):
-    def get(self, req_options: Optional[RequestOptions]) -> Tuple[List[T], PaginationItem]:
-        ...
+    def get(self, req_options: Optional[RequestOptions]) -> tuple[list[T], PaginationItem]: ...
 
 
 @runtime_checkable
 class CallableEndpoint(Protocol[T]):
-    def __call__(self, __req_options: Optional[RequestOptions], **kwargs) -> Tuple[List[T], PaginationItem]:
-        ...
+    def __call__(self, __req_options: Optional[RequestOptions], **kwargs) -> tuple[list[T], PaginationItem]: ...
 
 
 class Pager(Iterable[T]):
@@ -27,7 +26,31 @@ class Pager(Iterable[T]):
     Supports all `RequestOptions` including starting on any page. Also used by models to load sub-models
     (users in a group, views in a workbook, etc) by passing a different endpoint.
 
-    Will loop over anything that returns (List[ModelItem], PaginationItem).
+    Will loop over anything that returns (list[ModelItem], PaginationItem).
+
+    Will make a copy of the `RequestOptions` object passed in so it can be reused.
+
+    Makes a call to the Server for each page of items, then yields each item in the list.
+
+    Parameters
+    ----------
+    endpoint: CallableEndpoint[T] or Endpoint[T]
+        The endpoint to call to get the items. Can be a callable or an Endpoint object.
+        Expects a tuple of (list[T], PaginationItem) to be returned.
+
+    request_opts: RequestOptions, optional
+        The request options to pass to the endpoint. If not provided, will use default RequestOptions.
+        Filters, sorts, page size, starting page number, etc can be set here.
+
+    Yields
+    ------
+    T
+        The items returned from the endpoint.
+
+    Raises
+    ------
+    ValueError
+        If the endpoint is not a callable or an Endpoint object.
     """
 
     def __init__(

tableauserverclient/server/query.py

@@ -1,8 +1,10 @@
-from collections.abc import Sized
+from collections.abc import Iterable, Iterator, Sized
 from itertools import count
-from typing import Iterable, Iterator, List, Optional, Protocol, Tuple, TYPE_CHECKING, TypeVar, overload
+from typing import Optional, Protocol, TYPE_CHECKING, TypeVar, overload
+import sys
 from tableauserverclient.config import config
 from tableauserverclient.models.pagination_item import PaginationItem
+from tableauserverclient.server.endpoint.exceptions import ServerResponseError
 from tableauserverclient.server.filter import Filter
 from tableauserverclient.server.request_options import RequestOptions
 from tableauserverclient.server.sort import Sort
@@ -34,10 +36,36 @@ see pagination_sample
 
 
 class QuerySet(Iterable[T], Sized):
+    """
+    QuerySet is a class that allows easy filtering, sorting, and iterating over
+    many endpoints in TableauServerClient. It is designed to be used in a similar
+    way to Django QuerySets, but with a more limited feature set.
+
+    QuerySet is an iterable, and can be used in for loops, list comprehensions,
+    and other places where iterables are expected.
+
+    QuerySet is also Sized, and can be used in places where the length of the
+    QuerySet is needed. The length of the QuerySet is the total number of items
+    available in the QuerySet, not just the number of items that have been
+    fetched. If the endpoint does not return a total count of items, the length
+    of the QuerySet will be sys.maxsize. If there is no total count, the
+    QuerySet will continue to fetch items until there are no more items to
+    fetch.
+
+    QuerySet is not re-entrant. It is not designed to be used in multiple places
+    at the same time. If you need to use a QuerySet in multiple places, you
+    should create a new QuerySet for each place you need to use it, convert it
+    to a list, or create a deep copy of the QuerySet.
+
+    QuerySets are also indexable, and can be sliced. If you try to access an
+    index that has not been fetched, the QuerySet will fetch the page that
+    contains the item you are looking for.
+    """
+
     def __init__(self, model: "QuerysetEndpoint[T]", page_size: Optional[int] = None) -> None:
         self.model = model
         self.request_options = RequestOptions(pagesize=page_size or config.PAGE_SIZE)
-        self._result_cache: List[T] = []
+        self._result_cache: list[T] = []
         self._pagination_item = PaginationItem()
 
     def __iter__(self: Self) -> Iterator[T]:
@@ -49,19 +77,30 @@ class QuerySet(Iterable[T], Sized):
         for page in count(1):
             self.request_options.pagenumber = page
             self._result_cache = []
-            self._fetch_all()
+            self._pagination_item._page_number = None
+            try:
+                self._fetch_all()
+            except ServerResponseError as e:
+                if e.code == "400006":
+                    # If the endpoint does not support pagination, it will end
+                    # up overrunning the total number of pages. Catch the
+                    # error and break out of the loop.
+                    raise StopIteration
+            if len(self._result_cache) == 0:
+                return
             yield from self._result_cache
-            # Set result_cache to empty so the fetch will populate
-            if (page * self.page_size) >= len(self):
+            # If the length of the QuerySet is unknown, continue fetching until
+            # the result cache is empty.
+            if (size := len(self)) == 0:
+                continue
+            if (page * self.page_size) >= size:
                 return
 
     @overload
-    def __getitem__(self: Self, k: Slice) -> List[T]:
-        ...
+    def __getitem__(self: Self, k: Slice) -> list[T]: ...
 
     @overload
-    def __getitem__(self: Self, k: int) -> T:
-        ...
+    def __getitem__(self: Self, k: int) -> T: ...
 
     def __getitem__(self, k):
         page = self.page_number
@@ -103,6 +142,7 @@ class QuerySet(Iterable[T], Sized):
         elif k in range(self.total_available):
             # Otherwise, check if k is even sensible to return
             self._result_cache = []
+            self._pagination_item._page_number = None
             # Add one to k, otherwise it gets stuck at page boundaries, e.g. 100
             self.request_options.pagenumber = max(1, math.ceil((k + 1) / size))
             return self[k]
@@ -114,11 +154,16 @@ class QuerySet(Iterable[T], Sized):
         """
         Retrieve the data and store result and pagination item in cache
         """
-        if not self._result_cache:
-            self._result_cache, self._pagination_item = self.model.get(self.request_options)
+        if not self._result_cache and self._pagination_item._page_number is None:
+            response = self.model.get(self.request_options)
+            if isinstance(response, tuple):
+                self._result_cache, self._pagination_item = response
+            else:
+                self._result_cache = response
+                self._pagination_item = PaginationItem()
 
     def __len__(self: Self) -> int:
-        return self.total_available
+        return sys.maxsize if self.total_available is None else self.total_available
 
     @property
     def total_available(self: Self) -> int:
@@ -128,12 +173,16 @@ class QuerySet(Iterable[T], Sized):
     @property
     def page_number(self: Self) -> int:
         self._fetch_all()
-        return self._pagination_item.page_number
+        # If the PaginationItem is not returned from the endpoint, use the
+        # pagenumber from the RequestOptions.
+        return self._pagination_item.page_number or self.request_options.pagenumber
 
     @property
     def page_size(self: Self) -> int:
         self._fetch_all()
-        return self._pagination_item.page_size
+        # If the PaginationItem is not returned from the endpoint, use the
+        # pagesize from the RequestOptions.
+        return self._pagination_item.page_size or self.request_options.pagesize
 
     def filter(self: Self, *invalid, page_size: Optional[int] = None, **kwargs) -> Self:
         if invalid:
@@ -160,22 +209,22 @@ class QuerySet(Iterable[T], Sized):
         return self
 
     @staticmethod
-    def _parse_shorthand_filter(key: str) -> Tuple[str, str]:
+    def _parse_shorthand_filter(key: str) -> tuple[str, str]:
         tokens = key.split("__", 1)
         if len(tokens) == 1:
             operator = RequestOptions.Operator.Equals
         else:
             operator = tokens[1]
             if operator not in RequestOptions.Operator.__dict__.values():
-                raise ValueError("Operator `{}` is not valid.".format(operator))
+                raise ValueError(f"Operator `{operator}` is not valid.")
 
         field = to_camel_case(tokens[0])
         if field not in RequestOptions.Field.__dict__.values():
-            raise ValueError("Field name `{}` is not valid.".format(field))
+            raise ValueError(f"Field name `{field}` is not valid.")
         return (field, operator)
 
     @staticmethod
-    def _parse_shorthand_sort(key: str) -> Tuple[str, str]:
+    def _parse_shorthand_sort(key: str) -> tuple[str, str]:
         direction = RequestOptions.Direction.Asc
         if key.startswith("-"):
             direction = RequestOptions.Direction.Desc

tableauserverclient/server/request_factory.py

@@ -1,5 +1,6 @@
 import xml.etree.ElementTree as ET
-from typing import Any, Callable, Dict, Iterable, List, Optional, Set, Tuple, TypeVar, TYPE_CHECKING, Union
+from typing import Any, Callable, Optional, TypeVar, TYPE_CHECKING, Union
+from collections.abc import Iterable
 
 from typing_extensions import ParamSpec
 
@@ -15,7 +16,7 @@ if TYPE_CHECKING:
 # this file could be largely replaced if we were willing to import the huge file from generateDS
 
 
-def _add_multipart(parts: Dict) -> Tuple[Any, str]:
+def _add_multipart(parts: dict) -> tuple[Any, str]:
     mime_multipart_parts = list()
     for name, (filename, data, content_type) in parts.items():
         multipart_part = RequestField(name=name, data=data, filename=filename)
@@ -80,7 +81,7 @@ def _add_credentials_element(parent_element, connection_credentials):
         credentials_element.attrib["oAuth"] = "true"
 
 
-class AuthRequest(object):
+class AuthRequest:
     def signin_req(self, auth_item):
         xml_request = ET.Element("tsRequest")
 
@@ -104,7 +105,7 @@ class AuthRequest(object):
         return ET.tostring(xml_request)
 
 
-class ColumnRequest(object):
+class ColumnRequest:
     def update_req(self, column_item):
         xml_request = ET.Element("tsRequest")
         column_element = ET.SubElement(xml_request, "column")
@@ -115,7 +116,7 @@ class ColumnRequest(object):
         return ET.tostring(xml_request)
 
 
-class DataAlertRequest(object):
+class DataAlertRequest:
     def add_user_to_alert(self, alert_item: "DataAlertItem", user_id: str) -> bytes:
         xml_request = ET.Element("tsRequest")
         user_element = ET.SubElement(xml_request, "user")
@@ -140,7 +141,7 @@ class DataAlertRequest(object):
         return ET.tostring(xml_request)
 
 
-class DatabaseRequest(object):
+class DatabaseRequest:
     def update_req(self, database_item):
         xml_request = ET.Element("tsRequest")
         database_element = ET.SubElement(xml_request, "database")
@@ -159,7 +160,7 @@ class DatabaseRequest(object):
         return ET.tostring(xml_request)
 
 
-class DatasourceRequest(object):
+class DatasourceRequest:
     def _generate_xml(self, datasource_item: DatasourceItem, connection_credentials=None, connections=None):
         xml_request = ET.Element("tsRequest")
         datasource_element = ET.SubElement(xml_request, "datasource")
@@ -244,7 +245,7 @@ class DatasourceRequest(object):
         return _add_multipart(parts)
 
 
-class DQWRequest(object):
+class DQWRequest:
     def add_req(self, dqw_item):
         xml_request = ET.Element("tsRequest")
         dqw_element = ET.SubElement(xml_request, "dataQualityWarning")
@@ -274,7 +275,7 @@ class DQWRequest(object):
         return ET.tostring(xml_request)
 
 
-class FavoriteRequest(object):
+class FavoriteRequest:
     def add_request(self, id_: Optional[str], target_type: str, label: Optional[str]) -> bytes:
         """
         <favorite label="...">
@@ -329,7 +330,7 @@ class FavoriteRequest(object):
         return self.add_request(id_, Resource.Workbook, name)
 
 
-class FileuploadRequest(object):
+class FileuploadRequest:
     def chunk_req(self, chunk):
         parts = {
             "request_payload": ("", "", "text/xml"),
@@ -338,8 +339,8 @@ class FileuploadRequest(object):
         return _add_multipart(parts)
 
 
-class FlowRequest(object):
-    def _generate_xml(self, flow_item: "FlowItem", connections: Optional[List["ConnectionItem"]] = None) -> bytes:
+class FlowRequest:
+    def _generate_xml(self, flow_item: "FlowItem", connections: Optional[list["ConnectionItem"]] = None) -> bytes:
         xml_request = ET.Element("tsRequest")
         flow_element = ET.SubElement(xml_request, "flow")
         if flow_item.name is not None:
@@ -370,8 +371,8 @@ class FlowRequest(object):
         flow_item: "FlowItem",
         filename: str,
         file_contents: bytes,
-        connections: Optional[List["ConnectionItem"]] = None,
-    ) -> Tuple[Any, str]:
+        connections: Optional[list["ConnectionItem"]] = None,
+    ) -> tuple[Any, str]:
         xml_request = self._generate_xml(flow_item, connections)
 
         parts = {
@@ -380,14 +381,14 @@ class FlowRequest(object):
         }
         return _add_multipart(parts)
 
-    def publish_req_chunked(self, flow_item, connections=None) -> Tuple[Any, str]:
+    def publish_req_chunked(self, flow_item, connections=None) -> tuple[Any, str]:
         xml_request = self._generate_xml(flow_item, connections)
 
         parts = {"request_payload": ("", xml_request, "text/xml")}
         return _add_multipart(parts)
 
 
-class GroupRequest(object):
+class GroupRequest:
     def add_user_req(self, user_id: str) -> bytes:
         xml_request = ET.Element("tsRequest")
         user_element = ET.SubElement(xml_request, "user")
@@ -477,7 +478,7 @@ class GroupRequest(object):
         return ET.tostring(xml_request)
 
 
-class PermissionRequest(object):
+class PermissionRequest:
     def add_req(self, rules: Iterable[PermissionsRule]) -> bytes:
         xml_request = ET.Element("tsRequest")
         permissions_element = ET.SubElement(xml_request, "permissions")
@@ -499,7 +500,7 @@ class PermissionRequest(object):
             capability_element.attrib["mode"] = mode
 
 
-class ProjectRequest(object):
+class ProjectRequest:
     def update_req(self, project_item: "ProjectItem") -> bytes:
         xml_request = ET.Element("tsRequest")
         project_element = ET.SubElement(xml_request, "project")
@@ -530,7 +531,7 @@ class ProjectRequest(object):
         return ET.tostring(xml_request)
 
 
-class ScheduleRequest(object):
+class ScheduleRequest:
     def create_req(self, schedule_item):
         xml_request = ET.Element("tsRequest")
         schedule_element = ET.SubElement(xml_request, "schedule")
@@ -609,7 +610,7 @@ class ScheduleRequest(object):
         return self._add_to_req(id_, "flow", task_type)
 
 
-class SiteRequest(object):
+class SiteRequest:
     def update_req(self, site_item: "SiteItem", parent_srv: Optional["Server"] = None):
         xml_request = ET.Element("tsRequest")
         site_element = ET.SubElement(xml_request, "site")
@@ -848,7 +849,7 @@ class SiteRequest(object):
                 warnings.warn("In version 3.10 and earlier there is only one option: FlowsEnabled")
 
 
-class TableRequest(object):
+class TableRequest:
     def update_req(self, table_item):
         xml_request = ET.Element("tsRequest")
         table_element = ET.SubElement(xml_request, "table")
@@ -871,7 +872,7 @@ class TableRequest(object):
 content_types = Iterable[Union["ColumnItem", "DatabaseItem", "DatasourceItem", "FlowItem", "TableItem", "WorkbookItem"]]
 
 
-class TagRequest(object):
+class TagRequest:
     def add_req(self, tag_set):
         xml_request = ET.Element("tsRequest")
         tags_element = ET.SubElement(xml_request, "tags")
@@ -881,7 +882,7 @@ class TagRequest(object):
         return ET.tostring(xml_request)
 
     @_tsrequest_wrapped
-    def batch_create(self, element: ET.Element, tags: Set[str], content: content_types) -> bytes:
+    def batch_create(self, element: ET.Element, tags: set[str], content: content_types) -> bytes:
         tag_batch = ET.SubElement(element, "tagBatch")
         tags_element = ET.SubElement(tag_batch, "tags")
         for tag in tags:
@@ -897,7 +898,7 @@ class TagRequest(object):
         return ET.tostring(element)
 
 
-class UserRequest(object):
+class UserRequest:
     def update_req(self, user_item: UserItem, password: Optional[str]) -> bytes:
         xml_request = ET.Element("tsRequest")
         user_element = ET.SubElement(xml_request, "user")
@@ -931,7 +932,7 @@ class UserRequest(object):
         return ET.tostring(xml_request)
 
 
-class WorkbookRequest(object):
+class WorkbookRequest:
     def _generate_xml(
         self,
         workbook_item,
@@ -957,9 +958,15 @@ class WorkbookRequest(object):
             views_element = ET.SubElement(workbook_element, "views")
             for view_name in workbook_item.hidden_views:
                 _add_hiddenview_element(views_element, view_name)
+
+        if workbook_item.thumbnails_user_id is not None:
+            workbook_element.attrib["thumbnailsUserId"] = workbook_item.thumbnails_user_id
+        elif workbook_item.thumbnails_group_id is not None:
+            workbook_element.attrib["thumbnailsGroupId"] = workbook_item.thumbnails_group_id
+
         return ET.tostring(xml_request)
 
-    def update_req(self, workbook_item):
+    def update_req(self, workbook_item, parent_srv: Optional["Server"] = None):
         xml_request = ET.Element("tsRequest")
         workbook_element = ET.SubElement(xml_request, "workbook")
         if workbook_item.name:
@@ -972,6 +979,12 @@ class WorkbookRequest(object):
         if workbook_item.owner_id:
             owner_element = ET.SubElement(workbook_element, "owner")
             owner_element.attrib["id"] = workbook_item.owner_id
+        if (
+            workbook_item.description is not None
+            and parent_srv is not None
+            and parent_srv.check_at_least_version("3.21")
+        ):
+            workbook_element.attrib["description"] = workbook_item.description
         if workbook_item._views is not None:
             views_element = ET.SubElement(workbook_element, "views")
             for view in workbook_item.views:
@@ -995,9 +1008,9 @@ class WorkbookRequest(object):
             if data_freshness_policy_config.option == "FreshEvery":
                 if data_freshness_policy_config.fresh_every_schedule is not None:
                     fresh_every_element = ET.SubElement(data_freshness_policy_element, "freshEverySchedule")
-                    fresh_every_element.attrib[
-                        "frequency"
-                    ] = data_freshness_policy_config.fresh_every_schedule.frequency
+                    fresh_every_element.attrib["frequency"] = (
+                        data_freshness_policy_config.fresh_every_schedule.frequency
+                    )
                     fresh_every_element.attrib["value"] = str(data_freshness_policy_config.fresh_every_schedule.value)
                 else:
                     raise ValueError(f"data_freshness_policy_config.fresh_every_schedule must be populated.")
@@ -1075,7 +1088,7 @@ class WorkbookRequest(object):
                     datasource_element.attrib["id"] = id_
 
 
-class Connection(object):
+class Connection:
     @_tsrequest_wrapped
     def update_req(self, xml_request: ET.Element, connection_item: "ConnectionItem") -> None:
         connection_element = ET.SubElement(xml_request, "connection")
@@ -1098,12 +1111,19 @@ class Connection(object):
             connection_element.attrib["queryTaggingEnabled"] = str(connection_item.query_tagging).lower()
 
 
-class TaskRequest(object):
+class TaskRequest:
     @_tsrequest_wrapped
     def run_req(self, xml_request: ET.Element, task_item: Any) -> None:
         # Send an empty tsRequest
         pass
 
+    @_tsrequest_wrapped
+    def refresh_req(self, xml_request: ET.Element, incremental: bool = False) -> bytes:
+        task_element = ET.SubElement(xml_request, "extractRefresh")
+        if incremental:
+            task_element.attrib["incremental"] = "true"
+        return ET.tostring(xml_request)
+
     @_tsrequest_wrapped
     def create_extract_req(self, xml_request: ET.Element, extract_item: "TaskItem") -> bytes:
         extract_element = ET.SubElement(xml_request, "extractRefresh")
@@ -1137,7 +1157,7 @@ class TaskRequest(object):
         return ET.tostring(xml_request)
 
 
-class FlowTaskRequest(object):
+class FlowTaskRequest:
     @_tsrequest_wrapped
     def create_flow_task_req(self, xml_request: ET.Element, flow_item: "TaskItem") -> bytes:
         flow_element = ET.SubElement(xml_request, "runFlow")
@@ -1171,7 +1191,7 @@ class FlowTaskRequest(object):
         return ET.tostring(xml_request)
 
 
-class SubscriptionRequest(object):
+class SubscriptionRequest:
     @_tsrequest_wrapped
     def create_req(self, xml_request: ET.Element, subscription_item: "SubscriptionItem") -> bytes:
         subscription_element = ET.SubElement(xml_request, "subscription")
@@ -1235,13 +1255,13 @@ class SubscriptionRequest(object):
         return ET.tostring(xml_request)
 
 
-class EmptyRequest(object):
+class EmptyRequest:
     @_tsrequest_wrapped
     def empty_req(self, xml_request: ET.Element) -> None:
         pass
 
 
-class WebhookRequest(object):
+class WebhookRequest:
     @_tsrequest_wrapped
     def create_req(self, xml_request: ET.Element, webhook_item: "WebhookItem") -> bytes:
         webhook = ET.SubElement(xml_request, "webhook")
@@ -1287,7 +1307,7 @@ class MetricRequest:
         return ET.tostring(xml_request)
 
 
-class CustomViewRequest(object):
+class CustomViewRequest:
     @_tsrequest_wrapped
     def update_req(self, xml_request: ET.Element, custom_view_item: CustomViewItem):
         updating_element = ET.SubElement(xml_request, "customView")
@@ -1415,7 +1435,7 @@ class VirtualConnectionRequest:
         return ET.tostring(xml_request)
 
 
-class RequestFactory(object):
+class RequestFactory:
     Auth = AuthRequest()
     Connection = Connection()
     Column = ColumnRequest()