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 22, 15:45 UTC
fix: resolve mypy errors in Python docs generator
- Handle filepath as Path | list[Path] correctly - Add explicit Optional type annotation for prop_to_class parameter 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sushmithamallesh committed
Jan 6, 2026 at 18:37 UTC
da031aa7fa5cc98d119d4f37f8c0684dd5468dbe
1 file changed
+94
-53
python/scripts/generate-docs.py
+94
-53
@@ -25,7 +25,14 @@ except ImportError:
25
# Paths
26
SCRIPT_DIR = Path(__file__).parent
27
PACKAGE_DIR = SCRIPT_DIR.parent
28
-OUTPUT_DIR = PACKAGE_DIR.parent / "fumadocs" / "content" / "reference" / "sdk-reference" / "python"
28
+OUTPUT_DIR = (
29
+ PACKAGE_DIR.parent
30
+ / "fumadocs"
31
+ / "content"
32
+ / "reference"
33
+ / "sdk-reference"
34
+ / "python"
35
+)
36
37
# GitHub base URL for source links
38
GITHUB_BASE = "https://github.com/composiohq/composio/blob/next/python"
@@ -67,8 +74,8 @@ def to_kebab_case(name: str) -> str:
74
75
def escape_yaml_string(s: str) -> str:
76
"""Escape a string for YAML frontmatter."""
70
- if any(c in s for c in [':', '"', "'", '\n', '#', '{', '}']):
71
- return f'"{s.replace(chr(34), chr(92)+chr(34))}"'
77
+ if any(c in s for c in [":", '"', "'", "\n", "#", "{", "}"]):
78
+ return f'"{s.replace(chr(34), chr(92) + chr(34))}"'
79
return s
80
81
@@ -77,7 +84,15 @@ def get_source_link(obj: griffe.Object) -> str | None:
84
if not hasattr(obj, "filepath") or not obj.filepath:
85
return None
86
try:
80
- rel_path = Path(obj.filepath).relative_to(PACKAGE_DIR)
87
+ raw_filepath = obj.filepath
88
+ # Handle case where filepath might be a list (griffe edge case)
89
+ if isinstance(raw_filepath, list):
90
+ resolved_path: Path | None = raw_filepath[0] if raw_filepath else None
91
+ else:
92
+ resolved_path = raw_filepath
93
+ if not resolved_path:
94
+ return None
95
+ rel_path = resolved_path.relative_to(PACKAGE_DIR)
96
except ValueError:
97
return None
98
line = obj.lineno if hasattr(obj, "lineno") and obj.lineno else 1
@@ -93,11 +108,11 @@ def format_type(annotation: Any) -> str:
108
# Clean up common prefixes
109
type_str = type_str.replace("typing.", "").replace("typing_extensions.", "")
110
type_str = type_str.replace("composio.client.types.", "")
96
- type_str = re.sub(r'\bt\.', '', type_str)
97
- type_str = re.sub(r'\bte\.', '', type_str) # typing_extensions alias
98
- type_str = re.sub(r'Optional\[([^\]]+)\]', r'\1 | None', type_str)
111
+ type_str = re.sub(r"\bt\.", "", type_str)
112
+ type_str = re.sub(r"\bte\.", "", type_str) # typing_extensions alias
113
+ type_str = re.sub(r"Optional\[([^\]]+)\]", r"\1 | None", type_str)
114
# Clean up Unpack to just show the type
100
- type_str = re.sub(r'Unpack\[([^\]]+)\]', r'\1', type_str)
115
+ type_str = re.sub(r"Unpack\[([^\]]+)\]", r"\1", type_str)
116
117
# Truncate very long types
118
if len(type_str) > 60:
@@ -164,7 +179,9 @@ def parse_docstring(docstring: str | None) -> dict[str, Any]:
179
}
180
181
167
-def extract_class_info(cls: griffe.Class, class_name: str, config: dict) -> dict[str, Any]:
182
+def extract_class_info(
183
+ cls: griffe.Class, class_name: str, config: dict
184
+) -> dict[str, Any]:
185
"""Extract documentation from a class."""
186
doc = parse_docstring(cls.docstring.value if cls.docstring else None)
187
@@ -183,49 +200,63 @@ def extract_class_info(cls: griffe.Class, class_name: str, config: dict) -> dict
200
continue
201
if isinstance(member, griffe.Attribute):
202
attr_doc = member.docstring.value if member.docstring else ""
186
- info["properties"].append({
187
- "name": name,
188
- "type": format_type(member.annotation),
189
- "description": attr_doc.strip() if attr_doc else "",
190
- })
203
+ info["properties"].append(
204
+ {
205
+ "name": name,
206
+ "type": format_type(member.annotation),
207
+ "description": attr_doc.strip() if attr_doc else "",
208
+ }
209
+ )
210
211
# Extract methods
212
for name, member in cls.members.items():
213
if name.startswith("_"):
214
continue
215
if isinstance(member, griffe.Function):
197
- method_doc = parse_docstring(member.docstring.value if member.docstring else None)
216
+ method_doc = parse_docstring(
217
+ member.docstring.value if member.docstring else None
218
+ )
219
220
params = []
221
for p in member.parameters:
222
if p.name in ("self", "cls"):
223
continue
203
- params.append({
204
- "name": p.name,
205
- "type": format_type(p.annotation),
206
- "optional": p.default is not None,
207
- "description": method_doc["params"].get(p.name, ""),
208
- })
209
-
210
- info["methods"].append({
211
- "name": name,
212
- "source_link": get_source_link(member),
213
- "description": method_doc["description"],
214
- "parameters": params,
215
- "return_type": format_type(member.returns),
216
- "return_description": method_doc["returns"],
217
- "examples": method_doc["examples"],
218
- })
224
+ params.append(
225
+ {
226
+ "name": p.name,
227
+ "type": format_type(p.annotation),
228
+ "optional": p.default is not None,
229
+ "description": method_doc["params"].get(p.name, ""),
230
+ }
231
+ )
232
+
233
+ info["methods"].append(
234
+ {
235
+ "name": name,
236
+ "source_link": get_source_link(member),
237
+ "description": method_doc["description"],
238
+ "parameters": params,
239
+ "return_type": format_type(member.returns),
240
+ "return_description": method_doc["returns"],
241
+ "examples": method_doc["examples"],
242
+ }
243
+ )
244
245
return info
246
247
223
-def generate_class_mdx(info: dict[str, Any], prop_to_class: dict[str, str] = None) -> str:
248
+def generate_class_mdx(
249
+ info: dict[str, Any], prop_to_class: dict[str, str] | None = None
250
+) -> str:
251
"""Generate MDX for a class."""
252
lines = []
253
254
# Frontmatter
228
- desc = info["description"].split("\n")[0] if info["description"] else f"{info['name']} class"
255
+ desc = (
256
+ info["description"].split("\n")[0]
257
+ if info["description"]
258
+ else f"{info['name']} class"
259
+ )
260
if len(desc) > 150:
261
desc = desc[:147] + "..."
262
@@ -334,7 +365,11 @@ def generate_index_mdx(classes: list[dict], decorators: list[dict]) -> str:
365
class_rows = []
366
for c in classes:
367
link = f"/reference/sdk-reference/python/{to_kebab_case(c['name'])}"
337
- desc = c["description"][:80] + "..." if len(c["description"]) > 80 else c["description"]
368
+ desc = (
369
+ c["description"][:80] + "..."
370
+ if len(c["description"]) > 80
371
+ else c["description"]
372
+ )
373
class_rows.append(f"| [`{c['name']}`]({link}) | {desc} |")
374
375
# Decorators section
@@ -363,7 +398,7 @@ def generate_index_mdx(classes: list[dict], decorators: list[dict]) -> str:
398
dec_lines.append("")
399
dec_section = "\n".join(dec_lines)
400
366
- return f'''---
401
+ return f"""---
402
title: Python SDK Reference
403
description: API reference for the Composio Python SDK
404
---
@@ -409,7 +444,7 @@ result = composio.tools.execute(
444
```
445
446
{dec_section}
412
-'''
447
+"""
448
449
450
def main():
@@ -477,10 +512,12 @@ def main():
512
file_path = OUTPUT_DIR / f"{to_kebab_case(class_name)}.mdx"
513
file_path.write_text(mdx)
514
480
- documented_classes.append({
481
- "name": class_name,
482
- "description": info["description"] or f"{class_name} class",
483
- })
515
+ documented_classes.append(
516
+ {
517
+ "name": class_name,
518
+ "description": info["description"] or f"{class_name} class",
519
+ }
520
+ )
521
522
# Process decorators
523
decorators = []
@@ -502,19 +539,23 @@ def main():
539
for p in func.parameters:
540
if p.name in ("self", "cls"):
541
continue
505
- params.append({
506
- "name": p.name,
507
- "type": format_type(p.annotation),
508
- "optional": p.default is not None,
509
- "description": doc["params"].get(p.name, ""),
510
- })
511
-
512
- decorators.append({
513
- "name": dec_name,
514
- "source_link": get_source_link(func),
515
- "description": doc["description"],
516
- "parameters": params,
517
- })
542
+ params.append(
543
+ {
544
+ "name": p.name,
545
+ "type": format_type(p.annotation),
546
+ "optional": p.default is not None,
547
+ "description": doc["params"].get(p.name, ""),
548
+ }
549
+ )
550
+
551
+ decorators.append(
552
+ {
553
+ "name": dec_name,
554
+ "source_link": get_source_link(func),
555
+ "description": doc["description"],
556
+ "parameters": params,
557
+ }
558
+ )
559
560
# Generate index
561
index_content = generate_index_mdx(documented_classes, decorators)