GeezerVison

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) <[email protected]>

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) <[email protected]>

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) <[email protected]>

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) <[email protected]>

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) <[email protected]>

Copilot AI left a comment

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.

Copilot AI left a comment

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) <[email protected]>

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) <[email protected]>

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.