Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 08:30 UTC
feat(python): warn once per deprecated toolkit version reported by the API (PLEN-4352) (#4884)
## What Adds `composio/utils/toolkit_deprecation.py` and installs its `response_hook` as an httpx response event hook on the generated client's underlying `httpx.Client` in `HttpClient.__init__` (`python/composio/client/__init__.py`, right after `_install_client_log_forwarder`). Every response is checked for the `Composio-Deprecated-Toolkits` header, an RFC 9651 structured-field list with one item per deprecated toolkit version (`"GMAIL";version="20250114_00";deprecated=@1779840000;sunset=@1787788800;reason="lifecycle"`). Items are parsed by a hand-rolled parser for that subset; parse failures drop the item. Each `UPPER(slug)@version` is warned about once per process (set guarded by a `threading.Lock`) as a `ComposioDeprecationWarning`, one line per toolkit: ``` [Deprecation] Toolkit GMAIL version 20250114_00 was deprecated on 2026-05-27 (lifecycle) and will stop working on 2026-08-27. Pin a newer version with toolkit_versions={"gmail": "<version>"} or COMPOSIO_TOOLKIT_VERSION_GMAIL. See https://docs.composio.dev/docs/tools-direct/toolkit-versioning#deprecation-and-sunset. ``` The reason and sunset clauses are omitted when the header omits them. The hook never raises (failures log at DEBUG on `composio.utils.toolkit_deprecation`) and never reads the body. ## Why Phase 1 of toolkit version deprecation (PLEN-2553; platform #13516, #13517) emits the header; without this the SDK is silent until the Phase 2 410. ## Design decisions - Global response hook, not per call site: eight single-toolkit routes emit the header today and more may follow; one hook below the generated client covers them all, including retried attempts and the `without_retries` clone, without touching `composio/core/models/*`. - Dedupe key UPPER(slug)@version per process: `tools.execute` and `triggers.create` each make two header-bearing requests, and a once-per-process boolean would hide a second deprecated toolkit. - Grouped formatter, five versions per line: every Phase 1 header carries one item, so this is one version per line today; the rule exists so a future listing emitter cannot produce a burst of lines. - Channel: `warnings.warn(line, ComposioDeprecationWarning, stacklevel=2)` with the class re-exported from `composio.exceptions`; silence with `warnings.filterwarnings("ignore", category=ComposioDeprecationWarning)`. No new config flag, no telemetry event. - Listings never carry the header (platform decision); CLI, MCP, 410 mapping, telemetry are follow-ups. ## Owned-client facts verified Verified on the pinned `composio-client==2.0.0rc14` as installed from `uv.lock` (the handoff cited rc10; `next` moved to rc14 and the same lines hold; rc10 was also checked from `pip download` with identical results): - (a) The httpx client is stored at `self._client`: `composio_client/_base_client.py:856` (`self._client = http_client if http_client is not None else httpx.Client()`), and every request goes through `self._client.send(` (line 1328), where httpx fires response event hooks, once per attempt inside the client's retry loop. - (b) `copy()` passes `"http_client": self._client if http_client is None else http_client` (`composio_client/_client.py:339`) and `with_options = copy` (line 353), so the `without_retries` clone built in `python/composio/client/__init__.py` shares the httpx client and therefore the hook. Proved by test, not by reading (see below). - (c) A user-supplied `http_client` is used as-is (same line as (a), no wrapping), so `install_hook` appends to the user's own `event_hooks["response"]` list without replacing it, and only once (identity check). - Path taken: the main path (hook in `HttpClient.__init__`); the fallback in `composio/sdk.py` was not needed. - httpx 0.28.1 (installed): `Client.event_hooks` returns the live dict; `install_hook` reassigns through the setter anyway and preserves `request` hooks. - Construction sites: `HttpClient(...)` is built once, in `python/composio/sdk.py:251`. ## Not changed composio/core/models/*, generated surfaces, client pins, lockfiles, mocks. No changeset and no version bump: the bump rides the next `make bump`. ## Tests - `tests/test_toolkit_deprecation.py` (37): parser goldens mirroring the TypeScript list (full params; bare STRAVA; two items; escaped quote and backslash in a slug; whitespace around separators; seven garbage inputs yield `[]`; unknown params ignored; missing `version` dropped while siblings are kept; wrong-typed known params and an invalid escape drop the item); datetimes are timezone-aware UTC; formatting with and without sunset and reason, default docs URL, six versions grouped into one line with "and 1 more", case-insensitive grouping; `warn_deprecated_toolkits` warns once across calls, still warns for a second version, matches the header name case-insensitively, is silent on no header or garbage, re-warns after `_reset_for_tests()`, and emits one warning from two threads started on a barrier; `response_hook` warns and never raises (logs at DEBUG); `install_hook` appends once, preserves pre-existing user request and response hooks, and fires on `send`. - `tests/test_sdk_logging.py::TestToolkitDeprecationHeader` (8), using the file's mock-transport pattern and autouse telemetry fixture, with `warnings.catch_warnings(record=True)` + `simplefilter("always")` and an autouse `_reset_for_tests()` fixture: `composio.tools.get_raw_composio_tool_by_slug("GMAIL_SEND_EMAIL")` twice raises exactly one `ComposioDeprecationWarning` naming GMAIL, 20250114_00, the dates, the pin hint and the docs URL; `tools.execute` with a pinned version (retrieve plus execute, both with the header, execute via `without_retries`) still one; header only on the execute response, served by the clone (asserted to share `_client`), still warns; no header, none (`simplefilter("error")`); `Deprecation: @1688169599` plus our header produce two distinct warnings (the client's `tools.retrieve` one and ours); a malformed header keeps the body and stays silent; a user-supplied `http_client` with its own response hook keeps it first and gets ours; a second `Composio` does not re-warn until reset. ## Checks run From `python/` with the mise toolchain (`uv 0.8.19`): - `make env`: created the seeded `python/.venv` and the uv workspace root `.venv` with the dev group. - `make fmt` (`nox -s fmt`): the nox venv's ruff reformatted 7 files and fixed 42 import-order findings in files unrelated to this change; those were reverted (`git checkout`) and the four files in this PR are formatted. - `make chk` (`nox -s chk`): ruff check clean; mypy `Success: no issues found` in `composio/` (64 files), `providers/` (37), `tests/` (71), `scripts/` (2). `Session chk was successful`. - `make tst` (`nox -s tst`): `tests/`: `2417 passed, 4 skipped, 261 warnings in 30.62s`; `providers/openai_agents/tests`: 11 passed; `providers/claude_agent_sdk/tests`: 16 passed; `providers/anthropic/tests`: 6 passed. `Session tst was successful`. - Isolation: `pytest tests/test_toolkit_deprecation.py`: 37 passed; `pytest tests/test_sdk_logging.py::TestToolkitDeprecationHeader`: 8 passed; both files together with `test_connected_accounts.py` and `test_no_retry_writes.py`: 133 passed. `pytest-randomly` is not installed, so order is deterministic and `-p no:randomly` was not needed; `config/pytest.ini` has only `--strict-markers` (no `-W error`), and the new tests assert the warning explicitly anyway. - Diff grep for em dashes and `print(`: none. ## Rollout and rollback No-op until Apollo #13517 is deployed; plain revert. ## Sibling PR - TypeScript: https://github.com/ComposioHQ/composio/pull/4883 - Docs: https://github.com/ComposioHQ/composio/pull/4881 Linear: PLEN-4352 🤖 Generated with [Claude Code](https://claude.com/claude-code)
No changes.