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 272 lines 8.73 KB
Raw
1 """Regression tests for SDK reference generation."""
2
3 from __future__ import annotations
4
5 import ast
6 import importlib.util
7 import re
8 from pathlib import Path
9
10 import pytest
11
12 from composio.core.models.triggers import Triggers
13
14
15 def load_generate_docs_module():
16 script_path = Path(__file__).resolve().parents[1] / "scripts" / "generate-docs.py"
17 spec = importlib.util.spec_from_file_location("_generate_docs", script_path)
18 assert spec is not None
19 assert spec.loader is not None
20
21 module = importlib.util.module_from_spec(spec)
22 spec.loader.exec_module(module)
23 return module
24
25
26 def test_triggers_parse_generated_example_is_valid_python():
27 generate_docs = load_generate_docs_module()
28
29 parsed = generate_docs.parse_docstring(Triggers.parse.__doc__)
30 assert parsed["examples"], "Triggers.parse() must keep its public example"
31
32 try:
33 ast.parse(parsed["examples"][0])
34 except SyntaxError as exc:
35 pytest.fail(
36 "Triggers.parse() generated SDK reference example must be "
37 f"copy-pasteable Python: {exc}"
38 )
39
40
41 def test_parse_docstring_extracts_raises_after_returns():
42 generate_docs = load_generate_docs_module()
43
44 parsed = generate_docs.parse_docstring(
45 """
46 Verify a webhook.
47
48 :param secret: The webhook secret
49 :return: VerifyWebhookResult containing version and payload
50 :raises WebhookSignatureVerificationError: If the signature verification fails
51 :raises WebhookPayloadError: If the payload cannot be parsed
52 """
53 )
54
55 assert parsed["returns"] == "VerifyWebhookResult containing version and payload"
56 assert parsed["raises"] == [
57 {
58 "exception": "WebhookSignatureVerificationError",
59 "description": "If the signature verification fails",
60 },
61 {
62 "exception": "WebhookPayloadError",
63 "description": "If the payload cannot be parsed",
64 },
65 ]
66
67
68 def test_parse_docstring_keeps_raises_continuation_lines():
69 generate_docs = load_generate_docs_module()
70
71 parsed = generate_docs.parse_docstring(
72 """
73 Fetch a tool.
74
75 :raises ToolNotFoundError: when the backend reports the slug as unknown
76 (404, or 400 for a malformed slug). Any other client error is
77 re-raised unchanged.
78 """
79 )
80
81 assert parsed["raises"] == [
82 {
83 "exception": "ToolNotFoundError",
84 "description": (
85 "when the backend reports the slug as unknown (404, or 400 for a "
86 "malformed slug). Any other client error is re-raised unchanged."
87 ),
88 }
89 ]
90
91
92 def test_parse_docstring_normalizes_double_backtick_literals():
93 generate_docs = load_generate_docs_module()
94
95 parsed = generate_docs.parse_docstring(
96 """
97 Parse a webhook. Pass ``body=`` explicitly. Uses ``verify_secret``.
98
99 :return: the normalized payload for ``verify_secret``
100 :raises ValidationError: If ``verify_secret`` is empty
101 """
102 )
103
104 assert "``" not in parsed["description"]
105 assert "`verify_secret`" in parsed["description"]
106 assert "`verify_secret`" in parsed["returns"]
107 assert "`verify_secret`" in parsed["raises"][0]["description"]
108
109
110 def test_parse_docstring_normalizes_rst_roles():
111 generate_docs = load_generate_docs_module()
112
113 parsed = generate_docs.parse_docstring(
114 """
115 Build a ``Modifier`` for the file-upload hook (same scoping pattern as
116 :func:`before_execute`). Raises :class:`~composio.exceptions.FileUploadAbortedError`
117 on abort; see :meth:`composio.core.models.tools.Tools.execute`.
118 """
119 )
120
121 description = parsed["description"]
122 assert "`Modifier`" in description
123 assert ":func:" not in description
124 assert "`before_execute`" in description
125 assert ":class:" not in description
126 assert "`FileUploadAbortedError`" in description
127 assert "`composio.core.models.tools.Tools.execute`" in description
128
129
130 def test_generated_mdx_renders_raises_section_without_raw_directives():
131 generate_docs = load_generate_docs_module()
132
133 info = {
134 "name": "Triggers",
135 "access": "composio.triggers",
136 "source_link": None,
137 "description": "Trigger management.",
138 "deprecated": None,
139 "properties": [],
140 "methods": [
141 {
142 "name": "verify_webhook",
143 "source_link": None,
144 "description": "Verify a signed webhook request.",
145 "parameters": [],
146 "return_type": "VerifyWebhookResult",
147 "return_description": "The verified payload",
148 "raises": [
149 {
150 "exception": "WebhookSignatureVerificationError",
151 "description": "If the signature verification fails",
152 },
153 {"exception": "WebhookPayloadError", "description": ""},
154 ],
155 "examples": [],
156 }
157 ],
158 }
159
160 mdx = generate_docs.generate_class_mdx(info)
161
162 # Strip legitimate ```python fences before checking for stray reST markup.
163 prose = re.sub(r"```.*?```", "", mdx, flags=re.DOTALL)
164
165 assert ":raises" not in mdx
166 assert "``" not in prose
167 assert "**Raises**" in mdx
168 assert (
169 "- `WebhookSignatureVerificationError` — If the signature verification "
170 "fails" in mdx
171 )
172 assert "- `WebhookPayloadError`" in mdx
173
174
175 def test_generated_examples_do_not_keep_nested_markdown_fences():
176 generate_docs = load_generate_docs_module()
177
178 parsed = generate_docs.parse_docstring(
179 """
180 Fetch SDK data.
181
182 Example:
183 ```python
184 result = composio.tools.get_raw_tool_router_meta_tools("session_123")
185 print(result)
186 ```
187 """
188 )
189
190 assert parsed["examples"] == [
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_keyword_only_parameters_with_descriptions():
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 "kind": "keyword-only",
242 "type": rendered_type,
243 "optional": True,
244 "description": "",
245 },
246 {
247 "name": "polling_interval",
248 "kind": "keyword-only",
249 "type": "int | None",
250 "optional": True,
251 "description": 'Minutes between polls. Overrides `trigger_config["interval"]`.',
252 },
253 ],
254 "return_type": "Any",
255 "return_description": "",
256 "raises": [],
257 "examples": [],
258 }
259 ],
260 }
261
262 mdx = generate_docs.generate_class_mdx(info)
263
264 assert (
265 "def create(*, type: Literal['webhook', 'poll'] | None = ..., "
266 "polling_interval: int | None = ...)" in mdx
267 )
268 assert "| `type?` | `Literal['webhook', 'poll'] \\| None` |" in mdx
269 assert (
270 "| `polling_interval?` | `int \\| None` | Minutes between polls. "
271 'Overrides `trigger_config["interval"]`. |' in mdx
272 )