feat: consolidate and export public type aliases (HyperAction, FilePath, AddResponse, IDP types)

.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Build and publish docs
+
+on:
+  push:
+    branches: [master]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  build-and-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install docs dependencies
+        run: pip install -e ".[docs]"
+
+      - name: Build Sphinx docs
+        run: sphinx-build -b html docs sphinx_build
+
+      - name: Checkout gh-pages
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+          path: gh-pages
+
+      - name: Copy Sphinx output into gh-pages/sphinx
+        run: |
+          rm -rf gh-pages/sphinx
+          cp -r sphinx_build gh-pages/sphinx
+
+      - name: Create PR to gh-pages
+        uses: peter-evans/create-pull-request@v6
+        with:
+          path: gh-pages
+          branch: docs-update
+          base: gh-pages
+          title: "docs: update generated API reference"
+          body: "Automated update of Sphinx-generated API reference from master."
+          commit-message: "docs: regenerate Sphinx API reference"

.readthedocs.yaml

@@ -0,0 +1,25 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - method: pip
+     path: .
+     extra_requirements:
+     - docs

docs/conf.py

@@ -0,0 +1,68 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+
+# -- Project information -----------------------------------------------------
+# Source - https://stackoverflow.com/a/75396624
+# Posted by Jan, modified by community. See post 'Timeline' for change history
+# Retrieved 2026-06-19, License - CC BY-SA 4.0
+
+# conf.py
+
+try:
+    import tomllib
+except ImportError:
+    import tomli as tomllib
+
+from pathlib import Path
+import importlib.metadata
+
+with open(Path(__file__).parent.parent / "pyproject.toml", "rb") as f:
+    toml = tomllib.load(f)
+
+# -- Project information -----------------------------------------------------
+
+project = toml["project"]["name"]
+release = importlib.metadata.version(project)
+version = ".".join(release.split(".")[:2])
+
+# -- General configuration ---------------------------------------------------
+# -- General configuration
+
+extensions = [
+    "sphinx.ext.duration",
+    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+]
+
+intersphinx_mapping = {
+    "rtd": ("https://docs.readthedocs.io/en/stable/", None),
+    "python": ("https://docs.python.org/3/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
+}
+intersphinx_disabled_domains = ["std"]
+
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "furo"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = []

docs/index.rst

@@ -0,0 +1,9 @@
+tableauserverclient
+===================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+.. automodule:: tableauserverclient
+   :members:

pyproject.toml

@@ -35,6 +35,7 @@ repository = "https://github.com/tableau/server-client-python"
 [project.optional-dependencies]
 test = ["black==26.3.1", "build", "mypy==1.4", "pytest>=7.0", "pytest-cov", "pytest-subtests",
     "pytest-xdist", "requests-mock>=1.0,<2.0", "types-requests>=2.32.4.20250913"]
+docs = ["sphinx", "tomli", "furo"]
 
 [tool.setuptools.package-data]
 # Only include data for tableauserverclient, not for samples, test, docs

tableauserverclient/__init__.py

@@ -58,6 +58,24 @@
     WorkbookItem,
 )
 
+from tableauserverclient.types import (
+    AddResponse,
+    FilePath,
+    FileObject,
+    FileObjectR,
+    FileObjectW,
+    HasIdpConfigurationID,
+    HyperAction,
+    HyperActionCondition,
+    HyperActionRow,
+    HyperActionTable,
+    IDPAttributes,
+    IDPProperty,
+    PathOrFile,
+    PathOrFileR,
+    PathOrFileW,
+)
+
 from tableauserverclient.server import (
     CSVRequestOptions,
     ExcelRequestOptions,
@@ -76,6 +94,7 @@
 )
 
 __all__ = [
+    "AddResponse",
     "BackgroundJobItem",
     "CollectionItem",
     "ColumnItem",
@@ -96,13 +115,24 @@
     "FailedSignInError",
     "FavoriteItem",
     "FileuploadItem",
+    "FilePath",
+    "FileObject",
+    "FileObjectR",
+    "FileObjectW",
     "Filter",
     "FlowItem",
     "FlowRunItem",
     "get_versions",
     "GroupItem",
     "GroupSetItem",
+    "HasIdpConfigurationID",
     "HourlyInterval",
+    "HyperAction",
+    "HyperActionCondition",
+    "HyperActionRow",
+    "HyperActionTable",
+    "IDPAttributes",
+    "IDPProperty",
     "ImageRequestOptions",
     "IntervalItem",
     "JobItem",
@@ -122,6 +152,9 @@
     "Permission",
     "PermissionsRule",
     "PersonalAccessTokenAuth",
+    "PathOrFile",
+    "PathOrFileR",
+    "PathOrFileW",
     "ProjectItem",
     "RequestOptions",
     "Resource",

tableauserverclient/models/connection_item.py

@@ -150,16 +150,7 @@ def from_response(cls, resp, ns) -> list["ConnectionItem"]:
 
     @classmethod
     def from_xml_element(cls, parsed_response, ns) -> list["ConnectionItem"]:
-        """
-        <connections>
-            <connection serverAddress="mysql.test.com">
-                <connectionCredentials embed="true" name="test" password="secret" />
-            </connection>
-            <connection serverAddress="pgsql.test.com">
-                <connectionCredentials embed="true" name="test" password="secret" />
-                </connection>
-        </connections>
-        """
+        """Parse connection items from an XML ``<connections>`` element."""
         all_connection_items: list["ConnectionItem"] = list()
         all_connection_xml = parsed_response.findall(".//t:connection", namespaces=ns)
 

tableauserverclient/models/job_item.py

@@ -27,7 +27,7 @@ class JobItem:
 
     Parameters
     ----------
-    id_ : str
+    id : str
         The identifier of the job.
 
     job_type : str

tableauserverclient/models/site_item.py

@@ -52,10 +52,13 @@ class SiteItem:
         cause an error.
 
     tier_explorer_capacity: int
+        (Optional) The maximum number of licenses for users with the Explorer role allowed on a site.
+
     tier_creator_capacity: int
+        (Optional) The maximum number of licenses for users with the Creator role allowed on a site.
+
     tier_viewer_capacity: int
-        (Optional) The maximum number of licenses for users with the Creator,
-        Explorer, or Viewer role, respectively, allowed on a site.
+        (Optional) The maximum number of licenses for users with the Viewer role allowed on a site.
 
     storage_quota: int
         (Optional) Specifies the maximum amount of space for the new site, in

tableauserverclient/models/task_item.py

@@ -13,7 +13,7 @@ class TaskItem:
 
     Parameters
     ----------
-    id_ : str
+    id : str
         The ID of the task.
 
     task_type : str

tableauserverclient/server/endpoint/custom_views_endpoint.py

@@ -32,12 +32,8 @@
 update the name or owner of a custom view.
 """
 
-FilePath = str | os.PathLike
-FileObject = io.BufferedReader | io.BytesIO
-FileObjectR = io.BufferedReader | io.BytesIO
-FileObjectW = io.BufferedWriter | io.BytesIO
-PathOrFileR = FilePath | FileObjectR
-PathOrFileW = FilePath | FileObjectW
+from tableauserverclient.types import FilePath, FileObject, FileObjectR, FileObjectW, PathOrFileR, PathOrFileW
+
 io_types_r = (io.BufferedReader, io.BytesIO)
 io_types_w = (io.BufferedWriter, io.BytesIO)
 

tableauserverclient/server/endpoint/datasources_endpoint.py

@@ -6,16 +6,29 @@
 
 from contextlib import closing
 from pathlib import Path
-from typing import Literal, TYPE_CHECKING, TypedDict, TypeVar, overload
+from typing import Literal, TYPE_CHECKING, TypeVar, overload
 from collections.abc import Iterable, Sequence
 
 from tableauserverclient.models.dqw_item import DQWItem
 from tableauserverclient.server.query import QuerySet
+from tableauserverclient.types import (
+    FilePath,
+    FileObject,
+    FileObjectR,
+    FileObjectW,
+    PathOrFile,
+    PathOrFileR,
+    PathOrFileW,
+    HyperAction,
+    HyperActionCondition,
+    HyperActionRow,
+    HyperActionTable,
+    AddResponse,
+)
 
 if TYPE_CHECKING:
     from tableauserverclient.server import Server
     from tableauserverclient.models import PermissionsRule
-    from .schedules_endpoint import AddResponse
 
 from tableauserverclient.server.endpoint.dqw_endpoint import _DataQualityWarningEndpoint
 from tableauserverclient.server.endpoint.endpoint import QuerysetEndpoint, api, parameter_added_in
@@ -50,53 +63,6 @@
 io_types_r = (io.BytesIO, io.BufferedReader)
 io_types_w = (io.BytesIO, io.BufferedWriter)
 
-FilePath = str | os.PathLike
-FileObject = io.BufferedReader | io.BytesIO
-PathOrFile = FilePath | FileObject
-
-FileObjectR = io.BufferedReader | io.BytesIO
-FileObjectW = io.BufferedWriter | io.BytesIO
-PathOrFileR = FilePath | FileObjectR
-PathOrFileW = 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 = HyperActionTable | HyperActionRow
-
 
 _UNSET = object()