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

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.

* docs: cite wildcard-filter server version requirement

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>

* docs: ASCII em dashes, drop dead docs link, soften AD claim

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.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jacalata

tableauserverclient/models/user_item.py

@@ -33,7 +33,16 @@ class UserItem:
     Parameters
     ----------
     name: str
-        The name of the user.
+        The username used to authenticate the user, NOT the person's display
+        name (that is ``fullname``). The required format depends on the site's
+        authentication scheme:
+
+        - Tableau Cloud: the sign-in email address (e.g. ``user@example.com``).
+        - Local authentication (on-prem Tableau Server): any unique username
+          for the site (e.g. ``jsmith``).
+        - Active Directory: the fully-qualified AD username, typically
+          ``SAMAccountName@FullyQualifiedDomain`` (e.g.
+          ``jsmith@corp.example.com``), or the User Principal Name (UPN).
 
     site_role: str
         The role of the user on the site.

tableauserverclient/server/endpoint/projects_endpoint.py

@@ -293,6 +293,32 @@ def update_permissions(self, item: ProjectItem, rules: list[PermissionsRule]) ->
         -------
         list[PermissionsRule]
             Returns the updated list of permissions rules.
+
+        Examples
+        --------
+        Assign a group as Project Leader on a project. ``ProjectLeader`` is
+        the capability that grants the group the ability to publish and
+        manage content in the project as if they were the project owner.
+
+        >>> import tableauserverclient as TSC
+        >>> server = TSC.Server('https://SERVERURL')
+        >>> # Login to the server
+
+        >>> project = next(p for p in TSC.Pager(server.projects) if p.name == 'Marketing')
+        >>> group = next(g for g in TSC.Pager(server.groups) if g.name == 'Marketing Leads')
+
+        >>> rule = TSC.PermissionsRule(
+        ...     grantee=group,
+        ...     capabilities={
+        ...         TSC.Permission.Capability.ProjectLeader: TSC.Permission.Mode.Allow,
+        ...     },
+        ... )
+        >>> server.projects.update_permissions(project, [rule])
+
+        Note: ``update_permissions`` REPLACES the full permissions list on the
+        project. Any existing rules not included in the call will be removed.
+        To preserve existing rules, call ``populate_permissions(project)``
+        first, then modify ``project.permissions`` and pass the full list.
         """
 
         return self._permissions.update(item, rules)

tableauserverclient/server/endpoint/users_endpoint.py

@@ -254,11 +254,26 @@ def add(self, user_item: UserItem) -> UserItem:
         To add a new user to the site you need to first create a new user_item
         (from UserItem class). When you create a new user, you specify the name
         of the user and their site role. For Tableau Cloud, you also specify
-        the auth_setting attribute in your request. When you add user to
-        Tableau Cloud, the name of the user must be the email address that is
-        used to sign in to Tableau Cloud. After you add a user, Tableau Cloud
-        sends the user an email invitation. The user can click the link in the
-        invitation to sign in and update their full name and password.
+        the auth_setting attribute in your request. After you add a user, Tableau
+        Cloud sends the user an email invitation. The user can click the link in
+        the invitation to sign in and update their full name and password.
+
+        The value of ``user_item.name`` is the username the server uses to
+        authenticate the user, NOT the person's display name. Its required
+        format depends on the site's authentication scheme:
+
+        - Tableau Cloud: the user's email address (e.g. ``user@example.com``),
+          which is also what they sign in with.
+        - Local authentication (on-prem Tableau Server): any username unique to
+          the site (e.g. ``jsmith``).
+        - Active Directory: the fully-qualified AD username, either
+          ``SAMAccountName@FullyQualifiedDomain`` (e.g.
+          ``jsmith@corp.example.com``) or the User Principal Name (UPN) if AD
+          is configured to use UPNs. A bare ``SAMAccountName`` may not
+          resolve depending on how AD is configured.
+
+        Set the person's display name via ``user_item.fullname``; it is a
+        separate attribute.
 
         Parameters
         ----------
@@ -333,9 +348,16 @@ def add(self, user_item: UserItem) -> UserItem:
         >>> server = TSC.Server('https://SERVERURL')
         >>> # Login to the server
 
-        >>> new_user = TSC.UserItem(name='new_user', site_role=TSC.UserItem.Role.Unlicensed)
+        >>> # Tableau Cloud: name must be the sign-in email address
+        >>> new_user = TSC.UserItem(name='jsmith@example.com', site_role=TSC.UserItem.Role.Explorer)
+        >>> new_user.auth_setting = TSC.UserItem.Auth.TableauIDWithMFA
+        >>> new_user.fullname = 'Jane Smith'
         >>> new_user = server.users.add(new_user)
 
+        >>> # Active Directory-backed Tableau Server: name is SAMAccountName@Domain
+        >>> ad_user = TSC.UserItem(name='jsmith@corp.example.com', site_role=TSC.UserItem.Role.Viewer)
+        >>> ad_user = server.users.add(ad_user)
+
         """
         url = self.baseurl
         logger.info(f"Add user {user_item.name}")

tableauserverclient/server/filter.py

@@ -5,6 +5,49 @@
 
 
 class Filter:
+    """Represents a single Tableau REST API filter clause.
+
+    A `Filter` is one entry in a `?filter=` query parameter and serializes as
+    ``<field>:<operator>:<value>``. Use one filter per attribute, and pass
+    multiple filters via `RequestOptions.filter.add(...)` if you need to AND
+    conditions.
+
+    Special characters in filter values
+    ----------------------------------
+    The REST API's filter grammar treats several characters as delimiters. The
+    server does NOT support escaping them, so a value containing any of these
+    characters cannot be matched exactly with the `Equals` operator:
+
+    - ``,`` -- separates values in an ``in`` list.
+    - ``&`` -- separates filter clauses.
+    - ``:`` -- separates field/operator/value.
+    - ``[`` and ``]`` -- bracket an ``in`` value list.
+
+    Workaround for names containing these characters: use the ``Equals``
+    operator with an asterisk substituted for the special character. Asterisk
+    behaves as a wildcard (starts-with, ends-with, and contains matching are
+    supported by the server; see the Tableau REST API docs for "Filtering
+    and Sorting"), so for example filtering a workbook named
+    ``T(L-F,SZ&V-MY) - PC`` can be found via ``name="T(L-F*SZ*V-MY) - PC"``.
+    Wildcard filtering requires Tableau Cloud May 2023 or Tableau Server
+    2022.1.14 or later. Post-filter the result client-side to disambiguate
+    if multiple names could match.
+
+    Parameters
+    ----------
+    field : str
+        The field to filter on (e.g. ``RequestOptions.Field.Name``).
+
+    operator : str
+        The operator to apply (e.g. ``RequestOptions.Operator.Equals``,
+        ``In``, ``GreaterThan``).
+
+    value : str | int | bool | datetime | list
+        The value to compare against. Lists require operator ``In``. Datetimes
+        must be timezone-aware and serialize as ISO-8601 UTC. Bools serialize
+        as lowercase ``true``/``false``.
+    """
+
     def __init__(self, field, operator, value):
         self.field = field
         self.operator = operator

tableauserverclient/server/query.py

@@ -186,6 +186,19 @@ def page_size(self: Self) -> int:
         return self._pagination_item.page_size or self.request_options.pagesize
 
     def filter(self: Self, *invalid, page_size: int | None = None, **kwargs) -> Self:
+        """Add filter clauses to the queryset.
+
+        Each keyword argument becomes one filter. Shorthand suffixes select
+        the operator (e.g. ``name__gt="A"`` -> operator ``GreaterThan``); a
+        bare keyword uses ``Equals``. See
+        https://tableau.github.io/server-client-python/docs/filter-sort for
+        the supported suffixes.
+
+        Special-character caveat: values containing ``,``, ``&``, ``:``, ``[``
+        or ``]`` cannot be matched exactly with ``Equals``; the REST filter
+        grammar treats them as delimiters and the server does not support
+        escaping. See ``Filter`` for details and the wildcard workaround.
+        """
         if invalid:
             raise RuntimeError("Only accepts keyword arguments.")
         for kwarg_key, value in kwargs.items():