feat: support extra_body in HttpOptions

PiperOrigin-RevId: 772616357

Author: qiaodev

google/genai/_api_client.py

@@ -741,6 +741,14 @@ def _build_request(
     else:
       base_url = patched_http_options.base_url
 
+    if (
+        hasattr(patched_http_options, 'extra_body')
+        and patched_http_options.extra_body
+    ):
+      _common.recursive_dict_update(
+          request_dict, patched_http_options.extra_body
+      )
+
     url = _join_url_path(
         base_url,
         versioned_path,

google/genai/_common.py

@@ -19,6 +19,7 @@
 import datetime
 import enum
 import functools
+import logging
 import typing
 from typing import Any, Callable, Optional, Union, get_origin, get_args
 import uuid
@@ -30,6 +31,7 @@
 from . import _api_client
 from . import errors
 
+logger = logging.getLogger('google_genai._common')
 
 def set_value_by_path(data: Optional[dict[Any, Any]], keys: list[str], value: Any) -> None:
   """Examples:
@@ -365,3 +367,74 @@ def wrapper(*args: Any, **kwargs: Any) -> Any:
     return wrapper
   return decorator
 
+
+def _normalize_key_for_matching(key_str: str) -> str:
+  """Normalizes a key for case-insensitive and snake/camel matching."""
+  return key_str.replace("_", "").lower()
+
+
+def align_key_case(target_dict: dict[str, Any], update_dict: dict[str, Any]) -> dict[str, Any]:
+  """Aligns the keys of update_dict to the case of target_dict keys.
+
+  Args:
+      target_dict: The dictionary with the target key casing.
+      update_dict: The dictionary whose keys need to be aligned.
+
+  Returns:
+      A new dictionary with keys aligned to target_dict's key casing.
+  """
+  aligned_update_dict: dict[str, Any] = {}
+  target_keys_map = {_normalize_key_for_matching(key): key for key in target_dict.keys()}
+
+  for key, value in update_dict.items():
+    normalized_update_key = _normalize_key_for_matching(key)
+
+    if normalized_update_key in target_keys_map:
+      aligned_key = target_keys_map[normalized_update_key]
+    else:
+      aligned_key = key
+
+    if isinstance(value, dict) and isinstance(target_dict.get(aligned_key), dict):
+      aligned_update_dict[aligned_key] = align_key_case(target_dict[aligned_key], value)
+    elif isinstance(value, list) and isinstance(target_dict.get(aligned_key), list):
+      # Direct assign as we treat update_dict list values as golden source.
+      aligned_update_dict[aligned_key] = value
+    else:
+      aligned_update_dict[aligned_key] = value
+  return aligned_update_dict
+
+
+def recursive_dict_update(
+    target_dict: dict[str, Any], update_dict: dict[str, Any]
+) -> None:
+  """Recursively updates a target dictionary with values from an update dictionary.
+
+  We don't enforce the updated dict values to have the same type with the
+  target_dict values except log warnings.
+  Users providing the update_dict should be responsible for constructing correct
+  data.
+
+  Args:
+      target_dict (dict): The dictionary to be updated.
+      update_dict (dict): The dictionary containing updates.
+  """
+  # Python SDK http request may change in camel case or snake case:
+  # If the field is directly set via setv() function, then it is camel case;
+  # otherwise it is snake case.
+  # Align the update_dict key case to target_dict to ensure correct dict update.
+  aligned_update_dict = align_key_case(target_dict, update_dict)
+  for key, value in aligned_update_dict.items():
+    if (
+        key in target_dict
+        and isinstance(target_dict[key], dict)
+        and isinstance(value, dict)
+    ):
+      recursive_dict_update(target_dict[key], value)
+    elif key in target_dict and not isinstance(target_dict[key], type(value)):
+      logger.warning(
+          f"Type mismatch for key '{key}'. Existing type:"
+          f' {type(target_dict[key])}, new type: {type(value)}. Overwriting.'
+      )
+      target_dict[key] = value
+    else:
+      target_dict[key] = value

google/genai/tests/client/test_http_options.py

@@ -29,6 +29,7 @@ def test_patch_http_options_with_copies_all_fields():
       timeout=10000,
       client_args={'http2': True},
       async_client_args={'http1': True},
+      extra_body={'key': 'value'},
   )
   options = types.HttpOptions()
   patched = _api_client._patch_http_options(options, patch_options)

google/genai/tests/common/test_common.py

@@ -18,6 +18,7 @@
 
 import warnings
 import inspect
+import logging
 import typing
 
 import pytest
@@ -60,4 +61,248 @@ def test_is_struct_type():
   assert not _common._is_struct_type(typing.List[typing.Dict[str, int]])
   assert not _common._is_struct_type(typing.List[typing.Dict[int, typing.Any]])
   assert not _common._is_struct_type(typing.List[str])
-  assert not _common._is_struct_type(typing.Dict[str, typing.Any])
+  assert not _common._is_struct_type(typing.Dict[str, typing.Any])
+
+
+
+@pytest.mark.parametrize(
+    "test_id, initial_target, update_dict, expected_target",
+    [
+        (
+            "simple_update",
+            {"a": 1, "b": 2},
+            {"b": 3, "c": 4},
+            {"a": 1, "b": 3, "c": 4},
+        ),
+        (
+            "nested_update",
+            {"a": 1, "b": {"x": 10, "y": 20}},
+            {"b": {"y": 30, "z": 40}, "c": 3},
+            {"a": 1, "b": {"x": 10, "y": 30, "z": 40}, "c": 3},
+        ),
+        (
+            "add_new_nested_dict",
+            {"a": 1},
+            {"b": {"x": 10, "y": 20}},
+            {"a": 1, "b": {"x": 10, "y": 20}},
+        ),
+        (
+            "empty_target",
+            {},
+            {"a": 1, "b": {"x": 10}},
+            {"a": 1, "b": {"x": 10}},
+        ),
+        (
+            "empty_update",
+            {"a": 1, "b": {"x": 10}},
+            {},
+            {"a": 1, "b": {"x": 10}},
+        ),
+        (
+            "overwrite_non_dict_with_dict",
+            {"a": 1, "b": 2},
+            {"b": {"x": 10}},
+            {"a": 1, "b": {"x": 10}},
+        ),
+        (
+            "overwrite_dict_with_non_dict",
+            {"a": 1, "b": {"x": 10}},
+            {"b": 2},
+            {"a": 1, "b": 2},
+        ),
+        (
+            "deeper_nesting",
+            {"a": {"b": {"c": 1, "d": 2}, "e": 3}},
+            {"a": {"b": {"d": 4, "f": 5}, "g": 6}, "h": 7},
+            {"a": {"b": {"c": 1, "d": 4, "f": 5}, "e": 3, "g": 6}, "h": 7},
+        ),
+        (
+            "different_value_types",
+            {"key1": "string_val", "key2": {"nested_int": 100}},
+            {"key1": 123, "key2": {"nested_list": [1, 2, 3]}, "key3": True},
+            {
+                "key1": 123,
+                "key2": {"nested_int": 100, "nested_list": [1, 2, 3]},
+                "key3": True,
+            },
+        ),
+        (
+            "update_with_empty_nested_dict", # Existing nested dict in target should not be cleared
+            {"a": {"b": 1}},
+            {"a": {}},
+            {"a": {"b": 1}},
+        ),
+        (
+            "target_with_empty_nested_dict",
+            {"a": {}},
+            {"a": {"b": 1}},
+            {"a": {"b": 1}},
+        ),
+        (
+            "key_case_alignment_check",
+            {"first_name": "John", "contact_info": {"email_address": "[email protected]"}},
+            {"firstName": "Jane", "contact_info": {"email_address": "[email protected]", "phone_number": "123"}},
+            {"first_name": "Jane", "contact_info": {"email_address": "[email protected]", "phone_number": "123"}},
+        )
+    ],
+)
+def test_recursive_dict_update(
+    test_id: str, initial_target: dict, update_dict: dict, expected_target: dict
+):
+  _common.recursive_dict_update(initial_target, update_dict)
+  assert initial_target == expected_target
+
+
+@pytest.mark.parametrize(
+    "test_id, initial_target, update_dict, expected_target, expect_warning, expected_log_message_part",
+    [
+        (
+            "type_match_int",
+            {"a": 1},
+            {"a": 2},
+            {"a": 2},
+            False,
+            "",
+        ),
+        (
+            "type_match_dict",
+            {"a": {"b": 1}},
+            {"a": {"b": 2}},
+            {"a": {"b": 2}},
+            False,
+            "",
+        ),
+        (
+            "type_mismatch_int_to_str",
+            {"a": 1},
+            {"a": "hello"},
+            {"a": "hello"},
+            True,
+            "Type mismatch for key 'a'. Existing type: <class 'int'>, new type: <class 'str'>. Overwriting.",
+        ),
+        (
+            "type_mismatch_dict_to_int",
+            {"a": {"b": 1}},
+            {"a": 100},
+            {"a": 100},
+            True,
+            "Type mismatch for key 'a'. Existing type: <class 'dict'>, new type: <class 'int'>. Overwriting.",
+        ),
+        (
+            "type_mismatch_int_to_dict",
+            {"a": 100},
+            {"a": {"b": 1}},
+            {"a": {"b": 1}},
+            True,
+            "Type mismatch for key 'a'. Existing type: <class 'int'>, new type: <class 'dict'>. Overwriting.",
+        ),
+        ("add_new_key", {"a": 1}, {"b": "new"}, {"a": 1, "b": "new"}, False, ""),
+    ],
+)
+def test_recursive_dict_update_type_warnings(test_id, initial_target, update_dict, expected_target, expect_warning, expected_log_message_part, caplog):
+    _common.recursive_dict_update(initial_target, update_dict)
+    assert initial_target == expected_target
+    if expect_warning:
+        assert len(caplog.records) == 1
+        assert caplog.records[0].levelname == "WARNING"
+        assert expected_log_message_part in caplog.records[0].message
+    else:
+        for record in caplog.records:
+            if record.levelname == "WARNING" and expected_log_message_part in record.message:
+                 pytest.fail(f"Unexpected warning logged for {test_id}: {record.message}")
+
+
+@pytest.mark.parametrize(
+    "test_id, target_dict, update_dict, expected_aligned_dict",
+    [
+        (
+            "simple_snake_to_camel",
+            {"first_name": "John", "last_name": "Doe"},
+            {"firstName": "Jane", "lastName": "Doe"},
+            {"first_name": "Jane", "last_name": "Doe"},
+        ),
+        (
+            "simple_camel_to_snake",
+            {"firstName": "John", "lastName": "Doe"},
+            {"first_name": "Jane", "last_name": "Doe"},
+            {"firstName": "Jane", "lastName": "Doe"},
+        ),
+        (
+            "nested_dict_alignment",
+            {"user_info": {"contact_details": {"email_address": ""}}},
+            {"userInfo": {"contactDetails": {"emailAddress": "[email protected]"}}},
+            {"user_info": {"contact_details": {"email_address": "[email protected]"}}},
+        ),
+        (
+            "list_of_dicts_alignment",
+            {"users_list": [{"user_id": 0, "user_name": ""}]},
+            {"usersList": [{"userId": 1, "userName": "Alice"}]},
+            {"users_list": [{"userId": 1, "userName": "Alice"}]},
+        ),
+        (
+            "list_of_dicts_alignment_mixed_case_in_update",
+            {"users_list": [{"user_id": 0, "user_name": ""}]},
+            {"usersList": [{"user_id": 1, "UserName": "Alice"}]},
+            {"users_list": [{"user_id": 1, "UserName": "Alice"}]},
+        ),
+        (
+            "list_of_dicts_different_lengths_update_longer",
+            {"items_data": [{"item_id": 0}]},
+            {"itemsData": [{"itemId": 1}, {"item_id": 2, "itemName": "Extra"}]},
+            {"items_data": [{"itemId": 1}, {"item_id": 2, "itemName": "Extra"}]},
+        ),
+        (
+            "list_of_dicts_different_lengths_target_longer",
+            {"items_data": [{"item_id": 0, "item_name": ""}, {"item_id": 1}]},
+            {"itemsData": [{"itemId": 10}]},
+            {"items_data": [{"itemId": 10}]},
+        ),
+        (
+            "no_matching_keys_preserves_update_case",
+            {"key_one": 1},
+            {"KEY_TWO": 2, "keyThree": 3},
+            {"KEY_TWO": 2, "keyThree": 3},
+        ),
+        (
+            "mixed_match_and_no_match",
+            {"first_name": "John", "age_years": 30},
+            {"firstName": "Jane", "AGE_YEARS": 28, "occupation_title": "Engineer"},
+            {"first_name": "Jane", "age_years": 28, "occupation_title": "Engineer"},
+        ),
+        (
+            "empty_target_dict",
+            {},
+            {"new_key": "new_value", "anotherKey": "anotherValue"},
+            {"new_key": "new_value", "anotherKey": "anotherValue"},
+        ),
+        (
+            "empty_update_dict",
+            {"existing_key": "value"},
+            {},
+            {},
+        ),
+        (
+            "target_has_non_dict_value_for_nested_key",
+            {"config_settings": 123},
+            {"configSettings": {"themeName": "dark"}},
+            {"config_settings": {"themeName": "dark"}}, # Overwrites as per recursive_dict_update logic
+        ),
+        (
+            "update_has_non_dict_value_for_nested_key",
+            {"config_settings": {"theme_name": "light"}},
+            {"configSettings": "dark_theme_string"},
+            {"config_settings": "dark_theme_string"}, # Overwrites
+        ),
+         (
+            "deeply_nested_with_lists",
+            {"level_one": {"list_items": [{"item_name": "", "item_value": 0}]}},
+            {"levelOne": {"listItems": [{"itemName": "Test", "itemValue": 100}, {"itemName": "Test2", "itemValue": 200}]}},
+            {"level_one": {"list_items": [{"itemName": "Test", "itemValue": 100}, {"itemName": "Test2", "itemValue": 200}]}},
+        ),
+    ],
+)
+def test_align_key_case(
+    test_id: str, target_dict: dict, update_dict: dict, expected_aligned_dict: dict
+):
+  aligned_dict = _common.align_key_case(target_dict, update_dict)
+  assert aligned_dict == expected_aligned_dict, f"Test failed for: {test_id}"