@devries-cameron20 / composio-1 / commits / da031aa7f
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: 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)