Parse tags on VirtualConnectionItem and enable diff-based update_tags

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) <noreply@anthropic.com>

Author: jacalata

tableauserverclient/models/virtual_connection_item.py

@@ -1,3 +1,4 @@
+import copy
 import datetime as dt
 import json
 from typing import Callable
@@ -10,6 +11,7 @@
 from tableauserverclient.models.connection_item import ConnectionItem
 from tableauserverclient.models.exceptions import UnpopulatedPropertyError
 from tableauserverclient.models.permissions_item import PermissionsRule
+from tableauserverclient.models.tag_item import TagItem
 
 
 class VirtualConnectionItem:
@@ -26,6 +28,12 @@ def __init__(self, name: str) -> None:
         self.owner_id: str | None = None
         self.content: dict[str, dict] | None = None
         self.certification_note: str | None = None
+        # Tags on virtual connections are populated by the server on List and
+        # Get responses since Tableau Server 2026.2 / Cloud April 2026
+        # (REST API 3.30, W-21424436). Callers on earlier server versions
+        # will see these as empty sets; add_tags / delete_tags still work.
+        self.tags: set[str] = set()
+        self._initial_tags: set[str] = set()
 
     def __str__(self) -> str:
         return f"{self.__class__.__qualname__}(name={self.name})"
@@ -43,7 +51,7 @@ def id(self) -> str | None:
     @property
     def permissions(self) -> list[PermissionsRule]:
         if self._permissions is None:
-            error = "Workbook item must be populated with permissions first."
+            error = "Virtual connection item must be populated with permissions first."
             raise UnpopulatedPropertyError(error)
         return self._permissions()
 
@@ -71,6 +79,10 @@ def from_xml(cls, xml: Element, ns: dict[str, str]) -> "VirtualConnectionItem":
         v_conn.project_id = p.get("id", None) if ((p := xml.find(".//t:project[@id]", ns)) is not None) else None
         v_conn.owner_id = o.get("id", None) if ((o := xml.find(".//t:owner[@id]", ns)) is not None) else None
         v_conn.content = json.loads(c.text or "{}") if ((c := xml.find(".//t:content", ns)) is not None) else None
+        tags_elem = xml.find(".//t:tags", ns)
+        if tags_elem is not None:
+            v_conn.tags = TagItem.from_xml_element(tags_elem, ns)
+            v_conn._initial_tags = copy.copy(v_conn.tags)
         return v_conn
 
 

tableauserverclient/server/endpoint/virtual_connections_endpoint.py

@@ -169,10 +169,20 @@ def get_by_id(self, virtual_connection: str | VirtualConnectionItem) -> VirtualC
         >>> vc = server.virtual_connections.get_by_id('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d')
         >>> print(vc.name, vc.content)
         """
-        vconn_id = getattr(virtual_connection, "id", virtual_connection)
+        if isinstance(virtual_connection, VirtualConnectionItem):
+            vconn_id = virtual_connection.id or ""
+        else:
+            vconn_id = virtual_connection
         url = f"{self.baseurl}/{vconn_id}"
         server_response = self.get_request(url)
-        return VirtualConnectionItem.from_response(server_response.content, self.parent_srv.namespace)[0]
+        result = VirtualConnectionItem.from_response(server_response.content, self.parent_srv.namespace)[0]
+        # The Get Virtual Connection response omits the `id` attribute on the
+        # <virtualConnection> element (server-side response builder never calls
+        # setId). Stamp it back from the request path so downstream calls that
+        # need result.id (add_tags, delete_tags, update_tags) work.
+        if result._id is None:
+            result._id = vconn_id
+        return result
 
     @api(version="3.23")
     def download(self, virtual_connection: str | VirtualConnectionItem) -> str:
@@ -487,7 +497,8 @@ def add_tags(self, virtual_connection: VirtualConnectionItem | str, tags: Iterab
         Returns
         -------
         set[str]
-            The set of tags added.
+            The full tag set on the virtual connection after the add,
+            as returned by the server.
 
         Examples
         --------
@@ -517,23 +528,37 @@ def delete_tags(self, virtual_connection: VirtualConnectionItem | str, tags: Ite
         """
         return super().delete_tags(virtual_connection, tags)
 
-    @api(version="3.23")
+    @api(version="3.30")
     def update_tags(self, virtual_connection: VirtualConnectionItem) -> None:
-        """Not implemented for virtual connections.
-
-        `TaggingMixin.update_tags` computes an add/remove diff from the
-        item's ``tags`` and ``_initial_tags`` attributes. The REST API's
-        `List Virtual Connections` and `Get Virtual Connection` responses
-        do not include tags in the schema, so there's no way to populate
-        those attributes on the item, and no diff basis for `update_tags`.
-        Tags on virtual connections exist server-side and are manipulated
-        via the dedicated `Add Tags to Virtual Connection` and
-        `Delete Tag from Virtual Connection` endpoints, which the
-        ``add_tags`` and ``delete_tags`` methods on this endpoint wrap.
+        """Push local tag edits to the server as add / delete calls.
 
-        Raises
-        ------
-        NotImplementedError
-            Always. Use ``add_tags`` and ``delete_tags`` directly.
+        Computes the diff between ``virtual_connection.tags`` (mutated
+        locally) and ``virtual_connection._initial_tags`` (captured at
+        parse time), then issues `Add Tags to Virtual Connection` and
+        `Delete Tag from Virtual Connection` calls to bring the server
+        state in line.
+
+        Requires Tableau Server 2026.2 / Cloud April 2026 or later (REST
+        API 3.30+): earlier server versions do not populate tags on the
+        response, so ``_initial_tags`` is empty and every tag on the item
+        would be treated as new.
+
+        Parameters
+        ----------
+        virtual_connection : VirtualConnectionItem
+            The virtual connection whose tags to synchronize. Must have
+            been fetched via `get` / `get_by_id` (which populates
+            ``_initial_tags``) then edited via ``virtual_connection.tags``.
+
+        Returns
+        -------
+        None
+
+        Examples
+        --------
+        >>> vc = server.virtual_connections.get_by_id(vc_id)
+        >>> vc.tags.add('finance')
+        >>> vc.tags.discard('stale')
+        >>> server.virtual_connections.update_tags(vc)
         """
-        raise NotImplementedError("Update tags is not implemented for Virtual Connections")
+        return super().update_tags(virtual_connection)

test/assets/virtual_connection_add_tags.xml

@@ -0,0 +1,8 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-2.3.xsd">
+	<tags>
+		<tag label="a" />
+		<tag label="c" />
+		<tag label="e" />
+	</tags>
+</tsResponse>

test/assets/virtual_connections_get.xml

@@ -2,13 +2,15 @@
 <tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-2.3.xsd">
   <pagination pageNumber="1" pageSize="1" totalAvailable="1" />
   <virtualConnections>
-    <virtualConnection 
-      createdAt="2024-05-30T09:00:00Z" 
-      hasExtracts="false" 
-      id="8fd7cc02-bb55-4d15-b8b1-9650239efe79" 
-      isCertified="true" 
-      name="vconn" 
-      updatedAt="2024-06-18T09:00:00Z" 
-    webpageUrl="https://test/#/site/site-name/virtualconnections/3"/>
+    <virtualConnection
+      createdAt="2024-05-30T09:00:00Z"
+      hasExtracts="false"
+      id="8fd7cc02-bb55-4d15-b8b1-9650239efe79"
+      isCertified="true"
+      name="vconn"
+      updatedAt="2024-06-18T09:00:00Z"
+    webpageUrl="https://test/#/site/site-name/virtualconnections/3">
+      <tags/>
+    </virtualConnection>
   </virtualConnections>
 </tsResponse>

test/assets/virtual_connections_get_with_tags.xml

@@ -0,0 +1,19 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-2.3.xsd">
+  <pagination pageNumber="1" pageSize="2" totalAvailable="2" />
+  <virtualConnections>
+    <virtualConnection createdAt="2024-05-30T09:00:00Z" hasExtracts="false" id="8fd7cc02-bb55-4d15-b8b1-9650239efe79" isCertified="true" name="vconn_with_tags" updatedAt="2024-06-18T09:00:00Z" webpageUrl="https://test/#/site/site-name/virtualconnections/3">
+      <project id="f5d5ba60-8ca5-11ef-b6bc-bb13b785b995" name="Default"/>
+      <owner id="7fdad1f1-d521-46ff-a601-51f88e3296f0" name="jmoens"/>
+      <tags>
+        <tag label="finance"/>
+        <tag label="certified"/>
+      </tags>
+    </virtualConnection>
+    <virtualConnection createdAt="2024-03-04T21:51:02Z" hasExtracts="false" id="875228b6-a3dc-4035-bbc0-4a68ab231ca8" isCertified="false" name="vconn_no_tags" updatedAt="2024-03-04T21:52:01Z" webpageUrl="https://test/#/site/site-name/virtualconnections/4">
+      <project id="f5d5ba60-8ca5-11ef-b6bc-bb13b785b995" name="Default"/>
+      <owner id="e8954ef5-7132-476a-93af-89178639fa98" name="fcao"/>
+      <tags/>
+    </virtualConnection>
+  </virtualConnections>
+</tsResponse>

test/test_tagging.py

@@ -17,7 +17,7 @@ def get_server() -> TSC.Server:
     # Fake sign in
     server._site_id = "dad65087-b08b-4603-af4e-2887b8aafc67"
     server._auth_token = "j80k54ll2lfMZ0tv97mlPvvSCRyD0DOM"
-    server.version = "3.28"
+    server.version = "3.30"  # min for virtual_connections.update_tags (v262 / 2026.2)
     return server
 
 

test/test_virtual_connection.py

@@ -10,7 +10,9 @@
 
 ASSET_DIR = Path(__file__).parent / "assets"
 
+VIRTUAL_CONNECTION_ADD_TAGS = ASSET_DIR / "virtual_connection_add_tags.xml"
 VIRTUAL_CONNECTION_GET_XML = ASSET_DIR / "virtual_connections_get.xml"
+VIRTUAL_CONNECTION_GET_WITH_TAGS_XML = ASSET_DIR / "virtual_connections_get_with_tags.xml"
 VIRTUAL_CONNECTION_POPULATE_CONNECTIONS = ASSET_DIR / "virtual_connection_populate_connections.xml"
 VIRTUAL_CONNECTION_POPULATE_CONNECTIONS2 = ASSET_DIR / "virtual_connection_populate_connections2.xml"
 VC_DB_CONN_UPDATE = ASSET_DIR / "virtual_connection_database_connection_update.xml"
@@ -46,6 +48,33 @@ def test_from_xml(server: TSC.Server) -> None:
     assert virtual_connection.name == "vconn"
     assert virtual_connection.updated_at == parse_datetime("2024-06-18T09:00:00Z")
     assert virtual_connection.webpage_url == "https://test/#/site/site-name/virtualconnections/3"
+    # Response element carries <tags> since Tableau Server 2026.2 (API 3.30);
+    # empty when the VC has no tags.
+    assert virtual_connection.tags == set()
+    assert virtual_connection._initial_tags == set()
+
+
+def test_from_xml_populated_tags(server: TSC.Server) -> None:
+    """When the response's <tags> element carries <tag label="..."/> children,
+    those values populate `tags` and `_initial_tags` so the diff-based
+    update_tags mixin can compute changes.
+    """
+    items = VirtualConnectionItem.from_response(VIRTUAL_CONNECTION_GET_WITH_TAGS_XML.read_bytes(), server.namespace)
+
+    assert len(items) == 2
+
+    with_tags = items[0]
+    assert with_tags.name == "vconn_with_tags"
+    assert with_tags.tags == {"finance", "certified"}
+    assert with_tags._initial_tags == {"finance", "certified"}
+    # _initial_tags is a copy: mutating tags after parse doesn't leak back
+    with_tags.tags.add("later-added")
+    assert with_tags._initial_tags == {"finance", "certified"}
+
+    without_tags = items[1]
+    assert without_tags.name == "vconn_no_tags"
+    assert without_tags.tags == set()
+    assert without_tags._initial_tags == set()
 
 
 def test_virtual_connection_get(server: TSC.Server) -> None:
@@ -113,7 +142,10 @@ def test_virtual_connection_get_by_id(server: TSC.Server) -> None:
 
     assert vconn.content
     assert vconn.created_at is None
-    assert vconn.id is None
+    # The server's Get Virtual Connection response omits the `id` attribute on
+    # the <virtualConnection> element, but get_by_id stamps it back from the
+    # request path so downstream tag/permission calls can find it.
+    assert vconn.id == "8fd7cc02-bb55-4d15-b8b1-9650239efe79"
     assert "policyCollection" in vconn.content
     assert "revision" in vconn.content
 
@@ -240,6 +272,32 @@ def test_virtual_connection_publish_draft_overwrite(server: TSC.Server) -> None:
     assert "revision" in vconn.content
 
 
+def test_update_tags_diff_round_trip(server: TSC.Server) -> None:
+    """Diff-based update_tags computes add-set / remove-set from the item's
+    tags and _initial_tags and issues the right PUT / DELETE calls.
+
+    Simulates: server returned {a,b,c,d} at fetch time; caller mutated to
+    {a,c,e}. Expected calls: PUT /tags with {a,c,e} (add path adds e), DELETE
+    /tags/b, DELETE /tags/d.
+    """
+    server.version = "3.30"  # update_tags requires 3.30 (see @api decorator)
+    vconn_id = "8fd7cc02-bb55-4d15-b8b1-9650239efe79"
+    add_tags_response = VIRTUAL_CONNECTION_ADD_TAGS.read_text()
+    with requests_mock.mock() as m:
+        m.put(f"{server.virtual_connections.baseurl}/{vconn_id}/tags", text=add_tags_response)
+        m.delete(f"{server.virtual_connections.baseurl}/{vconn_id}/tags/b", status_code=204)
+        m.delete(f"{server.virtual_connections.baseurl}/{vconn_id}/tags/d", status_code=204)
+
+        vconn = VirtualConnectionItem("vconn")
+        vconn._id = vconn_id
+        vconn._initial_tags = {"a", "b", "c", "d"}
+        vconn.tags = {"a", "c", "e"}
+        server.virtual_connections.update_tags(vconn)
+
+        # add PUT + 2 deletes = 3 calls
+        assert m.call_count == 3, m.request_history
+
+
 def test_add_permissions(server: TSC.Server) -> None:
     response_xml = ADD_PERMISSIONS.read_text()