@devries-cameron20 / composio-1 / commits / 0658179fd
Fork 0

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

feat(python): warn once per deprecated toolkit version reported by the API (PLEN-4352)

Install an httpx response event hook on the generated client's underlying httpx.Client so every response is checked for the Composio-Deprecated-Toolkits header (an RFC 9651 structured-field list). Entries are parsed with a hand-rolled parser for the emitted subset; each UPPER(slug)@version is warned about once per process as a ComposioDeprecationWarning, grouped one line per toolkit, naming the deprecation and sunset dates and how to pin a newer version. Parse errors drop the entry and the hook never raises. The without_retries clone shares the httpx client and therefore the hook; a user-supplied client keeps its own hooks. Linear: PLEN-4352 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Sankaran committed Oct 15, 2026 at 17:42 UTC 0658179fd5fbf6db3e4236feb1be086c32f75718
4 files changed +879
python/composio/client/__init__.py
+9
@@ -29,6 +29,9 @@ from composio.core.models.tool_router_constants import (
29 )
30 from composio.exceptions import ComposioError, InvalidParams
31 from composio.utils.logging import LogLevel, WithLogger, _VerbosityWrapper
32 +from composio.utils.toolkit_deprecation import (
33 + install_hook as _install_toolkit_deprecation_hook,
34 +)
35
36
37 def _distribution_version(name: str) -> str:
@@ -427,6 +430,12 @@ class HttpClient(BaseComposio, WithLogger):
430 _environment_variables=_environment_variables,
431 )
432 _install_client_log_forwarder(self._logger)
433 + # Warns once per deprecated toolkit version reported through the
434 + # `Composio-Deprecated-Toolkits` response header. The hook lives on the
435 + # underlying httpx client, which `copy()` / `with_options()` (and so
436 + # `without_retries`) reuse, so clones share it. Idempotent, and a
437 + # user-supplied client keeps its own hooks.
438 + _install_toolkit_deprecation_hook(self._client)
439 self.provider = provider
440 self.request_ctx = contextvars.ContextVar[RequestContext](
441 "request_ctx",
python/composio/utils/toolkit_deprecation.py new
+298
@@ -0,0 +1,298 @@
1 +"""
2 +Toolkit version deprecation warnings.
3 +
4 +When a request resolves to a deprecated toolkit version, the API adds a
5 +``Composio-Deprecated-Toolkits`` response header (an RFC 9651 structured-field
6 +list). This module parses that header from an ``httpx`` response event hook
7 +installed below the generated client, and warns once per process for each
8 +deprecated toolkit version it sees. The response body is never read.
9 +
10 +Example header::
11 +
12 + "GMAIL";version="20250114_00";deprecated=@1779840000;sunset=@1787788800;reason="lifecycle"
13 +
14 +Kept intentionally equivalent to the TypeScript SDK's
15 +``ts/packages/core/src/utils/toolkitDeprecation.ts``.
16 +"""
17 +
18 +from __future__ import annotations
19 +
20 +import logging
21 +import re
22 +import threading
23 +import typing as t
24 +import warnings
25 +from dataclasses import dataclass
26 +from datetime import datetime, timezone
27 +
28 +import httpx
29 +
30 +from composio.exceptions import ComposioDeprecationWarning
31 +from composio.utils.toolkit_version import normalize_toolkit_slug
32 +
33 +#: Response header name. ``httpx.Headers`` lookups are case-insensitive.
34 +HEADER = "composio-deprecated-toolkits"
35 +
36 +#: Anchor of the docs section every warning points at.
37 +DOCS_URL = "https://docs.composio.dev/docs/tools-direct/toolkit-versioning#deprecation-and-sunset"
38 +
39 +#: Versions named per toolkit before the formatter collapses the rest into "and N more".
40 +_MAX_VERSIONS_PER_LINE = 5
41 +
42 +_logger = logging.getLogger(__name__)
43 +
44 +_SF_STRING = re.compile(r'^"((?:[^"\\]|\\.)*)"$')
45 +_SF_DATE = re.compile(r"^@(-?\d{1,15})$")
46 +_SF_ESCAPE = re.compile(r"\\(.)")
47 +
48 +
49 +@dataclass(frozen=True)
50 +class DeprecatedToolkit:
51 + """One item of the ``Composio-Deprecated-Toolkits`` header."""
52 +
53 + slug: str
54 + version: str
55 + deprecated_at: t.Optional[datetime] = None
56 + sunset_at: t.Optional[datetime] = None
57 + reason: t.Optional[str] = None
58 +
59 + @property
60 + def key(self) -> str:
61 + """Once-per-process dedupe key, ``UPPER(slug)@version``."""
62 + return f"{self.slug.upper()}@{self.version}"
63 +
64 +
65 +_warned: set[str] = set()
66 +_lock = threading.Lock()
67 +
68 +
69 +def _split_outside_quotes(value: str, delimiter: str) -> list[str]:
70 + """Split ``value`` on ``delimiter`` outside double-quoted strings.
71 +
72 + Backslash escapes inside the quotes are honoured. Empty pieces are dropped
73 + and the rest are stripped of surrounding whitespace.
74 + """
75 + pieces: list[str] = []
76 + current: list[str] = []
77 + in_string = False
78 + index = 0
79 + while index < len(value):
80 + char = value[index]
81 + if in_string:
82 + current.append(char)
83 + if char == "\\" and index + 1 < len(value):
84 + index += 1
85 + current.append(value[index])
86 + elif char == '"':
87 + in_string = False
88 + elif char == '"':
89 + in_string = True
90 + current.append(char)
91 + elif char == delimiter:
92 + pieces.append("".join(current))
93 + current = []
94 + else:
95 + current.append(char)
96 + index += 1
97 + pieces.append("".join(current))
98 + return [piece.strip() for piece in pieces if piece.strip()]
99 +
100 +
101 +def _decode_sf_string(raw: str) -> t.Optional[str]:
102 + """Decode an sf-string; ``None`` unless it is complete and validly escaped."""
103 + match = _SF_STRING.match(raw)
104 + if match is None:
105 + return None
106 + invalid = False
107 +
108 + def _unescape(escape: re.Match[str]) -> str:
109 + nonlocal invalid
110 + char = escape.group(1)
111 + if char in ('"', "\\"):
112 + return char
113 + invalid = True
114 + return ""
115 +
116 + decoded = _SF_ESCAPE.sub(_unescape, match.group(1))
117 + return None if invalid else decoded
118 +
119 +
120 +def _decode_sf_date(raw: str) -> t.Optional[datetime]:
121 + """Decode an sf-date (``@`` plus Unix seconds) into an aware UTC datetime."""
122 + match = _SF_DATE.match(raw)
123 + if match is None:
124 + return None
125 + try:
126 + return datetime.fromtimestamp(int(match.group(1)), tz=timezone.utc)
127 + except (OverflowError, OSError, ValueError):
128 + return None
129 +
130 +
131 +def _parse_item(item: str) -> t.Optional[DeprecatedToolkit]:
132 + """Parse one list item; ``None`` when the slug or a known parameter is invalid."""
133 + head, *params = _split_outside_quotes(item, ";")
134 + slug = _decode_sf_string(head)
135 + if not slug:
136 + return None
137 + version: t.Optional[str] = None
138 + deprecated_at: t.Optional[datetime] = None
139 + sunset_at: t.Optional[datetime] = None
140 + reason: t.Optional[str] = None
141 + for param in params:
142 + key, separator, raw_value = param.partition("=")
143 + if not separator:
144 + continue
145 + key = key.strip()
146 + raw_value = raw_value.strip()
147 + if key == "version":
148 + version = _decode_sf_string(raw_value)
149 + if not version:
150 + return None
151 + elif key == "reason":
152 + reason = _decode_sf_string(raw_value)
153 + if not reason:
154 + return None
155 + elif key == "deprecated":
156 + deprecated_at = _decode_sf_date(raw_value)
157 + if deprecated_at is None:
158 + return None
159 + elif key == "sunset":
160 + sunset_at = _decode_sf_date(raw_value)
161 + if sunset_at is None:
162 + return None
163 + # Unknown parameters are ignored.
164 + if version is None:
165 + return None
166 + return DeprecatedToolkit(
167 + slug=slug,
168 + version=version,
169 + deprecated_at=deprecated_at,
170 + sunset_at=sunset_at,
171 + reason=reason,
172 + )
173 +
174 +
175 +def parse_deprecated_toolkits_header(value: str) -> list[DeprecatedToolkit]:
176 + """Parse a ``Composio-Deprecated-Toolkits`` header value.
177 +
178 + Items that fail to parse are dropped silently; garbage input yields an
179 + empty list. Never raises.
180 + """
181 + try:
182 + entries: list[DeprecatedToolkit] = []
183 + for item in _split_outside_quotes(value, ","):
184 + entry = _parse_item(item)
185 + if entry is not None:
186 + entries.append(entry)
187 + return entries
188 + except Exception: # pragma: no cover - defensive, the parser is total
189 + return []
190 +
191 +
192 +def _iso_date(value: datetime) -> str:
193 + return value.astimezone(timezone.utc).date().isoformat()
194 +
195 +
196 +def _pin_hint(slug: str, docs_url: str) -> str:
197 + config_key = normalize_toolkit_slug(slug)
198 + env_var = f"COMPOSIO_TOOLKIT_VERSION_{slug.upper()}"
199 + return (
200 + f'Pin a newer version with toolkit_versions={{"{config_key}": "<version>"}} '
201 + f"or {env_var}. See {docs_url}."
202 + )
203 +
204 +
205 +def _format_single(entry: DeprecatedToolkit, docs_url: str) -> str:
206 + sentence = (
207 + f"[Deprecation] Toolkit {entry.slug.upper()} version {entry.version} "
208 + "was deprecated"
209 + )
210 + if entry.deprecated_at is not None:
211 + sentence += f" on {_iso_date(entry.deprecated_at)}"
212 + if entry.reason is not None:
213 + sentence += f" ({entry.reason})"
214 + if entry.sunset_at is not None:
215 + sentence += f" and will stop working on {_iso_date(entry.sunset_at)}"
216 + return f"{sentence}. {_pin_hint(entry.slug, docs_url)}"
217 +
218 +
219 +def _format_group(
220 + slug: str, entries: t.Sequence[DeprecatedToolkit], docs_url: str
221 +) -> str:
222 + versions = [entry.version for entry in entries]
223 + named = ", ".join(versions[:_MAX_VERSIONS_PER_LINE])
224 + remaining = len(versions) - _MAX_VERSIONS_PER_LINE
225 + listed = f"{named} and {remaining} more" if remaining > 0 else named
226 + sentence = f"[Deprecation] Toolkit {slug} versions {listed} are deprecated"
227 + sunsets = sorted(
228 + entry.sunset_at for entry in entries if entry.sunset_at is not None
229 + )
230 + if sunsets:
231 + sentence += f" and the earliest will stop working on {_iso_date(sunsets[0])}"
232 + return f"{sentence}. {_pin_hint(slug, docs_url)}"
233 +
234 +
235 +def format_warnings(
236 + entries: t.Sequence[DeprecatedToolkit], docs_url: str = DOCS_URL
237 +) -> list[str]:
238 + """Render one warning line per toolkit slug.
239 +
240 + A slug with a single deprecated version gets the full sentence with its
241 + dates and reason; a slug with several names at most five versions and
242 + collapses the rest into "and N more".
243 + """
244 + groups: dict[str, list[DeprecatedToolkit]] = {}
245 + for entry in entries:
246 + groups.setdefault(entry.slug.upper(), []).append(entry)
247 + return [
248 + _format_single(group[0], docs_url)
249 + if len(group) == 1
250 + else _format_group(slug, group, docs_url)
251 + for slug, group in groups.items()
252 + ]
253 +
254 +
255 +def warn_deprecated_toolkits(headers: httpx.Headers, docs_url: str = DOCS_URL) -> None:
256 + """Warn once per process for each deprecated toolkit version in ``headers``."""
257 + value = headers.get(HEADER)
258 + if not value:
259 + return
260 + entries = parse_deprecated_toolkits_header(value)
261 + fresh: list[DeprecatedToolkit] = []
262 + with _lock:
263 + for entry in entries:
264 + if entry.key in _warned:
265 + continue
266 + _warned.add(entry.key)
267 + fresh.append(entry)
268 + for line in format_warnings(fresh, docs_url):
269 + warnings.warn(line, ComposioDeprecationWarning, stacklevel=2)
270 +
271 +
272 +def response_hook(response: httpx.Response) -> None:
273 + """``httpx`` response event hook. Never raises and never reads the body."""
274 + try:
275 + warn_deprecated_toolkits(response.headers)
276 + except Exception: # noqa: BLE001 - a warning must never fail a call
277 + _logger.debug("Failed to inspect the toolkit deprecation header", exc_info=True)
278 +
279 +
280 +def install_hook(client: httpx.Client) -> None:
281 + """Append :func:`response_hook` to ``client`` once, keeping existing hooks.
282 +
283 + ``httpx.Client.event_hooks`` is a plain attribute holding the live dict in
284 + the pinned httpx, so appending to its ``response`` list takes effect
285 + immediately; the assignment below also covers an httpx that returns a copy.
286 + """
287 + hooks = client.event_hooks
288 + response_hooks = list(hooks.get("response", []))
289 + if any(hook is response_hook for hook in response_hooks):
290 + return
291 + response_hooks.append(response_hook)
292 + client.event_hooks = {**hooks, "response": response_hooks}
293 +
294 +
295 +def _reset_for_tests() -> None:
296 + """Clear the once-per-process record. Tests only."""
297 + with _lock:
298 + _warned.clear()
python/tests/test_sdk_logging.py
+246
@@ -337,3 +337,249 @@ class TestToolsListWireParams:
337 params = seen[0].url.params
338 assert params["query"] == "github issues"
339 assert "search" not in params
340 +
341 +
342 +_TOOL_BODY: dict[str, t.Any] = {
343 + "slug": "GMAIL_SEND_EMAIL",
344 + "name": "Send email",
345 + "description": "Sends an email",
346 + "input_parameters": {"type": "object", "properties": {}},
347 + "output_parameters": {"type": "object", "properties": {}},
348 + "toolkit": {"slug": "gmail", "name": "Gmail", "logo": ""},
349 + "version": "20250114_00",
350 +}
351 +_EXECUTE_BODY: dict[str, t.Any] = {
352 + "data": {"ok": True},
353 + "successful": True,
354 + "error": None,
355 +}
356 +
357 +_DEPRECATED_TOOLKITS_HEADER = "Composio-Deprecated-Toolkits"
358 +_GMAIL_ITEM = (
359 + '"GMAIL";version="20250114_00";deprecated=@1779840000;'
360 + 'sunset=@1787788800;reason="lifecycle"'
361 +)
362 +
363 +
364 +def _tool_transport(
365 + retrieve_headers: t.Optional[dict[str, str]] = None,
366 + execute_headers: t.Optional[dict[str, str]] = None,
367 + seen: t.Optional[list[httpx.Request]] = None,
368 + event_hooks: t.Optional[dict[str, list[t.Callable[..., t.Any]]]] = None,
369 +) -> httpx.Client:
370 + """Serve the tool schema on GET and the execute body on POST."""
371 +
372 + def handler(request: httpx.Request) -> httpx.Response:
373 + if seen is not None:
374 + seen.append(request)
375 + if request.method == "POST":
376 + return httpx.Response(
377 + 200, json=_EXECUTE_BODY, headers=execute_headers or {}
378 + )
379 + return httpx.Response(200, json=_TOOL_BODY, headers=retrieve_headers or {})
380 +
381 + return httpx.Client(
382 + transport=httpx.MockTransport(handler), event_hooks=event_hooks or {}
383 + )
384 +
385 +
386 +class TestToolkitDeprecationHeader:
387 + """``Composio-Deprecated-Toolkits`` surfaces once per toolkit version as a
388 + :class:`ComposioDeprecationWarning`, beside the client's own ``Deprecation``
389 + handling and without ever failing the call."""
390 +
391 + @pytest.fixture(autouse=True)
392 + def _reset_warned(self):
393 + from composio.utils import toolkit_deprecation
394 +
395 + toolkit_deprecation._reset_for_tests()
396 + yield
397 + toolkit_deprecation._reset_for_tests()
398 +
399 + @staticmethod
400 + def _deprecations(caught: list[warnings.WarningMessage]) -> list[str]:
401 + return [
402 + str(w.message)
403 + for w in caught
404 + if issubclass(w.category, ComposioDeprecationWarning)
405 + ]
406 +
407 + def test_tool_retrieve_warns_once(self, custom_logger):
408 + logger, _ = custom_logger
409 + composio = Composio(
410 + api_key="test-key",
411 + http_client=_tool_transport(
412 + retrieve_headers={_DEPRECATED_TOOLKITS_HEADER: _GMAIL_ITEM}
413 + ),
414 + logger=logger,
415 + )
416 +
417 + with warnings.catch_warnings(record=True) as caught:
418 + warnings.simplefilter("always")
419 + tool = composio.tools.get_raw_composio_tool_by_slug("GMAIL_SEND_EMAIL")
420 + composio.tools.get_raw_composio_tool_by_slug("GMAIL_SEND_EMAIL")
421 +
422 + assert tool.slug == "GMAIL_SEND_EMAIL"
423 + messages = self._deprecations(caught)
424 + assert len(messages) == 1
425 + assert "[Deprecation] Toolkit GMAIL version 20250114_00" in messages[0]
426 + assert "deprecated on 2026-05-27 (lifecycle)" in messages[0]
427 + assert "stop working on 2026-08-27" in messages[0]
428 + assert 'toolkit_versions={"gmail": "<version>"}' in messages[0]
429 + assert "COMPOSIO_TOOLKIT_VERSION_GMAIL" in messages[0]
430 + assert (
431 + "https://docs.composio.dev/docs/tools-direct/toolkit-versioning"
432 + "#deprecation-and-sunset"
433 + ) in messages[0]
434 +
435 + def test_execute_path_warns_once_across_retrieve_and_execute(self, custom_logger):
436 + logger, _ = custom_logger
437 + seen: list[httpx.Request] = []
438 + composio = Composio(
439 + api_key="test-key",
440 + http_client=_tool_transport(
441 + retrieve_headers={_DEPRECATED_TOOLKITS_HEADER: _GMAIL_ITEM},
442 + execute_headers={_DEPRECATED_TOOLKITS_HEADER: _GMAIL_ITEM},
443 + seen=seen,
444 + ),
445 + logger=logger,
446 + )
447 +
448 + with warnings.catch_warnings(record=True) as caught:
449 + warnings.simplefilter("always")
450 + result = composio.tools.execute(
451 + "GMAIL_SEND_EMAIL", {}, user_id="user-1", version="20250114_00"
452 + )
453 +
454 + assert result["successful"] is True
455 + assert [request.method for request in seen] == ["GET", "POST"]
456 + assert len(self._deprecations(caught)) == 1
457 +
458 + def test_without_retries_clone_shares_the_hook(self, custom_logger):
459 + """Only the execute response, served through ``client.without_retries``,
460 + carries the header: the warning proves the clone shares the hook."""
461 + logger, _ = custom_logger
462 + composio = Composio(
463 + api_key="test-key",
464 + http_client=_tool_transport(
465 + execute_headers={_DEPRECATED_TOOLKITS_HEADER: _GMAIL_ITEM}
466 + ),
467 + logger=logger,
468 + )
469 + assert composio.client.without_retries._client is composio.client._client
470 +
471 + with warnings.catch_warnings(record=True) as caught:
472 + warnings.simplefilter("always")
473 + composio.tools.execute(
474 + "GMAIL_SEND_EMAIL", {}, user_id="user-1", version="20250114_00"
475 + )
476 +
477 + messages = self._deprecations(caught)
478 + assert len(messages) == 1
479 + assert "GMAIL version 20250114_00" in messages[0]
480 +
481 + def test_no_header_no_warning(self, custom_logger):
482 + logger, _ = custom_logger
483 + composio = Composio(
484 + api_key="test-key", http_client=_tool_transport(), logger=logger
485 + )
486 +
487 + with warnings.catch_warnings():
488 + warnings.simplefilter("error", ComposioDeprecationWarning)
489 + composio.tools.get_raw_composio_tool_by_slug("GMAIL_SEND_EMAIL")
490 + composio.tools.execute(
491 + "GMAIL_SEND_EMAIL", {}, user_id="user-1", version="20250114_00"
492 + )
493 +
494 + def test_client_deprecation_and_toolkit_header_are_two_warnings(
495 + self, custom_logger
496 + ):
497 + logger, _ = custom_logger
498 + composio = Composio(
499 + api_key="test-key",
500 + http_client=_tool_transport(
501 + retrieve_headers={
502 + "Deprecation": "@1688169599",
503 + _DEPRECATED_TOOLKITS_HEADER: _GMAIL_ITEM,
504 + }
505 + ),
506 + logger=logger,
507 + )
508 +
509 + with warnings.catch_warnings(record=True) as caught:
510 + warnings.simplefilter("always")
511 + composio.tools.get_raw_composio_tool_by_slug("GMAIL_SEND_EMAIL")
512 +
513 + messages = self._deprecations(caught)
514 + assert len(messages) == 2
515 + ours = [m for m in messages if "[Deprecation] Toolkit GMAIL" in m]
516 + theirs = [m for m in messages if "tools.retrieve" in m]
517 + assert len(ours) == 1
518 + assert len(theirs) == 1
519 +
520 + def test_malformed_header_keeps_body_and_stays_silent(self, custom_logger):
521 + logger, _ = custom_logger
522 + composio = Composio(
523 + api_key="test-key",
524 + http_client=_tool_transport(
525 + retrieve_headers={_DEPRECATED_TOOLKITS_HEADER: '"GMAIL;version=;;@@'}
526 + ),
527 + logger=logger,
528 + )
529 +
530 + with warnings.catch_warnings(record=True) as caught:
531 + warnings.simplefilter("always")
532 + tool = composio.tools.get_raw_composio_tool_by_slug("GMAIL_SEND_EMAIL")
533 +
534 + assert tool.slug == "GMAIL_SEND_EMAIL"
535 + assert self._deprecations(caught) == []
536 +
537 + def test_user_http_client_keeps_its_own_hook_and_gets_ours(self, custom_logger):
538 + logger, _ = custom_logger
539 + user_seen: list[httpx.Response] = []
540 +
541 + def user_hook(response: httpx.Response) -> None:
542 + user_seen.append(response)
543 +
544 + http_client = _tool_transport(
545 + retrieve_headers={_DEPRECATED_TOOLKITS_HEADER: _GMAIL_ITEM},
546 + event_hooks={"response": [user_hook]},
547 + )
548 + composio = Composio(api_key="test-key", http_client=http_client, logger=logger)
549 +
550 + with warnings.catch_warnings(record=True) as caught:
551 + warnings.simplefilter("always")
552 + composio.tools.get_raw_composio_tool_by_slug("GMAIL_SEND_EMAIL")
553 +
554 + assert http_client.event_hooks["response"][0] is user_hook
555 + assert len(http_client.event_hooks["response"]) == 2
556 + assert len(user_seen) == 1
557 + assert len(self._deprecations(caught)) == 1
558 +
559 + def test_second_instance_does_not_rewarn_until_reset(self, custom_logger):
560 + from composio.utils import toolkit_deprecation
561 +
562 + logger, _ = custom_logger
563 + headers = {_DEPRECATED_TOOLKITS_HEADER: _GMAIL_ITEM}
564 +
565 + with warnings.catch_warnings(record=True) as caught:
566 + warnings.simplefilter("always")
567 + Composio(
568 + api_key="test-key",
569 + http_client=_tool_transport(retrieve_headers=headers),
570 + logger=logger,
571 + ).tools.get_raw_composio_tool_by_slug("GMAIL_SEND_EMAIL")
572 + Composio(
573 + api_key="test-key",
574 + http_client=_tool_transport(retrieve_headers=headers),
575 + logger=logger,
576 + ).tools.get_raw_composio_tool_by_slug("GMAIL_SEND_EMAIL")
577 + assert len(self._deprecations(caught)) == 1
578 + toolkit_deprecation._reset_for_tests()
579 + Composio(
580 + api_key="test-key",
581 + http_client=_tool_transport(retrieve_headers=headers),
582 + logger=logger,
583 + ).tools.get_raw_composio_tool_by_slug("GMAIL_SEND_EMAIL")
584 +
585 + assert len(self._deprecations(caught)) == 2
python/tests/test_toolkit_deprecation.py new
+326
@@ -0,0 +1,326 @@
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_item_without_version_is_dropped_but_siblings_kept(self):
128 + assert parse_deprecated_toolkits_header(
129 + f'"GMAIL";deprecated=@1779840000, {BARE_ITEM}'
130 + ) == [DeprecatedToolkit(slug="STRAVA", version="20240902_00")]
131 +
132 + @pytest.mark.parametrize(
133 + "value",
134 + [
135 + '"GMAIL";version=20250114_00',
136 + '"GMAIL";version="1";deprecated="2026-05-27"',
137 + '"GMAIL";version="1";reason=lifecycle',
138 + '"GM\\nAIL";version="1"',
139 + ],
140 + )
141 + def test_wrong_type_or_bad_escape_drops_item(self, value: str):
142 + assert parse_deprecated_toolkits_header(value) == []
143 +
144 +
145 +class TestFormat:
146 + def test_full_message(self):
147 + (line,) = format_warnings(parse_deprecated_toolkits_header(FULL_ITEM), DOCS)
148 + assert line == (
149 + "[Deprecation] Toolkit GMAIL version 20250114_00 was deprecated on "
150 + "2026-05-27 (lifecycle) and will stop working on 2026-08-27. "
151 + 'Pin a newer version with toolkit_versions={"gmail": "<version>"} '
152 + f"or COMPOSIO_TOOLKIT_VERSION_GMAIL. See {DOCS}."
153 + )
154 +
155 + def test_omits_reason_and_sunset_when_absent(self):
156 + (line,) = format_warnings([_entry(slug="STRAVA", version="20240902_00")], DOCS)
157 + assert line == (
158 + "[Deprecation] Toolkit STRAVA version 20240902_00 was deprecated. "
159 + 'Pin a newer version with toolkit_versions={"strava": "<version>"} '
160 + f"or COMPOSIO_TOOLKIT_VERSION_STRAVA. See {DOCS}."
161 + )
162 +
163 + def test_keeps_deprecation_date_when_only_sunset_missing(self):
164 + (line,) = format_warnings(
165 + [_entry(deprecated_at=_utc(1779840000), reason="security")], DOCS
166 + )
167 + assert "was deprecated on 2026-05-27 (security). Pin" in line
168 + assert "stop working" not in line
169 +
170 + def test_default_docs_url(self):
171 + (line,) = format_warnings([_entry()])
172 + assert line.endswith(f"See {DOCS_URL}.")
173 + assert DOCS_URL == (
174 + "https://docs.composio.dev/docs/tools-direct/toolkit-versioning"
175 + "#deprecation-and-sunset"
176 + )
177 +
178 + def test_groups_six_versions_into_one_line_naming_five(self):
179 + entries = [
180 + _entry(
181 + version=f"202501{suffix:02d}_00",
182 + sunset_at=datetime(2026, 8, 20 + suffix, tzinfo=timezone.utc),
183 + )
184 + for suffix in range(1, 7)
185 + ]
186 + lines = format_warnings(entries, DOCS)
187 + assert lines == [
188 + "[Deprecation] Toolkit GMAIL versions 20250101_00, 20250102_00, "
189 + "20250103_00, 20250104_00, 20250105_00 and 1 more are deprecated and "
190 + "the earliest will stop working on 2026-08-21. "
191 + 'Pin a newer version with toolkit_versions={"gmail": "<version>"} '
192 + f"or COMPOSIO_TOOLKIT_VERSION_GMAIL. See {DOCS}."
193 + ]
194 +
195 + def test_one_line_per_slug_grouped_case_insensitively(self):
196 + lines = format_warnings(
197 + [
198 + _entry(slug="GMAIL", version="1"),
199 + _entry(slug="STRAVA", version="1"),
200 + _entry(slug="gmail", version="2"),
201 + ],
202 + DOCS,
203 + )
204 + assert len(lines) == 2
205 + assert "Toolkit GMAIL versions 1, 2 are deprecated." in lines[0]
206 + assert "Toolkit STRAVA version 1 was deprecated." in lines[1]
207 +
208 + def test_no_entries_no_lines(self):
209 + assert format_warnings([], DOCS) == []
210 +
211 +
212 +class TestWarnOnce:
213 + def test_warns_once_per_key_across_calls(self):
214 + headers = httpx.Headers({HEADER: FULL_ITEM})
215 + with warnings.catch_warnings(record=True) as caught:
216 + warnings.simplefilter("always")
217 + warn_deprecated_toolkits(headers)
218 + warn_deprecated_toolkits(headers)
219 + messages = _deprecations(caught)
220 + assert len(messages) == 1
221 + assert "GMAIL version 20250114_00" in messages[0]
222 +
223 + def test_second_version_still_warns_after_first_was_deduped(self):
224 + with warnings.catch_warnings(record=True) as caught:
225 + warnings.simplefilter("always")
226 + warn_deprecated_toolkits(
227 + httpx.Headers({HEADER: f"{FULL_ITEM}, {BARE_ITEM}"})
228 + )
229 + warn_deprecated_toolkits(
230 + httpx.Headers({HEADER: '"GMAIL";version="20250201_00"'})
231 + )
232 + assert len(_deprecations(caught)) == 3
233 +
234 + def test_header_name_is_case_insensitive(self):
235 + with warnings.catch_warnings(record=True) as caught:
236 + warnings.simplefilter("always")
237 + warn_deprecated_toolkits(
238 + httpx.Headers({"Composio-Deprecated-Toolkits": BARE_ITEM})
239 + )
240 + assert len(_deprecations(caught)) == 1
241 +
242 + def test_no_header_or_garbage_is_silent(self):
243 + with warnings.catch_warnings(record=True) as caught:
244 + warnings.simplefilter("always")
245 + warn_deprecated_toolkits(httpx.Headers({}))
246 + warn_deprecated_toolkits(httpx.Headers({HEADER: "%%% nope"}))
247 + assert _deprecations(caught) == []
248 +
249 + def test_reset_allows_warning_again(self):
250 + headers = httpx.Headers({HEADER: BARE_ITEM})
251 + with warnings.catch_warnings(record=True) as caught:
252 + warnings.simplefilter("always")
253 + warn_deprecated_toolkits(headers)
254 + td._reset_for_tests()
255 + warn_deprecated_toolkits(headers)
256 + assert len(_deprecations(caught)) == 2
257 +
258 + def test_two_threads_one_warning(self):
259 + headers = httpx.Headers({HEADER: FULL_ITEM})
260 + barrier = threading.Barrier(2)
261 +
262 + def worker() -> None:
263 + barrier.wait()
264 + warn_deprecated_toolkits(headers)
265 +
266 + with warnings.catch_warnings(record=True) as caught:
267 + warnings.simplefilter("always")
268 + threads = [threading.Thread(target=worker) for _ in range(2)]
269 + for thread in threads:
270 + thread.start()
271 + for thread in threads:
272 + thread.join()
273 + assert len(_deprecations(caught)) == 1
274 +
275 +
276 +class TestResponseHook:
277 + def test_warns_from_response_headers(self):
278 + response = httpx.Response(200, headers={HEADER: BARE_ITEM})
279 + with warnings.catch_warnings(record=True) as caught:
280 + warnings.simplefilter("always")
281 + response_hook(response)
282 + assert len(_deprecations(caught)) == 1
283 +
284 + def test_never_raises(self, caplog: pytest.LogCaptureFixture):
285 + class _Broken:
286 + @property
287 + def headers(self) -> httpx.Headers:
288 + raise RuntimeError("headers unavailable")
289 +
290 + with caplog.at_level("DEBUG", logger="composio.utils.toolkit_deprecation"):
291 + response_hook(t.cast(httpx.Response, _Broken()))
292 + assert "Failed to inspect the toolkit deprecation header" in caplog.text
293 +
294 +
295 +class TestInstallHook:
296 + def test_appends_once(self):
297 + client = httpx.Client()
298 + install_hook(client)
299 + install_hook(client)
300 + assert client.event_hooks["response"] == [response_hook]
301 +
302 + def test_preserves_user_hooks(self):
303 + def user_request(request: httpx.Request) -> None:
304 + pass
305 +
306 + def user_response(response: httpx.Response) -> None:
307 + pass
308 +
309 + client = httpx.Client(
310 + event_hooks={"request": [user_request], "response": [user_response]}
311 + )
312 + install_hook(client)
313 + assert client.event_hooks["request"] == [user_request]
314 + assert client.event_hooks["response"] == [user_response, response_hook]
315 +
316 + def test_installed_hook_fires_on_send(self):
317 + def handler(request: httpx.Request) -> httpx.Response:
318 + return httpx.Response(200, headers={HEADER: BARE_ITEM}, json={})
319 +
320 + client = httpx.Client(transport=httpx.MockTransport(handler))
321 + install_hook(client)
322 + with warnings.catch_warnings(record=True) as caught:
323 + warnings.simplefilter("always")
324 + response = client.get("https://backend.invalid/api/v3/toolkits/strava")
325 + assert response.json() == {}
326 + assert len(_deprecations(caught)) == 1