refactor(types): rename transform_in_post to transform_in_body and improve docs

amimas · amimas · commit ba5b539003f0 · 2026-03-21T15:24:45.000-04:00
The `transform_in_post` attribute controls whether data transformation
(via `get_for_api`) occurs for request bodies. Since this applies to
PUT and PATCH requests as well as POST, `transform_in_body` is a more
accurate name.

This change also improves code documentation to clarify the data
transformation flow between `types.py` and `utils.py`.
diff --git a/gitlab/types.py b/gitlab/types.py
@@ -37,6 +37,13 @@ def validate_attrs(
 
 
 class GitlabAttribute:
+    # Used in utils._transform_types() to decide if we should call get_for_api()
+    # on the attribute when transform_data is False (e.g. for POST/PUT/PATCH).
+    #
+    # This allows us to force transformation of data even when sending JSON bodies,
+    # which is useful for types like CommaSeparatedStringAttribute.
+    transform_in_body = False
+
     def __init__(self, value: Any = None) -> None:
         self._value = value
 
@@ -91,9 +98,10 @@ def get_for_api(self, *, key: str) -> tuple[str, Any]:
 
 
 class CommaSeparatedListAttribute(_ListArrayAttribute):
-    """For values which are sent to the server as a Comma Separated Values
-    (CSV) string.  We allow them to be specified as a list and we convert it
-    into a CSV"""
+    """
+    For values which are sent to the server as a Comma Separated Values (CSV) string
+    in query parameters (GET), but as a list/array in JSON bodies (POST/PUT).
+    """
 
 
 class CommaSeparatedStringAttribute(_ListArrayAttribute):
@@ -103,7 +111,10 @@ class CommaSeparatedStringAttribute(_ListArrayAttribute):
     to a string even in JSON bodies (POST/PUT requests).
     """
 
-    transform_in_post = True
+    # Used in utils._transform_types() to ensure the value is converted to a string
+    # via get_for_api() even when transform_data is False (e.g. for POST/PUT/PATCH).
+    # This is needed because some APIs require a CSV string instead of a JSON array.
+    transform_in_body = True
 
 
 class LowercaseStringAttribute(GitlabAttribute):
diff --git a/gitlab/utils.py b/gitlab/utils.py
@@ -198,9 +198,15 @@ def _transform_types(
             files[attr_name] = (key, data.pop(attr_name))
             continue
 
-        if not transform_data and not getattr(
-            gitlab_attribute, "transform_in_post", False
-        ):
+        # If transform_data is False, it means we are preparing data for a JSON body
+        # (POST/PUT/PATCH). In this case, we normally skip transformation because
+        # most types (like ArrayAttribute) only need transformation for query
+        # parameters (GET).
+        #
+        # However, some types (like CommaSeparatedStringAttribute) need to be
+        # transformed even in JSON bodies (e.g. converting a list to a CSV string).
+        # The 'transform_in_body' flag on the attribute class controls this behavior.
+        if not transform_data and not gitlab_attribute.transform_in_body:
             continue
 
         if isinstance(gitlab_attribute, types.GitlabAttribute):
diff --git a/tests/unit/test_types.py b/tests/unit/test_types.py
@@ -157,5 +157,5 @@ def test_comma_separated_string_attribute() -> None:
     attr.set_from_cli("")
     assert attr.get() == []
 
-    # Verify transform_in_post is True
-    assert types.CommaSeparatedStringAttribute.transform_in_post is True
+    # Verify transform_in_body is True
+    assert types.CommaSeparatedStringAttribute.transform_in_body is True
