tableauserverclient 0.34__tar.gz → 0.36__tar.gz

{tableauserverclient-0.34 → tableauserverclient-0.36}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: tableauserverclient
-Version: 0.34
+Version: 0.36
 Summary: A Python module for working with the Tableau Server REST API.
 Author-email: Tableau <github@tableau.com>
 License: The MIT License (MIT)
@@ -41,7 +41,7 @@ Requires-Dist: defusedxml>=0.7.1
 Requires-Dist: packaging>=23.1
 Requires-Dist: requests>=2.32
 Requires-Dist: urllib3<3,>=2.2.2
-Requires-Dist: typing_extensions>=4.0.1
+Requires-Dist: typing_extensions>=4.0
 Provides-Extra: test
 Requires-Dist: black==24.8; extra == "test"
 Requires-Dist: build; extra == "test"

{tableauserverclient-0.34 → tableauserverclient-0.36}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools>=68.0", "versioneer>=0.29", "wheel"]
+requires = ["setuptools>=75.0", "versioneer[toml]==0.29", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
@@ -16,7 +16,7 @@ dependencies = [
     'packaging>=23.1',   # latest as at 7/31/23
     'requests>=2.32',  # latest as at 7/31/23
     'urllib3>=2.2.2,<3',
-    'typing_extensions>=4.0.1',
+    'typing_extensions>=4.0',
 ]
 requires-python = ">=3.9"
 classifiers = [
@@ -38,6 +38,7 @@ test = ["black==24.8", "build", "mypy==1.4", "pytest>=7.0", "pytest-cov", "pytes
 [tool.black]
 line-length = 120
 target-version = ['py39', 'py310', 'py311', 'py312', 'py313']
+force-exclude = "tableauserverclient/bin/*"
 
 [tool.mypy]
 check_untyped_defs = false
@@ -50,7 +51,15 @@ show_error_codes = true
 ignore_missing_imports = true  # defusedxml library has no types
 no_implicit_reexport = true
 implicit_optional = true
+exclude = ['/bin/']
 
 [tool.pytest.ini_options]
 testpaths = ["test"]
 addopts = "--junitxml=./test.junit.xml"
+
+[tool.versioneer]
+VCS = "git"
+style = "pep440-pre"
+versionfile_source = "tableauserverclient/bin/_version.py"
+versionfile_build = "tableauserverclient/bin/_version.py"
+tag_prefix = "v"

{tableauserverclient-0.34 → tableauserverclient-0.36}/samples/create_extract_task.py

@@ -29,7 +29,9 @@ def main():
         help="desired logging level (set to error by default)",
     )
     # Options specific to this sample:
-    # This sample has no additional options, yet. If you add some, please add them here
+    parser.add_argument("resource_type", choices=["workbook", "datasource"])
+    parser.add_argument("resource_id")
+    parser.add_argument("--incremental", default=False)
 
     args = parser.parse_args()
 
@@ -45,6 +47,7 @@ def main():
         # Monthly Schedule
         # This schedule will run on the 15th of every month at 11:30PM
         monthly_interval = TSC.MonthlyInterval(start_time=time(23, 30), interval_value=15)
+        print(monthly_interval)
         monthly_schedule = TSC.ScheduleItem(
             None,
             None,
@@ -53,18 +56,20 @@ def main():
             monthly_interval,
         )
 
-        # Default to using first workbook found in server
-        all_workbook_items, pagination_item = server.workbooks.get()
-        my_workbook: TSC.WorkbookItem = all_workbook_items[0]
+        my_workbook: TSC.WorkbookItem = server.workbooks.get_by_id(args.resource_id)
 
         target_item = TSC.Target(
             my_workbook.id,  # the id of the workbook or datasource
             "workbook",  # alternatively can be "datasource"
         )
 
-        extract_item = TSC.TaskItem(
+        refresh_type = "FullRefresh"
+        if args.incremental:
+            refresh_type = "Incremental"
+
+        scheduled_extract_item = TSC.TaskItem(
             None,
-            "FullRefresh",
+            refresh_type,
             None,
             None,
             None,
@@ -74,7 +79,7 @@ def main():
         )
 
         try:
-            response = server.tasks.create(extract_item)
+            response = server.tasks.create(scheduled_extract_item)
             print(response)
         except Exception as e:
             print(e)

{tableauserverclient-0.34 → tableauserverclient-0.36}/samples/extracts.py

@@ -25,8 +25,11 @@ def main():
         help="desired logging level (set to error by default)",
     )
     # Options specific to this sample
-    parser.add_argument("--delete")
-    parser.add_argument("--create")
+    parser.add_argument("--create", action="store_true")
+    parser.add_argument("--delete", action="store_true")
+    parser.add_argument("--refresh", action="store_true")
+    parser.add_argument("--workbook", required=False)
+    parser.add_argument("--datasource", required=False)
     args = parser.parse_args()
 
     # Set logging level based on user input, or error by default
@@ -39,20 +42,45 @@ def main():
     server.add_http_options({"verify": False})
     server.use_server_version()
     with server.auth.sign_in(tableau_auth):
-        # Gets all workbook items
-        all_workbooks, pagination_item = server.workbooks.get()
-        print(f"\nThere are {pagination_item.total_available} workbooks on site: ")
-        print([workbook.name for workbook in all_workbooks])
 
-        if all_workbooks:
-            # Pick one workbook from the list
-            wb = all_workbooks[3]
+        wb = None
+        ds = None
+        if args.workbook:
+            wb = server.workbooks.get_by_id(args.workbook)
+            if wb is None:
+                raise ValueError(f"Workbook not found for id {args.workbook}")
+        elif args.datasource:
+            ds = server.datasources.get_by_id(args.datasource)
+            if ds is None:
+                raise ValueError(f"Datasource not found for id {args.datasource}")
+        else:
+            # Gets all workbook items
+            all_workbooks, pagination_item = server.workbooks.get()
+            print(f"\nThere are {pagination_item.total_available} workbooks on site: ")
+            print([workbook.name for workbook in all_workbooks])
+
+            if all_workbooks:
+                # Pick one workbook from the list
+                wb = all_workbooks[3]
 
         if args.create:
             print("create extract on wb ", wb.name)
             extract_job = server.workbooks.create_extract(wb, includeAll=True)
             print(extract_job)
 
+        if args.refresh:
+            extract_job = None
+            if ds is not None:
+                print(f"refresh extract on datasource {ds.name}")
+                extract_job = server.datasources.refresh(ds, includeAll=True, incremental=True)
+            elif wb is not None:
+                print(f"refresh extract on workbook {wb.name}")
+                extract_job = server.workbooks.refresh(wb)
+            else:
+                print("no content item selected to refresh")
+
+            print(extract_job)
+
         if args.delete:
             print("delete extract on wb ", wb.name)
             jj = server.workbooks.delete_extract(wb)

{tableauserverclient-0.34 → tableauserverclient-0.36}/samples/publish_workbook.py

@@ -36,9 +36,16 @@ def main():
         help="desired logging level (set to error by default)",
     )
     # Options specific to this sample
+    group = parser.add_mutually_exclusive_group(required=False)
+    group.add_argument("--thumbnails-user-id", "-u", help="User ID to use for thumbnails")
+    group.add_argument("--thumbnails-group-id", "-g", help="Group ID to use for thumbnails")
+
+    parser.add_argument("--workbook-name", "-n", help="Name with which to publish the workbook")
     parser.add_argument("--file", "-f", help="local filepath of the workbook to publish")
     parser.add_argument("--as-job", "-a", help="Publishing asynchronously", action="store_true")
     parser.add_argument("--skip-connection-check", "-c", help="Skip live connection check", action="store_true")
+    parser.add_argument("--project", help="Project within which to publish the workbook")
+    parser.add_argument("--show-tabs", help="Publish workbooks with tabs displayed", action="store_true")
 
     args = parser.parse_args()
 
@@ -48,11 +55,22 @@ def main():
 
     # Step 1: Sign in to server.
     tableau_auth = TSC.PersonalAccessTokenAuth(args.token_name, args.token_value, site_id=args.site)
-    server = TSC.Server(args.server, use_server_version=True)
+    server = TSC.Server(args.server, use_server_version=True, http_options={"verify": False})
     with server.auth.sign_in(tableau_auth):
-        # Step 2: Get all the projects on server, then look for the default one.
-        all_projects, pagination_item = server.projects.get()
-        default_project = next((project for project in all_projects if project.is_default()), None)
+        # Step2: Retrieve the project id, if a project name was passed
+        if args.project is not None:
+            req_options = TSC.RequestOptions()
+            req_options.filter.add(
+                TSC.Filter(TSC.RequestOptions.Field.Name, TSC.RequestOptions.Operator.Equals, args.project)
+            )
+            projects = list(TSC.Pager(server.projects, req_options))
+            if len(projects) > 1:
+                raise ValueError("The project name is not unique")
+            project_id = projects[0].id
+        else:
+            # Get all the projects on server, then look for the default one.
+            all_projects, pagination_item = server.projects.get()
+            project_id = next((project for project in all_projects if project.is_default()), None).id
 
         connection1 = ConnectionItem()
         connection1.server_address = "mssql.test.com"
@@ -67,10 +85,16 @@ def main():
         all_connections.append(connection1)
         all_connections.append(connection2)
 
-        # Step 3: If default project is found, form a new workbook item and publish.
+        # Step 3: Form a new workbook item and publish.
         overwrite_true = TSC.Server.PublishMode.Overwrite
-        if default_project is not None:
-            new_workbook = TSC.WorkbookItem(default_project.id)
+        if project_id is not None:
+            new_workbook = TSC.WorkbookItem(
+                project_id=project_id,
+                name=args.workbook_name,
+                show_tabs=args.show_tabs,
+                thumbnails_user_id=args.thumbnails_user_id,
+                thumbnails_group_id=args.thumbnails_group_id,
+            )
             if args.as_job:
                 new_job = server.workbooks.publish(
                     new_workbook,
@@ -92,7 +116,7 @@ def main():
                 )
                 print(f"Workbook published. ID: {new_workbook.id}")
         else:
-            error = "The default project could not be found."
+            error = "The destination project could not be found."
             raise LookupError(error)
 
 

{tableauserverclient-0.34 → tableauserverclient-0.36}/samples/refresh.py

@@ -27,6 +27,8 @@ def main():
     # Options specific to this sample
     parser.add_argument("resource_type", choices=["workbook", "datasource"])
     parser.add_argument("resource_id")
+    parser.add_argument("--incremental")
+    parser.add_argument("--synchronous")
 
     args = parser.parse_args()
 
@@ -34,27 +36,42 @@ def main():
     logging_level = getattr(logging, args.logging_level.upper())
     logging.basicConfig(level=logging_level)
 
+    refresh_type = "FullRefresh"
+    incremental = False
+    if args.incremental:
+        refresh_type = "Incremental"
+        incremental = True
+
     tableau_auth = TSC.PersonalAccessTokenAuth(args.token_name, args.token_value, site_id=args.site)
-    server = TSC.Server(args.server, use_server_version=True)
+    server = TSC.Server(args.server, use_server_version=True, http_options={"verify": False})
     with server.auth.sign_in(tableau_auth):
         if args.resource_type == "workbook":
             # Get the workbook by its Id to make sure it exists
             resource = server.workbooks.get_by_id(args.resource_id)
+            print(resource)
 
             # trigger the refresh, you'll get a job id back which can be used to poll for when the refresh is done
-            job = server.workbooks.refresh(args.resource_id)
+            job = server.workbooks.refresh(args.resource_id, incremental=incremental)
         else:
             # Get the datasource by its Id to make sure it exists
             resource = server.datasources.get_by_id(args.resource_id)
+            print(resource)
+
+            # server.datasources.create_extract(resource)
 
             # trigger the refresh, you'll get a job id back which can be used to poll for when the refresh is done
-            job = server.datasources.refresh(resource)
+            job = server.datasources.refresh(resource, incremental=incremental)  # by default runs as a sync task,
 
-        print(f"Update job posted (ID: {job.id})")
-        print("Waiting for job...")
-        # `wait_for_job` will throw if the job isn't executed successfully
-        job = server.jobs.wait_for_job(job)
-        print("Job finished succesfully")
+            print(f"{refresh_type} job posted (ID: {job.id})")
+        if args.synchronous:
+            # equivalent to tabcmd --synchnronous: wait for the job to complete
+            try:
+                # `wait_for_job` will throw if the job isn't executed successfully
+                print("Waiting for job...")
+                server.jobs.wait_for_job(job)
+                print("Job finished succesfully")
+            except Exception as e:
+                print(f"Job failed! {e}")
 
 
 if __name__ == "__main__":

tableauserverclient-0.36/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

{tableauserverclient-0.34 → tableauserverclient-0.36}/setup.py

@@ -1,15 +1,6 @@
 import versioneer
 from setuptools import setup
 
-"""
-once versioneer 0.25 gets released, we can move this from setup.cfg to pyproject.toml
-[tool.versioneer]
-VCS = "git"
-style = "pep440-pre"
-versionfile_source = "tableauserverclient/_version.py"
-versionfile_build = "tableauserverclient/_version.py"
-tag_prefix = "v"
-"""
 setup(
     version=versioneer.get_version(),
     cmdclass=versioneer.get_cmdclass(),

{tableauserverclient-0.34 → tableauserverclient-0.36}/tableauserverclient/__init__.py

@@ -1,4 +1,4 @@
-from tableauserverclient._version import get_versions
+from tableauserverclient.bin._version import get_versions
 from tableauserverclient.namespace import NEW_NAMESPACE as DEFAULT_NAMESPACE
 from tableauserverclient.models import (
     BackgroundJobItem,
@@ -133,3 +133,7 @@ __all__ = [
     "WeeklyInterval",
     "WorkbookItem",
 ]
+
+from .bin import _version
+
+__version__ = _version.get_versions()["version"]

{tableauserverclient-0.34/tableauserverclient → tableauserverclient-0.36/tableauserverclient/bin}/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2024-10-25T16:34:58-0700",
+ "date": "2025-01-10T10:20:30-0800",
  "dirty": false,
  "error": null,
- "full-revisionid": "1d98fdad189ebed130fb904e8fa5dca2207f9011",
- "version": "0.34"
+ "full-revisionid": "42cecfe268d494284ca74b49aa4e9bfb6cfa197a",
+ "version": "0.36"
 }
 '''  # END VERSION_JSON
 

{tableauserverclient-0.34 → tableauserverclient-0.36}/tableauserverclient/models/connection_credentials.py

@@ -2,11 +2,27 @@ from .property_decorators import property_is_boolean
 
 
 class ConnectionCredentials:
-    """Connection Credentials for Workbooks and Datasources publish request.
+    """
+    Connection Credentials for Workbooks and Datasources publish request.
 
     Consider removing this object and other variables holding secrets
     as soon as possible after use to avoid them hanging around in memory.
 
+    Parameters
+    ----------
+    name: str
+        The username for the connection.
+
+    password: str
+        The password used for the connection.
+
+    embed: bool, default True
+        Determines whether to embed the password (True) for the workbook or data source connection or not (False).
+
+    oauth: bool, default False
+        Determines whether to use OAuth for the connection (True) or not (False).
+        For more information see: https://help.tableau.com/current/server/en-us/protected_auth.htm
+
     """
 
     def __init__(self, name, password, embed=True, oauth=False):

{tableauserverclient-0.34 → tableauserverclient-0.36}/tableauserverclient/models/connection_item.py

@@ -9,6 +9,44 @@ from tableauserverclient.helpers.logging import logger
 
 
 class ConnectionItem:
+    """
+    Corresponds to workbook and data source connections.
+
+    Attributes
+    ----------
+    datasource_id: str
+        The identifier of the data source.
+
+    datasource_name: str
+        The name of the data source.
+
+    id: str
+        The identifier of the connection.
+
+    connection_type: str
+        The type of connection.
+
+    username: str
+        The username for the connection. (see ConnectionCredentials)
+
+    password: str
+        The password used for the connection. (see ConnectionCredentials)
+
+    embed_password: bool
+        Determines whether to embed the password (True) for the workbook or data source connection or not (False). (see ConnectionCredentials)
+
+    server_address: str
+        The server address for the connection.
+
+    server_port: str
+        The port used for the connection.
+
+    connection_credentials: ConnectionCredentials
+        The Connection Credentials object containing authentication details for
+        the connection. Replaces username/password/embed_password when
+        publishing a flow, document or workbook file in the request body.
+    """
+
     def __init__(self):
         self._datasource_id: Optional[str] = None
         self._datasource_name: Optional[str] = None

{tableauserverclient-0.34 → tableauserverclient-0.36}/tableauserverclient/models/custom_view_item.py

@@ -5,14 +5,58 @@ from defusedxml.ElementTree import fromstring, tostring
 from typing import Callable, Optional
 from collections.abc import Iterator
 
-from .exceptions import UnpopulatedPropertyError
-from .user_item import UserItem
-from .view_item import ViewItem
-from .workbook_item import WorkbookItem
-from ..datetime_helpers import parse_datetime
+from tableauserverclient.models.exceptions import UnpopulatedPropertyError
+from tableauserverclient.models.user_item import UserItem
+from tableauserverclient.models.view_item import ViewItem
+from tableauserverclient.models.workbook_item import WorkbookItem
+from tableauserverclient.datetime_helpers import parse_datetime
 
 
 class CustomViewItem:
+    """
+    Represents a Custom View item on Tableau Server.
+
+    Parameters
+    ----------
+    id : Optional[str]
+        The ID of the Custom View item.
+
+    name : Optional[str]
+        The name of the Custom View item.
+
+    Attributes
+    ----------
+    content_url : Optional[str]
+        The content URL of the Custom View item.
+
+    created_at : Optional[datetime]
+        The date and time the Custom View item was created.
+
+    image: bytes
+        The image of the Custom View item. Must be populated first.
+
+    pdf: bytes
+        The PDF of the Custom View item. Must be populated first.
+
+    csv: Iterator[bytes]
+        The CSV of the Custom View item. Must be populated first.
+
+    shared : Optional[bool]
+        Whether the Custom View item is shared.
+
+    updated_at : Optional[datetime]
+        The date and time the Custom View item was last updated.
+
+    owner : Optional[UserItem]
+        The id of the owner of the Custom View item.
+
+    workbook : Optional[WorkbookItem]
+        The id of the workbook the Custom View item belongs to.
+
+    view : Optional[ViewItem]
+        The id of the view the Custom View item belongs to.
+    """
+
     def __init__(self, id: Optional[str] = None, name: Optional[str] = None) -> None:
         self._content_url: Optional[str] = None  # ?
         self._created_at: Optional["datetime"] = None

{tableauserverclient-0.34 → tableauserverclient-0.36}/tableauserverclient/models/flow_item.py

@@ -1,7 +1,7 @@
 import copy
 import datetime
 import xml.etree.ElementTree as ET
-from typing import Optional
+from typing import Iterable, Optional
 
 from defusedxml.ElementTree import fromstring
 
@@ -15,6 +15,51 @@ from tableauserverclient.models.tag_item import TagItem
 
 
 class FlowItem:
+    """
+    Represents a Tableau Flow item.
+
+    Parameters
+    ----------
+    project_id: str
+        The ID of the project that the flow belongs to.
+
+    name: Optional[str]
+        The name of the flow.
+
+    Attributes
+    ----------
+    connections: Iterable[ConnectionItem]
+        The connections associated with the flow. This property is not populated
+        by default and must be populated by calling the `populate_connections`
+        method.
+
+    created_at: Optional[datetime.datetime]
+        The date and time when the flow was created.
+
+    description: Optional[str]
+        The description of the flow.
+
+    dqws: Iterable[DQWItem]
+        The data quality warnings associated with the flow. This property is not
+        populated by default and must be populated by calling the `populate_dqws`
+        method.
+
+    id: Optional[str]
+        The ID of the flow.
+
+    name: Optional[str]
+        The name of the flow.
+
+    owner_id: Optional[str]
+        The ID of the user who owns the flow.
+
+    project_name: Optional[str]
+        The name of the project that the flow belongs to.
+
+    tags: set[str]
+        The tags associated with the flow.
+    """
+
     def __repr__(self):
         return "<Flow {} '{}' ({}) Project={} createdAt={}".format(
             self._id, self.name, self.description, self.project_id, self.created_at
@@ -33,9 +78,9 @@ class FlowItem:
         self.tags: set[str] = set()
         self.description: Optional[str] = None
 
-        self._connections: Optional[ConnectionItem] = None
-        self._permissions: Optional[Permission] = None
-        self._data_quality_warnings: Optional[DQWItem] = None
+        self._connections: Optional[Iterable[ConnectionItem]] = None
+        self._permissions: Optional[Iterable[Permission]] = None
+        self._data_quality_warnings: Optional[Iterable[DQWItem]] = None
 
     @property
     def connections(self):

{tableauserverclient-0.34 → tableauserverclient-0.36}/tableauserverclient/models/group_item.py

@@ -12,6 +12,46 @@ if TYPE_CHECKING:
 
 
 class GroupItem:
+    """
+    The GroupItem class contains the attributes for the group resources on
+    Tableau Server. The GroupItem class defines the information you can request
+    or query from Tableau Server. The class members correspond to the attributes
+    of a server request or response payload.
+
+    Parameters
+    ----------
+    name: str
+        The name of the group.
+
+    domain_name: str
+        The name of the Active Directory domain ("local" if local authentication is used).
+
+    Properties
+    ----------
+    users: Pager[UserItem]
+        The users in the group. Must be populated with a call to `populate_users()`.
+
+    id: str
+        The unique identifier for the group.
+
+    minimum_site_role: str
+        The minimum site role for users in the group. Use the `UserItem.Roles` enum.
+        Users in the group cannot have their site role set lower than this value.
+
+    license_mode: str
+        The mode defining when to apply licenses for group members. When the
+        mode is onLogin, a license is granted for each group member when they
+        login to a site. When the mode is onSync, a license is granted for group
+        members each time the domain is synced.
+
+    Examples
+    --------
+    >>> # Create a new group item
+    >>>  newgroup = TSC.GroupItem('My Group')
+
+
+    """
+
     tag_name: str = "group"
 
     class LicenseMode: