Add structural Protocol types for TSC item classes by jacalata · Pull Request #1802 · tableau/server-client-python

jacalata · 2026-06-26T23:19:52Z

Motivation

tableau_types.py has carried a # todo: refactoring: should actually define TableauItem as an interface... comment for years. The current
TableauItem is a Union[DatasourceItem, FlowItem, ...] which forces
every new item type to be enumerated by hand and doesn't compose well
with tag/permission helpers that only need a subset of attributes.

Extracting a Protocol hierarchy (TableauItem, OwnedItem,
TaggableItem, ContentItem) closes that TODO and gives the internal
helpers (resource_tagger, permissions_endpoint.populate) a real
type they can name without importing every concrete class.

Behavior change

Public TableauItem semantics change. It was a Union, now it's a
structural Protocol. Two observable effects for downstream code:

Static type checks that used to require one of the Union members
now accept any object with id and name -- widening.
isinstance(x, TableauItem) previously raised TypeError (Union
isn't a runtime-checkable class); it now returns True for any
object with the right shape. If you relied on the TypeError as a
guard, add an explicit concrete-type check instead.

Called out in CHANGELOG.md in this PR.

Also bundled (cosmetic):

resource_tagger's private Taggable protocol replaced by
_TaggableWithInitial
default_permissions_endpoint's local BaseItem type alias renamed
to DefaultPermissionsTarget
_initial_tags: set narrowed to set[str] in DatasourceItem /
WorkbookItem
Duplicate SiteOIDCConfiguration entry removed from
models.__all__ (pre-existing bug)

Test plan

test/test_protocols.py covers positive cases (workbook, datasource,
view, flow, metric satisfy the Protocols), negative cases (TaskItem /
DataAlertItem don't satisfy TableauItem because they lack name),
and the issubclass -> TypeError gotcha
Full suite: 918 passed, 1 skipped
mypy: no issues in 211 source files
TSC.TableauItem, TSC.ContentItem, TSC.OwnedItem,
TSC.TaggableItem all reachable from top-level package
Schema alignment: ts-api_3_29.xsd primary content types
(workbook/datasource/view/flow/metric) all carry id, name, owner, tags,
createdAt/updatedAt -- Protocol hierarchy matches

🤖 Generated with Claude Code

…gs type - Rename DefaultPermissionsEndpoint's local BaseItem alias to DefaultPermissionsTarget to avoid shadowing the new public Protocol - Remove _initial_tags from TaggableItem (internal dirty-tracking detail, not a public contract); update ContentItem docstring to include MetricItem - Narrow WorkbookItem._initial_tags and DatasourceItem._initial_tags annotations from bare set to set[str] for Protocol invariance compliance Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

… __all__ Taggable in resource_tagger.py was never used as a type bound -- TaggableItem in base_item.py now covers the public contract. Also remove runtime_checkable import which became unused. Fix pre-existing duplicate SiteOIDCConfiguration entry in models/__init__.__all__. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

ViewItem.owner_id is not independently writable (it tracks the parent workbook's owner), so a plain writable Protocol attribute annotation would mislead mypy. A @Property annotation satisfies both ViewItem's read-only property and the writable instance attributes on other item classes. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Add test/test_protocols.py covering isinstance() checks for BaseItem, OwnedItem, TaggableItem, and ContentItem against all representative item classes (WorkbookItem, DatasourceItem, ViewItem, FlowItem, ProjectItem, MetricItem, UserItem) and plain structural objects, including negative cases and protocol-hierarchy checks. - Add _TaggableWithInitial private Protocol in resource_tagger.py to capture the _initial_tags implementation detail alongside the public TaggableItem surface; use it to fully annotate _ResourceTagger._add_tags, _delete_tag, and update_tags. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…test Add section comments to __init__.__all__ to distinguish the new structural protocols from the alphabetical concrete-model list. Move the inline `import datetime` in test_protocols.py to module level, matching the import style used throughout the test suite. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions · 2026-06-26T23:20:33Z

Coverage Report

File	Stmts	Miss	Cover	Missing
tableauserverclient
__init__.py	5	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%
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	47	0	100%
base_item.py	14	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	17	1	1	94%
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	152	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	323	33	33	90%
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	198	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	42	1	1	98%
permissions_endpoint.py	45	3	3	93%
projects_endpoint.py	178	24	24	87%
resource_tagger.py	124	34	34	73%
schedules_endpoint.py	119	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	338	22	22	93%
TOTAL	12005	1422	88%

jorwoods · 2026-06-26T23:25:34Z

This is great and will make other typing easier. Should they be named differently to clearly differentiate them?

Something like _BaseItem or BaseItemProtocol

jacalata · 2026-06-27T07:26:54Z

Hm, I think underscores would make some more helpful IDEs hide/limit them in autocomplete etc, so not that. A common approach is something like "SupportsOwner", but that doesn't quite work for "ContentItem". I think the current item works ok and is pretty standard.
But thinking about it did make me remember to absorb the half-implemented TableauItem, so good question :)

…es.py BaseItem is renamed to TableauItem to match the existing name in tableau_types.py and fulfill its TODO comment ("should define TableauItem as an interface"). The Union type alias is replaced with an import of the Protocol, removing the need to enumerate concrete types. id and name are now declared as @Property on the Protocol so that concrete classes with read-only property implementations (and VirtualConnectionItem whose name: str is narrower than str | None) satisfy it under mypy's covariant property checking. A private _PermissibleItem Protocol is added to permissions_endpoint.py to type the populate() method's _set_permissions call, which is an implementation detail not appropriate for the public TableauItem Protocol. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- base_item.py TableauItem docstring: fix the stale first paragraph that claimed "plain Protocol attributes (not @Property)". The code uses @Property; the docstring now matches. Also documents that TaskItem and DataAlertItem (no `name` attribute) don't satisfy the protocol, and calls out the issubclass-raises-TypeError gotcha for data-attribute Protocols. - __init__.py: export ContentItem, OwnedItem, TaggableItem from the top-level package. Previously only TableauItem was accessible as TSC.TableauItem; the other three were only under models/__init__.py, which meant TSC.ContentItem raised AttributeError. - test_protocols.py: add coverage for previously-untested types the original Union included. DatabaseItem, TableItem, VirtualConnectionItem positive on TableauItem; VirtualConnectionItem positive on OwnedItem and negative on TaggableItem (no `tags` attribute). TaskItem negative on TableauItem (has `id` but no `name`), validating the docstring's explicit exclusion. Plus an issubclass-raises-TypeError test to lock in the data-attribute Protocol limitation. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds structural typing.Protocol interfaces for Tableau resource items and updates internal endpoints/tests to rely on these protocols for runtime and static type checks.

Changes:

Introduces TableauItem, OwnedItem, TaggableItem, and ContentItem structural protocols in models/base_item.py and exports them via package inits.
Refactors endpoint typing to use private structural protocols (permissions/tagging) and improves tag typing in model items.
Adds a new pytest suite validating runtime isinstance() behavior for the new protocols.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
test/test_protocols.py	Adds tests validating runtime structural protocol conformance across representative items.
tableauserverclient/server/endpoint/resource_tagger.py	Replaces the old runtime-checkable protocol with a private protocol and tightens method type hints.
tableauserverclient/server/endpoint/permissions_endpoint.py	Introduces a private protocol for items that support permission population and updates `populate()` typing.
tableauserverclient/server/endpoint/default_permissions_endpoint.py	Renames the `BaseItem` alias to a clearer `DefaultPermissionsTarget`.
tableauserverclient/models/workbook_item.py	Tightens `_initial_tags` typing to `set[str]`.
tableauserverclient/models/datasource_item.py	Tightens `_initial_tags` typing to `set[str]`.
tableauserverclient/models/tableau_types.py	Removes the old `Union[...]` TableauItem alias and documents the new Protocol-based approach.
tableauserverclient/models/base_item.py	Adds the new structural Protocol definitions.
tableauserverclient/models/init.py	Re-exports the new protocols and updates imports/`__all__`.
tableauserverclient/init.py	Exposes the new protocols at the top-level package API.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

    from tableauserverclient.server.server import Server


+class _TaggableWithInitial(Protocol):


+    id: str | None
+    tags: set[str]
+    _initial_tags: set[str]


    "ServerInfoItem",
    "SiteAuthConfiguration",
    "SiteItem",
-    "SiteOIDCConfiguration",
    "SubscriptionItem",
    "TableItem",
    "TableauAuth",
    "PersonalAccessTokenAuth",
    "JWTAuth",
    "Resource",
-    "TableauItem",
    "plural_type",


+        class Tagged:
+            id: str | None = None
+            name: str | None = "x"
+            tags: set = set()


Adds a release-note entry for the isinstance() semantics change so users who relied on the TypeError from isinstance(x, Union) will see it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

jacalata and others added 7 commits June 25, 2026 17:31

feat: add BaseItem protocol for item type safety

f87287e

feat: add OwnedItem and TaggableItem protocols to base_item.py

c3a8043

jacalata mentioned this pull request Jul 6, 2026

Add find_by_name() to QuerysetEndpoint for content item lookup #1810

Closed

jacalata and others added 2 commits July 28, 2026 00:26

Merge origin/development into jac/base-item-class

020d610

jacalata requested a lite review from Copilot August 6, 2026 21:19

jacalata enabled auto-merge (squash) August 6, 2026 21:19

Copilot AI reviewed Aug 6, 2026

View reviewed changes

docs: note TableauItem Union -> Protocol behavior change in CHANGELOG

4e6ead1

Adds a release-note entry for the isinstance() semantics change so users who relied on the TypeError from isinstance(x, Union) will see it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Navigation Menu

Uh oh!

Add structural Protocol types for TSC item classes - #1802

Add structural Protocol types for TSC item classes#1802
jacalata wants to merge 11 commits into
developmentfrom
jac/base-item-class

jacalata commented Jun 26, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 26, 2026 •

edited

Loading

Uh oh!

jorwoods commented Jun 26, 2026

Uh oh!

jacalata commented Jun 27, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		from tableauserverclient.server.server import Server


		class _TaggableWithInitial(Protocol):

Uh oh!

Conversation

jacalata commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Behavior change

Test plan

Uh oh!

github-actions Bot commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jorwoods commented Jun 26, 2026

Uh oh!

jacalata commented Jun 27, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jacalata commented Jun 26, 2026 •

edited

Loading

github-actions Bot commented Jun 26, 2026 •

edited

Loading