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

tableauserverclient/server/endpoint/workbooks_endpoint.py

@@ -7,11 +7,12 @@ from contextlib import closing
 from pathlib import Path
 
 from tableauserverclient.helpers.headers import fix_filename
+from tableauserverclient.server.query import QuerySet
 
-from .endpoint import QuerysetEndpoint, api, parameter_added_in
-from .exceptions import InternalServerError, MissingRequiredFieldError
-from .permissions_endpoint import _PermissionsEndpoint
-from .resource_tagger import _ResourceTagger
+from tableauserverclient.server.endpoint.endpoint import QuerysetEndpoint, api, parameter_added_in
+from tableauserverclient.server.endpoint.exceptions import InternalServerError, MissingRequiredFieldError
+from tableauserverclient.server.endpoint.permissions_endpoint import _PermissionsEndpoint
+from tableauserverclient.server.endpoint.resource_tagger import TaggingMixin
 
 from tableauserverclient.filesys_helpers import (
     to_filename,
@@ -24,9 +25,11 @@ from tableauserverclient.models import WorkbookItem, ConnectionItem, ViewItem, P
 from tableauserverclient.server import RequestFactory
 
 from typing import (
+    Iterable,
     List,
     Optional,
     Sequence,
+    Set,
     Tuple,
     TYPE_CHECKING,
     Union,
@@ -35,8 +38,8 @@ from typing import (
 if TYPE_CHECKING:
     from tableauserverclient.server import Server
     from tableauserverclient.server.request_options import RequestOptions
-    from tableauserverclient.models import DatasourceItem, ConnectionCredentials
-    from .schedules_endpoint import AddResponse
+    from tableauserverclient.models import DatasourceItem
+    from tableauserverclient.server.endpoint.schedules_endpoint import AddResponse
 
 io_types_r = (io.BytesIO, io.BufferedReader)
 io_types_w = (io.BytesIO, io.BufferedWriter)
@@ -56,10 +59,9 @@ PathOrFileR = Union[FilePath, FileObjectR]
 PathOrFileW = Union[FilePath, FileObjectW]
 
 
-class Workbooks(QuerysetEndpoint):
+class Workbooks(QuerysetEndpoint[WorkbookItem], TaggingMixin[WorkbookItem]):
     def __init__(self, parent_srv: "Server") -> None:
         super(Workbooks, self).__init__(parent_srv)
-        self._resource_tagger = _ResourceTagger(parent_srv)
         self._permissions = _PermissionsEndpoint(parent_srv, lambda: self.baseurl)
 
         return None
@@ -147,7 +149,7 @@ class Workbooks(QuerysetEndpoint):
             error = "Workbook item missing ID. Workbook must be retrieved from server first."
             raise MissingRequiredFieldError(error)
 
-        self._resource_tagger.update_tags(self.baseurl, workbook_item)
+        self.update_tags(workbook_item)
 
         # Update the workbook itself
         url = "{0}/{1}".format(self.baseurl, workbook_item.id)
@@ -160,13 +162,6 @@ class Workbooks(QuerysetEndpoint):
         updated_workbook = copy.copy(workbook_item)
         return updated_workbook._parse_common_tags(server_response.content, self.parent_srv.namespace)
 
-    @api(version="2.3")
-    def update_conn(self, *args, **kwargs):
-        import warnings
-
-        warnings.warn("update_conn is deprecated, please use update_connection instead")
-        return self.update_connection(*args, **kwargs)
-
     # Update workbook_connection
     @api(version="2.3")
     def update_connection(self, workbook_item: WorkbookItem, connection_item: ConnectionItem) -> ConnectionItem:
@@ -189,9 +184,13 @@ class Workbooks(QuerysetEndpoint):
         workbook_id: str,
         filepath: Optional[PathOrFileW] = None,
         include_extract: bool = True,
-        no_extract: Optional[bool] = None,
-    ) -> str:
-        return self.download_revision(workbook_id, None, filepath, include_extract, no_extract)
+    ) -> PathOrFileW:
+        return self.download_revision(
+            workbook_id,
+            None,
+            filepath,
+            include_extract,
+        )
 
     # Get all views of workbook
     @api(version="2.0")
@@ -315,21 +314,11 @@ class Workbooks(QuerysetEndpoint):
         workbook_item: WorkbookItem,
         file: PathOrFileR,
         mode: str,
-        connection_credentials: Optional["ConnectionCredentials"] = None,
         connections: Optional[Sequence[ConnectionItem]] = None,
         as_job: bool = False,
-        hidden_views: Optional[Sequence[str]] = None,
         skip_connection_check: bool = False,
         parameters=None,
     ):
-        if connection_credentials is not None:
-            import warnings
-
-            warnings.warn(
-                "connection_credentials is being deprecated. Use connections instead",
-                DeprecationWarning,
-            )
-
         if isinstance(file, (str, os.PathLike)):
             if not os.path.isfile(file):
                 error = "File path does not lead to an existing file."
@@ -391,12 +380,9 @@ class Workbooks(QuerysetEndpoint):
             logger.info("Publishing {0} to server with chunking method (workbook over 64MB)".format(workbook_item.name))
             upload_session_id = self.parent_srv.fileuploads.upload(file)
             url = "{0}&uploadSessionId={1}".format(url, upload_session_id)
-            conn_creds = connection_credentials
             xml_request, content_type = RequestFactory.Workbook.publish_req_chunked(
                 workbook_item,
-                connection_credentials=conn_creds,
                 connections=connections,
-                hidden_views=hidden_views,
             )
         else:
             logger.info("Publishing {0} to server".format(filename))
@@ -411,14 +397,11 @@ class Workbooks(QuerysetEndpoint):
             else:
                 raise TypeError("file should be a filepath or file object.")
 
-            conn_creds = connection_credentials
             xml_request, content_type = RequestFactory.Workbook.publish_req(
                 workbook_item,
                 filename,
                 file_contents,
-                connection_credentials=conn_creds,
                 connections=connections,
-                hidden_views=hidden_views,
             )
         logger.debug("Request xml: {0} ".format(redact_xml(xml_request[:1000])))
 
@@ -468,7 +451,6 @@ class Workbooks(QuerysetEndpoint):
         revision_number: Optional[str],
         filepath: Optional[PathOrFileW] = None,
         include_extract: bool = True,
-        no_extract: Optional[bool] = None,
     ) -> PathOrFileW:
         if not workbook_id:
             error = "Workbook ID undefined."
@@ -478,15 +460,6 @@ class Workbooks(QuerysetEndpoint):
         else:
             url = "{0}/{1}/revisions/{2}/content".format(self.baseurl, workbook_id, revision_number)
 
-        if no_extract is False or no_extract is True:
-            import warnings
-
-            warnings.warn(
-                "no_extract is deprecated, use include_extract instead.",
-                DeprecationWarning,
-            )
-            include_extract = not no_extract
-
         if not include_extract:
             url += "?includeExtract=False"
 
@@ -527,3 +500,82 @@ class Workbooks(QuerysetEndpoint):
         self, schedule_id: str, item: WorkbookItem
     ) -> List["AddResponse"]:  # actually should return a task
         return self.parent_srv.schedules.add_to_schedule(schedule_id, workbook=item)
+
+    @api(version="1.0")
+    def add_tags(self, item: Union[WorkbookItem, str], tags: Union[Iterable[str], str]) -> Set[str]:
+        return super().add_tags(item, tags)
+
+    @api(version="1.0")
+    def delete_tags(self, item: Union[WorkbookItem, str], tags: Union[Iterable[str], str]) -> None:
+        return super().delete_tags(item, tags)
+
+    @api(version="1.0")
+    def update_tags(self, item: WorkbookItem) -> None:
+        return super().update_tags(item)
+
+    def filter(self, *invalid, page_size: Optional[int] = None, **kwargs) -> QuerySet[WorkbookItem]:
+        """
+        Queries the Tableau Server for items using the specified filters. Page
+        size can be specified to limit the number of items returned in a single
+        request. If not specified, the default page size is 100. Page size can
+        be an integer between 1 and 1000.
+
+        No positional arguments are allowed. All filters must be specified as
+        keyword arguments. If you use the equality operator, you can specify it
+        through <field_name>=<value>. If you want to use a different operator,
+        you can specify it through <field_name>__<operator>=<value>. Field
+        names can either be in snake_case or camelCase.
+
+        This endpoint supports the following fields and operators:
+
+
+        created_at=...
+        created_at__gt=...
+        created_at__gte=...
+        created_at__lt=...
+        created_at__lte=...
+        content_url=...
+        content_url__in=...
+        display_tabs=...
+        favorites_total=...
+        favorites_total__gt=...
+        favorites_total__gte=...
+        favorites_total__lt=...
+        favorites_total__lte=...
+        has_alerts=...
+        has_extracts=...
+        name=...
+        name__in=...
+        owner_domain=...
+        owner_domain__in=...
+        owner_email=...
+        owner_email__in=...
+        owner_name=...
+        owner_name__in=...
+        project_name=...
+        project_name__in=...
+        sheet_count=...
+        sheet_count__gt=...
+        sheet_count__gte=...
+        sheet_count__lt=...
+        sheet_count__lte=...
+        size=...
+        size__gt=...
+        size__gte=...
+        size__lt=...
+        size__lte=...
+        subscriptions_total=...
+        subscriptions_total__gt=...
+        subscriptions_total__gte=...
+        subscriptions_total__lt=...
+        subscriptions_total__lte=...
+        tags=...
+        tags__in=...
+        updated_at=...
+        updated_at__gt=...
+        updated_at__gte=...
+        updated_at__lt=...
+        updated_at__lte=...
+        """
+
+        return super().filter(*invalid, page_size=page_size, **kwargs)

tableauserverclient/server/pager.py

@@ -1,9 +1,27 @@
+import copy
 from functools import partial
+from typing import Iterable, Iterator, List, Optional, Protocol, Tuple, TypeVar, Union, runtime_checkable
 
-from . import RequestOptions
+from tableauserverclient.models.pagination_item import PaginationItem
+from tableauserverclient.server.request_options import RequestOptions
 
 
-class Pager(object):
+T = TypeVar("T")
+
+
+@runtime_checkable
+class Endpoint(Protocol[T]):
+    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]:
+        ...
+
+
+class Pager(Iterable[T]):
     """
     Generator that takes an endpoint (top level endpoints with `.get)` and lazily loads items from Server.
     Supports all `RequestOptions` including starting on any page. Also used by models to load sub-models
@@ -12,12 +30,17 @@ class Pager(object):
     Will loop over anything that returns (List[ModelItem], PaginationItem).
     """
 
-    def __init__(self, endpoint, request_opts=None, **kwargs):
-        if hasattr(endpoint, "get"):
+    def __init__(
+        self,
+        endpoint: Union[CallableEndpoint[T], Endpoint[T]],
+        request_opts: Optional[RequestOptions] = None,
+        **kwargs,
+    ) -> None:
+        if isinstance(endpoint, Endpoint):
             # The simpliest case is to take an Endpoint and call its get
             endpoint = partial(endpoint.get, **kwargs)
             self._endpoint = endpoint
-        elif callable(endpoint):
+        elif isinstance(endpoint, CallableEndpoint):
             # but if they pass a callable then use that instead (used internally)
             endpoint = partial(endpoint, **kwargs)
             self._endpoint = endpoint
@@ -25,47 +48,24 @@ class Pager(object):
             # Didn't get something we can page over
             raise ValueError("Pager needs a server endpoint to page through.")
 
-        self._options = request_opts
+        self._options = request_opts or RequestOptions()
 
-        # If we have options we could be starting on any page, backfill the count
-        if self._options:
-            self._count = (self._options.pagenumber - 1) * self._options.pagesize
-        else:
-            self._count = 0
-            self._options = RequestOptions()
-
-    def __iter__(self):
-        # Fetch the first page
-        current_item_list, last_pagination_item = self._endpoint(self._options)
-
-        if last_pagination_item.total_available is None:
-            # This endpoint does not support pagination, drain the list and return
-            while current_item_list:
-                yield current_item_list.pop(0)
-
-            return
-
-        # Get the rest on demand as a generator
-        while self._count < last_pagination_item.total_available:
-            if (
-                len(current_item_list) == 0
-                and (last_pagination_item.page_number * last_pagination_item.page_size)
-                < last_pagination_item.total_available
-            ):
-                current_item_list, last_pagination_item = self._load_next_page(last_pagination_item)
-
-            try:
-                yield current_item_list.pop(0)
-                self._count += 1
-
-            except IndexError:
-                # The total count on Server changed while fetching exit gracefully
+    def __iter__(self) -> Iterator[T]:
+        options = copy.deepcopy(self._options)
+        while True:
+            # Fetch the first page
+            current_item_list, pagination_item = self._endpoint(options)
+
+            if pagination_item.total_available is None:
+                # This endpoint does not support pagination, drain the list and return
+                yield from current_item_list
+                return
+            yield from current_item_list
+
+            if pagination_item.page_size * pagination_item.page_number >= pagination_item.total_available:
+                # Last page, exit
                 return
 
-    def _load_next_page(self, last_pagination_item):
-        next_page = last_pagination_item.page_number + 1
-        opts = RequestOptions(pagenumber=next_page, pagesize=last_pagination_item.page_size)
-        if self._options is not None:
-            opts.sort, opts.filter = self._options.sort, self._options.filter
-        current_item_list, last_pagination_item = self._endpoint(opts)
-        return current_item_list, last_pagination_item
+            # Update the options to fetch the next page
+            options.pagenumber = pagination_item.page_number + 1
+            options.pagesize = pagination_item.page_size

tableauserverclient/server/query.py

@@ -1,9 +1,26 @@
-from typing import Tuple
-from .filter import Filter
-from .request_options import RequestOptions
-from .sort import Sort
+from collections.abc import Sized
+from itertools import count
+from typing import Iterable, Iterator, List, Optional, Protocol, Tuple, TYPE_CHECKING, TypeVar, overload
+from tableauserverclient.config import config
+from tableauserverclient.models.pagination_item import PaginationItem
+from tableauserverclient.server.filter import Filter
+from tableauserverclient.server.request_options import RequestOptions
+from tableauserverclient.server.sort import Sort
 import math
 
+from typing_extensions import Self
+
+if TYPE_CHECKING:
+    from tableauserverclient.server.endpoint import QuerysetEndpoint
+
+T = TypeVar("T")
+
+
+class Slice(Protocol):
+    start: Optional[int]
+    step: Optional[int]
+    stop: Optional[int]
+
 
 def to_camel_case(word: str) -> str:
     return word.split("_")[0] + "".join(x.capitalize() or "_" for x in word.split("_")[1:])
@@ -16,28 +33,35 @@ see pagination_sample
 """
 
 
-class QuerySet:
-    def __init__(self, model):
+class QuerySet(Iterable[T], Sized):
+    def __init__(self, model: "QuerysetEndpoint[T]", page_size: Optional[int] = None) -> None:
         self.model = model
-        self.request_options = RequestOptions()
-        self._result_cache = None
-        self._pagination_item = None
+        self.request_options = RequestOptions(pagesize=page_size or config.PAGE_SIZE)
+        self._result_cache: List[T] = []
+        self._pagination_item = PaginationItem()
 
-    def __iter__(self):
+    def __iter__(self: Self) -> Iterator[T]:
         # Not built to be re-entrant. Starts back at page 1, and empties
-        # the result cache.
-        self.request_options.pagenumber = 1
-        self._result_cache = None
-        total = self.total_available
-        size = self.page_size
-        yield from self._result_cache
+        # the result cache. Ensure the result_cache is empty to not yield
+        # items from prior usage.
+        self._result_cache = []
 
-        # Loop through the subsequent pages.
-        for page in range(1, math.ceil(total / size)):
-            self.request_options.pagenumber = page + 1
-            self._result_cache = None
+        for page in count(1):
+            self.request_options.pagenumber = page
+            self._result_cache = []
             self._fetch_all()
             yield from self._result_cache
+            # Set result_cache to empty so the fetch will populate
+            if (page * self.page_size) >= len(self):
+                return
+
+    @overload
+    def __getitem__(self: Self, k: Slice) -> List[T]:
+        ...
+
+    @overload
+    def __getitem__(self: Self, k: int) -> T:
+        ...
 
     def __getitem__(self, k):
         page = self.page_number
@@ -78,7 +102,7 @@ class QuerySet:
             return self._result_cache[k % size]
         elif k in range(self.total_available):
             # Otherwise, check if k is even sensible to return
-            self._result_cache = None
+            self._result_cache = []
             # 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]
@@ -86,53 +110,57 @@ class QuerySet:
             # If k is unreasonable, raise an IndexError.
             raise IndexError
 
-    def _fetch_all(self):
+    def _fetch_all(self: Self) -> None:
         """
         Retrieve the data and store result and pagination item in cache
         """
-        if self._result_cache is None:
+        if not self._result_cache:
             self._result_cache, self._pagination_item = self.model.get(self.request_options)
 
-    def __len__(self) -> int:
+    def __len__(self: Self) -> int:
         return self.total_available
 
     @property
-    def total_available(self) -> int:
+    def total_available(self: Self) -> int:
         self._fetch_all()
         return self._pagination_item.total_available
 
     @property
-    def page_number(self) -> int:
+    def page_number(self: Self) -> int:
         self._fetch_all()
         return self._pagination_item.page_number
 
     @property
-    def page_size(self) -> int:
+    def page_size(self: Self) -> int:
         self._fetch_all()
         return self._pagination_item.page_size
 
-    def filter(self, *invalid, **kwargs):
+    def filter(self: Self, *invalid, page_size: Optional[int] = None, **kwargs) -> Self:
         if invalid:
-            raise RuntimeError(f"Only accepts keyword arguments.")
+            raise RuntimeError("Only accepts keyword arguments.")
         for kwarg_key, value in kwargs.items():
             field_name, operator = self._parse_shorthand_filter(kwarg_key)
             self.request_options.filter.add(Filter(field_name, operator, value))
+
+        if page_size:
+            self.request_options.pagesize = page_size
         return self
 
-    def order_by(self, *args):
+    def order_by(self: Self, *args) -> Self:
         for arg in args:
             field_name, direction = self._parse_shorthand_sort(arg)
             self.request_options.sort.add(Sort(field_name, direction))
         return self
 
-    def paginate(self, **kwargs):
+    def paginate(self: Self, **kwargs) -> Self:
         if "page_number" in kwargs:
             self.request_options.pagenumber = kwargs["page_number"]
         if "page_size" in kwargs:
             self.request_options.pagesize = kwargs["page_size"]
         return self
 
-    def _parse_shorthand_filter(self, key: str) -> Tuple[str, str]:
+    @staticmethod
+    def _parse_shorthand_filter(key: str) -> Tuple[str, str]:
         tokens = key.split("__", 1)
         if len(tokens) == 1:
             operator = RequestOptions.Operator.Equals
@@ -146,7 +174,8 @@ class QuerySet:
             raise ValueError("Field name `{}` is not valid.".format(field))
         return (field, operator)
 
-    def _parse_shorthand_sort(self, key: str) -> Tuple[str, str]:
+    @staticmethod
+    def _parse_shorthand_sort(key: str) -> Tuple[str, str]:
         direction = RequestOptions.Direction.Asc
         if key.startswith("-"):
             direction = RequestOptions.Direction.Desc