docs: expand RequestOptions.vf() with vf_ wire-format rules by jacalata · Pull Request #1840 · tableau/server-client-python · GitHub

Summary

The vf_ REST view filter has several server-side quirks that aren't obvious from the current one-line vf() docstring. This expands it to document what values actually mean on the wire: exact-match by default, , as OR-list, \, for a literal comma, the empty-value override behavior, no wildcards, no operators, boolean 'true'/'false' only.

Callers who build vf_ requests through TSC no longer have to reverse-engineer server behavior to figure out why their filter returned zero rows.

Why now

Working through --filter parsing bugs in tabcmd, I verified the wire-format behavior end-to-end against Tableau Cloud. Recording those findings in the library the tabcmd (and other callers) build on top of, so the next person doesn't have to redo the experiment.

Notable server-side behaviors documented:

Rock\, Paper\, Scissors — backslash-escape works for a literal comma. %2C does NOT.
vf_Region= (empty value) — overrides any workbook-embedded filter on that column. Undocumented but stable and useful.
* — NOT a wildcard on vf_. It's a wildcard on the filter= list-endpoint syntax, which is a different query parameter.

Test plan

help(PDFRequestOptions.vf) renders the expanded docstring cleanly
mypy passes (pre-commit hook)
No behavior change; docstring-only

🤖 Generated with Claude Code

The vf_ view filter has several server-side quirks that aren't obvious from the current one-line docstring. Document what values actually mean on the wire: exact match by default, comma as OR-list, backslash-escape for literal comma, empty-value override behavior, no wildcards, no operators, boolean 'true'/'false' only. This surfaces the behavior verified end-to-end against Tableau Cloud while working through --filter parsing issues in tabcmd, so callers who build vf_ requests through TSC know what the server will accept without having to reverse-engineer it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The `filter=` list-endpoint syntax is unrelated to view-filter export requests (it's for querying lists of workbooks/users/etc). Steering readers there was scope creep. Just say ranges/operators aren't supported and point at workbook-side design. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

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	323	16	16	95%
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	73	10	10	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	259	24	24	91%
exceptions.py	79	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	12065	1424	88%

Empirically verified: '\' in a vf_ value is the escape character. To match a literal backslash you must double it ('\\'). Consolidate the comma-escape and backslash rules into a single "backslash escapes" bullet, since it's one mechanism. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Dropped the abstract "\c means literal c" phrasing (weird to read with a random letter) and led with the two concrete cases -- escape a comma, escape a backslash -- and noted why each escape matters (comma would otherwise start an OR-list; backslash otherwise consumed as escape). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Empirically tested 20+ candidate metacharacters (/ % + : ; { } [ ] ( ) ? # * @ = & " ' < >) against a live server; every one passes through untouched when URL-encoded. Only ',' and '\' are vf_ metacharacters that need escaping in the wire value. Explicitly call that out so readers don't assume everything URL-special needs a client-side workaround. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Pull request overview

Note

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

Expands the RequestOptions.vf() docstring to more thoroughly document Tableau REST view-filter (vf_) query semantics.

Changes:

Adds detailed vf_<name>=<value> serialization and parsing rules (OR-lists, escaping, empty value behavior).
Clarifies unsupported patterns (wildcards, range/comparison operators) and boolean value constraints.
Improves formatting and provides a direct link to Tableau REST filtering documentation.

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

Copilot flagged the vf() docstring as internally inconsistent: it said 'vf() does not transform your input' and later 'vf() URL-encodes them for transport' -- both true, but confusing side-by-side. Rewrite to distinguish (a) no Tableau-specific escaping/semantic transforms (b) percent-encoding for HTTP transport. Also fold in a note that percent-encoding is transport-layer only: %2C reaches the server as ',' and gets processed as a comma delimiter, so URL-encoding does NOT escape a literal comma or backslash. Also softened the 'empty value' bullet from 'undocumented but stable behavior' (reads as a compat promise the library can't make) to 'observed... may change without notice.' No behavior change.

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (1)

tableauserverclient/server/request_options.py:359

The docstring says vf() “only percent-encodes the value for HTTP transport”, but vf() just appends (name, value) to self.view_filters and does not perform any encoding. Query-string percent-encoding (when it happens) is done later by the HTTP client/request construction, so attributing it to vf() is misleading and can be incorrect for code paths that build URLs manually.

        Serialized to the REST API as ``vf_<name>=<value>``. The rules below
        describe how the server interprets the wire value. ``vf()`` itself
        does not apply any Tableau-specific escaping or semantic transforms
        to your value; it only percent-encodes the value for HTTP transport,
        which the server decodes back before applying the rules below.

Fresh-eyes review noted two nits on the expanded docstring: - The percent-encoding-does-not-escape claim (that %2C/%5C reach the server as literal comma/backslash and are then processed by the escaping rules like any other) is not on the public REST API doc page -- it was verified end-to-end against Tableau Cloud. Mark it as empirical with a verification date so a future maintainer knows to re-check if the wire behavior changes. Note that only the \, escape is documented; \ and the percent-encoding claim are empirical. - The wildcard note previously suggested "use .parameter() and design the workbook accordingly" as a workaround. That conflates two mechanisms (workbook filter controls' wildcard behavior vs. parameters) and doesn't cleanly work around vf_'s exact-match limit. Reworded to just state the fact: vf_ is exact-match / OR-list only, no contains/starts-with/ends-with. Docstring-only change; 41 request_option tests still pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

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>

The prior wording ('not documented, verify against your target') was correct but weakly stated. Ran the actual experiments against Tableau Server 3.30: vf_ passes * and % through as literal data, so a value of 'Widget*' matches only a product literally named 'Widget*', 'META /star*/' matches its one row, and '*' or '%' on their own return zero rows. Docstring now states that outcome directly and cites the verification date.

Three findings from a post-push opus-5 pass: - Bold "**Value syntax**" instead of an underlined RST section header. Sitting an underlined heading above the Napoleon Parameters block can render weirdly depending on Sphinx config. - Label the escape examples explicitly as "wire form" vs "data value" so a reader can't confuse a Python-literal reading with the wire interpretation the docstring is describing. - Say "Tableau REST API 3.30" rather than "Tableau Server 3.30". Server versions are 2026.N-shaped; 3.30 is the REST API contract identifier, which is what actually determines the behavior. Also drops an unverified aside about Cloud/Server sharing the URL parser.

Opus-5 review found the entry's tracker link (#1431) points at a closed-not-planned issue; the underlying gap was filed with the Tableau REST API docs team internally and there's no realistic timeline for it being tracked back in the TSC repo. Rather than carry an untracked entry indefinitely, drop it. The behavior claim (vf_ is exact-match / OR-list only) is now covered by the expanded docstring on RequestOptions.vf() in #1840.

docs only change, merging with AI review only

* docs: add Known server-side limitations section Add a new user-facing section to docs/api-ref.md that lists behaviors users may hit that are constrained by the Tableau Server REST API rather than by TSC. Each entry links its tracking issue and notes where the fix is expected to land. Cross-link the new section from the top-of-page note, and point at the `Server-Side Enhancement` label as the live tracker maintained by this repo. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: drop internal work-item IDs and per-bullet fix-scope tag Public docs on gh-pages will be indexed, so remove the internal work-item numbers (W-...) from the Known server-side limitations section along with the paragraph that described what they were. Also strip the redundant per-bullet "Fix expected: server-side" tag: the section title already scopes the whole list to server-side gaps. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Drop On Extract Refresh entry, soften intro and daily-schedule wording Three fresh-eyes findings: - Remove the "Subscriptions cannot use On Extract Refresh" entry. The REST API's refreshExtractTriggered attribute does support this, and TSC support is landing in #1861 (which closes the tracker #1658). The entry is about to be factually wrong on both counts. - Soften the intro: it promised "follow the appropriate issues" for every item, but the vf_-silently-dropped entry has no tracker filed. New wording says "where filed" so the doc doesn't overpromise. - Reword the daily-schedules note to describe behavior neutrally ("currently runs daily schedules hourly instead") rather than calling it a "bug", which reads punchy on a public docs page. * Drop the vf_ exact-match limitation entry Opus-5 review found the entry's tracker link (#1431) points at a closed-not-planned issue; the underlying gap was filed with the Tableau REST API docs team internally and there's no realistic timeline for it being tracked back in the TSC repo. Rather than carry an untracked entry indefinitely, drop it. The behavior claim (vf_ is exact-match / OR-list only) is now covered by the expanded docstring on RequestOptions.vf() in #1840. --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

jacalata and others added 2 commits July 29, 2026 15:57

jacalata and others added 3 commits July 29, 2026 16:00

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

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

Copilot AI reviewed Aug 6, 2026

View reviewed changes

Comment thread tableauserverclient/server/request_options.py Outdated

Comment thread tableauserverclient/server/request_options.py Outdated

Comment thread tableauserverclient/server/request_options.py Outdated

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

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

Copilot AI reviewed Aug 17, 2026

View reviewed changes

jacalata and others added 4 commits August 17, 2026 13:20

jacalata disabled auto-merge August 20, 2026 07:37

jacalata merged commit 51b3efc into development Aug 20, 2026
31 checks passed

jacalata deleted the jac/vf-docs branch August 20, 2026 07:39

docs: expand RequestOptions.vf() with vf_ wire-format rules by jacalata · Pull Request #1840 · tableau/server-client-python · GitHub

Uh oh!

docs: expand RequestOptions.vf() with vf_ wire-format rules - #1840

docs: expand RequestOptions.vf() with vf_ wire-format rules#1840
jacalata merged 10 commits into
developmentfrom
jac/vf-docs

jacalata commented Jul 29, 2026

Uh oh!

github-actions Bot commented Jul 29, 2026 •
edited
Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

jacalata commented Aug 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

docs: expand RequestOptions.vf() with vf_ wire-format rules by jacalata · Pull Request #1840 · tableau/server-client-python · GitHub

Uh oh!

docs: expand RequestOptions.vf() with vf_ wire-format rules - #1840

docs: expand RequestOptions.vf() with vf_ wire-format rules#1840jacalata merged 10 commits intodevelopmenttableau/server-client-python:developmentfrom jac/vf-docstableau/server-client-python:jac/vf-docsCopy head branch name to clipboard

Conversation

jacalata commented Jul 29, 2026

Summary

Why now

Test plan

Uh oh!

github-actions Bot commented Jul 29, 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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

jacalata commented Aug 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

docs: expand RequestOptions.vf() with vf_ wire-format rules#1840
jacalata merged 10 commits into
developmentfrom
jac/vf-docs

github-actions Bot commented Jul 29, 2026 •
edited
Loading