chore(toolbox-core): deprecate add_headers feature

packages/toolbox-core/README.md

@@ -300,24 +300,15 @@ that fresh credentials or header values can be used.
 
 ### Configuration
 
-You can configure these dynamic headers in two ways:
+You can configure these dynamic headers as seen below:
 
-1. **During Client Initialization**
-
-    ```python
-    from toolbox_core import ToolboxClient
-
-    async with ToolboxClient("toolbox-url", client_headers={"header1": header1_getter, "header2": header2_getter, ...}) as client:
-    ```
-
-1. **After Client Initialization**
-
-    ```python
-    from toolbox_core import ToolboxClient
+```python
+from toolbox_core import ToolboxClient
 
-    async with ToolboxClient("toolbox-url") as client:
-        client.add_headers({"header1": header1_getter, "header2": header2_getter, ...})
-    ```
+async with ToolboxClient("toolbox-url", client_headers={"header1": header1_getter, "header2": header2_getter, ...}) as client:
+    # Use client
+    pass
+```
 
 ### Authenticating with Google Cloud Servers
 

packages/toolbox-core/pyproject.toml

@@ -12,6 +12,7 @@ authors = [
 dependencies = [
     "pydantic>=2.7.0,<3.0.0",
     "aiohttp>=3.8.6,<4.0.0",
+    "deprecated>=1.2.15,<2.0.0",
 ]
 
 classifiers = [

packages/toolbox-core/requirements.txt

@@ -1,2 +1,3 @@
 aiohttp==3.12.12
 pydantic==2.11.5
+deprecated==1.2.15

packages/toolbox-core/src/toolbox_core/client.py

@@ -17,6 +17,7 @@
 from typing import Any, Awaitable, Callable, Mapping, Optional, Union
 
 from aiohttp import ClientSession
+from deprecated import deprecated
 
 from .protocol import ManifestSchema, ToolSchema
 from .tool import ToolboxTool
@@ -340,16 +341,17 @@ async def load_toolset(
 
         return tools
 
+    @deprecated(
+        "Use the `client_headers` parameter in the ToolboxClient constructor instead."
+    )
     def add_headers(
         self,
         headers: Mapping[str, Union[Callable[[], str], Callable[[], Awaitable[str]]]],
     ) -> None:
         """
         Add headers to be included in each request sent through this client.
-
         Args:
             headers: Headers to include in each request sent through this client.
-
         Raises:
             ValueError: If any of the headers are already registered in the client.
         """

packages/toolbox-core/src/toolbox_core/sync_client.py

@@ -17,6 +17,8 @@
 from threading import Thread
 from typing import Any, Awaitable, Callable, Mapping, Optional, Union
 
+from deprecated import deprecated
+
 from .client import ToolboxClient
 from .sync_tool import ToolboxSyncTool
 
@@ -153,6 +155,9 @@ def load_toolset(
             for async_tool in async_tools
         ]
 
+    @deprecated(
+        "Use the `client_headers` parameter in the ToolboxClient constructor instead."
+    )
     def add_headers(
         self,
         headers: Mapping[

packages/toolbox-core/tests/test_client.py

@@ -1443,23 +1443,41 @@ async def test_add_headers_success(
         )
 
         async with ToolboxClient(TEST_BASE_URL) as client:
-            client.add_headers(static_header)
+            with pytest.warns(
+                DeprecationWarning,
+                match="Use the `client_headers` parameter in the ToolboxClient constructor instead.",
+            ):
+                client.add_headers(static_header)
             assert client._ToolboxClient__client_headers == static_header
 
             tool = await client.load_tool(tool_name)
             result = await tool(param1="test")
             assert result == expected_payload["result"]
 
+    @pytest.mark.asyncio
+    async def test_add_headers_deprecation_warning(self):
+        """Tests that add_headers issues a DeprecationWarning."""
+        async with ToolboxClient(TEST_BASE_URL) as client:
+            with pytest.warns(
+                DeprecationWarning,
+                match="Use the `client_headers` parameter in the ToolboxClient constructor instead.",
+            ):
+                client.add_headers({"X-Deprecated-Test": "value"})
+
     @pytest.mark.asyncio
     async def test_add_headers_duplicate_fail(self, static_header):
         """Tests that adding a duplicate header via add_headers raises
         ValueError."""
         async with ToolboxClient(TEST_BASE_URL, client_headers=static_header) as client:
-            with pytest.raises(
-                ValueError,
-                match=f"Client header\\(s\\) `X-Static-Header` already registered",
+            with pytest.warns(
+                DeprecationWarning,
+                match="Use the `client_headers` parameter in the ToolboxClient constructor instead.",
             ):
-                await client.add_headers(static_header)
+                with pytest.raises(
+                    ValueError,
+                    match=f"Client header\\(s\\) `X-Static-Header` already registered",
+                ):
+                    client.add_headers(static_header)
 
     @pytest.mark.asyncio
     async def test_client_header_auth_token_conflict_fail(

packages/toolbox-core/tests/test_sync_client.py

@@ -383,7 +383,11 @@ def post_callback(url, **kwargs):
             f"{TEST_BASE_URL}/api/tool/{tool_name}/invoke", callback=post_callback
         )
 
-        sync_client.add_headers(headers_to_add)
+        with pytest.warns(
+            DeprecationWarning,
+            match="Use the `client_headers` parameter in the ToolboxClient constructor instead.",
+        ):
+            sync_client.add_headers(headers_to_add)
         tool = sync_client.load_tool(tool_name)
         result = tool(param1="test")
         assert result == expected_payload["result"]
@@ -409,11 +413,15 @@ def mock_add_headers(headers):
             with ToolboxSyncClient(
                 TEST_BASE_URL, client_headers=initial_headers
             ) as client:
-                with pytest.raises(
-                    ValueError,
-                    match="Client header\\(s\\) `X-Initial-Header` already registered",
+                with pytest.warns(
+                    DeprecationWarning,
+                    match="Use the `client_headers` parameter in the ToolboxClient constructor instead.",
                 ):
-                    client.add_headers({"X-Initial-Header": "another_value"})
+                    with pytest.raises(
+                        ValueError,
+                        match="Client header\\(s\\) `X-Initial-Header` already registered",
+                    ):
+                        client.add_headers({"X-Initial-Header": "another_value"})
 
 
 class TestSyncAuth: