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

fix(docs): render nested Python annotations in the SDK reference (#5262)

This PR: - Fixes Python SDK reference annotations where `| None` landed inside a nested generic, for example `Literal['webhook', 'poll' | None]` instead of `Literal['webhook', 'poll'] | None` (Greptile on the release PR: https://github.com/ComposioHQ/composio/pull/5261#discussion_r4496591833). - Root cause: `format_type` in `python/scripts/generate-docs.py` rewrote `Optional[...]` and `Unpack[...]` with a `[^\]]+` regex, so the match ended at the first `]`. Every `Optional[List[str]]` or `Optional[Dict[str, Any]]` also rendered wrong, as `List[str | None]` or `Dict[str, Any | None]`. - Replaces the regex with a bracket-matching rewrite that ignores brackets inside quoted strings. It handles nested and repeated `Optional`. The signature and the parameter table both use `format_type`, so both are fixed. - Adds regression tests in `python/tests/test_generate_docs.py` for `Optional[Literal["a", "b"]]`, `Literal["a", "b"] | None`, `dict[str, list[int]] | None`, `Optional` around and inside other generics, and the rendered signature and table row. - Regenerates `docs/content/reference/sdk-reference/python/` and keeps only the annotation hunks. This touches `connected-accounts`, `index`, `mcp`, `session`, `toolkits`, `tools` and `triggers`. Regeneration also picks up unrelated source drift: new `Triggers.create` `type`/`polling_interval` params, session `local_tools`/`local_toolkits`, and moved `View source` line anchors. That drift is left out; the next release regeneration brings it in, rendered correctly.

Alberto Schiabel committed Nov 9, 2026 at 13:49 UTC 2fc8fd7ec65ef71d89b5fb6799fe592bf65e46c8
9 files changed +172 -61
docs/content/reference/sdk-reference/python/connected-accounts.mdx
+3 -3
@@ -127,7 +127,7 @@ composio.connected_accounts.update('ca_abc123', alias='')
127 Update the per-user ACL on a SHARED connected account. Experimental — shape may change in future releases. Only valid on SHARED connections; raises `ComposioAclOnlyForSharedError` on a PRIVATE connection. Omit a parameter to leave it unchanged; pass an empty list to clear an allow/deny list. At least one parameter must be provided.
128
129 ```python
130 -def update_acl(nanoid: str, allow_all_users: bool | None = ..., allowed_user_ids: List[str | None] = ..., not_allowed_user_ids: List[str | None] = ...) -> connected_account_patch_response.ConnectedAccountPatchRes...
130 +def update_acl(nanoid: str, allow_all_users: bool | None = ..., allowed_user_ids: List[str] | None = ..., not_allowed_user_ids: List[str] | None = ...) -> connected_account_patch_response.ConnectedAccountPatchRes...
131 ```
132
133 **Parameters**
@@ -136,8 +136,8 @@ def update_acl(nanoid: str, allow_all_users: bool | None = ..., allowed_user_ids
136 |------|------|
137 | `nanoid` | `str` |
138 | `allow_all_users?` | `bool \| None` |
139 -| `allowed_user_ids?` | `List[str \| None]` |
140 -| `not_allowed_user_ids?` | `List[str \| None]` |
139 +| `allowed_user_ids?` | `List[str] \| None` |
140 +| `not_allowed_user_ids?` | `List[str] \| None` |
141
142 **Returns**
143
docs/content/reference/sdk-reference/python/index.mdx
+4 -4
@@ -49,7 +49,7 @@ result = composio.tools.execute(
49 [View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/_modifiers.py#L278)
50
51 ```python
52 -@before_execute(modifier: BeforeExecute | None = ..., tools: List[str | None] = ..., toolkits: List[str | None] = ...)
52 +@before_execute(modifier: BeforeExecute | None = ..., tools: List[str] | None = ..., toolkits: List[str] | None = ...)
53 def my_modifier(...):
54 ...
55 ```
@@ -59,7 +59,7 @@ def my_modifier(...):
59 [View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/_modifiers.py#L239)
60
61 ```python
62 -@after_execute(modifier: AfterExecute | None = ..., tools: List[str | None] = ..., toolkits: List[str | None] = ...)
62 +@after_execute(modifier: AfterExecute | None = ..., tools: List[str] | None = ..., toolkits: List[str] | None = ...)
63 def my_modifier(...):
64 ...
65 ```
@@ -71,7 +71,7 @@ Build a `Modifier` for the file-upload hook (same scoping pattern as `before_exe
71 [View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/_modifiers.py#L317)
72
73 ```python
74 -@before_file_upload(modifier: BeforeFileUploadLike | None = ..., tools: List[str | None] = ..., toolkits: List[str | None] = ...)
74 +@before_file_upload(modifier: BeforeFileUploadLike | None = ..., tools: List[str] | None = ..., toolkits: List[str] | None = ...)
75 def my_modifier(...):
76 ...
77 ```
@@ -81,7 +81,7 @@ def my_modifier(...):
81 [View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/_modifiers.py#L375)
82
83 ```python
84 -@schema_modifier(modifier: SchemaModifier | None = ..., tools: List[str | None] = ..., toolkits: List[str | None] = ...)
84 +@schema_modifier(modifier: SchemaModifier | None = ..., tools: List[str] | None = ..., toolkits: List[str] | None = ...)
85 def my_modifier(...):
86 ...
87 ```
docs/content/reference/sdk-reference/python/mcp.mdx
+8 -8
@@ -14,7 +14,7 @@ Use a session's MCP endpoint instead: `composio.create(user_id, mcp=True)` retur
14 Create a new MCP server configuration with specified toolkits and authentication settings.
15
16 ```python
17 -def create(name: str, toolkits: List[Union[ConfigToolkit, str]], manually_manage_connections: bool = ..., allowed_tools: List[str | None] = ...) -> MCPCreateResponse
17 +def create(name: str, toolkits: List[Union[ConfigToolkit, str]], manually_manage_connections: bool = ..., allowed_tools: List[str] | None = ...) -> MCPCreateResponse
18 ```
19
20 **Parameters**
@@ -24,7 +24,7 @@ def create(name: str, toolkits: List[Union[ConfigToolkit, str]], manually_manage
24 | `name` | `str` |
25 | `toolkits` | `List[Union[ConfigToolkit, str]]` |
26 | `manually_manage_connections?` | `bool` |
27 -| `allowed_tools?` | `List[str \| None]` |
27 +| `allowed_tools?` | `List[str] \| None` |
28
29 **Returns**
30
@@ -75,7 +75,7 @@ def create(name: str, toolkits: List[Union[ConfigToolkit, str]], manually_manage
75 List MCP servers with optional filtering and pagination.
76
77 ```python
78 -def list(page_no: int | None = ..., limit: int | None = ..., toolkits: str | None = ..., auth_config_ids: str | None = ..., name: str | None = ..., order_by: Literal['created_at', 'updated_at' | None] = ..., order_direction: Literal['asc', 'desc' | None] = ...) -> MCPListResponse
78 +def list(page_no: int | None = ..., limit: int | None = ..., toolkits: str | None = ..., auth_config_ids: str | None = ..., name: str | None = ..., order_by: Literal['created_at', 'updated_at'] | None = ..., order_direction: Literal['asc', 'desc'] | None = ...) -> MCPListResponse
79 ```
80
81 **Parameters**
@@ -87,8 +87,8 @@ def list(page_no: int | None = ..., limit: int | None = ..., toolkits: str | Non
87 | `toolkits?` | `str \| None` |
88 | `auth_config_ids?` | `str \| None` |
89 | `name?` | `str \| None` |
90 -| `order_by?` | `Literal['created_at', 'updated_at' \| None]` |
91 -| `order_direction?` | `Literal['asc', 'desc' \| None]` |
90 +| `order_by?` | `Literal['created_at', 'updated_at'] \| None` |
91 +| `order_direction?` | `Literal['asc', 'desc'] \| None` |
92
93 **Returns**
94
@@ -141,7 +141,7 @@ def get(server_id: str)
141 Update an existing MCP server configuration.
142
143 ```python
144 -def update(server_id: str, name: str | None = ..., toolkits: List[Union[ConfigToolkit, str | None]] = ..., manually_manage_connections: bool | None = ..., allowed_tools: List[str | None] = ...)
144 +def update(server_id: str, name: str | None = ..., toolkits: List[Union[ConfigToolkit, str]] | None = ..., manually_manage_connections: bool | None = ..., allowed_tools: List[str] | None = ...)
145 ```
146
147 **Parameters**
@@ -150,9 +150,9 @@ def update(server_id: str, name: str | None = ..., toolkits: List[Union[ConfigTo
150 |------|------|
151 | `server_id` | `str` |
152 | `name?` | `str \| None` |
153 -| `toolkits?` | `List[Union[ConfigToolkit, str \| None]]` |
153 +| `toolkits?` | `List[Union[ConfigToolkit, str]] \| None` |
154 | `manually_manage_connections?` | `bool \| None` |
155 -| `allowed_tools?` | `List[str \| None]` |
155 +| `allowed_tools?` | `List[str] \| None` |
156
157 **Example**
158
docs/content/reference/sdk-reference/python/session.mdx
+16 -16
@@ -63,14 +63,14 @@ def authorize(toolkit: str, callback_url: str | None = ..., alias: str | None =
63 Get toolkit connection states for the session.
64
65 ```python
66 -def toolkits(toolkits: List[str | None] = ..., next_cursor: str | None = ..., limit: int | None = ..., is_connected: bool | None = ..., search: str | None = ...) -> ToolkitConnectionsDetails
66 +def toolkits(toolkits: List[str] | None = ..., next_cursor: str | None = ..., limit: int | None = ..., is_connected: bool | None = ..., search: str | None = ...) -> ToolkitConnectionsDetails
67 ```
68
69 **Parameters**
70
71 | Name | Type |
72 |------|------|
73 -| `toolkits?` | `List[str \| None]` |
73 +| `toolkits?` | `List[str] \| None` |
74 | `next_cursor?` | `str \| None` |
75 | `limit?` | `int \| None` |
76 | `is_connected?` | `bool \| None` |
@@ -108,7 +108,7 @@ def search(query: str, model: str | None = ...) -> ToolRouterSessionSearchRespon
108 Execute a tool within the session. For custom tools, accepts the full slug (e.g. "LOCAL_GREP") or the original slug (e.g. "GREP") when that original slug is unique across the session's custom tools and toolkits. Custom tools are executed in-process; remote tools are sent to the Composio backend.
109
110 ```python
111 -def execute(tool_slug: str, arguments: Dict[str, Any | None] = ..., account: str | None = ..., input_responses: Dict[str, ToolRouterInputResponse | None] = ..., request_state: str | None = ...) -> ToolRouterSessionExecuteResponse
111 +def execute(tool_slug: str, arguments: Dict[str, Any] | None = ..., account: str | None = ..., input_responses: Dict[str, ToolRouterInputResponse] | None = ..., request_state: str | None = ...) -> ToolRouterSessionExecuteResponse
112 ```
113
114 **Parameters**
@@ -116,9 +116,9 @@ def execute(tool_slug: str, arguments: Dict[str, Any | None] = ..., account: str
116 | Name | Type |
117 |------|------|
118 | `tool_slug` | `str` |
119 -| `arguments?` | `Dict[str, Any \| None]` |
119 +| `arguments?` | `Dict[str, Any] \| None` |
120 | `account?` | `str \| None` |
121 -| `input_responses?` | `Dict[str, ToolRouterInputResponse \| None]` |
121 +| `input_responses?` | `Dict[str, ToolRouterInputResponse] \| None` |
122 | `request_state?` | `str \| None` |
123
124 **Returns**
@@ -137,7 +137,7 @@ def execute(tool_slug: str, arguments: Dict[str, Any | None] = ..., account: str
137 Execute a Composio meta tool (`COMPOSIO_*`) within the session. `execute` also runs meta tools. This method only accepts meta tool slugs, so a typo is a type error instead of a failed request. The call is sent to the Composio backend as is: custom tools named in a `COMPOSIO_MULTI_EXECUTE_TOOL` call are not run in-process here.
138
139 ```python
140 -def execute_meta(slug: ToolRouterSessionMetaToolSlug, arguments: Dict[str, Any | None] = ..., input_responses: Dict[str, ToolRouterInputResponse | None] = ..., request_state: str | None = ...) -> ToolRouterSessionExecuteResponse
140 +def execute_meta(slug: ToolRouterSessionMetaToolSlug, arguments: Dict[str, Any] | None = ..., input_responses: Dict[str, ToolRouterInputResponse] | None = ..., request_state: str | None = ...) -> ToolRouterSessionExecuteResponse
141 ```
142
143 **Parameters**
@@ -145,8 +145,8 @@ def execute_meta(slug: ToolRouterSessionMetaToolSlug, arguments: Dict[str, Any |
145 | Name | Type |
146 |------|------|
147 | `slug` | `ToolRouterSessionMetaToolSlug` |
148 -| `arguments?` | `Dict[str, Any \| None]` |
149 -| `input_responses?` | `Dict[str, ToolRouterInputResponse \| None]` |
148 +| `arguments?` | `Dict[str, Any] \| None` |
149 +| `input_responses?` | `Dict[str, ToolRouterInputResponse] \| None` |
150 | `request_state?` | `str \| None` |
151
152 **Returns**
@@ -243,7 +243,7 @@ def custom_toolkits() -> List[RegisteredCustomToolkit]
243 Proxy an API call through Composio's auth layer.
244
245 ```python
246 -def proxy_execute(toolkit: str, endpoint: str, method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH'], body: Any = ..., parameters: List[Dict[str, Any | None]] = ...) -> ToolRouterSessionProxyExecuteResponse
246 +def proxy_execute(toolkit: str, endpoint: str, method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH'], body: Any = ..., parameters: List[Dict[str, Any]] | None = ...) -> ToolRouterSessionProxyExecuteResponse
247 ```
248
249 **Parameters**
@@ -254,7 +254,7 @@ def proxy_execute(toolkit: str, endpoint: str, method: Literal['GET', 'POST', 'P
254 | `endpoint` | `str` |
255 | `method` | `Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH']` |
256 | `body?` | `Any` |
257 -| `parameters?` | `List[Dict[str, Any \| None]]` |
257 +| `parameters?` | `List[Dict[str, Any]] \| None` |
258
259 **Returns**
260
@@ -271,7 +271,7 @@ def proxy_execute(toolkit: str, endpoint: str, method: Literal['GET', 'POST', 'P
271 Partially update the session configuration. Only the fields provided are changed; omitted fields are preserved. For each policy block `None` removes the stored override (which can increase access: `toolkits=None` restores the unrestricted default, while `toolkits={"enable": []}` denies every app toolkit and is sent as-is). Supplied `tools`, `auth_configs` and `connected_accounts` maps replace the stored map entirely. Inside `manage_connections`, `callback_url=None` removes only the stored callback URL. Experimental `instant` accepts `False` to disable billed access or an object to set its filters; it does not accept `None`. Any object, even one that only sets `return_instant_charge` or `return_prices_in_search`, re-enables Instant usage on a Session set to `False`. `proxy_execute` takes a bool or `{"enable": bool}`; `True` exposes the `COMPOSIO_PROXY_EXECUTE` meta tool, `False` also turns off the sandbox `proxy_execute()` helper, and `None` removes the stored block. `hooks` replaces the whole list of hooks, and `None` removes every hook. `hooks` cannot be combined with `experimental={'session_config_id': ...}` (`hooks=None` counts). By default the request carries no precondition: the last writer wins. Pass `expected_config_version` (for example this object's `config_version`) to make the update conditional: the API then applies it only when the stored version still matches, and a concurrent change raises `SessionConfigConflictError` (HTTP 409) instead of being overwritten. The API must support the `expected_config_version` field; otherwise it rejects the request with a 400. `expected_config_version=False` is the same as omitting it. The PATCH is never retried by the transport, so a 409 is reported exactly once. On conflict this object stays unchanged: re-fetch the session with `composio.sessions.use(session_id)` and retry against the fresh `config_version`. `config`, `config_version` and `preload` are refreshed in place only after a successful response, and the updated `config` is returned. `workbench` is a backwards-compatible alias for `sandbox`. Prefer `sandbox` in new code. All other parameters use the same types as the generated `client.tool_router.session.patch()` method.
272
273 ```python
274 -def update(toolkits: Union[session_patch_params.Toolkits | None, 'Omit'] = ..., instant: Union[Literal[False], ToolRouterInstantConfig, 'Omit'] = ..., tools: Union[Dict[str, session_patch_params.Tools | None], 'Omit'] = ..., tags: Union[session_patch_params.Tags | None, 'Omit'] = ..., auth_configs: Union[Dict[str, str | None], 'Omit'] = ..., connected_accounts: Union[Dict[str, SequenceNotStr[str | None]], 'Omit'] = ..., manage_connections: Union[session_patch_params.ManageConnections | None, ToolRouterUpdateManageConnectionsConfig | None, 'Omit'] = ..., sandbox: Union[session_patch_params.Workbench | None, 'Omit'] = ..., workbench: Union[session_patch_params.Workbench | None, 'Omit'] = ..., multi_account: Union[session_patch_params.MultiAccount | None, ToolRouterUpdateMultiAccountConfig | None, 'Omit'] = ..., proxy_execute: Union[Union[bool, ToolRouterProxyExecuteConfig | None], 'Omit'] = ..., hooks: Union[List[ToolRouterHook | None], 'Omit'] = ..., preload: Union[session_patch_params.Preload | None, 'Omit'] = ..., search: Union[session_patch_params.Search | None, 'Omit'] = ..., execute: Union[session_patch_params.Execute | None, 'Omit'] = ..., experimental: Union[session_patch_params.Experimental | None, ToolRouterUpdateExperimentalConfig | None, 'Omit'] = ..., expected_config_version: Union[int, None, Literal[False]] = ...) -> ToolRouterSessionConfig
274 +def update(toolkits: Union[session_patch_params.Toolkits | None, 'Omit'] = ..., instant: Union[Literal[False], ToolRouterInstantConfig, 'Omit'] = ..., tools: Union[Dict[str, session_patch_params.Tools] | None, 'Omit'] = ..., tags: Union[session_patch_params.Tags | None, 'Omit'] = ..., auth_configs: Union[Dict[str, str] | None, 'Omit'] = ..., connected_accounts: Union[Dict[str, SequenceNotStr[str]] | None, 'Omit'] = ..., manage_connections: Union[session_patch_params.ManageConnections | None, ToolRouterUpdateManageConnectionsConfig | None, 'Omit'] = ..., sandbox: Union[session_patch_params.Workbench | None, 'Omit'] = ..., workbench: Union[session_patch_params.Workbench | None, 'Omit'] = ..., multi_account: Union[session_patch_params.MultiAccount | None, ToolRouterUpdateMultiAccountConfig | None, 'Omit'] = ..., proxy_execute: Union[Union[bool, ToolRouterProxyExecuteConfig] | None, 'Omit'] = ..., hooks: Union[List[ToolRouterHook] | None, 'Omit'] = ..., preload: Union[session_patch_params.Preload | None, 'Omit'] = ..., search: Union[session_patch_params.Search | None, 'Omit'] = ..., execute: Union[session_patch_params.Execute | None, 'Omit'] = ..., experimental: Union[session_patch_params.Experimental | None, ToolRouterUpdateExperimentalConfig | None, 'Omit'] = ..., expected_config_version: Union[int, None, Literal[False]] = ...) -> ToolRouterSessionConfig
275 ```
276
277 **Parameters**
@@ -280,16 +280,16 @@ def update(toolkits: Union[session_patch_params.Toolkits | None, 'Omit'] = ...,
280 |------|------|
281 | `toolkits?` | `Union[session_patch_params.Toolkits \| None, 'Omit']` |
282 | `instant?` | `Union[Literal[False], ToolRouterInstantConfig, 'Omit']` |
283 -| `tools?` | `Union[Dict[str, session_patch_params.Tools \| None], 'Omit']` |
283 +| `tools?` | `Union[Dict[str, session_patch_params.Tools] \| None, 'Omit']` |
284 | `tags?` | `Union[session_patch_params.Tags \| None, 'Omit']` |
285 -| `auth_configs?` | `Union[Dict[str, str \| None], 'Omit']` |
286 -| `connected_accounts?` | `Union[Dict[str, SequenceNotStr[str \| None]], 'Omit']` |
285 +| `auth_configs?` | `Union[Dict[str, str] \| None, 'Omit']` |
286 +| `connected_accounts?` | `Union[Dict[str, SequenceNotStr[str]] \| None, 'Omit']` |
287 | `manage_connections?` | `Union[session_patch_params.ManageConnections \| None, ToolRouterUpdateManageConnectionsConfig \| None, 'Omit']` |
288 | `sandbox?` | `Union[session_patch_params.Workbench \| None, 'Omit']` |
289 | `workbench?` | `Union[session_patch_params.Workbench \| None, 'Omit']` |
290 | `multi_account?` | `Union[session_patch_params.MultiAccount \| None, ToolRouterUpdateMultiAccountConfig \| None, 'Omit']` |
291 -| `proxy_execute?` | `Union[Union[bool, ToolRouterProxyExecuteConfig \| None], 'Omit']` |
292 -| `hooks?` | `Union[List[ToolRouterHook \| None], 'Omit']` |
291 +| `proxy_execute?` | `Union[Union[bool, ToolRouterProxyExecuteConfig] \| None, 'Omit']` |
292 +| `hooks?` | `Union[List[ToolRouterHook] \| None, 'Omit']` |
293 | `preload?` | `Union[session_patch_params.Preload \| None, 'Omit']` |
294 | `search?` | `Union[session_patch_params.Search \| None, 'Omit']` |
295 | `execute?` | `Union[session_patch_params.Execute \| None, 'Omit']` |
docs/content/reference/sdk-reference/python/toolkits.mdx
+6 -6
@@ -10,7 +10,7 @@ description: "Toolkits are a collectiono of tools that can be used to perform va
10 List all toolkits.
11
12 ```python
13 -def list(category: str | None = ..., cursor: str | None = ..., limit: float | None = ..., sort_by: Literal['usage', 'alphabetically' | None] = ..., managed_by: Literal['composio', 'all', 'project' | None] = ...) -> toolkit_list_response.ToolkitListResponse
13 +def list(category: str | None = ..., cursor: str | None = ..., limit: float | None = ..., sort_by: Literal['usage', 'alphabetically'] | None = ..., managed_by: Literal['composio', 'all', 'project'] | None = ...) -> toolkit_list_response.ToolkitListResponse
14 ```
15
16 **Parameters**
@@ -20,8 +20,8 @@ def list(category: str | None = ..., cursor: str | None = ..., limit: float | No
20 | `category?` | `str \| None` |
21 | `cursor?` | `str \| None` |
22 | `limit?` | `float \| None` |
23 -| `sort_by?` | `Literal['usage', 'alphabetically' \| None]` |
24 -| `managed_by?` | `Literal['composio', 'all', 'project' \| None]` |
23 +| `sort_by?` | `Literal['usage', 'alphabetically'] \| None` |
24 +| `managed_by?` | `Literal['composio', 'all', 'project'] \| None` |
25
26 **Returns**
27
@@ -53,7 +53,7 @@ def get(slug: str | None = ..., query: toolkit_list_params.ToolkitListParams | N
53 Fetch several toolkits by slug in one request.
54
55 ```python
56 -def get_many(slugs: Sequence[str], category: str | None = ..., managed_by: Literal['composio', 'all', 'project' | None] = ..., sort_by: Literal['usage', 'alphabetically' | None] = ..., limit: float | None = ..., cursor: str | None = ...) -> List[Any]
56 +def get_many(slugs: Sequence[str], category: str | None = ..., managed_by: Literal['composio', 'all', 'project'] | None = ..., sort_by: Literal['usage', 'alphabetically'] | None = ..., limit: float | None = ..., cursor: str | None = ...) -> List[Any]
57 ```
58
59 **Parameters**
@@ -62,8 +62,8 @@ def get_many(slugs: Sequence[str], category: str | None = ..., managed_by: Liter
62 |------|------|
63 | `slugs` | `Sequence[str]` |
64 | `category?` | `str \| None` |
65 -| `managed_by?` | `Literal['composio', 'all', 'project' \| None]` |
66 -| `sort_by?` | `Literal['usage', 'alphabetically' \| None]` |
65 +| `managed_by?` | `Literal['composio', 'all', 'project'] \| None` |
66 +| `sort_by?` | `Literal['usage', 'alphabetically'] \| None` |
67 | `limit?` | `float \| None` |
68 | `cursor?` | `str \| None` |
69
docs/content/reference/sdk-reference/python/tools.mdx
+10 -10
@@ -34,17 +34,17 @@ def get_raw_composio_tool_by_slug(slug: str) -> Tool
34 Get a list of tool schemas based on the provided filters.
35
36 ```python
37 -def get_raw_composio_tools(tools: list[str | None] = ..., search: str | None = ..., toolkits: list[str | None] = ..., scopes: List[str | None] = ..., limit: int | None = ...) -> list[Tool]
37 +def get_raw_composio_tools(tools: list[str] | None = ..., search: str | None = ..., toolkits: list[str] | None = ..., scopes: List[str] | None = ..., limit: int | None = ...) -> list[Tool]
38 ```
39
40 **Parameters**
41
42 | Name | Type |
43 |------|------|
44 -| `tools?` | `list[str \| None]` |
44 +| `tools?` | `list[str] \| None` |
45 | `search?` | `str \| None` |
46 -| `toolkits?` | `list[str \| None]` |
47 -| `scopes?` | `List[str \| None]` |
46 +| `toolkits?` | `list[str] \| None` |
47 +| `scopes?` | `List[str] \| None` |
48 | `limit?` | `int \| None` |
49
50 **Returns**
@@ -106,7 +106,7 @@ meta_tools = tools_model.get_raw_tool_router_meta_tools(
106 Get a tool or list of tools based on the provided arguments. The return type is automatically inferred based on the provider's generic parameters. For example: - OpenAIProvider -> list[ChatCompletionToolParam] - AnthropicProvider -> list[ToolParam] - CustomProvider[MyTool, list[MyTool]] -> list[MyTool]
107
108 ```python
109 -def get(user_id: str, slug: str | None = ..., tools: list[str | None] = ..., search: str | None = ..., toolkits: list[str | None] = ..., scopes: List[str | None] = ..., modifiers: Modifiers | None = ..., limit: int | None = ...) -> TToolCollection
109 +def get(user_id: str, slug: str | None = ..., tools: list[str] | None = ..., search: str | None = ..., toolkits: list[str] | None = ..., scopes: List[str] | None = ..., modifiers: Modifiers | None = ..., limit: int | None = ...) -> TToolCollection
110 ```
111
112 **Parameters**
@@ -115,10 +115,10 @@ def get(user_id: str, slug: str | None = ..., tools: list[str | None] = ..., sea
115 |------|------|
116 | `user_id` | `str` |
117 | `slug?` | `str \| None` |
118 -| `tools?` | `list[str \| None]` |
118 +| `tools?` | `list[str] \| None` |
119 | `search?` | `str \| None` |
120 -| `toolkits?` | `list[str \| None]` |
121 -| `scopes?` | `List[str \| None]` |
120 +| `toolkits?` | `list[str] \| None` |
121 +| `scopes?` | `List[str] \| None` |
122 | `modifiers?` | `Modifiers \| None` |
123 | `limit?` | `int \| None` |
124
@@ -162,7 +162,7 @@ def execute(slug: str, arguments: Dict, connected_account_id: str | None = ...,
162 Proxy a tool call to the Composio API. `user_id` is the user the connected account belongs to. Projects with 2FA enabled check it against the connected account and may require it.
163
164 ```python
165 -def proxy(endpoint: str, method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD'], body: object | None = ..., connected_account_id: str | None = ..., parameters: List[tool_proxy_params.Parameter | None] = ..., custom_connection_data: tool_proxy_params.CustomConnectionData | None = ..., user_id: str | None = ...) -> tool_proxy_response.ToolProxyResponse
165 +def proxy(endpoint: str, method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD'], body: object | None = ..., connected_account_id: str | None = ..., parameters: List[tool_proxy_params.Parameter] | None = ..., custom_connection_data: tool_proxy_params.CustomConnectionData | None = ..., user_id: str | None = ...) -> tool_proxy_response.ToolProxyResponse
166 ```
167
168 **Parameters**
@@ -173,7 +173,7 @@ def proxy(endpoint: str, method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH'
173 | `method` | `Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD']` |
174 | `body?` | `object \| None` |
175 | `connected_account_id?` | `str \| None` |
176 -| `parameters?` | `List[tool_proxy_params.Parameter \| None]` |
176 +| `parameters?` | `List[tool_proxy_params.Parameter] \| None` |
177 | `custom_connection_data?` | `tool_proxy_params.CustomConnectionData \| None` |
178 | `user_id?` | `str \| None` |
179
docs/content/reference/sdk-reference/python/triggers.mdx
+12 -12
@@ -10,7 +10,7 @@ description: "Triggers (instance) class"
10 Create or update the project webhook subscription used for webhook delivery. If a subscription already exists, the first subscription is updated. Otherwise a new subscription is created. By default this subscribes to V3 trigger message events.
11
12 ```python
13 -def set_webhook_subscription(webhook_url: str, enabled_events: Sequence[str | None] = ..., version: Union[WebhookVersion, str] = ...) -> WebhookSubscription
13 +def set_webhook_subscription(webhook_url: str, enabled_events: Sequence[str] | None = ..., version: Union[WebhookVersion, str] = ...) -> WebhookSubscription
14 ```
15
16 **Parameters**
@@ -18,7 +18,7 @@ def set_webhook_subscription(webhook_url: str, enabled_events: Sequence[str | No
18 | Name | Type |
19 |------|------|
20 | `webhook_url` | `str` |
21 -| `enabled_events?` | `Sequence[str \| None]` |
21 +| `enabled_events?` | `Sequence[str] \| None` |
22 | `version?` | `Union[WebhookVersion, str]` |
23
24 **Returns**
@@ -60,17 +60,17 @@ def get_type(slug: str) -> TriggersTypeRetrieveResponse
60 List all active triggers
61
62 ```python
63 -def list_active(trigger_ids: list[str | None] = ..., trigger_names: list[str | None] = ..., auth_config_ids: list[str | None] = ..., connected_account_ids: list[str | None] = ..., show_disabled: bool | None = ..., limit: int | None = ..., cursor: str | None = ...)
63 +def list_active(trigger_ids: list[str] | None = ..., trigger_names: list[str] | None = ..., auth_config_ids: list[str] | None = ..., connected_account_ids: list[str] | None = ..., show_disabled: bool | None = ..., limit: int | None = ..., cursor: str | None = ...)
64 ```
65
66 **Parameters**
67
68 | Name | Type |
69 |------|------|
70 -| `trigger_ids?` | `list[str \| None]` |
71 -| `trigger_names?` | `list[str \| None]` |
72 -| `auth_config_ids?` | `list[str \| None]` |
73 -| `connected_account_ids?` | `list[str \| None]` |
70 +| `trigger_ids?` | `list[str] \| None` |
71 +| `trigger_names?` | `list[str] \| None` |
72 +| `auth_config_ids?` | `list[str] \| None` |
73 +| `connected_account_ids?` | `list[str] \| None` |
74 | `show_disabled?` | `bool \| None` |
75 | `limit?` | `int \| None` |
76 | `cursor?` | `str \| None` |
@@ -82,7 +82,7 @@ def list_active(trigger_ids: list[str | None] = ..., trigger_names: list[str | N
82 List all the trigger types.
83
84 ```python
85 -def list(cursor: str | None = ..., limit: int | None = ..., toolkit_slugs: list[str | None] = ...)
85 +def list(cursor: str | None = ..., limit: int | None = ..., toolkit_slugs: list[str] | None = ...)
86 ```
87
88 **Parameters**
@@ -91,7 +91,7 @@ def list(cursor: str | None = ..., limit: int | None = ..., toolkit_slugs: list[
91 |------|------|
92 | `cursor?` | `str \| None` |
93 | `limit?` | `int \| None` |
94 -| `toolkit_slugs?` | `list[str \| None]` |
94 +| `toolkit_slugs?` | `list[str] \| None` |
95
96 ---
97
@@ -100,7 +100,7 @@ def list(cursor: str | None = ..., limit: int | None = ..., toolkit_slugs: list[
100 Create a trigger instance
101
102 ```python
103 -def create(slug: str, user_id: str | None = ..., connected_account_id: str | None = ..., trigger_config: Dict[str, Any | None] = ..., type: Literal['webhook', 'poll' | None] = ..., polling_interval: int | None = ...) -> trigger_instance_upsert_response.TriggerInstanceUpsertRes...
103 +def create(slug: str, user_id: str | None = ..., connected_account_id: str | None = ..., trigger_config: Dict[str, Any] | None = ..., type: Literal['webhook', 'poll'] | None = ..., polling_interval: int | None = ...) -> trigger_instance_upsert_response.TriggerInstanceUpsertRes...
104 ```
105
106 **Parameters**
@@ -110,8 +110,8 @@ def create(slug: str, user_id: str | None = ..., connected_account_id: str | Non
110 | `slug` | `str` |
111 | `user_id?` | `str \| None` |
112 | `connected_account_id?` | `str \| None` |
113 -| `trigger_config?` | `Dict[str, Any \| None]` |
114 -| `type?` | `Literal['webhook', 'poll' \| None]` |
113 +| `trigger_config?` | `Dict[str, Any] \| None` |
114 +| `type?` | `Literal['webhook', 'poll'] \| None` |
115 | `polling_interval?` | `int \| None` |
116
117 **Returns**
python/scripts/generate-docs.py
+49 -2
@@ -143,6 +143,53 @@ def get_source_link(obj: griffe_t.Object) -> str | None:
143 return f"{GITHUB_BASE}/{rel_path}#L{line}"
144
145
146 +def _matching_bracket(text: str, open_index: int) -> int | None:
147 + """Return the index of the ``]`` closing the ``[`` at ``open_index``.
148 +
149 + Brackets inside quoted strings, such as ``Literal['[']``, are ignored.
150 + """
151 + depth = 0
152 + quote: str | None = None
153 + escaped = False
154 + for index in range(open_index, len(text)):
155 + char = text[index]
156 + if quote is not None:
157 + if escaped:
158 + escaped = False
159 + elif char == "\\":
160 + escaped = True
161 + elif char == quote:
162 + quote = None
163 + elif char in ("'", '"'):
164 + quote = char
165 + elif char == "[":
166 + depth += 1
167 + elif char == "]":
168 + depth -= 1
169 + if depth == 0:
170 + return index
171 + return None
172 +
173 +
174 +def _rewrite_subscript(type_str: str, name: str, render: t.Callable[[str], str]) -> str:
175 + """Replace every ``name[...]`` with ``render(...)``, honoring nested brackets.
176 +
177 + The outermost occurrence is rewritten first, and the search restarts from
178 + the beginning so occurrences nested in its arguments are rewritten too.
179 + """
180 + pattern = re.compile(rf"(?<!\w){re.escape(name)}\[")
181 + while match := pattern.search(type_str):
182 + open_index = match.end() - 1
183 + close_index = _matching_bracket(type_str, open_index)
184 + if close_index is None:
185 + break
186 + inner = type_str[open_index + 1 : close_index]
187 + type_str = (
188 + type_str[: match.start()] + render(inner) + type_str[close_index + 1 :]
189 + )
190 + return type_str
191 +
192 +
193 def format_type(annotation: Any, *, max_length: int | None = 60) -> str:
194 """Format a type annotation to readable string.
195
@@ -159,9 +206,9 @@ def format_type(annotation: Any, *, max_length: int | None = 60) -> str:
206 type_str = type_str.replace("composio.client.types.", "")
207 type_str = re.sub(r"\bt\.", "", type_str)
208 type_str = re.sub(r"\bte\.", "", type_str) # typing_extensions alias
162 - type_str = re.sub(r"Optional\[([^\]]+)\]", r"\1 | None", type_str)
209 + type_str = _rewrite_subscript(type_str, "Optional", lambda inner: f"{inner} | None")
210 # Clean up Unpack to just show the type
164 - type_str = re.sub(r"Unpack\[([^\]]+)\]", r"\1", type_str)
211 + type_str = _rewrite_subscript(type_str, "Unpack", lambda inner: inner)
212
213 # Truncate very long types
214 if max_length is not None and len(type_str) > max_length:
python/tests/test_generate_docs.py
+64
@@ -191,3 +191,67 @@ def test_generated_examples_do_not_keep_nested_markdown_fences():
191 'result = composio.tools.get_raw_tool_router_meta_tools("session_123")\n'
192 "print(result)"
193 ]
194 +
195 +
196 +@pytest.mark.parametrize(
197 + ("annotation", "expected"),
198 + [
199 + ('t.Optional[t.Literal["a", "b"]]', 'Literal["a", "b"] | None'),
200 + ('Literal["a", "b"] | None', 'Literal["a", "b"] | None'),
201 + ("Optional[dict[str, list[int]]]", "dict[str, list[int]] | None"),
202 + ("dict[str, list[int]] | None", "dict[str, list[int]] | None"),
203 + ("t.Optional[t.List[str]]", "List[str] | None"),
204 + ("t.Optional[t.Dict[str, t.Any]]", "Dict[str, Any] | None"),
205 + (
206 + "t.Optional[t.List[t.Union[ConfigToolkit, str]]]",
207 + "List[Union[ConfigToolkit, str]] | None",
208 + ),
209 + ("t.List[t.Optional[t.Literal['x']]]", "List[Literal['x'] | None]"),
210 + ("Optional[Literal[']', '[']]", "Literal[']', '['] | None"),
211 + ("te.Unpack[SDKConfig]", "SDKConfig"),
212 + ],
213 +)
214 +def test_format_type_keeps_nested_generics_intact(annotation, expected):
215 + generate_docs = load_generate_docs_module()
216 +
217 + assert generate_docs.format_type(annotation, max_length=None) == expected
218 +
219 +
220 +def test_generated_mdx_renders_optional_literal_in_signature_and_table():
221 + generate_docs = load_generate_docs_module()
222 +
223 + rendered_type = generate_docs.format_type(
224 + "t.Optional[t.Literal['webhook', 'poll']]", max_length=None
225 + )
226 + info = {
227 + "name": "Triggers",
228 + "access": "composio.triggers",
229 + "source_link": None,
230 + "description": "Trigger management.",
231 + "deprecated": None,
232 + "properties": [],
233 + "methods": [
234 + {
235 + "name": "create",
236 + "source_link": None,
237 + "description": "Create a trigger instance.",
238 + "parameters": [
239 + {
240 + "name": "type",
241 + "type": rendered_type,
242 + "optional": True,
243 + "description": "",
244 + }
245 + ],
246 + "return_type": "Any",
247 + "return_description": "",
248 + "raises": [],
249 + "examples": [],
250 + }
251 + ],
252 + }
253 +
254 + mdx = generate_docs.generate_class_mdx(info)
255 +
256 + assert "def create(type: Literal['webhook', 'poll'] | None = ...)" in mdx
257 + assert "| `type?` | `Literal['webhook', 'poll'] \\| None` |" in mdx