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

tableauserverclient/server/endpoint/custom_views_endpoint.py

@@ -1,8 +1,13 @@
+import io
 import logging
-from typing import List, Optional, Tuple
-
-from .endpoint import QuerysetEndpoint, api
-from .exceptions import MissingRequiredFieldError
+import os
+from pathlib import Path
+from typing import List, Optional, Tuple, Union
+
+from tableauserverclient.config import BYTES_PER_MB, FILESIZE_LIMIT_MB
+from tableauserverclient.filesys_helpers import get_file_object_size
+from tableauserverclient.server.endpoint.endpoint import QuerysetEndpoint, api
+from tableauserverclient.server.endpoint.exceptions import MissingRequiredFieldError
 from tableauserverclient.models import CustomViewItem, PaginationItem
 from tableauserverclient.server import RequestFactory, RequestOptions, ImageRequestOptions
 
@@ -16,6 +21,15 @@ Delete a custom view
 update the name or owner of a custom view.
 """
 
+FilePath = Union[str, os.PathLike]
+FileObject = Union[io.BufferedReader, io.BytesIO]
+FileObjectR = Union[io.BufferedReader, io.BytesIO]
+FileObjectW = Union[io.BufferedWriter, io.BytesIO]
+PathOrFileR = Union[FilePath, FileObjectR]
+PathOrFileW = Union[FilePath, FileObjectW]
+io_types_r = (io.BufferedReader, io.BytesIO)
+io_types_w = (io.BufferedWriter, io.BytesIO)
+
 
 class CustomViews(QuerysetEndpoint[CustomViewItem]):
     def __init__(self, parent_srv):
@@ -25,6 +39,10 @@ class CustomViews(QuerysetEndpoint[CustomViewItem]):
     def baseurl(self) -> str:
         return "{0}/sites/{1}/customviews".format(self.parent_srv.baseurl, self.parent_srv.site_id)
 
+    @property
+    def expurl(self) -> str:
+        return f"{self.parent_srv._server_address}/api/exp/sites/{self.parent_srv.site_id}/customviews"
+
     """
     If the request has no filter parameters: Administrators will see all custom views. 
         Other users will see only custom views that they own.
@@ -102,3 +120,46 @@ class CustomViews(QuerysetEndpoint[CustomViewItem]):
         url = "{0}/{1}".format(self.baseurl, view_id)
         self.delete_request(url)
         logger.info("Deleted single custom view (ID: {0})".format(view_id))
+
+    @api(version="3.21")
+    def download(self, view_item: CustomViewItem, file: PathOrFileW) -> PathOrFileW:
+        url = f"{self.expurl}/{view_item.id}/content"
+        server_response = self.get_request(url)
+        if isinstance(file, io_types_w):
+            file.write(server_response.content)
+            return file
+
+        with open(file, "wb") as f:
+            f.write(server_response.content)
+
+        return file
+
+    @api(version="3.21")
+    def publish(self, view_item: CustomViewItem, file: PathOrFileR) -> Optional[CustomViewItem]:
+        url = self.expurl
+        if isinstance(file, io_types_r):
+            size = get_file_object_size(file)
+        elif isinstance(file, (str, Path)) and (p := Path(file)).is_file():
+            size = p.stat().st_size
+        else:
+            raise ValueError("File path or file object required for publishing custom view.")
+
+        if size >= FILESIZE_LIMIT_MB * BYTES_PER_MB:
+            upload_session_id = self.parent_srv.fileuploads.upload(file)
+            url = f"{url}?uploadSessionId={upload_session_id}"
+            xml_request, content_type = RequestFactory.CustomView.publish_req_chunked(view_item)
+        else:
+            if isinstance(file, io_types_r):
+                file.seek(0)
+                contents = file.read()
+                if view_item.name is None:
+                    raise MissingRequiredFieldError("Custom view item missing name.")
+                filename = view_item.name
+            elif isinstance(file, (str, Path)):
+                filename = Path(file).name
+                contents = Path(file).read_bytes()
+
+            xml_request, content_type = RequestFactory.CustomView.publish_req(view_item, filename, contents)
+
+        server_response = self.post_request(url, xml_request, content_type)
+        return CustomViewItem.from_response(server_response.content, self.parent_srv.namespace)

tableauserverclient/server/endpoint/databases_endpoint.py

@@ -1,17 +1,19 @@
 import logging
-
-from .default_permissions_endpoint import _DefaultPermissionsEndpoint
-from .dqw_endpoint import _DataQualityWarningEndpoint
-from .endpoint import api, Endpoint
-from .exceptions import MissingRequiredFieldError
-from .permissions_endpoint import _PermissionsEndpoint
+from typing import Union, Iterable, Set
+
+from tableauserverclient.server.endpoint.default_permissions_endpoint import _DefaultPermissionsEndpoint
+from tableauserverclient.server.endpoint.dqw_endpoint import _DataQualityWarningEndpoint
+from tableauserverclient.server.endpoint.endpoint import api, Endpoint
+from tableauserverclient.server.endpoint.exceptions import MissingRequiredFieldError
+from tableauserverclient.server.endpoint.permissions_endpoint import _PermissionsEndpoint
+from tableauserverclient.server.endpoint.resource_tagger import TaggingMixin
 from tableauserverclient.server import RequestFactory
 from tableauserverclient.models import DatabaseItem, TableItem, PaginationItem, Resource
 
 from tableauserverclient.helpers.logging import logger
 
 
-class Databases(Endpoint):
+class Databases(Endpoint, TaggingMixin):
     def __init__(self, parent_srv):
         super(Databases, self).__init__(parent_srv)
 
@@ -123,3 +125,15 @@ class Databases(Endpoint):
     @api(version="3.5")
     def delete_dqw(self, item):
         self._data_quality_warnings.clear(item)
+
+    @api(version="3.9")
+    def add_tags(self, item: Union[DatabaseItem, str], tags: Iterable[str]) -> Set[str]:
+        return super().add_tags(item, tags)
+
+    @api(version="3.9")
+    def delete_tags(self, item: Union[DatabaseItem, str], tags: Iterable[str]) -> None:
+        super().delete_tags(item, tags)
+
+    @api(version="3.9")
+    def update_tags(self, item: DatabaseItem) -> None:
+        raise NotImplementedError("Update tags is not supported for databases.")

tableauserverclient/server/endpoint/datasources_endpoint.py

@@ -6,9 +6,10 @@ import os
 
 from contextlib import closing
 from pathlib import Path
-from typing import List, Mapping, Optional, Sequence, Tuple, TYPE_CHECKING, Union
+from typing import Iterable, List, Mapping, Optional, Sequence, Set, Tuple, TYPE_CHECKING, Union
 
 from tableauserverclient.helpers.headers import fix_filename
+from tableauserverclient.server.query import QuerySet
 
 if TYPE_CHECKING:
     from tableauserverclient.server import Server
@@ -19,9 +20,9 @@ from tableauserverclient.server.endpoint.dqw_endpoint import _DataQualityWarning
 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 _ResourceTagger
+from tableauserverclient.server.endpoint.resource_tagger import TaggingMixin
 
-from tableauserverclient.config import ALLOWED_FILE_EXTENSIONS, FILESIZE_LIMIT_MB, BYTES_PER_MB, CHUNK_SIZE_MB
+from tableauserverclient.config import ALLOWED_FILE_EXTENSIONS, FILESIZE_LIMIT_MB, BYTES_PER_MB, config
 from tableauserverclient.filesys_helpers import (
     make_download_path,
     get_file_type,
@@ -54,10 +55,9 @@ PathOrFileR = Union[FilePath, FileObjectR]
 PathOrFileW = Union[FilePath, FileObjectW]
 
 
-class Datasources(QuerysetEndpoint[DatasourceItem]):
+class Datasources(QuerysetEndpoint[DatasourceItem], TaggingMixin[DatasourceItem]):
     def __init__(self, parent_srv: "Server") -> None:
         super(Datasources, self).__init__(parent_srv)
-        self._resource_tagger = _ResourceTagger(parent_srv)
         self._permissions = _PermissionsEndpoint(parent_srv, lambda: self.baseurl)
         self._data_quality_warnings = _DataQualityWarningEndpoint(self.parent_srv, "datasource")
 
@@ -126,7 +126,7 @@ class Datasources(QuerysetEndpoint[DatasourceItem]):
         datasource_id: str,
         filepath: Optional[PathOrFileW] = None,
         include_extract: bool = True,
-    ) -> str:
+    ) -> PathOrFileW:
         return self.download_revision(
             datasource_id,
             None,
@@ -149,7 +149,7 @@ class Datasources(QuerysetEndpoint[DatasourceItem]):
                 )
                 raise MissingRequiredFieldError(error)
 
-        self._resource_tagger.update_tags(self.baseurl, datasource_item)
+        self.update_tags(datasource_item)
 
         # Update the datasource itself
         url = "{0}/{1}".format(self.baseurl, datasource_item.id)
@@ -272,7 +272,7 @@ class Datasources(QuerysetEndpoint[DatasourceItem]):
         if file_size >= FILESIZE_LIMIT_MB * BYTES_PER_MB:
             logger.info(
                 "Publishing {} to server with chunking method (datasource over {}MB, chunk size {}MB)".format(
-                    filename, FILESIZE_LIMIT_MB, CHUNK_SIZE_MB
+                    filename, FILESIZE_LIMIT_MB, config.CHUNK_SIZE_MB
                 )
             )
             upload_session_id = self.parent_srv.fileuploads.upload(file)
@@ -405,7 +405,7 @@ class Datasources(QuerysetEndpoint[DatasourceItem]):
     def download_revision(
         self,
         datasource_id: str,
-        revision_number: str,
+        revision_number: Optional[str],
         filepath: Optional[PathOrFileW] = None,
         include_extract: bool = True,
     ) -> PathOrFileW:
@@ -459,3 +459,99 @@ class Datasources(QuerysetEndpoint[DatasourceItem]):
         self, schedule_id: str, item: DatasourceItem
     ) -> List["AddResponse"]:  # actually should return a task
         return self.parent_srv.schedules.add_to_schedule(schedule_id, datasource=item)
+
+    @api(version="1.0")
+    def add_tags(self, item: Union[DatasourceItem, str], tags: Union[Iterable[str], str]) -> Set[str]:
+        return super().add_tags(item, tags)
+
+    @api(version="1.0")
+    def delete_tags(self, item: Union[DatasourceItem, str], tags: Union[Iterable[str], str]) -> None:
+        return super().delete_tags(item, tags)
+
+    @api(version="1.0")
+    def update_tags(self, item: DatasourceItem) -> None:
+        return super().update_tags(item)
+
+    def filter(self, *invalid, page_size: Optional[int] = None, **kwargs) -> QuerySet[DatasourceItem]:
+        """
+        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:
+
+
+        authentication_type=...
+        authentication_type__in=...
+        connected_workbook_type=...
+        connected_workbook_type__gt=...
+        connected_workbook_type__gte=...
+        connected_workbook_type__lt=...
+        connected_workbook_type__lte=...
+        connection_to=...
+        connection_to__in=...
+        connection_type=...
+        connection_type__in=...
+        content_url=...
+        content_url__in=...
+        created_at=...
+        created_at__gt=...
+        created_at__gte=...
+        created_at__lt=...
+        created_at__lte=...
+        database_name=...
+        database_name__in=...
+        database_user_name=...
+        database_user_name__in=...
+        description=...
+        description__in=...
+        favorites_total=...
+        favorites_total__gt=...
+        favorites_total__gte=...
+        favorites_total__lt=...
+        favorites_total__lte=...
+        has_alert=...
+        has_embedded_password=...
+        has_extracts=...
+        is_certified=...
+        is_connectable=...
+        is_default_port=...
+        is_hierarchical=...
+        is_published=...
+        name=...
+        name__in=...
+        owner_domain=...
+        owner_domain__in=...
+        owner_email=...
+        owner_name=...
+        owner_name__in=...
+        project_name=...
+        project_name__in=...
+        server_name=...
+        server_name__in=...
+        server_port=...
+        size=...
+        size__gt=...
+        size__gte=...
+        size__lt=...
+        size__lte=...
+        table_name=...
+        table_name__in=...
+        tags=...
+        tags__in=...
+        type=...
+        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/endpoint/endpoint.py

@@ -1,30 +1,41 @@
+from typing_extensions import Concatenate, ParamSpec
 from tableauserverclient import datetime_helpers as datetime
 
 import abc
 from packaging.version import Version
 from functools import wraps
 from xml.etree.ElementTree import ParseError
-from typing import Any, Callable, Dict, Generic, List, Optional, TYPE_CHECKING, Tuple, TypeVar, Union
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Generic,
+    List,
+    Optional,
+    TYPE_CHECKING,
+    Tuple,
+    TypeVar,
+    Union,
+)
 
 from tableauserverclient.models.pagination_item import PaginationItem
 from tableauserverclient.server.request_options import RequestOptions
 
-from .exceptions import (
+from tableauserverclient.server.endpoint.exceptions import (
     ServerResponseError,
     InternalServerError,
     NonXMLResponseError,
     NotSignedInError,
 )
-from ..exceptions import EndpointUnavailableError
+from tableauserverclient.server.exceptions import EndpointUnavailableError
 
 from tableauserverclient.server.query import QuerySet
 from tableauserverclient import helpers, get_versions
 
 from tableauserverclient.helpers.logging import logger
-from tableauserverclient.config import DELAY_SLEEP_SECONDS
 
 if TYPE_CHECKING:
-    from ..server import Server
+    from tableauserverclient.server.server import Server
     from requests import Response
 
 
@@ -38,7 +49,7 @@ TABLEAU_AUTH_HEADER = "x-tableau-auth"
 USER_AGENT_HEADER = "User-Agent"
 
 
-class Endpoint(object):
+class Endpoint:
     def __init__(self, parent_srv: "Server"):
         self.parent_srv = parent_srv
 
@@ -133,7 +144,9 @@ class Endpoint(object):
 
         loggable_response = self.log_response_safely(server_response)
         logger.debug("Server response from {0}".format(url))
-        # logger.debug("\n\t{1}".format(loggable_response))
+        # uncomment the following to log full responses in debug mode
+        # BE CAREFUL WHEN SHARING THESE RESULTS - MAY CONTAIN YOUR SENSITIVE DATA
+        # logger.debug(loggable_response)
 
         if content_type == "application/xml":
             self.parent_srv._namespace.detect(server_response.content)
@@ -232,7 +245,12 @@ class Endpoint(object):
         )
 
 
-def api(version):
+E = TypeVar("E", bound="Endpoint")
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def api(version: str) -> Callable[[Callable[Concatenate[E, P], R]], Callable[Concatenate[E, P], R]]:
     """Annotate the minimum supported version for an endpoint.
 
     Checks the version on the server object and compares normalized versions.
@@ -251,9 +269,9 @@ def api(version):
     >>>     ...
     """
 
-    def _decorator(func):
+    def _decorator(func: Callable[Concatenate[E, P], R]) -> Callable[Concatenate[E, P], R]:
         @wraps(func)
-        def wrapper(self, *args, **kwargs):
+        def wrapper(self: E, *args: P.args, **kwargs: P.kwargs) -> R:
             self.parent_srv.assert_at_least_version(version, self.__class__.__name__)
             return func(self, *args, **kwargs)
 
@@ -262,7 +280,7 @@ def api(version):
     return _decorator
 
 
-def parameter_added_in(**params):
+def parameter_added_in(**params: str) -> Callable[[Callable[Concatenate[E, P], R]], Callable[Concatenate[E, P], R]]:
     """Annotate minimum versions for new parameters or request options on an endpoint.
 
     The api decorator documents when an endpoint was added, this decorator annotates
@@ -285,9 +303,9 @@ def parameter_added_in(**params):
     >>>     ...
     """
 
-    def _decorator(func):
+    def _decorator(func: Callable[Concatenate[E, P], R]) -> Callable[Concatenate[E, P], R]:
         @wraps(func)
-        def wrapper(self, *args, **kwargs):
+        def wrapper(self: E, *args: P.args, **kwargs: P.kwargs) -> R:
             import warnings
 
             server_ver = Version(self.parent_srv.version or "0.0")
@@ -335,5 +353,5 @@ class QuerysetEndpoint(Endpoint, Generic[T]):
         return queryset
 
     @abc.abstractmethod
-    def get(self, request_options: RequestOptions) -> Tuple[List[T], PaginationItem]:
+    def get(self, request_options: Optional[RequestOptions] = None) -> Tuple[List[T], PaginationItem]:
         raise NotImplementedError(f".get has not been implemented for {self.__class__.__qualname__}")

tableauserverclient/server/endpoint/fileuploads_endpoint.py

@@ -2,7 +2,7 @@ from .endpoint import Endpoint, api
 from tableauserverclient import datetime_helpers as datetime
 from tableauserverclient.helpers.logging import logger
 
-from tableauserverclient.config import BYTES_PER_MB, CHUNK_SIZE_MB
+from tableauserverclient.config import BYTES_PER_MB, config
 from tableauserverclient.models import FileuploadItem
 from tableauserverclient.server import RequestFactory
 
@@ -41,7 +41,7 @@ class Fileuploads(Endpoint):
 
         try:
             while True:
-                chunked_content = file_content.read(CHUNK_SIZE_MB * BYTES_PER_MB)
+                chunked_content = file_content.read(config.CHUNK_SIZE_MB * BYTES_PER_MB)
                 if not chunked_content:
                     break
                 yield chunked_content

tableauserverclient/server/endpoint/flow_runs_endpoint.py

@@ -1,16 +1,17 @@
 import logging
 from typing import List, Optional, Tuple, TYPE_CHECKING
 
-from .endpoint import QuerysetEndpoint, api
-from .exceptions import FlowRunFailedException, FlowRunCancelledException
+from tableauserverclient.server.endpoint.endpoint import QuerysetEndpoint, api
+from tableauserverclient.server.endpoint.exceptions import FlowRunFailedException, FlowRunCancelledException
 from tableauserverclient.models import FlowRunItem, PaginationItem
 from tableauserverclient.exponential_backoff import ExponentialBackoffTimer
 
 from tableauserverclient.helpers.logging import logger
+from tableauserverclient.server.query import QuerySet
 
 if TYPE_CHECKING:
-    from ..server import Server
-    from ..request_options import RequestOptions
+    from tableauserverclient.server.server import Server
+    from tableauserverclient.server.request_options import RequestOptions
 
 
 class FlowRuns(QuerysetEndpoint[FlowRunItem]):
@@ -78,3 +79,42 @@ class FlowRuns(QuerysetEndpoint[FlowRunItem]):
             raise FlowRunCancelledException(flow_run)
         else:
             raise AssertionError("Unexpected status in flow_run", flow_run)
+
+    def filter(self, *invalid, page_size: Optional[int] = None, **kwargs) -> QuerySet[FlowRunItem]:
+        """
+        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:
+
+
+        complete_at=...
+        complete_at__gt=...
+        complete_at__gte=...
+        complete_at__lt=...
+        complete_at__lte=...
+        flow_id=...
+        flow_id__in=...
+        progress=...
+        progress__gt=...
+        progress__gte=...
+        progress__lt=...
+        progress__lte=...
+        started_at=...
+        started_at__gt=...
+        started_at__gte=...
+        started_at__lt=...
+        started_at__lte=...
+        user_id=...
+        user_id__in=...
+        """
+
+        return super().filter(*invalid, page_size=page_size, **kwargs)

tableauserverclient/server/endpoint/flows_endpoint.py

@@ -9,11 +9,11 @@ from typing import Iterable, List, Optional, TYPE_CHECKING, Tuple, Union
 
 from tableauserverclient.helpers.headers import fix_filename
 
-from .dqw_endpoint import _DataQualityWarningEndpoint
-from .endpoint import QuerysetEndpoint, api
-from .exceptions import InternalServerError, MissingRequiredFieldError
-from .permissions_endpoint import _PermissionsEndpoint
-from .resource_tagger import _ResourceTagger
+from tableauserverclient.server.endpoint.dqw_endpoint import _DataQualityWarningEndpoint
+from tableauserverclient.server.endpoint.endpoint import QuerysetEndpoint, api
+from tableauserverclient.server.endpoint.exceptions import InternalServerError, MissingRequiredFieldError
+from tableauserverclient.server.endpoint.permissions_endpoint import _PermissionsEndpoint
+from tableauserverclient.server.endpoint.resource_tagger import _ResourceTagger, TaggingMixin
 from tableauserverclient.models import FlowItem, PaginationItem, ConnectionItem, JobItem
 from tableauserverclient.server import RequestFactory
 from tableauserverclient.filesys_helpers import (
@@ -22,6 +22,7 @@ from tableauserverclient.filesys_helpers import (
     get_file_type,
     get_file_object_size,
 )
+from tableauserverclient.server.query import QuerySet
 
 io_types_r = (io.BytesIO, io.BufferedReader)
 io_types_w = (io.BytesIO, io.BufferedWriter)
@@ -50,7 +51,7 @@ PathOrFileR = Union[FilePath, FileObjectR]
 PathOrFileW = Union[FilePath, FileObjectW]
 
 
-class Flows(QuerysetEndpoint[FlowItem]):
+class Flows(QuerysetEndpoint[FlowItem], TaggingMixin[FlowItem]):
     def __init__(self, parent_srv):
         super(Flows, self).__init__(parent_srv)
         self._resource_tagger = _ResourceTagger(parent_srv)
@@ -295,3 +296,39 @@ class Flows(QuerysetEndpoint[FlowItem]):
         self, schedule_id: str, item: FlowItem
     ) -> List["AddResponse"]:  # actually should return a task
         return self.parent_srv.schedules.add_to_schedule(schedule_id, flow=item)
+
+    def filter(self, *invalid, page_size: Optional[int] = None, **kwargs) -> QuerySet[FlowItem]:
+        """
+        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=...
+        name=...
+        name__in=...
+        owner_name=...
+        project_id=...
+        project_name=...
+        project_name__in=...
+        updated=...
+        updated__gt=...
+        updated__gte=...
+        updated__lt=...
+        updated__lte=...
+        """
+
+        return super().filter(*invalid, page_size=page_size, **kwargs)