GeezerVison

Adds a class-level docstring plus 15 method docstrings (14 public
methods + the private _get_virtual_database_connections is unchanged).
Content ported from api-ref.md's Virtual Connections section on
gh-pages so once the Sphinx pipeline in #1832 is live the generated
output will cover what the handwritten page does today.

Virtual Connections was the largest remaining chunk in the
needs_docstring bucket per the api-ref migration audit (14 of the 41
remaining public endpoint methods without docstrings, after the 15
Favorites methods in #1855).

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

- add_permissions and delete_permission grow proper type hints
  (VirtualConnectionItem, list[PermissionsRule], PermissionsRule) so the
  docstring claims and the signatures agree.
- Rename docstring/signature params to `virtual_connection` throughout
  the permissions methods; `item`, `resource`, `capability_item` were
  inconsistent with the rest of the class and with each other.
- Rename `delete_permission`'s second param from `capability_item` to
  `permission_rule` (which is what it actually is).
- Class docstring's REST API line now uses the same RST link style as
  every method's REST API line.
- update_tags docstring documents WHY it's not implemented: the REST
  API's virtual-connection response schema doesn't include tags, so
  there's no way to populate _initial_tags on the item and no diff
  basis for the mixin's update_tags. Tags exist server-side and are
  manipulated via the add-tags / delete-tag endpoints that add_tags /
  delete_tags already wrap.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

The `VirtualConnections` REST endpoints have carried tags on their
response bodies since Tableau Server 2026.2 / Cloud April 2026 (server
commit 2e687548e10, W-21424436, shipping in v262 with REST API 3.30+).
The public REST docs still don't reflect this (filed W-23806318);
`VirtualConnectionItem` previously didn't parse the <tags> element.

Changes:

- `VirtualConnectionItem.__init__` gains `tags: set[str]` and
  `_initial_tags: set[str]` matching every other taggable item.
- `VirtualConnectionItem.from_xml` parses <tags><tag label="..."/></tags>
  via the existing `TagItem.from_xml_element` helper. `_initial_tags`
  is a shallow copy of `tags` (strings are immutable so copy.copy is
  sufficient).
- `VirtualConnections.update_tags` drops the NotImplementedError
  override and delegates to `TaggingMixin.update_tags`. Bumped to
  `@api(version="3.30")` since older server responses don't carry
  <tags>, meaning `_initial_tags` would be empty and every locally-set
  tag would be treated as new -- silent no-op on removes.
- `VirtualConnections.get_by_id` stamps the id back onto the returned
  item. The `Get Virtual Connection` server response element omits the
  `id` attribute (separate server-side bug filed as W-23806343);
  downstream calls that need result.id (add_tags, delete_tags,
  update_tags) would fail with 'ID not found.' Client-side workaround
  until the server fix ships.
- Fixed pre-existing "Workbook item must be populated with permissions
  first" copy-paste error in the `permissions` property error message.
- Test fixture `virtual_connections_get.xml` grew a matching empty
  `<tags/>` element to reflect the current server response shape.
- `test_from_xml` and `test_virtual_connection_get_by_id` assert on the
  new tags/id shape.
- New `test_from_xml_populated_tags` covers the tag-parse path
  including no-back-propagation from `tags` to `_initial_tags`.
- New `test_update_tags_diff_round_trip` mocks the PUT/DELETE calls to
  verify the diff-based mixin end-to-end.
- `test_tagging.py` server version bumped from 3.28 to 3.30 so the
  parametrized virtual_connections update_tags case exercises the real
  code path.

Live-verified end-to-end against a Tableau server (build 2026-08-09,
REST API 3.30): fetch a VC, mutate .tags locally, call update_tags,
re-fetch, server state matches the local edit.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Copilot AI left a comment

… test docstring

- VirtualConnectionItem.__init__ now initializes _permissions so accessing
  .permissions before populate_permissions raises UnpopulatedPropertyError
  instead of AttributeError, matching peer models.
- get_by_id raises ValueError when the resolved id is falsy (empty string
  or unset item id), rather than silently building a URL that hits the
  list endpoint and returning the wrong object.
- test_update_tags_diff_round_trip docstring corrected: the PUT /tags
  call receives only the add-set {e}, not {a,c,e}, per TaggingMixin diff.
- get_by_id docstring notes the id is stamped from the request path due
  to a server-side response quirk.
- Drop stray internal ticket reference from a tag-parsing comment.

- test_update_tags_diff_round_trip now inspects the PUT XML body and
  asserts the add-set is exactly the diff; also asserts the two
  DELETEs target the correct tag URLs. Catches regressions in the
  add-set that call_count alone couldn't.
- Extract the "server omits id, stamp from request path" workaround
  into VirtualConnectionItem._stamp_id_from_request() so the docstring
  explaining W-23806343 lives with the class it mutates. Endpoint no
  longer reaches across encapsulation into result._id.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Copilot AI left a comment

Copilot AI left a comment