Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
py 368 lines 13.4 KB
Raw
1 """Parsing, formatting and once-per-process emission of the
2 ``Composio-Deprecated-Toolkits`` response header.
3
4 The end-to-end path through ``Composio(...)`` and the generated client lives in
5 ``tests/test_sdk_logging.py``; this file pins the pure helpers.
6 """
7
8 import threading
9 import typing as t
10 import warnings
11 from datetime import datetime, timezone
12
13 import httpx
14 import pytest
15
16 from composio import ComposioDeprecationWarning
17 from composio.utils import toolkit_deprecation as td
18 from composio.utils.toolkit_deprecation import (
19 DOCS_URL,
20 HEADER,
21 DeprecatedToolkit,
22 format_warnings,
23 install_hook,
24 parse_deprecated_toolkits_header,
25 response_hook,
26 warn_deprecated_toolkits,
27 )
28
29 FULL_ITEM = (
30 '"GMAIL";version="20250114_00";deprecated=@1779840000;'
31 'sunset=@1787788800;reason="lifecycle"'
32 )
33 BARE_ITEM = '"STRAVA";version="20240902_00"'
34 DOCS = "https://docs.example/deprecation"
35
36
37 def _utc(seconds: int) -> datetime:
38 return datetime.fromtimestamp(seconds, tz=timezone.utc)
39
40
41 def _entry(**overrides: t.Any) -> DeprecatedToolkit:
42 values: dict[str, t.Any] = {"slug": "GMAIL", "version": "20250114_00"}
43 values.update(overrides)
44 return DeprecatedToolkit(**values)
45
46
47 @pytest.fixture(autouse=True)
48 def _reset_warned() -> t.Iterator[None]:
49 td._reset_for_tests()
50 yield
51 td._reset_for_tests()
52
53
54 def _deprecations(caught: list[warnings.WarningMessage]) -> list[str]:
55 return [
56 str(w.message)
57 for w in caught
58 if issubclass(w.category, ComposioDeprecationWarning)
59 ]
60
61
62 class TestParse:
63 def test_full_item(self):
64 assert parse_deprecated_toolkits_header(FULL_ITEM) == [
65 DeprecatedToolkit(
66 slug="GMAIL",
67 version="20250114_00",
68 deprecated_at=_utc(1779840000),
69 sunset_at=_utc(1787788800),
70 reason="lifecycle",
71 )
72 ]
73
74 def test_dates_are_timezone_aware_utc(self):
75 (entry,) = parse_deprecated_toolkits_header(FULL_ITEM)
76 assert entry.deprecated_at is not None
77 assert entry.deprecated_at.tzinfo is timezone.utc
78 assert entry.deprecated_at.isoformat() == "2026-05-27T00:00:00+00:00"
79
80 def test_bare_item(self):
81 assert parse_deprecated_toolkits_header(BARE_ITEM) == [
82 DeprecatedToolkit(slug="STRAVA", version="20240902_00")
83 ]
84
85 def test_two_items(self):
86 entries = parse_deprecated_toolkits_header(f"{FULL_ITEM}, {BARE_ITEM}")
87 assert [e.key for e in entries] == ["GMAIL@20250114_00", "STRAVA@20240902_00"]
88
89 def test_escaped_quote_and_backslash_in_slug(self):
90 entries = parse_deprecated_toolkits_header(
91 '"ODD\\"SLUG\\\\";version="20250101_00", "GMAIL";version="20250114_00"'
92 )
93 assert [e.slug for e in entries] == ['ODD"SLUG\\', "GMAIL"]
94
95 def test_whitespace_variations(self):
96 entries = parse_deprecated_toolkits_header(
97 ' "GMAIL" ; version = "20250114_00" ; sunset = @1787788800 ,'
98 '"STRAVA";version="20240902_00" '
99 )
100 assert entries == [
101 DeprecatedToolkit(
102 slug="GMAIL", version="20250114_00", sunset_at=_utc(1787788800)
103 ),
104 DeprecatedToolkit(slug="STRAVA", version="20240902_00"),
105 ]
106
107 @pytest.mark.parametrize(
108 "value",
109 [
110 "",
111 " ",
112 "not a structured field",
113 "GMAIL;version=20250114_00",
114 '"GMAIL";version="unterminated',
115 ",,,;;;===",
116 '"GMAIL;version=;;@@',
117 ],
118 )
119 def test_garbage_yields_empty_list(self, value: str):
120 assert parse_deprecated_toolkits_header(value) == []
121
122 def test_unknown_parameters_are_ignored(self):
123 assert parse_deprecated_toolkits_header(
124 '"GMAIL";version="20250114_00";severity=3;flag;note="x"'
125 ) == [DeprecatedToolkit(slug="GMAIL", version="20250114_00")]
126
127 def test_empty_item_is_dropped_but_siblings_kept(self):
128 assert parse_deprecated_toolkits_header('"GMAIL";version="1", ;;') == [
129 DeprecatedToolkit(slug="GMAIL", version="1")
130 ]
131
132 def test_item_without_version_is_dropped_but_siblings_kept(self):
133 assert parse_deprecated_toolkits_header(
134 f'"GMAIL";deprecated=@1779840000, {BARE_ITEM}'
135 ) == [DeprecatedToolkit(slug="STRAVA", version="20240902_00")]
136
137 @pytest.mark.parametrize(
138 "value",
139 [
140 '"GMAIL";version=20250114_00',
141 '"GMAIL";version="1";deprecated="2026-05-27"',
142 '"GMAIL";version="1";reason=lifecycle',
143 '"GM\\nAIL";version="1"',
144 ],
145 )
146 def test_wrong_type_or_bad_escape_drops_item(self, value: str):
147 assert parse_deprecated_toolkits_header(value) == []
148
149
150 class TestFormat:
151 def test_full_message(self):
152 (line,) = format_warnings(parse_deprecated_toolkits_header(FULL_ITEM), DOCS)
153 assert line == (
154 "[Deprecation] Toolkit GMAIL version 20250114_00 was deprecated on "
155 "2026-05-27 (lifecycle) and will stop working on 2026-08-27. "
156 'Pin a newer version with toolkit_versions={"gmail": "<version>"} '
157 f"or COMPOSIO_TOOLKIT_VERSION_GMAIL. See {DOCS}."
158 )
159
160 def test_omits_reason_and_sunset_when_absent(self):
161 (line,) = format_warnings([_entry(slug="STRAVA", version="20240902_00")], DOCS)
162 assert line == (
163 "[Deprecation] Toolkit STRAVA version 20240902_00 was deprecated. "
164 'Pin a newer version with toolkit_versions={"strava": "<version>"} '
165 f"or COMPOSIO_TOOLKIT_VERSION_STRAVA. See {DOCS}."
166 )
167
168 def test_keeps_deprecation_date_when_only_sunset_missing(self):
169 (line,) = format_warnings(
170 [_entry(deprecated_at=_utc(1779840000), reason="security")], DOCS
171 )
172 assert "was deprecated on 2026-05-27 (security). Pin" in line
173 assert "stop working" not in line
174
175 def test_default_docs_url(self):
176 (line,) = format_warnings([_entry()])
177 assert line.endswith(f"See {DOCS_URL}.")
178 assert DOCS_URL == (
179 "https://docs.composio.dev/docs/tools-direct/toolkit-versioning"
180 "#deprecation-and-sunset"
181 )
182
183 def test_groups_six_versions_into_one_line_naming_five(self):
184 entries = [
185 _entry(
186 version=f"202501{suffix:02d}_00",
187 sunset_at=datetime(2026, 8, 20 + suffix, tzinfo=timezone.utc),
188 )
189 for suffix in range(1, 7)
190 ]
191 lines = format_warnings(entries, DOCS)
192 assert lines == [
193 "[Deprecation] Toolkit GMAIL versions 20250101_00, 20250102_00, "
194 "20250103_00, 20250104_00, 20250105_00 and 1 more are deprecated and "
195 "the earliest will stop working on 2026-08-21. "
196 'Pin a newer version with toolkit_versions={"gmail": "<version>"} '
197 f"or COMPOSIO_TOOLKIT_VERSION_GMAIL. See {DOCS}."
198 ]
199
200 def test_one_line_per_slug_grouped_case_insensitively(self):
201 lines = format_warnings(
202 [
203 _entry(slug="GMAIL", version="1"),
204 _entry(slug="STRAVA", version="1"),
205 _entry(slug="gmail", version="2"),
206 ],
207 DOCS,
208 )
209 assert len(lines) == 2
210 assert "Toolkit GMAIL versions 1, 2 are deprecated." in lines[0]
211 assert "Toolkit STRAVA version 1 was deprecated." in lines[1]
212
213 def test_no_entries_no_lines(self):
214 assert format_warnings([], DOCS) == []
215
216
217 class TestWarnOnce:
218 def test_warns_once_per_key_across_calls(self):
219 headers = httpx.Headers({HEADER: FULL_ITEM})
220 with warnings.catch_warnings(record=True) as caught:
221 warnings.simplefilter("always")
222 warn_deprecated_toolkits(headers)
223 warn_deprecated_toolkits(headers)
224 messages = _deprecations(caught)
225 assert len(messages) == 1
226 assert "GMAIL version 20250114_00" in messages[0]
227
228 def test_second_version_still_warns_after_first_was_deduped(self):
229 with warnings.catch_warnings(record=True) as caught:
230 warnings.simplefilter("always")
231 warn_deprecated_toolkits(
232 httpx.Headers({HEADER: f"{FULL_ITEM}, {BARE_ITEM}"})
233 )
234 warn_deprecated_toolkits(
235 httpx.Headers({HEADER: '"GMAIL";version="20250201_00"'})
236 )
237 assert len(_deprecations(caught)) == 3
238
239 def test_header_name_is_case_insensitive(self):
240 with warnings.catch_warnings(record=True) as caught:
241 warnings.simplefilter("always")
242 warn_deprecated_toolkits(
243 httpx.Headers({"Composio-Deprecated-Toolkits": BARE_ITEM})
244 )
245 assert len(_deprecations(caught)) == 1
246
247 def test_no_header_or_garbage_is_silent(self):
248 with warnings.catch_warnings(record=True) as caught:
249 warnings.simplefilter("always")
250 warn_deprecated_toolkits(httpx.Headers({}))
251 warn_deprecated_toolkits(httpx.Headers({HEADER: "%%% nope"}))
252 assert _deprecations(caught) == []
253
254 def test_reset_allows_warning_again(self):
255 headers = httpx.Headers({HEADER: BARE_ITEM})
256 with warnings.catch_warnings(record=True) as caught:
257 warnings.simplefilter("always")
258 warn_deprecated_toolkits(headers)
259 td._reset_for_tests()
260 warn_deprecated_toolkits(headers)
261 assert len(_deprecations(caught)) == 2
262
263 def test_stops_recording_after_1024_keys_without_evicting(self):
264 def send(version: int) -> None:
265 warn_deprecated_toolkits(
266 httpx.Headers({HEADER: f'"GMAIL";version="{version}"'})
267 )
268
269 with warnings.catch_warnings(record=True) as caught:
270 warnings.simplefilter("always")
271 for version in range(1, 1025):
272 send(version)
273 assert len(_deprecations(caught)) == 1024
274 send(1025)
275 assert len(_deprecations(caught)) == 1024
276 for version in range(1, 1025):
277 send(version)
278 assert len(_deprecations(caught)) == 1024
279 assert len(td._warned) == 1024
280
281 def test_two_threads_one_warning(self):
282 headers = httpx.Headers({HEADER: FULL_ITEM})
283 barrier = threading.Barrier(2)
284
285 def worker() -> None:
286 barrier.wait()
287 warn_deprecated_toolkits(headers)
288
289 with warnings.catch_warnings(record=True) as caught:
290 warnings.simplefilter("always")
291 threads = [threading.Thread(target=worker) for _ in range(2)]
292 for thread in threads:
293 thread.start()
294 for thread in threads:
295 thread.join()
296 assert len(_deprecations(caught)) == 1
297
298
299 class TestResponseHook:
300 def test_warns_from_response_headers(self):
301 response = httpx.Response(200, headers={HEADER: BARE_ITEM})
302 with warnings.catch_warnings(record=True) as caught:
303 warnings.simplefilter("always")
304 response_hook(response)
305 assert len(_deprecations(caught)) == 1
306
307 def test_oversized_header_is_ignored_and_body_kept(self):
308 oversized = '"GMAIL";version="1";reason="' + "x" * 2048 + '"'
309 response = httpx.Response(200, headers={HEADER: oversized}, json={})
310 with warnings.catch_warnings(record=True) as caught:
311 warnings.simplefilter("always")
312 response_hook(response)
313 assert response.json() == {}
314 assert _deprecations(caught) == []
315
316 def test_control_character_in_header_is_ignored_and_body_kept(self):
317 response = httpx.Response(
318 200, headers={HEADER: '"GMAIL";version="1";reason="\x1b[2J"'}, json={}
319 )
320 with warnings.catch_warnings(record=True) as caught:
321 warnings.simplefilter("always")
322 response_hook(response)
323 assert response.json() == {}
324 assert _deprecations(caught) == []
325
326 def test_never_raises(self, caplog: pytest.LogCaptureFixture):
327 class _Broken:
328 @property
329 def headers(self) -> httpx.Headers:
330 raise RuntimeError("headers unavailable")
331
332 with caplog.at_level("DEBUG", logger="composio.utils.toolkit_deprecation"):
333 response_hook(t.cast(httpx.Response, _Broken()))
334 assert "Failed to inspect the toolkit deprecation header" in caplog.text
335
336
337 class TestInstallHook:
338 def test_appends_once(self):
339 client = httpx.Client()
340 install_hook(client)
341 install_hook(client)
342 assert client.event_hooks["response"] == [response_hook]
343
344 def test_preserves_user_hooks(self):
345 def user_request(request: httpx.Request) -> None:
346 pass
347
348 def user_response(response: httpx.Response) -> None:
349 pass
350
351 client = httpx.Client(
352 event_hooks={"request": [user_request], "response": [user_response]}
353 )
354 install_hook(client)
355 assert client.event_hooks["request"] == [user_request]
356 assert client.event_hooks["response"] == [user_response, response_hook]
357
358 def test_installed_hook_fires_on_send(self):
359 def handler(request: httpx.Request) -> httpx.Response:
360 return httpx.Response(200, headers={HEADER: BARE_ITEM}, json={})
361
362 client = httpx.Client(transport=httpx.MockTransport(handler))
363 install_hook(client)
364 with warnings.catch_warnings(record=True) as caught:
365 warnings.simplefilter("always")
366 response = client.get("https://backend.invalid/api/v3/toolkits/strava")
367 assert response.json() == {}
368 assert len(_deprecations(caught)) == 1