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

[jacalata]

Summary

• HyperAction, HyperActionTable, HyperActionRow, HyperActionCondition — needed to annotate the actions argument to datasources.update_hyper_data()
• FilePath, FileObject, FileObjectR, FileObjectW, PathOrFile, PathOrFileR, PathOrFileW — needed to annotate publish()/download() arguments across datasources, workbooks, flows, and custom views; were duplicated across 4 endpoint files
• AddResponse — return type of schedules.add_to_schedule(), also used by the same method on datasources, workbooks, and flows
• IDPAttributes, IDPProperty, HasIdpConfigurationID — needed to annotate arguments to oidc.get_by_id() and oidc.delete_configuration()

All types are now defined in tableauserverclient/types.py and exported from tableauserverclient/__init__.py. The endpoint files import from types.py instead of defining them locally.

Test plan

• 849 existing tests pass (pytest test/)
• Types importable directly: from tableauserverclient import HyperAction, FilePath, AddResponse, HasIdpConfigurationID

🤖 Generated with Claude Code

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
tableauserverclient
__init__.py	6	0	100%
config.py	15	0	100%
datetime_helpers.py	25	1	1	96%
exponential_backoff.py	20	0	100%
filesys_helpers.py	31	0	100%
namespace.py	26	3	3	88%
types.py	20	0	100%
tableauserverclient/bin
__init__.py	2	0	100%
_version.py	358	212	212	41%
tableauserverclient/helpers
__init__.py	1	0	100%
logging.py	2	0	100%
strings.py	31	1	1	97%
tableauserverclient/models
__init__.py	46	0	100%
collection_item.py	41	7	7	83%
column_item.py	55	32	32	42%
connection_credentials.py	35	11	11	69%
connection_item.py	94	14	14	85%
custom_view_item.py	144	21	21	85%
data_acceleration_report_item.py	54	1	1	98%
data_alert_item.py	158	4	4	97%
data_freshness_policy_item.py	155	15	15	90%
database_item.py	207	36	36	83%
datasource_item.py	300	12	12	96%
dqw_item.py	104	5	5	95%
exceptions.py	4	0	100%
extensions_item.py	132	4	4	97%
extract_item.py	44	4	4	91%
favorites_item.py	69	8	8	88%
fileupload_item.py	19	0	100%
flow_item.py	149	10	10	93%
flow_run_item.py	71	0	100%
group_item.py	89	6	6	93%
groupset_item.py	49	7	7	86%
interval_item.py	182	32	32	82%
job_item.py	187	10	10	95%
linked_tasks_item.py	79	1	1	99%
location_item.py	29	2	2	93%
metric_item.py	129	13	13	90%
oidc_item.py	63	3	3	95%
pagination_item.py	34	1	1	97%
permissions_item.py	111	12	12	89%
project_item.py	207	31	31	85%
property_decorators.py	100	18	18	82%
reference_item.py	26	2	2	92%
revision_item.py	59	1	1	98%
schedule_item.py	209	6	6	97%
server_info_item.py	37	7	7	81%
site_item.py	636	13	13	98%
subscription_item.py	101	2	2	98%
table_item.py	119	18	18	85%
tableau_auth.py	61	25	25	59%
tableau_types.py	27	1	1	96%
tag_item.py	15	0	100%
target.py	6	0	100%
task_item.py	56	2	2	96%
user_item.py	310	18	18	94%
view_item.py	220	16	16	93%
virtual_connection_item.py	64	8	8	88%
webhook_item.py	69	1	1	99%
workbook_item.py	362	16	16	96%
tableauserverclient/server
__init__.py	9	0	100%
exceptions.py	4	0	100%
filter.py	29	1	1	97%
pager.py	33	1	1	97%
query.py	143	15	15	90%
request_factory.py	1335	195	195	85%
request_options.py	386	5	5	99%
server.py	188	23	23	88%
sort.py	6	0	100%
tableauserverclient/server/endpoint
__init__.py	35	0	100%
auth_endpoint.py	77	11	11	86%
custom_views_endpoint.py	147	12	12	92%
data_acceleration_report_endpoint.py	21	0	100%
data_alert_endpoint.py	94	23	23	76%
databases_endpoint.py	111	30	30	73%
datasources_endpoint.py	313	33	33	89%
default_permissions_endpoint.py	44	3	3	93%
dqw_endpoint.py	45	16	16	64%
endpoint.py	212	20	20	91%
exceptions.py	77	6	6	92%
extensions_endpoint.py	31	0	100%
favorites_endpoint.py	94	22	22	77%
fileuploads_endpoint.py	51	0	100%
flow_runs_endpoint.py	62	9	9	85%
flow_task_endpoint.py	21	2	2	90%
flows_endpoint.py	194	53	53	73%
groups_endpoint.py	126	9	9	93%
groupsets_endpoint.py	72	7	7	90%
jobs_endpoint.py	67	9	9	87%
linked_tasks_endpoint.py	37	0	100%
metadata_endpoint.py	88	14	14	84%
metrics_endpoint.py	55	6	6	89%
oidc_endpoint.py	39	1	1	97%
permissions_endpoint.py	44	3	3	93%
projects_endpoint.py	178	24	24	87%
resource_tagger.py	127	35	35	72%
schedules_endpoint.py	118	11	11	91%
server_info_endpoint.py	36	10	10	72%
sites_endpoint.py	130	27	27	79%
subscriptions_endpoint.py	56	14	14	75%
tables_endpoint.py	110	36	36	67%
tasks_endpoint.py	63	6	6	90%
users_endpoint.py	183	8	8	96%
views_endpoint.py	150	9	9	94%
virtual_connections_endpoint.py	113	10	10	91%
webhooks_endpoint.py	54	9	9	83%
workbooks_endpoint.py	333	22	22	93%
TOTAL	11995	1423	88%

[bcantoni]

Claude Code posted this on my behalf after review:

Overview

The PR title/description says this consolidates five families of previously-duplicated type aliases (HyperAction*, FilePath/FileObject*/PathOrFile*, AddResponse, IDP types) into a new tableauserverclient/types.py, exported from __init__.py. That part is real and well-executed. However, the actual diff (gh pr diff 1825) is much larger than the description implies — it also includes:

• A new Sphinx/ReadTheDocs setup (.github/workflows/docs.yml, .readthedocs.yaml, docs/conf.py, docs/index.rst, pyproject.toml's new docs extra)
• ~600 lines of new e2e tests (test_e2e/test_publisher.py, test_e2e/test_site_admin.py) plus binary fixture assets and conftest.py fixture/marker changes
• Unrelated docstring fixes (job_item.py, task_item.py: id_ → id; site_item.py tier-capacity wording; connection_item.py XML sample removed from a docstring)

This looks like squashed/rebased history from other branches (commit messages like "Create Sphinx configuration file for documentation," "add more e2e tests," "change theme" appear in git log for this PR head but aren't attributed to any other open/merged PR). Before merging, confirm with the author whether development is missing commits this branch already has, or whether this branch accidentally bundled unrelated work — as-is, reviewing "type alias consolidation" together with a docs pipeline and a large e2e suite makes it hard to review each concern on its own merits, and a revert of one would be entangled with the others.

What's good about the core type-consolidation change

• tableauserverclient/types.py is a clean leaf module — no internal imports, so no circular-import risk from moving these definitions out of per-endpoint files and out of TYPE_CHECKING-guarded blocks.
• Confirmed real, not cosmetic: AddResponse was previously defined in schedules_endpoint.py and imported via TYPE_CHECKING-only forward references in datasources_endpoint.py, workbooks_endpoint.py, and flows_endpoint.py — a real duplication smell now fixed.
• IDPAttributes/IDPProperty/HasIdpConfigurationID and the Hyper-action TypedDicts move cleanly with no behavior change.
• Verified locally: black --check, mypy (with the repo's CI flags), and pytest test -n auto all pass — 849 passed, 1 skipped, matching the PR's stated test plan.

Issues found

1. Dead imports introduced across nearly every touched endpoint file. Several endpoint files now import names from tableauserverclient.types that are unused in that file (confirmed via pyflakes):

   • custom_views_endpoint.py: FilePath, FileObject, FileObjectR, FileObjectW all unused (only PathOrFileR/PathOrFileW are used).
   • datasources_endpoint.py: FileObject, FileObjectR, PathOrFile, PathOrFileW, HyperActionCondition, HyperActionRow, HyperActionTable all unused.
   • workbooks_endpoint.py: FileObject, FileObjectR, PathOrFileW unused.
   • flows_endpoint.py: FilePath, FileObjectR, FileObjectW unused.
   • oidc_endpoint.py: IDPAttributes, IDPProperty unused (only HasIdpConfigurationID is used).

   To be fair, most of these were already dead as locally-defined-but-unused type aliases before this PR (mypy/black don't flag unused module-level assignments the way they flag unused imports), so this PR doesn't regress runtime behavior — but converting them to imports makes the dead code visible to linters like pyflakes/ruff for the first time, and it's a quick cleanup to just drop the unused names from each from tableauserverclient.types import (...) block while you're already touching every one of these import lines.

2. No test coverage for the new public export surface. The PR description's "test plan" mentions manually verifying from tableauserverclient import HyperAction, FilePath, AddResponse, HasIdpConfigurationID works, but there's no automated test (e.g., under test/models/ or a new test/test_types.py) asserting these names are importable from the top-level package and stay in __all__. Since this PR's whole purpose is establishing a public API surface, a regression test that imports every new name from tableauserverclient (not just tableauserverclient.types) would guard against someone later reordering __init__.py or renaming something in types.py.

3. No CHANGELOG entry. Per repo convention (CHANGELOG.md gets a flat bullet per user-visible PR, ideally with the PR number), this newly-exported public API surface should get an entry — this is the kind of change users may rely on afterward (e.g. for type-checking their own update_hyper_data() calls), so it's worth documenting explicitly rather than leaving users to discover it from source.

4. Scope/hygiene concerns (see Overview):

   • The e2e test additions (test_publisher.py, test_site_admin.py) and the two new binary fixtures (.twbx, .tdsx) add real repo size/maintenance surface and aren't mentioned in the PR description at all — worth a sanity check that they're intentional here and not meant for PR test(e2e): add e2e tests for workbooks, datasources, views, pagination, jobs, tagging, projects, favorites, metadata, site-admin #1823 (jac/e2e-tests), which appears to cover similar/overlapping ground (workbooks, datasources, site-admin, favorites, tagging, metadata).
   • The Sphinx/docs pipeline is a meaningful new CI surface (a workflow with contents: write/pull-requests: write permissions that pushes to gh-pages via peter-evans/create-pull-request) that deserves its own dedicated review, ideally separate from a type-refactor PR.
   • The docstring tweaks to job_item.py/task_item.py/site_item.py/connection_item.py are harmless improvements but have nothing to do with type consolidation; worth splitting out if this PR gets re-scoped.

Security

Nothing security-sensitive in the type-consolidation change itself. The new docs.yml workflow grants contents: write and pull-requests: write and runs on push: branches: [master] — this is fine since it only ever builds and PRs into gh-pages, but it's a new automated write path worth a second look if the docs work is reviewed independently.

Recommendation

The type-consolidation refactor itself is sound (verified by tests/mypy/black) and worth merging, but I'd ask the author to confirm the diff scope before approval — specifically, whether this branch should be rebased to drop the docs/e2e/docstring commits so this PR reviews cleanly as "consolidate and export public type aliases," matching its title and description.

[bcantoni]

@jacalata see the things claude code pointed out above -- in particular are we sure the "docs" changes should be in here? (Docs are still in gh-pages branch.)

[jacalata]

cleaned up, docs work now lives in #1832.