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

tableauserverclient/models/workbook_item.py

@@ -2,7 +2,7 @@ import copy
 import datetime
 import uuid
 import xml.etree.ElementTree as ET
-from typing import Callable, Dict, List, Optional, Set
+from typing import Callable, Optional
 
 from defusedxml.ElementTree import fromstring
 
@@ -20,8 +20,93 @@ from .view_item import ViewItem
 from .data_freshness_policy_item import DataFreshnessPolicyItem
 
 
-class WorkbookItem(object):
-    def __init__(self, project_id: Optional[str] = None, name: Optional[str] = None, show_tabs: bool = False) -> None:
+class WorkbookItem:
+    """
+    The workbook resources for Tableau are defined in the WorkbookItem class.
+    The class corresponds to the workbook resources you can access using the
+    Tableau REST API. Some workbook methods take an instance of the WorkbookItem
+    class as arguments. The workbook item specifies the project.
+
+    Parameters
+    ----------
+    project_id : Optional[str], optional
+        The project ID for the workbook, by default None.
+
+    name : Optional[str], optional
+        The name of the workbook, by default None.
+
+    show_tabs : bool, optional
+        Determines whether the workbook shows tabs for the view.
+
+    Attributes
+    ----------
+    connections : list[ConnectionItem]
+        The list of data connections (ConnectionItem) for the data sources used
+        by the workbook. You must first call the workbooks.populate_connections
+        method to access this data. See the ConnectionItem class.
+
+    content_url : Optional[str]
+        The name of the workbook as it appears in the URL.
+
+    created_at : Optional[datetime.datetime]
+        The date and time the workbook was created.
+
+    description : Optional[str]
+        User-defined description of the workbook.
+
+    id : Optional[str]
+       The identifier for the workbook. You need this value to query a specific
+       workbook or to delete a workbook with the get_by_id and delete methods.
+
+    owner_id : Optional[str]
+        The identifier for the owner (UserItem) of the workbook.
+
+    preview_image : bytes
+        The thumbnail image for the view. You must first call the
+        workbooks.populate_preview_image method to access this data.
+
+    project_name : Optional[str]
+        The name of the project that contains the workbook.
+
+    size: int
+        The size of the workbook in megabytes.
+
+    hidden_views: Optional[list[str]]
+        List of string names of views that need to be hidden when the workbook
+        is published.
+
+    tags: set[str]
+        The set of tags associated with the workbook.
+
+    updated_at : Optional[datetime.datetime]
+        The date and time the workbook was last updated.
+
+    views : list[ViewItem]
+        The list of views (ViewItem) for the workbook. You must first call the
+        workbooks.populate_views method to access this data. See the ViewItem
+        class.
+
+    web_page_url : Optional[str]
+        The full URL for the workbook.
+
+    Examples
+    --------
+    # creating a new instance of a WorkbookItem
+    >>> import tableauserverclient as TSC
+
+    >>> # Create new workbook_item with project id '3a8b6148-493c-11e6-a621-6f3499394a39'
+
+    >>> new_workbook = TSC.WorkbookItem('3a8b6148-493c-11e6-a621-6f3499394a39')
+    """
+
+    def __init__(
+        self,
+        project_id: Optional[str] = None,
+        name: Optional[str] = None,
+        show_tabs: bool = False,
+        thumbnails_user_id: Optional[str] = None,
+        thumbnails_group_id: Optional[str] = None,
+    ) -> None:
         self._connections = None
         self._content_url = None
         self._webpage_url = None
@@ -35,15 +120,15 @@ class WorkbookItem(object):
         self._revisions = None
         self._size = None
         self._updated_at = None
-        self._views: Optional[Callable[[], List[ViewItem]]] = None
+        self._views: Optional[Callable[[], list[ViewItem]]] = None
         self.name = name
         self._description = None
         self.owner_id: Optional[str] = None
         # workaround for Personal Space workbooks without a project
         self.project_id: Optional[str] = project_id or uuid.uuid4().__str__()
         self.show_tabs = show_tabs
-        self.hidden_views: Optional[List[str]] = None
-        self.tags: Set[str] = set()
+        self.hidden_views: Optional[list[str]] = None
+        self.tags: set[str] = set()
         self.data_acceleration_config = {
             "acceleration_enabled": None,
             "accelerate_now": None,
@@ -52,11 +137,13 @@ class WorkbookItem(object):
         }
         self.data_freshness_policy = None
         self._permissions = None
+        self.thumbnails_user_id = thumbnails_user_id
+        self.thumbnails_group_id = thumbnails_group_id
 
         return None
 
     def __str__(self):
-        return "<WorkbookItem {0} '{1}' contentUrl='{2}' project={3}>".format(
+        return "<WorkbookItem {} '{}' contentUrl='{}' project={}>".format(
             self._id, self.name, self.content_url, self.project_id
         )
 
@@ -64,14 +151,14 @@ class WorkbookItem(object):
         return self.__str__() + "  { " + ", ".join(" % s: % s" % item for item in vars(self).items()) + "}"
 
     @property
-    def connections(self) -> List[ConnectionItem]:
+    def connections(self) -> list[ConnectionItem]:
         if self._connections is None:
             error = "Workbook item must be populated with connections first."
             raise UnpopulatedPropertyError(error)
         return self._connections()
 
     @property
-    def permissions(self) -> List[PermissionsRule]:
+    def permissions(self) -> list[PermissionsRule]:
         if self._permissions is None:
             error = "Workbook item must be populated with permissions first."
             raise UnpopulatedPropertyError(error)
@@ -152,7 +239,7 @@ class WorkbookItem(object):
         return self._updated_at
 
     @property
-    def views(self) -> List[ViewItem]:
+    def views(self) -> list[ViewItem]:
         # Views can be set in an initial workbook response OR by a call
         # to Server. Without getting too fancy, I think we can rely on
         # returning a list from the response, until they call
@@ -191,19 +278,35 @@ class WorkbookItem(object):
         self._data_freshness_policy = value
 
     @property
-    def revisions(self) -> List[RevisionItem]:
+    def revisions(self) -> list[RevisionItem]:
         if self._revisions is None:
             error = "Workbook item must be populated with revisions first."
             raise UnpopulatedPropertyError(error)
         return self._revisions()
 
+    @property
+    def thumbnails_user_id(self) -> Optional[str]:
+        return self._thumbnails_user_id
+
+    @thumbnails_user_id.setter
+    def thumbnails_user_id(self, value: str):
+        self._thumbnails_user_id = value
+
+    @property
+    def thumbnails_group_id(self) -> Optional[str]:
+        return self._thumbnails_group_id
+
+    @thumbnails_group_id.setter
+    def thumbnails_group_id(self, value: str):
+        self._thumbnails_group_id = value
+
     def _set_connections(self, connections):
         self._connections = connections
 
     def _set_permissions(self, permissions):
         self._permissions = permissions
 
-    def _set_views(self, views: Callable[[], List[ViewItem]]) -> None:
+    def _set_views(self, views: Callable[[], list[ViewItem]]) -> None:
         self._views = views
 
     def _set_pdf(self, pdf: Callable[[], bytes]) -> None:
@@ -316,7 +419,7 @@ class WorkbookItem(object):
             self.data_freshness_policy = data_freshness_policy
 
     @classmethod
-    def from_response(cls, resp: str, ns: Dict[str, str]) -> List["WorkbookItem"]:
+    def from_response(cls, resp: str, ns: dict[str, str]) -> list["WorkbookItem"]:
         all_workbook_items = list()
         parsed_response = fromstring(resp)
         all_workbook_xml = parsed_response.findall(".//t:workbook", namespaces=ns)

tableauserverclient/namespace.py

@@ -11,7 +11,7 @@ class UnknownNamespaceError(Exception):
     pass
 
 
-class Namespace(object):
+class Namespace:
     def __init__(self):
         self._namespace = {"t": NEW_NAMESPACE}
         self._detected = False

tableauserverclient/server/__init__.py

@@ -11,7 +11,7 @@ from tableauserverclient.server.filter import Filter
 from tableauserverclient.server.sort import Sort
 from tableauserverclient.server.server import Server
 from tableauserverclient.server.pager import Pager
-from tableauserverclient.server.endpoint.exceptions import NotSignedInError
+from tableauserverclient.server.endpoint.exceptions import FailedSignInError, NotSignedInError
 
 from tableauserverclient.server.endpoint import (
     Auth,
@@ -57,6 +57,7 @@ __all__ = [
     "Sort",
     "Server",
     "Pager",
+    "FailedSignInError",
     "NotSignedInError",
     "Auth",
     "CustomViews",

tableauserverclient/server/endpoint/auth_endpoint.py

@@ -16,7 +16,7 @@ if TYPE_CHECKING:
 
 
 class Auth(Endpoint):
-    class contextmgr(object):
+    class contextmgr:
         def __init__(self, callback):
             self._callback = callback
 
@@ -28,7 +28,7 @@ class Auth(Endpoint):
 
     @property
     def baseurl(self) -> str:
-        return "{0}/auth".format(self.parent_srv.baseurl)
+        return f"{self.parent_srv.baseurl}/auth"
 
     @api(version="2.0")
     def sign_in(self, auth_req: "Credentials") -> contextmgr:
@@ -41,8 +41,32 @@ class Auth(Endpoint):
         optionally a user_id to impersonate.
 
         Creates a context manager that will sign out of the server upon exit.
+
+        Parameters
+        ----------
+        auth_req : Credentials
+            The credentials object to use for signing in. Can be a TableauAuth,
+            PersonalAccessTokenAuth, or JWTAuth object.
+
+        Returns
+        -------
+        contextmgr
+            A context manager that will sign out of the server upon exit.
+
+        Examples
+        --------
+        >>> import tableauserverclient as TSC
+
+        >>> # create an auth object
+        >>> tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
+
+        >>> # create an instance for your server
+        >>> server = TSC.Server('https://SERVER_URL')
+
+        >>> # call the sign-in method with the auth object
+        >>> server.auth.sign_in(tableau_auth)
         """
-        url = "{0}/{1}".format(self.baseurl, "signin")
+        url = f"{self.baseurl}/signin"
         signin_req = RequestFactory.Auth.signin_req(auth_req)
         server_response = self.parent_srv.session.post(
             url, data=signin_req, **self.parent_srv.http_options, allow_redirects=False
@@ -60,25 +84,29 @@ class Auth(Endpoint):
         self._check_status(server_response, url)
         parsed_response = fromstring(server_response.content)
         site_id = parsed_response.find(".//t:site", namespaces=self.parent_srv.namespace).get("id", None)
+        site_url = parsed_response.find(".//t:site", namespaces=self.parent_srv.namespace).get("contentUrl", None)
         user_id = parsed_response.find(".//t:user", namespaces=self.parent_srv.namespace).get("id", None)
         auth_token = parsed_response.find("t:credentials", namespaces=self.parent_srv.namespace).get("token", None)
-        self.parent_srv._set_auth(site_id, user_id, auth_token)
-        logger.info("Signed into {0} as user with id {1}".format(self.parent_srv.server_address, user_id))
+        self.parent_srv._set_auth(site_id, user_id, auth_token, site_url)
+        logger.info(f"Signed into {self.parent_srv.server_address} as user with id {user_id}")
         return Auth.contextmgr(self.sign_out)
 
     # We use the same request that username/password login uses for all auth types.
     # The distinct methods are mostly useful for explicitly showing api version support for each auth type
     @api(version="3.6")
     def sign_in_with_personal_access_token(self, auth_req: "Credentials") -> contextmgr:
+        """Passthrough to sign_in method"""
         return self.sign_in(auth_req)
 
     @api(version="3.17")
     def sign_in_with_json_web_token(self, auth_req: "Credentials") -> contextmgr:
+        """Passthrough to sign_in method"""
         return self.sign_in(auth_req)
 
     @api(version="2.0")
     def sign_out(self) -> None:
-        url = "{0}/{1}".format(self.baseurl, "signout")
+        """Sign out of current session."""
+        url = f"{self.baseurl}/signout"
         # If there are no auth tokens you're already signed out. No-op
         if not self.parent_srv.is_signed_in():
             return
@@ -88,7 +116,34 @@ class Auth(Endpoint):
 
     @api(version="2.6")
     def switch_site(self, site_item: "SiteItem") -> contextmgr:
-        url = "{0}/{1}".format(self.baseurl, "switchSite")
+        """
+        Switch to a different site on the server. This will sign out of the
+        current site and sign in to the new site. If used as a context manager,
+        will sign out of the new site upon exit.
+
+        Parameters
+        ----------
+        site_item : SiteItem
+            The site to switch to.
+
+        Returns
+        -------
+        contextmgr
+            A context manager that will sign out of the new site upon exit.
+
+        Examples
+        --------
+        >>> import tableauserverclient as TSC
+
+        >>> # Find the site you want to switch to
+        >>> new_site = server.sites.get_by_id("9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d")
+        >>> # switch to the new site
+        >>> with server.auth.switch_site(new_site):
+        >>>     # do something on the new site
+        >>>     pass
+
+        """
+        url = f"{self.baseurl}/switchSite"
         switch_req = RequestFactory.Auth.switch_req(site_item.content_url)
         try:
             server_response = self.post_request(url, switch_req)
@@ -101,14 +156,18 @@ class Auth(Endpoint):
         self._check_status(server_response, url)
         parsed_response = fromstring(server_response.content)
         site_id = parsed_response.find(".//t:site", namespaces=self.parent_srv.namespace).get("id", None)
+        site_url = parsed_response.find(".//t:site", namespaces=self.parent_srv.namespace).get("contentUrl", None)
         user_id = parsed_response.find(".//t:user", namespaces=self.parent_srv.namespace).get("id", None)
         auth_token = parsed_response.find("t:credentials", namespaces=self.parent_srv.namespace).get("token", None)
-        self.parent_srv._set_auth(site_id, user_id, auth_token)
-        logger.info("Signed into {0} as user with id {1}".format(self.parent_srv.server_address, user_id))
+        self.parent_srv._set_auth(site_id, user_id, auth_token, site_url)
+        logger.info(f"Signed into {self.parent_srv.server_address} as user with id {user_id}")
         return Auth.contextmgr(self.sign_out)
 
     @api(version="3.10")
     def revoke_all_server_admin_tokens(self) -> None:
-        url = "{0}/{1}".format(self.baseurl, "revokeAllServerAdminTokens")
+        """
+        Revokes all personal access tokens for all server admins on the server.
+        """
+        url = f"{self.baseurl}/revokeAllServerAdminTokens"
         self.post_request(url, "")
         logger.info("Revoked all tokens for all server admins")