tableauserverclient 0.37__py3-none-any.whl → 0.39__py3-none-any.whl

{tableauserverclient/server → server}/endpoint/__init__.py

@@ -6,6 +6,7 @@ from tableauserverclient.server.endpoint.databases_endpoint import Databases
 from tableauserverclient.server.endpoint.datasources_endpoint import Datasources
 from tableauserverclient.server.endpoint.endpoint import Endpoint, QuerysetEndpoint
 from tableauserverclient.server.endpoint.exceptions import ServerResponseError, MissingRequiredFieldError
+from tableauserverclient.server.endpoint.extensions_endpoint import Extensions
 from tableauserverclient.server.endpoint.favorites_endpoint import Favorites
 from tableauserverclient.server.endpoint.fileuploads_endpoint import Fileuploads
 from tableauserverclient.server.endpoint.flow_runs_endpoint import FlowRuns
@@ -17,6 +18,7 @@ from tableauserverclient.server.endpoint.jobs_endpoint import Jobs
 from tableauserverclient.server.endpoint.linked_tasks_endpoint import LinkedTasks
 from tableauserverclient.server.endpoint.metadata_endpoint import Metadata
 from tableauserverclient.server.endpoint.metrics_endpoint import Metrics
+from tableauserverclient.server.endpoint.oidc_endpoint import OIDC
 from tableauserverclient.server.endpoint.projects_endpoint import Projects
 from tableauserverclient.server.endpoint.schedules_endpoint import Schedules
 from tableauserverclient.server.endpoint.server_info_endpoint import ServerInfo
@@ -41,6 +43,7 @@ __all__ = [
     "QuerysetEndpoint",
     "MissingRequiredFieldError",
     "Endpoint",
+    "Extensions",
     "Favorites",
     "Fileuploads",
     "FlowRuns",
@@ -52,6 +55,7 @@ __all__ = [
     "LinkedTasks",
     "Metadata",
     "Metrics",
+    "OIDC",
     "Projects",
     "Schedules",
     "ServerInfo",

{tableauserverclient/server → server}/endpoint/databases_endpoint.py

@@ -1,7 +1,8 @@
 import logging
-from typing import Union
+from typing import TYPE_CHECKING, Optional, Union
 from collections.abc import Iterable
 
+from tableauserverclient.models.permissions_item import PermissionsRule
 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
@@ -13,6 +14,10 @@ from tableauserverclient.models import DatabaseItem, TableItem, PaginationItem,
 
 from tableauserverclient.helpers.logging import logger
 
+if TYPE_CHECKING:
+    from tableauserverclient.models.dqw_item import DQWItem
+    from tableauserverclient.server.request_options import RequestOptions
+
 
 class Databases(Endpoint, TaggingMixin):
     def __init__(self, parent_srv):
@@ -23,11 +28,29 @@ class Databases(Endpoint, TaggingMixin):
         self._data_quality_warnings = _DataQualityWarningEndpoint(parent_srv, Resource.Database)
 
     @property
-    def baseurl(self):
+    def baseurl(self) -> str:
         return f"{self.parent_srv.baseurl}/sites/{self.parent_srv.site_id}/databases"
 
     @api(version="3.5")
-    def get(self, req_options=None):
+    def get(self, req_options: Optional["RequestOptions"] = None) -> tuple[list[DatabaseItem], PaginationItem]:
+        """
+        Get information about all databases on the site. Endpoint is paginated,
+        and will return a default of 100 items per page. Use the `req_options`
+        parameter to customize the request.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#query_databases
+
+        Parameters
+        ----------
+        req_options : RequestOptions, optional
+            Options to customize the request. If not provided, defaults to None.
+
+        Returns
+        -------
+        tuple[list[DatabaseItem], PaginationItem]
+            A tuple containing a list of DatabaseItem objects and a
+            PaginationItem object.
+        """
         logger.info("Querying all databases on site")
         url = self.baseurl
         server_response = self.get_request(url, req_options)
@@ -37,7 +60,27 @@ class Databases(Endpoint, TaggingMixin):
 
     # Get 1 database
     @api(version="3.5")
-    def get_by_id(self, database_id):
+    def get_by_id(self, database_id: str) -> DatabaseItem:
+        """
+        Get information about a single database asset on the site.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#query_database
+
+        Parameters
+        ----------
+        database_id : str
+            The ID of the database to retrieve.
+
+        Returns
+        -------
+        DatabaseItem
+            A DatabaseItem object representing the database.
+
+        Raises
+        ------
+        ValueError
+            If the database ID is undefined.
+        """
         if not database_id:
             error = "database ID undefined."
             raise ValueError(error)
@@ -47,7 +90,24 @@ class Databases(Endpoint, TaggingMixin):
         return DatabaseItem.from_response(server_response.content, self.parent_srv.namespace)[0]
 
     @api(version="3.5")
-    def delete(self, database_id):
+    def delete(self, database_id: str) -> None:
+        """
+        Deletes a single database asset from the server.
+
+        Parameters
+        ----------
+        database_id : str
+            The ID of the database to delete.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        ValueError
+            If the database ID is undefined.
+        """
         if not database_id:
             error = "Database ID undefined."
             raise ValueError(error)
@@ -56,7 +116,28 @@ class Databases(Endpoint, TaggingMixin):
         logger.info(f"Deleted single database (ID: {database_id})")
 
     @api(version="3.5")
-    def update(self, database_item):
+    def update(self, database_item: DatabaseItem) -> DatabaseItem:
+        """
+        Update the database description, certify the database, set permissions,
+        or assign a User as the database contact.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#update_database
+
+        Parameters
+        ----------
+        database_item : DatabaseItem
+            The DatabaseItem object to update.
+
+        Returns
+        -------
+        DatabaseItem
+            The updated DatabaseItem object.
+
+        Raises
+        ------
+        MissingRequiredFieldError
+            If the database item is missing an ID.
+        """
         if not database_item.id:
             error = "Database item missing ID."
             raise MissingRequiredFieldError(error)
@@ -88,43 +169,45 @@ class Databases(Endpoint, TaggingMixin):
         return tables
 
     @api(version="3.5")
-    def populate_permissions(self, item):
+    def populate_permissions(self, item: DatabaseItem) -> None:
         self._permissions.populate(item)
 
     @api(version="3.5")
-    def update_permissions(self, item, rules):
+    def update_permissions(self, item: DatabaseItem, rules: list[PermissionsRule]) -> list[PermissionsRule]:
         return self._permissions.update(item, rules)
 
     @api(version="3.5")
-    def delete_permission(self, item, rules):
+    def delete_permission(self, item: DatabaseItem, rules: list[PermissionsRule]) -> None:
         self._permissions.delete(item, rules)
 
     @api(version="3.5")
-    def populate_table_default_permissions(self, item):
+    def populate_table_default_permissions(self, item: DatabaseItem):
         self._default_permissions.populate_default_permissions(item, Resource.Table)
 
     @api(version="3.5")
-    def update_table_default_permissions(self, item):
-        return self._default_permissions.update_default_permissions(item, Resource.Table)
+    def update_table_default_permissions(
+        self, item: DatabaseItem, rules: list[PermissionsRule]
+    ) -> list[PermissionsRule]:
+        return self._default_permissions.update_default_permissions(item, rules, Resource.Table)
 
     @api(version="3.5")
-    def delete_table_default_permissions(self, item):
-        self._default_permissions.delete_default_permission(item, Resource.Table)
+    def delete_table_default_permissions(self, rule: PermissionsRule, item: DatabaseItem) -> None:
+        self._default_permissions.delete_default_permission(item, rule, Resource.Table)
 
     @api(version="3.5")
-    def populate_dqw(self, item):
+    def populate_dqw(self, item: DatabaseItem) -> None:
         self._data_quality_warnings.populate(item)
 
     @api(version="3.5")
-    def update_dqw(self, item, warning):
+    def update_dqw(self, item: DatabaseItem, warning: "DQWItem") -> list["DQWItem"]:
         return self._data_quality_warnings.update(item, warning)
 
     @api(version="3.5")
-    def add_dqw(self, item, warning):
+    def add_dqw(self, item: DatabaseItem, warning: "DQWItem") -> list["DQWItem"]:
         return self._data_quality_warnings.add(item, warning)
 
     @api(version="3.5")
-    def delete_dqw(self, item):
+    def delete_dqw(self, item: DatabaseItem) -> None:
         self._data_quality_warnings.clear(item)
 
     @api(version="3.9")

{tableauserverclient/server → server}/endpoint/datasources_endpoint.py

@@ -6,8 +6,8 @@ import os
 
 from contextlib import closing
 from pathlib import Path
-from typing import Literal, Optional, TYPE_CHECKING, Union, overload
-from collections.abc import Iterable, Mapping, Sequence
+from typing import Literal, Optional, TYPE_CHECKING, TypedDict, TypeVar, Union, overload
+from collections.abc import Iterable, Sequence
 
 from tableauserverclient.helpers.headers import fix_filename
 from tableauserverclient.models.dqw_item import DQWItem
@@ -50,13 +50,50 @@ FilePath = Union[str, os.PathLike]
 FileObject = Union[io.BufferedReader, io.BytesIO]
 PathOrFile = Union[FilePath, FileObject]
 
-FilePath = Union[str, os.PathLike]
 FileObjectR = Union[io.BufferedReader, io.BytesIO]
 FileObjectW = Union[io.BufferedWriter, io.BytesIO]
 PathOrFileR = Union[FilePath, FileObjectR]
 PathOrFileW = Union[FilePath, FileObjectW]
 
 
+HyperActionCondition = TypedDict(
+    "HyperActionCondition",
+    {
+        "op": str,
+        "target-col": str,
+        "source-col": str,
+    },
+)
+
+HyperActionRow = TypedDict(
+    "HyperActionRow",
+    {
+        "action": Literal[
+            "update",
+            "upsert",
+            "delete",
+        ],
+        "source-table": str,
+        "target-table": str,
+        "condition": HyperActionCondition,
+    },
+)
+
+HyperActionTable = TypedDict(
+    "HyperActionTable",
+    {
+        "action": Literal[
+            "insert",
+            "replace",
+        ],
+        "source-table": str,
+        "target-table": str,
+    },
+)
+
+HyperAction = Union[HyperActionTable, HyperActionRow]
+
+
 class Datasources(QuerysetEndpoint[DatasourceItem], TaggingMixin[DatasourceItem]):
     def __init__(self, parent_srv: "Server") -> None:
         super().__init__(parent_srv)
@@ -191,16 +228,34 @@ class Datasources(QuerysetEndpoint[DatasourceItem], TaggingMixin[DatasourceItem]
         self.delete_request(url)
         logger.info(f"Deleted single datasource (ID: {datasource_id})")
 
+    T = TypeVar("T", bound=FileObjectW)
+
+    @overload
+    def download(
+        self,
+        datasource_id: str,
+        filepath: T,
+        include_extract: bool = True,
+    ) -> T: ...
+
+    @overload
+    def download(
+        self,
+        datasource_id: str,
+        filepath: Optional[FilePath] = None,
+        include_extract: bool = True,
+    ) -> str: ...
+
     # Download 1 datasource by id
     @api(version="2.0")
     @parameter_added_in(no_extract="2.5")
     @parameter_added_in(include_extract="2.5")
     def download(
         self,
-        datasource_id: str,
-        filepath: Optional[PathOrFileW] = None,
-        include_extract: bool = True,
-    ) -> PathOrFileW:
+        datasource_id,
+        filepath=None,
+        include_extract=True,
+    ):
         """
         Downloads the specified data source from a site. The data source is
         downloaded as a .tdsx file.
@@ -319,8 +374,63 @@ class Datasources(QuerysetEndpoint[DatasourceItem], TaggingMixin[DatasourceItem]
         logger.info(f"Updated datasource item (ID: {datasource_item.id} & connection item {connection_item.id}")
         return connection
 
+    @api(version="3.26")
+    def update_connections(
+        self,
+        datasource_item: DatasourceItem,
+        connection_luids: Iterable[str],
+        authentication_type: str,
+        username: Optional[str] = None,
+        password: Optional[str] = None,
+        embed_password: Optional[bool] = None,
+    ) -> list[ConnectionItem]:
+        """
+        Bulk updates one or more datasource connections by LUID.
+
+        Parameters
+        ----------
+        datasource_item : DatasourceItem
+            The datasource item containing the connections.
+
+        connection_luids : Iterable of str
+            The connection LUIDs to update.
+
+        authentication_type : str
+            The authentication type to use (e.g., 'auth-keypair').
+
+        username : str, optional
+            The username to set.
+
+        password : str, optional
+            The password or secret to set.
+
+        embed_password : bool, optional
+            Whether to embed the password.
+
+        Returns
+        -------
+        Iterable of str
+            The connection LUIDs that were updated.
+        """
+
+        url = f"{self.baseurl}/{datasource_item.id}/connections"
+
+        request_body = RequestFactory.Datasource.update_connections_req(
+            connection_luids=connection_luids,
+            authentication_type=authentication_type,
+            username=username,
+            password=password,
+            embed_password=embed_password,
+        )
+        server_response = self.put_request(url, request_body)
+        connection_items = ConnectionItem.from_response(server_response.content, self.parent_srv.namespace)
+        updated_ids: list[str] = [conn.id for conn in connection_items]
+
+        logger.info(f"Updated connections for datasource {datasource_item.id}: {', '.join(updated_ids)}")
+        return connection_items
+
     @api(version="2.8")
-    def refresh(self, datasource_item: DatasourceItem, incremental: bool = False) -> JobItem:
+    def refresh(self, datasource_item: Union[DatasourceItem, str], incremental: bool = False) -> JobItem:
         """
         Refreshes the extract of an existing workbook.
 
@@ -328,8 +438,8 @@ class Datasources(QuerysetEndpoint[DatasourceItem], TaggingMixin[DatasourceItem]
 
         Parameters
         ----------
-        workbook_item : WorkbookItem | str
-            The workbook item or workbook ID.
+        workbook_item : DatasourceItem | str
+            The datasource item or datasource ID.
         incremental: bool
             Whether to do a full refresh or incremental refresh of the extract data
 
@@ -424,13 +534,13 @@ class Datasources(QuerysetEndpoint[DatasourceItem], TaggingMixin[DatasourceItem]
     @parameter_added_in(as_job="3.0")
     def publish(
         self,
-        datasource_item: DatasourceItem,
-        file: PathOrFileR,
-        mode: str,
-        connection_credentials: Optional[ConnectionCredentials] = None,
-        connections: Optional[Sequence[ConnectionItem]] = None,
-        as_job: bool = False,
-    ) -> Union[DatasourceItem, JobItem]:
+        datasource_item,
+        file,
+        mode,
+        connection_credentials=None,
+        connections=None,
+        as_job=False,
+    ):
         """
         Publishes a data source to a server, or appends data to an existing
         data source.
@@ -576,7 +686,7 @@ class Datasources(QuerysetEndpoint[DatasourceItem], TaggingMixin[DatasourceItem]
         datasource_or_connection_item: Union[DatasourceItem, ConnectionItem, str],
         *,
         request_id: str,
-        actions: Sequence[Mapping],
+        actions: Sequence[HyperAction],
         payload: Optional[FilePath] = None,
     ) -> JobItem:
         """
@@ -733,7 +843,7 @@ class Datasources(QuerysetEndpoint[DatasourceItem], TaggingMixin[DatasourceItem]
         self._data_quality_warnings.populate(item)
 
     @api(version="3.5")
-    def update_dqw(self, item, warning):
+    def update_dqw(self, item: DatasourceItem, warning: "DQWItem") -> list["DQWItem"]:
         """
         Update the warning type, status, and message of a data quality warning.
 
@@ -755,7 +865,7 @@ class Datasources(QuerysetEndpoint[DatasourceItem], TaggingMixin[DatasourceItem]
         return self._data_quality_warnings.update(item, warning)
 
     @api(version="3.5")
-    def add_dqw(self, item, warning):
+    def add_dqw(self, item: DatasourceItem, warning: "DQWItem") -> list["DQWItem"]:
         """
         Add a data quality warning to a datasource.
 
@@ -786,7 +896,7 @@ class Datasources(QuerysetEndpoint[DatasourceItem], TaggingMixin[DatasourceItem]
         return self._data_quality_warnings.add(item, warning)
 
     @api(version="3.5")
-    def delete_dqw(self, item):
+    def delete_dqw(self, item: DatasourceItem) -> None:
         """
         Delete a data quality warnings from an asset.
 
@@ -843,15 +953,35 @@ class Datasources(QuerysetEndpoint[DatasourceItem], TaggingMixin[DatasourceItem]
         revisions = RevisionItem.from_response(server_response.content, self.parent_srv.namespace, datasource_item)
         return revisions
 
-    # Download 1 datasource revision by revision number
-    @api(version="2.3")
+    T = TypeVar("T", bound=FileObjectW)
+
+    @overload
     def download_revision(
         self,
         datasource_id: str,
         revision_number: Optional[str],
-        filepath: Optional[PathOrFileW] = None,
+        filepath: T,
         include_extract: bool = True,
-    ) -> PathOrFileW:
+    ) -> T: ...
+
+    @overload
+    def download_revision(
+        self,
+        datasource_id: str,
+        revision_number: Optional[str],
+        filepath: Optional[FilePath] = None,
+        include_extract: bool = True,
+    ) -> str: ...
+
+    # Download 1 datasource revision by revision number
+    @api(version="2.3")
+    def download_revision(
+        self,
+        datasource_id,
+        revision_number,
+        filepath=None,
+        include_extract=True,
+    ):
         """
         Downloads a specific version of a data source prior to the current one
         in .tdsx format. To download the current version of a data source set

{tableauserverclient/server → server}/endpoint/dqw_endpoint.py

@@ -1,4 +1,5 @@
 import logging
+from typing import Callable, Optional, Protocol, TYPE_CHECKING
 
 from .endpoint import Endpoint
 from .exceptions import MissingRequiredFieldError
@@ -7,6 +8,15 @@ from tableauserverclient.models import DQWItem
 
 from tableauserverclient.helpers.logging import logger
 
+if TYPE_CHECKING:
+    from tableauserverclient.server.request_options import RequestOptions
+
+
+class HasId(Protocol):
+    @property
+    def id(self) -> Optional[str]: ...
+    def _set_data_quality_warnings(self, dqw: Callable[[], list[DQWItem]]): ...
+
 
 class _DataQualityWarningEndpoint(Endpoint):
     def __init__(self, parent_srv, resource_type):
@@ -14,12 +24,12 @@ class _DataQualityWarningEndpoint(Endpoint):
         self.resource_type = resource_type
 
     @property
-    def baseurl(self):
+    def baseurl(self) -> str:
         return "{}/sites/{}/dataQualityWarnings/{}".format(
             self.parent_srv.baseurl, self.parent_srv.site_id, self.resource_type
         )
 
-    def add(self, resource, warning):
+    def add(self, resource: HasId, warning: DQWItem) -> list[DQWItem]:
         url = f"{self.baseurl}/{resource.id}"
         add_req = RequestFactory.DQW.add_req(warning)
         response = self.post_request(url, add_req)
@@ -28,7 +38,7 @@ class _DataQualityWarningEndpoint(Endpoint):
 
         return warnings
 
-    def update(self, resource, warning):
+    def update(self, resource: HasId, warning: DQWItem) -> list[DQWItem]:
         url = f"{self.baseurl}/{resource.id}"
         add_req = RequestFactory.DQW.update_req(warning)
         response = self.put_request(url, add_req)
@@ -37,11 +47,11 @@ class _DataQualityWarningEndpoint(Endpoint):
 
         return warnings
 
-    def clear(self, resource):
+    def clear(self, resource: HasId) -> None:
         url = f"{self.baseurl}/{resource.id}"
         return self.delete_request(url)
 
-    def populate(self, item):
+    def populate(self, item: HasId) -> None:
         if not item.id:
             error = "Server item is missing ID. Item must be retrieved from server first."
             raise MissingRequiredFieldError(error)
@@ -52,7 +62,7 @@ class _DataQualityWarningEndpoint(Endpoint):
         item._set_data_quality_warnings(dqw_fetcher)
         logger.info(f"Populated permissions for item (ID: {item.id})")
 
-    def _get_data_quality_warnings(self, item, req_options=None):
+    def _get_data_quality_warnings(self, item: HasId, req_options: Optional["RequestOptions"] = None) -> list[DQWItem]:
         url = f"{self.baseurl}/{item.id}"
         server_response = self.get_request(url, req_options)
         dqws = DQWItem.from_response(server_response.content, self.parent_srv.namespace)

{tableauserverclient/server → server}/endpoint/endpoint.py

@@ -14,6 +14,7 @@ from typing import (
     TypeVar,
     Union,
 )
+from typing_extensions import Self
 
 from tableauserverclient.models.pagination_item import PaginationItem
 from tableauserverclient.server.request_options import RequestOptions
@@ -353,3 +354,41 @@ class QuerysetEndpoint(Endpoint, Generic[T]):
     @abc.abstractmethod
     def get(self, request_options: Optional[RequestOptions] = None) -> tuple[list[T], PaginationItem]:
         raise NotImplementedError(f".get has not been implemented for {self.__class__.__qualname__}")
+
+    def fields(self: Self, *fields: str) -> QuerySet:
+        """
+        Add fields to the request options. If no fields are provided, the
+        default fields will be used. If fields are provided, the default fields
+        will be used in addition to the provided fields.
+
+        Parameters
+        ----------
+        fields : str
+            The fields to include in the request options.
+
+        Returns
+        -------
+        QuerySet
+        """
+        queryset = QuerySet(self)
+        queryset.request_options.fields |= set(fields) | set(("_default_",))
+        return queryset
+
+    def only_fields(self: Self, *fields: str) -> QuerySet:
+        """
+        Add fields to the request options. If no fields are provided, the
+        default fields will be used. If fields are provided, the default fields
+        will be replaced by the provided fields.
+
+        Parameters
+        ----------
+        fields : str
+            The fields to include in the request options.
+
+        Returns
+        -------
+        QuerySet
+        """
+        queryset = QuerySet(self)
+        queryset.request_options.fields |= set(fields)
+        return queryset