Skip to content

Commit e7b6c3f

Browse files
committed
docs: clarify vf() percent-encoding vs escaping (Copilot review)
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.
1 parent 6b7a41f commit e7b6c3f

1 file changed

Lines changed: 15 additions & 10 deletions

File tree

tableauserverclient/server/request_options.py

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -353,8 +353,10 @@ def vf(self, name: str, value: str) -> Self:
353353
"""Apply a filter based on a column within the view.
354354
355355
Serialized to the REST API as ``vf_<name>=<value>``. The rules below
356-
describe how the server interprets the wire value; ``vf()`` itself
357-
does not transform your input.
356+
describe how the server interprets the wire value. ``vf()`` itself
357+
does not apply any Tableau-specific escaping or semantic transforms
358+
to your value; it only percent-encodes the value for HTTP transport,
359+
which the server decodes back before applying the rules below.
358360
359361
Value syntax
360362
------------
@@ -365,17 +367,20 @@ def vf(self, name: str, value: str) -> Self:
365367
matches rows where the column is ``East`` OR ``West``.
366368
- **Escaping** applies to two characters only, comma and backslash;
367369
all other characters (``&``, ``=``, ``/``, ``#``, ``%``, ``+``,
368-
quotes, brackets, etc.) pass through untouched -- ``vf()`` URL-
369-
encodes them for transport and the server treats them as literal
370-
data. To match a value containing a literal comma, escape it:
370+
quotes, brackets, etc.) pass through untouched and the server
371+
treats them as literal data. Percent-encoding is transport only:
372+
``%2C`` and ``%5C`` reach the server as ``,`` and ``\\`` and are
373+
then processed like any other comma or backslash -- so URL-
374+
encoding does NOT escape a literal comma or backslash. To match a
375+
value containing a literal comma, escape it:
371376
``"Rock\\, Paper\\, Scissors"`` matches ``Rock, Paper, Scissors``
372377
(without escaping, the comma starts an OR-list). To match a
373378
literal backslash, double it: ``"C:\\\\temp\\\\file"`` matches
374-
``C:\\temp\\file``. URL-encoding (``%2C``, ``%5C``) does NOT
375-
escape either character.
376-
- **Empty value** (``vf_<name>=``) overrides any workbook-embedded
377-
filter on that column, effectively widening it to all values.
378-
This is undocumented but stable behavior that some users rely on.
379+
``C:\\temp\\file``.
380+
- **Empty value** (``vf_<name>=``) is observed to override any
381+
workbook-embedded filter on that column, effectively widening it
382+
to all values. Not officially documented; behavior may change
383+
without notice.
379384
- **Wildcards** (``*``) are NOT supported by the REST view-filter
380385
layer. Wildcard matching is a viz-configured behavior on filter
381386
controls inside a workbook; use ``.parameter()`` and design the

0 commit comments

Comments
 (0)