tableauserverclient 0.32__py3-none-any.whl → 0.34__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,25 +1,23 @@
 import copy
 from functools import partial
-from typing import Generic, 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
 
 
 T = TypeVar("T")
-ReturnType = Tuple[List[T], PaginationItem]
 
 
 @runtime_checkable
-class Endpoint(Protocol):
-    def get(self, req_options: Optional[RequestOptions], **kwargs) -> ReturnType:
-        ...
+class Endpoint(Protocol[T]):
+    def get(self, req_options: Optional[RequestOptions]) -> tuple[list[T], PaginationItem]: ...
 
 
 @runtime_checkable
-class CallableEndpoint(Protocol):
-    def __call__(self, __req_options: Optional[RequestOptions], **kwargs) -> ReturnType:
-        ...
+class CallableEndpoint(Protocol[T]):
+    def __call__(self, __req_options: Optional[RequestOptions], **kwargs) -> tuple[list[T], PaginationItem]: ...
 
 
 class Pager(Iterable[T]):
@@ -28,12 +26,12 @@ 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).
     """
 
     def __init__(
         self,
-        endpoint: Union[CallableEndpoint, Endpoint],
+        endpoint: Union[CallableEndpoint[T], Endpoint[T]],
         request_opts: Optional[RequestOptions] = None,
         **kwargs,
     ) -> None:

tableauserverclient/server/query.py

@@ -1,7 +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
@@ -33,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 100)
-        self._result_cache: List[T] = []
+        self.request_options = RequestOptions(pagesize=page_size or config.PAGE_SIZE)
+        self._result_cache: list[T] = []
         self._pagination_item = PaginationItem()
 
     def __iter__(self: Self) -> Iterator[T]:
@@ -48,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
@@ -102,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]
@@ -113,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:
@@ -127,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:
@@ -159,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