docs: clarify username formats, ProjectLeader-as-group, and filter special-char behavior by jacalata · Pull Request #1854 · tableau/server-client-python · GitHub

Closes #993, #1067, #1200.

Motivation

Three long-standing stale issues, all traceable to gaps in the same doc
region:

Update docs and examples to properly show required fields for adding new users #993: users.add docstring gave no hint that name is the server-side
authentication identifier, not the person's display name. The primary
example TSC.UserItem('new_user', ...) misleads readers into treating it
as a display-name field.
Clarify/write docs for assigning a group as Project Leader (permissions) #1067: projects.update_permissions had no examples, so callers had no
guide for the common "assign a group as Project Leader" case.
workbook filter fails with special characters. #1200: The REST filter grammar treats ,, &, :, [, ] as
delimiters and the server does not support escaping, but nothing in the
docstring warned about this or documented the wildcard workaround.

Behavior change

Docs only. No API change.

UserItem.name + users.add docstrings describe the required format per
auth scheme: Cloud = email, local Server = username, AD-backed =
SAMAccountName@FullyQualifiedDomain or UPN. Example split into Cloud +
AD invocations.
projects.update_permissions example constructs a PermissionsRule
with grantee=<group> and capability=ProjectLeader, plus a note that
update_permissions fully replaces existing rules (call
populate_permissions first if preserving).
Filter class + QuerySet.filter docstrings document the reserved
delimiter characters and the *-wildcard workaround under the Equals
operator, citing the server version requirement (Tableau Cloud May 2023
or Tableau Server 2022.1.14) sourced from the public "Filtering and
Sorting" REST API docs.

Test plan

test/test_user.py, test_user_model.py, test_project.py,
test_project_model.py, test_filter.py: 89 passed
mypy clean

🤖 Generated with Claude Code

…ecial-char behavior Bundles three long-standing docs gaps flagged in stale issues: #993 - users.add example used a fake short username with no explanation that `name` is the server auth identifier (email on Cloud, SAM@Domain on AD-backed Server), not the person's display name. Rewrote the users.add docstring intro to describe the required formats per auth scheme, split the example into a Cloud invocation and an AD invocation, and added matching guidance to UserItem.name. #1067 - projects.update_permissions had no examples, so callers had no guide for the common "assign group as Project Leader" case. Added an example that shows constructing a PermissionsRule with grantee=<group> and capability=ProjectLeader, plus a note that update_permissions is a full replacement (call populate_permissions first if preserving existing rules). #1200 - the REST filter grammar treats ',', '&', ':', '[' and ']' as delimiters and the server does not support escaping, so `filter(name="T(L-F,SZ&V-MY)")` fails with 400065 for any name containing those characters. Documented the constraint on the Filter class docstring and on QuerySet.filter, along with the working wildcard workaround (Equals with '*' substituted). No behavior change. Docs only. Closes #993, #1067, #1200.

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	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	192	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	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	44	3	3	93%
projects_endpoint.py	178	24	24	87%
resource_tagger.py	127	35	35	72%
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	12007	1423	88%

The Equals-operator wildcard workaround for special characters requires Tableau Cloud May 2023 or Tableau Server 2022.1.14 (per the REST API "Filtering and Sorting" docs). Older servers reject `*` as a literal, so readers on those need to know before copying the example. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Pull request overview

This PR updates in-code documentation (docstrings) to clarify several commonly-misunderstood behaviors in the Tableau Server Client (TSC) Python library—specifically around user creation identifiers, project permission rules for Project Leaders, and REST filter limitations with reserved delimiter characters.

Changes:

Clarifies UserItem.name / users.add documentation to distinguish authentication username vs display name, with auth-scheme-specific examples.
Adds a concrete projects.update_permissions example for assigning a group as ProjectLeader, plus a warning that the call replaces the full permissions list.
Documents REST filter reserved delimiter characters and the * wildcard workaround in Filter and QuerySet.filter docstrings.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tableauserverclient/server/query.py	Adds QuerySet.filter docstring explaining shorthand operators and special-character caveat.
tableauserverclient/server/filter.py	Adds detailed Filter docstring documenting delimiter characters and wildcard workaround/version constraints.
tableauserverclient/server/endpoint/users_endpoint.py	Clarifies users.add docstring about required username formats and adds clearer examples.
tableauserverclient/server/endpoint/projects_endpoint.py	Adds an example for assigning a group as Project Leader and notes replacement semantics.
tableauserverclient/models/user_item.py	Clarifies UserItem.name parameter semantics and required formats per auth scheme.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Previous wording said wildcards, ranges, and operators are "NOT supported" -- but I don't have live verification that `*` or `%` are inert in a vf_ value. The public filtering docs describe only exact match and OR-lists; behavior of other characters is undocumented, not verifiably absent. Rephrase to say what we know (docs don't cover it, TSC doesn't emit operator prefixes) and tell callers to verify against their target server before relying on the outcome. This is intentionally less prescriptive than the previous version. The related open PR #1854 was flagged by the same fresh-eyes pass for making an unverified `*`-as-wildcard claim in the opposite direction -- both PRs should stay in "docs describe X; other behaviors are untested" territory until we run the experiments. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Three fresh-eyes findings: - Replace Unicode em dashes (U+2014) in filter.py and users_endpoint.py docstrings with ASCII `--` or `;`, matching the repo's ASCII-only convention that other docstrings follow. - query.py referenced docs/filter-sort.md, which lives on the gh-pages branch and does not exist in an installed package. Swap for the published URL so a `help()` reader can actually reach the doc. - Soften the AD username claim in users_endpoint.py: a bare SAMAccountName's resolution depends on the AD configuration, so "typically will not resolve" was stated more strongly than the surrounding server-behavior guidance warranted.

jacalata requested a lite review from Copilot August 17, 2026 20:02

Copilot started reviewing on behalf of jacalata August 17, 2026 20:03 View session

Copilot AI reviewed Aug 17, 2026

View reviewed changes

Comment thread tableauserverclient/server/query.py Outdated

docs: clarify username formats, ProjectLeader-as-group, and filter special-char behavior by jacalata · Pull Request #1854 · tableau/server-client-python · GitHub

Uh oh!

docs: clarify username formats, ProjectLeader-as-group, and filter special-char behavior - #1854

docs: clarify username formats, ProjectLeader-as-group, and filter special-char behavior#1854
jacalata wants to merge 3 commits into
developmentfrom
jac/docs-stale-cleanup

jacalata commented Aug 6, 2026 •
edited
Loading

Uh oh!

Uh oh!

github-actions Bot commented Aug 6, 2026 •
edited
Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

docs: clarify username formats, ProjectLeader-as-group, and filter special-char behavior by jacalata · Pull Request #1854 · tableau/server-client-python · GitHub

Uh oh!

docs: clarify username formats, ProjectLeader-as-group, and filter special-char behavior - #1854

docs: clarify username formats, ProjectLeader-as-group, and filter special-char behavior#1854jacalata wants to merge 3 commits intodevelopmenttableau/server-client-python:developmentfrom jac/docs-stale-cleanuptableau/server-client-python:jac/docs-stale-cleanupCopy head branch name to clipboard

Conversation

jacalata commented Aug 6, 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 Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

docs: clarify username formats, ProjectLeader-as-group, and filter special-char behavior#1854
jacalata wants to merge 3 commits into
developmentfrom
jac/docs-stale-cleanup

jacalata commented Aug 6, 2026 •
edited
Loading

github-actions Bot commented Aug 6, 2026 •
edited
Loading