@devries-cameron20 / composio-1 / commits / d27eecce2
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.

docs(py): sanitize public docstrings — remove internal references

Addresses 2 review comments from @abir-taheer on #3401: - tests/test_connected_accounts.py:546 — remove Hermes PR reference - models/connected_accounts.py:708 — update_acl docstring too long; match the style of other methods in the file (cf. update()) Swept the full PR diff for the same patterns rather than just the two flagged lines: - Removed Hermes PR numbers and TS-test cross-reference from TestConnectedAccountsAcl class docstring. - Trimmed update_acl docstring — kept ~10 lines (one-line description, param list, one example) instead of the original ~40 lines with the resolution-rule table, multiple examples, and verbose footgun-warning block. Matches the style of update() / delete() / refresh() in the same file. Resolution rule + per-list caps stay documented on ConnectedAccountAclConfigSchema (where the contract belongs). - Removed internal backend error codes from exception class docstrings (``ConnectedAccount_AclOnlyForShared``, ``ConnectedAccount_SharedAccessDenied``, ``ToolRouterV2_SharedConnectionNotAccessible``). Surfacing the internal code names leaks implementation details. - Reworded "users in the project" / "project member" / "Open access to everyone in the project" — users don't belong to a project entity in Composio's data model. Replaced with phrasing focused on ``user_id`` and the pinning mechanism. - Removed "Set at create time only" wording from the link() param description on connected_accounts.py and tool_router_session.py (the corresponding upstream API description has the same wording removed). - Cleaned inline catch comments referencing internal error code names. No behaviour changes — docstring / comment cleanup only. Verified: nox -s chk clean, ruff format --check clean, 49/49 tests pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

venkat82 committed May 12, 2026 at 01:21 UTC d27eecce204c5a669fb384562a7793498960efe1
4 files changed +37 -77
python/composio/core/models/connected_accounts.py
+21 -47
@@ -578,14 +578,14 @@ class ConnectedAccounts:
578 ``ACTIVE`` connection on this auth config. Pair with ``alias`` and a
579 session-level ``multi_account`` config to disambiguate at execution time.
580 :param account_type: Sharing model for the new connection. ``PRIVATE``
581 - (default) is usable only by the owning ``user_id``. ``SHARED`` is
582 - reachable from a tool-router session by other users in the project,
583 - but only when explicitly pinned and only when the requesting
584 - ``user_id`` passes the connection's ACL. Set at create time only.
585 - :param acl_config_for_shared: Per-user ACL for SHARED connections. Only
586 - valid when ``account_type == 'SHARED'`` — the backend rejects ACL
587 - on a PRIVATE connection with ``ComposioAclOnlyForSharedError``
588 - (400). Pass an ``ACLConfigForShared`` dict with any combination of
581 + (default) is usable only by the owning ``user_id``. ``SHARED`` can
582 + be used by other ``user_id``s — but only when the connection is
583 + explicitly pinned in a tool-router session's config and only when
584 + the requesting ``user_id`` passes the connection's ACL.
585 + :param acl_config_for_shared: Per-user ACL for SHARED connections.
586 + Only valid when ``account_type == 'SHARED'``; raises
587 + ``ComposioAclOnlyForSharedError`` on a PRIVATE connection. Pass
588 + an ``ACLConfigForShared`` dict with any combination of
589 ``allow_all_users``, ``allowed_user_ids``, ``not_allowed_user_ids``.
590 Omit to keep deny-by-default (only the creator can use).
591 :return: Connection request object.
@@ -652,9 +652,9 @@ class ConnectedAccounts:
652 ),
653 )
654 except BadRequestError as error:
655 - # Backend rejects ACL on PRIVATE rows with 400 +
656 - # ``ConnectedAccount_AclOnlyForShared``. Surface it as a typed
657 - # error so callers can ``except`` instead of grepping messages.
655 + # The server rejects ACL on PRIVATE connections — surface that
656 + # as a typed error so callers can ``except`` instead of grepping
657 + # messages.
658 message = str(error)
659 if "acl_config_for_shared is only valid on SHARED" in message:
660 raise exceptions.ComposioAclOnlyForSharedError(message) from error
@@ -678,53 +678,27 @@ class ConnectedAccounts:
678 """
679 Update the per-user ACL on a SHARED connected account.
680
681 - Only meaningful for SHARED connections — the backend rejects ACL
682 - writes on PRIVATE rows with ``ComposioAclOnlyForSharedError`` (400).
683 - Auth gate is creator-or-API-key (a non-creator project member
684 - updating an alias on a SHARED row still works via :meth:`update`,
685 - but ACL writes do not).
686 -
687 - PATCH semantics: omit a parameter to leave it unchanged; pass an
688 - empty list to clear an allow/deny list. At least one parameter must
689 - be provided — calling with all three as ``None`` raises
690 - :class:`composio.exceptions.ValidationError`.
691 -
692 - Resolution rule (deny wins):
693 - 1. requesting user_id in ``not_allowed_user_ids`` → DENY
694 - 2. ``allow_all_users == True`` → ALLOW
695 - 3. requesting user_id in ``allowed_user_ids`` → ALLOW
696 - 4. otherwise → DENY
681 + Only valid on SHARED connections; raises
682 + ``ComposioAclOnlyForSharedError`` on a PRIVATE connection. Omit a
683 + parameter to leave it unchanged; pass an empty list to clear an
684 + allow/deny list. At least one parameter must be provided.
685
686 :param nanoid: The connected account ID (``ca_xxx``).
699 - :param allow_all_users: Wildcard "any user_id in the project" allow.
700 - :param allowed_user_ids: Explicit allow list. Pass ``[]`` to clear.
687 + :param allow_all_users: When True, any ``user_id`` may use this
688 + SHARED connection (subject to the deny list).
689 + :param allowed_user_ids: Explicit list of allowed ``user_id`` strings.
690 + Pass ``[]`` to clear.
691 :param not_allowed_user_ids: Explicit deny list (wins over allow on
692 conflict). Pass ``[]`` to clear — note that clearing the deny
693 list silently re-grants access to previously-blocked users.
704 - :return: PATCH response (``id``, ``status``, ``success``). To read
705 - back the updated ``acl_config_for_shared`` block, call
706 - :meth:`get` after this returns.
707 -
708 - Example::
709 -
710 - # Open access to everyone in the project
711 - composio.connected_accounts.update_acl('ca_abc', allow_all_users=True)
694 + :return: Response with ``id``, ``status``, and ``success``.
695
713 - # Everyone except a specific user
696 + Example:
697 composio.connected_accounts.update_acl(
698 'ca_abc',
699 allow_all_users=True,
700 not_allowed_user_ids=['user_bob'],
701 )
719 -
720 - # Targeted allow
721 - composio.connected_accounts.update_acl(
722 - 'ca_abc',
723 - allowed_user_ids=['user_alice', 'user_bob'],
724 - )
725 -
726 - # Revoke a previously-granted allow list (back to deny-by-default)
727 - composio.connected_accounts.update_acl('ca_abc', allowed_user_ids=[])
702 """
703 if (
704 allow_all_users is None
python/composio/core/models/tool_router_session.py
+8 -9
@@ -552,13 +552,12 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
552 :param alias: Human-readable alias for the connection. Must be unique
553 per userId and toolkit within the project.
554 :param account_type: Sharing model for the new connection. ``PRIVATE``
555 - (default) is usable only by the owning user. ``SHARED`` lets other
556 - users in the project use the connection when pinned. Set at create
557 - time only.
558 - :param acl_config_for_shared: Per-user ACL for SHARED connections. Only
559 - valid when ``account_type == 'SHARED'`` — the backend rejects ACL
560 - on a PRIVATE connection with ``ComposioAclOnlyForSharedError``
561 - (400).
555 + (default) is usable only by the owning ``user_id``. ``SHARED`` can
556 + be used by other ``user_id``s when the connection is pinned in a
557 + tool-router session and the requesting user passes its ACL.
558 + :param acl_config_for_shared: Per-user ACL for SHARED connections.
559 + Only valid when ``account_type == 'SHARED'``; raises
560 + ``ComposioAclOnlyForSharedError`` on a PRIVATE connection.
561 """
562 try:
563 response = self._client.tool_router.session.link(
@@ -572,8 +571,8 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
571 ),
572 )
573 except BadRequestError as error:
575 - # Mirrors the mapper on ``composio.connected_accounts.link()`` —
576 - # the same backend handler returns ``AclOnlyForShared`` here.
574 + # The server rejects ACL on PRIVATE connections — surface that
575 + # as a typed error mirroring ``composio.connected_accounts.link()``.
576 message = str(error)
577 if "acl_config_for_shared is only valid on SHARED" in message:
578 raise exceptions.ComposioAclOnlyForSharedError(message) from error
python/composio/exceptions.py
+6 -16
@@ -334,12 +334,8 @@ class ComposioLegacyConnectedAccountsEndpointRetiredError(ConnectedAccountError)
334 class ComposioAclOnlyForSharedError(ConnectedAccountError):
335 """Raised when ACL fields (``allow_all_users``, ``allowed_user_ids``,
336 ``not_allowed_user_ids``) are sent on a ``PRIVATE`` connection — at
337 - create time or via PATCH.
338 -
339 - ACL is only meaningful for ``SHARED`` connections; the matching layer
340 - never reads it for PRIVATE. Backend rejects with 400 +
341 - ``ConnectedAccount_AclOnlyForShared`` rather than silently ignoring the
342 - ACL block, so developer misconfiguration surfaces loudly.
337 + create time or via PATCH. ACL is only meaningful for ``SHARED``
338 + connections.
339
340 Fix: set ``account_type='SHARED'`` at create time, or omit the ACL
341 fields when creating/updating a PRIVATE connection.
@@ -353,17 +349,14 @@ class ComposioSharedAccessDeniedError(ConnectedAccountError):
349 account but the requesting ``user_id`` is not allowed by the
350 connection's ACL.
351
356 - Surfaces from the matching layer when a SHARED connection is reached
357 - directly (e.g. via ``composio.tools.execute(slug, connected_account_id=...)``)
358 - without going through a tool-router session that already pre-flighted
359 - the ACL at session-create time.
352 + Surfaces when a SHARED connection is reached directly (e.g. via
353 + ``composio.tools.execute(slug, connected_account_id=...)``) without
354 + going through a tool-router session.
355
356 Fix: ask the connection's creator to grant access via
357 ``composio.connected_accounts.update_acl()`` — set ``allow_all_users``,
358 add the ``user_id`` to ``allowed_user_ids``, or remove it from
359 ``not_allowed_user_ids``.
365 -
366 - Backend response: 403 with code ``ConnectedAccount_SharedAccessDenied``.
360 """
361
362 pass
@@ -372,15 +365,12 @@ class ComposioSharedAccessDeniedError(ConnectedAccountError):
365 class ComposioSharedConnectionNotAccessibleError(ConnectedAccountError):
366 """Raised by tool-router session create / PATCH when the session's
367 ``user_id`` cannot use a pinned SHARED connection — caught at
375 - session-create time so the session never enters a state that 4xxs
368 + session-create time so the session never enters a state that fails
369 mid-execution.
370
371 Fix: grant the session user access via
372 ``composio.connected_accounts.update_acl()`` on the pinned connection,
373 or pin a different connection the user can use.
381 -
382 - Backend response: 400 with code
383 - ``ToolRouterV2_SharedConnectionNotAccessible``.
374 """
375
376 pass
python/tests/test_connected_accounts.py
+2 -5
@@ -543,11 +543,8 @@ def _make_bad_request_error(message: str):
543
544
545 class TestConnectedAccountsAcl:
546 - """Tests for accountType + per-user ACL surfacing (Hermes #9860, #9902).
547 -
548 - Mirrors the 12 behaviour tests in
549 - ``ts/packages/core/test/connectedAccounts/connectedAccounts.test.ts``.
550 - """
546 + """Tests for ``account_type`` + per-user ACL surfacing on ``link()``
547 + and ``update_acl()``."""
548
549 @pytest.fixture
550 def mock_client(self):