docs: improve Python SDK API reference with field descriptions and fix doc generator#1312
Merged
docs: improve Python SDK API reference with field descriptions and fix doc generator#1312
Conversation
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📝 WalkthroughWalkthroughThis PR refactors the Python SDK's async API surface by promoting internal async methods to public variants (e.g., Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/content/api-reference/sdk-python.mdx`:
- Line 174: The docs show an incorrect type for the parameter named callback;
update the type to the correct signature Callable[[list[FunctionInfo]], None]
(as implemented in iii.py around line 1018) and fix the doc-generator logic in
parse-griffe.mts so it does not truncate callable signatures—ensure
parse-griffe.mts preserves parameterized Callable types when extracting
annotations so the rendered table entry for callback becomes
`Callable[[list[FunctionInfo]], None]`.
In `@sdk/packages/python/iii/src/iii/iii_types.py`:
- Around line 474-476: The Field description for the direction attribute in
iii_types.py is inconsistent with its type: the Literal is defined as "read" |
"write" but the description says "reader" or "writer"; update the description on
the direction Field (symbol: direction) to accurately state "read or write" (or
alternatively change the Literal values to "reader"/"writer" if those are the
intended values) so the docstring matches the actual type.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 667412c7-eb86-4f8e-a2e6-adc1b287a911
📒 Files selected for processing (6)
docs/content/api-reference/iii-sdk.mdxdocs/content/api-reference/sdk-python.mdxdocs/scripts/parsers/parse-griffe.mtssdk/packages/python/iii/src/iii/iii.pysdk/packages/python/iii/src/iii/iii_constants.pysdk/packages/python/iii/src/iii/iii_types.py
| @@ -182,16 +171,16 @@ on_functions_available(callback: Callable[None]) | |||
|
|
|||
| | Name | Type | Required | Description | | |||
| | --- | --- | --- | --- | | |||
| | `callback` | `Callable[None]` | Yes | Receives the current list of ``FunctionInfo`` objects each time availability changes. | | |||
| | `callback` | `Callable[None]` | Yes | - | | |||
Contributor
There was a problem hiding this comment.
Incorrect callback type signature.
The type Callable[None] is incorrect. Per the source code in iii.py line 1018, the actual signature is Callable[[list[FunctionInfo]], None]. The doc generator appears to be truncating the callable type.
📝 Proposed fix
-| `callback` | `Callable[None]` | Yes | - |
+| `callback` | `Callable[[list[FunctionInfo]], None]` | Yes | Receives the current list of ``FunctionInfo`` objects each time availability changes. |Note: This may require a fix in the doc generator (parse-griffe.mts) to properly extract callable type signatures.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| | `callback` | `Callable[None]` | Yes | - | | |
| | `callback` | `Callable[[list[FunctionInfo]], None]` | Yes | Receives the current list of ``FunctionInfo`` objects each time availability changes. | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/content/api-reference/sdk-python.mdx` at line 174, The docs show an
incorrect type for the parameter named callback; update the type to the correct
signature Callable[[list[FunctionInfo]], None] (as implemented in iii.py around
line 1018) and fix the doc-generator logic in parse-griffe.mts so it does not
truncate callable signatures—ensure parse-griffe.mts preserves parameterized
Callable types when extracting annotations so the rendered table entry for
callback becomes `Callable[[list[FunctionInfo]], None]`.
Comment on lines
+474
to
+476
| direction: Literal["read", "write"] = Field( | ||
| description="Channel direction (``reader`` or ``writer``)." | ||
| ) |
Contributor
There was a problem hiding this comment.
Fix description mismatch for direction field.
The description says "reader or writer" but the actual Literal type values are "read" and "write".
📝 Proposed fix
direction: Literal["read", "write"] = Field(
- description="Channel direction (``reader`` or ``writer``)."
+ description="Channel direction (``read`` or ``write``)."
)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| direction: Literal["read", "write"] = Field( | |
| description="Channel direction (``reader`` or ``writer``)." | |
| ) | |
| direction: Literal["read", "write"] = Field( | |
| description="Channel direction (``read`` or ``write``)." | |
| ) |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@sdk/packages/python/iii/src/iii/iii_types.py` around lines 474 - 476, The
Field description for the direction attribute in iii_types.py is inconsistent
with its type: the Literal is defined as "read" | "write" but the description
says "reader" or "writer"; update the description on the direction Field
(symbol: direction) to accurately state "read or write" (or alternatively change
the Literal values to "reader"/"writer" if those are the intended values) so the
docstring matches the actual type.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/content/api-reference/sdk-python.mdx (1)
36-40: Async method signatures are missing method names.The signature shows
async ()but should include the method name for consistency with sync methods and clarity. This pattern appears across all*_asyncmethods (connect_async,create_channel_async,list_functions_async, etc.).Expected format:
async def connect_async()This likely requires a fix in the doc generator (
parse-griffe.mts) to include method names in async signatures.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/content/api-reference/sdk-python.mdx` around lines 36 - 40, The async signatures generated by parse-griffe.mts are missing method names (showing `async ()`) — update the generator (parse-griffe.mts) where async signatures are constructed (look for the signature formatting code / helper like formatSignature or renderSignature used for async methods) to emit a full Python async function signature including the method name (e.g., `async def {name}({params})`) for all *_async methods such as connect_async, create_channel_async, list_functions_async; ensure the same naming/template logic used for sync signatures is applied to async paths so the docs render `async def <method_name>(...)`.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/content/api-reference/sdk-python.mdx`:
- Around line 714-720: The docs generator parse-griffe.mts incorrectly marks
fields with no defaults (e.g., RegisterFunctionInput.id,
RegisterServiceInput.id, RegisterTriggerInput.type,
RegisterTriggerInput.function_id) as optional; update parse-griffe.mts to detect
Pydantic-required fields (fields with no default or explicitly Field(...)) and
set the "Required" column to "Yes" for those properties so the generated table
entries (like the row currently showing `id` as "No") reflect they are required;
adjust the generation logic that inspects field.default/Field(...) and
regenerate the affected docs.
---
Nitpick comments:
In `@docs/content/api-reference/sdk-python.mdx`:
- Around line 36-40: The async signatures generated by parse-griffe.mts are
missing method names (showing `async ()`) — update the generator
(parse-griffe.mts) where async signatures are constructed (look for the
signature formatting code / helper like formatSignature or renderSignature used
for async methods) to emit a full Python async function signature including the
method name (e.g., `async def {name}({params})`) for all *_async methods such as
connect_async, create_channel_async, list_functions_async; ensure the same
naming/template logic used for sync signatures is applied to async paths so the
docs render `async def <method_name>(...)`.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 53fa6dcc-88c6-450d-a517-53fdd7385308
📒 Files selected for processing (1)
docs/content/api-reference/sdk-python.mdx
guibeira
previously approved these changes
Mar 17, 2026
…cumentation - Refactored SDK initialization to use `register_worker` across examples. - Updated method signatures and documentation for clarity and consistency. - Enhanced docstrings with attribute descriptions for better understanding. - Improved example formatting in documentation for better readability.
- Eliminated references to the async `greet_async` function in both the documentation and code examples for clarity. - Streamlined the `greet` function example by removing unnecessary lines, enhancing readability.
…eadability - Consolidated multiline field definitions into single-line format for clarity. - Enhanced consistency across various model classes by applying uniform formatting to field descriptions.
…d clarity - Renamed private async methods to public counterparts (e.g., `_async_connect` to `connect_async`) for better usability. - Updated method signatures and documentation to reflect the new naming conventions. - Added async method tests to ensure proper functionality and documentation coverage. - Streamlined channel creation and triggering methods for a more intuitive API experience.
- Added detailed documentation for new async methods: `connect_async`, `create_channel_async`, `list_functions_async`, `list_triggers_async`, `list_workers_async`, and `shutdown_async`. - Included method signatures, parameters, and examples to enhance usability and clarity for developers. - Improved overall structure and consistency of the API reference documentation.
ytallo
force-pushed
the
docs/python-sdk-griffe
branch
from
856cc94 to
782263c
Compare
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (2)
sdk/packages/python/iii/src/iii/iii_types.py (1)
419-419:⚠️ Potential issue | 🟡 MinorAlign
directiondescription with itsLiteralvalues.
directionis typed asLiteral["read", "write"], but the description saysreader/writer.📝 Proposed fix
- direction: Literal["read", "write"] = Field(description="Channel direction (``reader`` or ``writer``).") + direction: Literal["read", "write"] = Field(description="Channel direction (``read`` or ``write``).")🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@sdk/packages/python/iii/src/iii/iii_types.py` at line 419, The Field description for the direction attribute in iii_types.py is inconsistent with its type; update the description of the direction: Literal["read", "write"] field (named direction) to reference "read" and "write" instead of "reader" and "writer" so the docstring matches the Literal values.docs/api-reference/sdk-python.mdx (1)
714-720:⚠️ Potential issue | 🟠 MajorMark
idandtype/function_idfields as "Yes" in the Required column.The Python SDK Pydantic models show
RegisterFunctionInput.id,RegisterServiceInput.id,RegisterTriggerInput.type, andRegisterTriggerInput.function_idare all defined with no default values (e.g.,id: str = Field(...)), making them required. The documentation incorrectly marks these as "No" in the Required column; all should be "Yes".🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/api-reference/sdk-python.mdx` around lines 714 - 720, The docs table incorrectly marks required fields as "No"; update the Required column to "Yes" for RegisterFunctionInput.id, RegisterServiceInput.id, and for RegisterTriggerInput.type and RegisterTriggerInput.function_id to match the Pydantic models (which use Field(...)); locate the table rows that list `id` and the rows for `type`/`function_id` in the SDK Python reference and change their Required value from "No" to "Yes" so the docs reflect the actual model requirements.
🧹 Nitpick comments (1)
docs/api-reference/sdk-python.mdx (1)
27-41: Signature format inconsistency for async methods.The signature shows
async ()without the method name, which differs from sync methods likecreate_channel(buffer_size: int | None = None). This inconsistency appears across all*_asyncmethods.📝 Suggested fix
**Signature** ```python -async () +async connect_async()Apply similar changes to other async method signatures (`create_channel_async`, `list_functions_async`, `list_triggers_async`, `list_workers_async`, `shutdown_async`, `trigger_async`). </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/api-reference/sdk-python.mdxaround lines 27 - 41, The async method
signatures in the docs are missing method names (e.g., showing "async ()");
update each async signature to include the function name (for example change the
connect_async signature to "async connect_async()" and apply the same pattern to
create_channel_async, list_functions_async, list_triggers_async,
list_workers_async, shutdown_async, trigger_async) so the documentation format
matches the sync examples and clearly shows the async method name and
parameters.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Inline comments:
In@sdk/packages/python/iii/src/iii/iii_types.py:
- Around line 260-264: The docstrings in iii_types.py incorrectly reference
non-existent action constructors like TriggerAction.Enqueue and
TriggerAction.Void; update the public docstrings for the related return types
(the Result for enqueue and the Void result) to use the correct model names
TriggerActionEnqueue and TriggerActionVoid (and any parentheses usage) so the
generated API docs show accurate types—search for docstrings that mention
"TriggerAction.Enqueue" and "TriggerAction.Void" (also the block around the
enqueue result and the subsequent void/result block) and replace those
references with the correct class names TriggerActionEnqueue and
TriggerActionVoid.In
@sdk/packages/python/iii/src/iii/iii.py:
- Around line 186-198: The docstring for shutdown_async incorrectly says it
"stops the background event-loop thread"; update the shutdown_async docstring
(function shutdown_async) to only describe what it actually does (cancel
reconnection attempts, reject in-flight invocations, close the WebSocket, and
stop background tasks) and remove or rephrase the claim about stopping the
thread—add a note that the synchronous shutdown() method is responsible for
stopping the event-loop thread and that callers who need the thread stopped
should call shutdown().
Duplicate comments:
In@docs/api-reference/sdk-python.mdx:
- Around line 714-720: The docs table incorrectly marks required fields as "No";
update the Required column to "Yes" for RegisterFunctionInput.id,
RegisterServiceInput.id, and for RegisterTriggerInput.type and
RegisterTriggerInput.function_id to match the Pydantic models (which use
Field(...)); locate the table rows that listidand the rows for
type/function_idin the SDK Python reference and change their Required value
from "No" to "Yes" so the docs reflect the actual model requirements.In
@sdk/packages/python/iii/src/iii/iii_types.py:
- Line 419: The Field description for the direction attribute in iii_types.py is
inconsistent with its type; update the description of the direction:
Literal["read", "write"] field (named direction) to reference "read" and "write"
instead of "reader" and "writer" so the docstring matches the Literal values.
Nitpick comments:
In@docs/api-reference/sdk-python.mdx:
- Around line 27-41: The async method signatures in the docs are missing method
names (e.g., showing "async ()"); update each async signature to include the
function name (for example change the connect_async signature to "async
connect_async()" and apply the same pattern to create_channel_async,
list_functions_async, list_triggers_async, list_workers_async, shutdown_async,
trigger_async) so the documentation format matches the sync examples and clearly
shows the async method name and parameters.</details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro **Run ID**: `21e0adde-9311-4fb1-a98a-b27a070951ea` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 856cc9406acd8c6a3e5d4def3e4b3a97054f07fa and 782263c5ae291495ddd7c0d6eea09448914e2b45. </details> <details> <summary>📒 Files selected for processing (10)</summary> * `docs/api-reference/sdk-python.mdx` * `docs/scripts/parsers/__tests__/parse-griffe.test.mts` * `docs/scripts/parsers/parse-griffe.mts` * `frameworks/motia/motia-py/packages/motia/tests/test_api_triggers.py` * `sdk/packages/python/iii/src/iii/iii.py` * `sdk/packages/python/iii/src/iii/iii_constants.py` * `sdk/packages/python/iii/src/iii/iii_types.py` * `sdk/packages/python/iii/src/iii/telemetry.py` * `sdk/packages/python/iii/tests/test_async_api.py` * `sdk/packages/python/iii/tests/test_data_channels.py` </details> <details> <summary>🚧 Files skipped from review as they are similar to previous changes (3)</summary> * sdk/packages/python/iii/src/iii/telemetry.py * sdk/packages/python/iii/tests/test_async_api.py * sdk/packages/python/iii/src/iii/iii_constants.py </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
Comment on lines
+260
to
+264
| """Result returned when a function is invoked with ``TriggerAction.Enqueue``. | ||
|
|
||
| messageReceiptId: str | ||
| """Unique receipt ID for the enqueued message.""" | ||
| Attributes: | ||
| messageReceiptId: UUID assigned by the engine to the enqueued job. | ||
| """ |
Contributor
There was a problem hiding this comment.
Fix invalid action type names in public docstrings.
These docstrings reference TriggerAction.Enqueue(...) / TriggerAction.Void(), but the declared models are TriggerActionEnqueue and TriggerActionVoid. This produces inaccurate API reference text.
📝 Proposed fix
class EnqueueResult(BaseModel):
- """Result returned when a function is invoked with ``TriggerAction.Enqueue``.
+ """Result returned when a function is invoked with ``TriggerActionEnqueue``.
@@
class TriggerRequest(BaseModel):
@@
- action: Routing action — ``None`` for sync, ``TriggerAction.Enqueue(...)``
- for queue, ``TriggerAction.Void()`` for fire-and-forget.
+ action: Routing action — ``None`` for sync, ``TriggerActionEnqueue(...)``
+ for queue, ``TriggerActionVoid()`` for fire-and-forget.
@@
action: TriggerActionEnqueue | TriggerActionVoid | None = Field(
@@
- "``TriggerAction.Enqueue(...)`` for queue, "
- "``TriggerAction.Void()`` for fire-and-forget."
+ "``TriggerActionEnqueue(...)`` for queue, "
+ "``TriggerActionVoid()`` for fire-and-forget."
),
)Also applies to: 275-288
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@sdk/packages/python/iii/src/iii/iii_types.py` around lines 260 - 264, The
docstrings in iii_types.py incorrectly reference non-existent action
constructors like TriggerAction.Enqueue and TriggerAction.Void; update the
public docstrings for the related return types (the Result for enqueue and the
Void result) to use the correct model names TriggerActionEnqueue and
TriggerActionVoid (and any parentheses usage) so the generated API docs show
accurate types—search for docstrings that mention "TriggerAction.Enqueue" and
"TriggerAction.Void" (also the block around the enqueue result and the
subsequent void/result block) and replace those references with the correct
class names TriggerActionEnqueue and TriggerActionVoid.
Comment on lines
+186
to
+198
| async def shutdown_async(self) -> None: | ||
| """Gracefully shut down the client, releasing all resources. | ||
|
|
||
| Cancels any pending reconnection attempts, rejects all in-flight | ||
| invocations with an error, closes the WebSocket connection, and | ||
| stops the background event-loop thread. After this call the | ||
| instance must not be reused. | ||
|
|
||
| Examples: | ||
| >>> iii = register_worker('ws://localhost:49134') | ||
| >>> # ... do work ... | ||
| >>> await iii.shutdown_async() | ||
| """ |
Contributor
There was a problem hiding this comment.
Minor docstring inaccuracy: shutdown_async doesn't stop the thread.
The docstring states it "stops the background event-loop thread," but shutdown_async only handles WebSocket cleanup and task cancellation. The thread stopping logic is in the synchronous shutdown() method (lines 157-158). This could confuse users calling shutdown_async directly.
📝 Proposed fix
async def shutdown_async(self) -> None:
- """Gracefully shut down the client, releasing all resources.
+ """Gracefully shut down the async resources.
Cancels any pending reconnection attempts, rejects all in-flight
- invocations with an error, closes the WebSocket connection, and
- stops the background event-loop thread. After this call the
- instance must not be reused.
+ invocations with an error, and closes the WebSocket connection.
+ Use the synchronous ``shutdown()`` method to also stop the
+ background event-loop thread.
Examples:
- >>> iii = register_worker('ws://localhost:49134')
- >>> # ... do work ...
>>> await iii.shutdown_async()
"""🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@sdk/packages/python/iii/src/iii/iii.py` around lines 186 - 198, The docstring
for shutdown_async incorrectly says it "stops the background event-loop thread";
update the shutdown_async docstring (function shutdown_async) to only describe
what it actually does (cancel reconnection attempts, reject in-flight
invocations, close the WebSocket, and stop background tasks) and remove or
rephrase the claim about stopping the thread—add a note that the synchronous
shutdown() method is responsible for stopping the event-loop thread and that
callers who need the thread stopped should call shutdown().
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Improves the auto-generated Python SDK API reference (
sdk-python.mdx) by adding field-level descriptions to all public types and fixing the doc generator to extract them.Before: 34 type fields showed "-" (no description) in the API reference tables.
After: 1 remaining (a method param, not a type field).
Changes
Python SDK docstrings (
iii.py,iii_types.py,iii_constants.py)Attributes:section (Google-style) to 13 Pydantic model docstrings — griffe extracts these for the API referenceregister_function,trigger,create_channel,on_functions_available,register_trigger,register_trigger_type,register_serviceregister_functionexample (removed mixed prose/code)Doc generator (
parse-griffe.mts)extractAttributeDescriptions()— new function that parsesAttributes:sections from class docstrings as fallback when griffe doesn't populate individual field docsregister_workeralias resolution — resolves fromiii.iiisubmodule when the root-level re-export has no metadataextractDocstring()— now strips all Google-style sections (Returns:,Raises:,Note:, etc.) from descriptionsextractExamples()— better cleanup of>>>/...doctest prefixesfrom iii import III, register_workertofrom iii import register_worker, InitOptionsGenerated output (
sdk-python.mdx)register_workerwith description and exampleTest plan
cd sdk/packages/python/iii && uv run pytest tests/ -x— verify no regressionscd sdk/packages/python/iii && uv run griffe dump iii -d google 2>/dev/null > api-docs.json && cd ../../docs && pnpm tsx scripts/generate-api-docs.mts— regenerate and verify outputsdk-python.mdxin docs previewSummary by CodeRabbit
New Features
Documentation