Add documentation for prefect sdk generate CLI#27
Conversation
- Add auto-generated CLI reference for `prefect sdk` command - Add how-to guide for generating typed SDKs from deployments - Update navigation in docs.json for both new pages - Regenerate CLI docs to include new --output options Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Keep only sdk.mdx from the CLI docs regeneration. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The code examples reference a hypothetical my_sdk module that doesn't exist, so they can't be executed as tests. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove marketing-style "before/after" section - Use sentence case headers - Task-oriented organization (CLI then Python) - Add opening context and further reading links - Direct, instructional tone throughout Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove marketing-style "before/after" section - Use sentence case headers - Task-oriented organization (CLI then Python) - Add opening context and further reading links - Direct, instructional tone throughout Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Move generate-custom-sdk.mdx to docs/v3/advanced/ - Create new "Deployments" group in Advanced section - Move form-building guide to new Deployments group - Both guides relate to deployment configuration Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
WalkthroughThis PR adds documentation and implementation for a new CLI feature enabling users to generate custom Python SDKs from Prefect deployments. The change includes two new documentation pages, navigation restructuring, and modifications to the SDK fetcher module to support deployment filtering by short name. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes 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
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
src/prefect/_sdk/fetcher.py (2)
178-182: Guard against non-dictbase_job_template["variables"].Line 182 can raise if
base_job_templateisn’t a mapping or ifvariablesisn’t a dict. A defensive guard avoids unexpected TypeErrors from API changes.🛡️ Suggested hardening
- if base_job_template and "variables" in base_job_template: - job_vars_schema = base_job_template["variables"] + if ( + isinstance(base_job_template, dict) + and isinstance(base_job_template.get("variables"), dict) + ): + job_vars_schema = base_job_template["variables"]
395-421: Record ambiguity warnings when short-name filters are used.Line 397 skips the match block when a short name is provided (e.g.,
--deployment my-deploy), soshort_name_matchesnever gets populated and ambiguity warnings are lost.✅ Minimal fix
# If filtering by deployment name, check the full name matches full_name = f"{flow_name}/{dep.name}" + if deployment_names and dep.name in deployment_names: + # Track short-name matches even when no further filtering is needed + short_name_matches.setdefault(dep.name, []).append(full_name) if deployment_names and dep.name not in deployment_names: # Only include if the full name matches (filter was by name parts) # Skip if user specified full names and this doesn't match found_match = False - matched_short_name: str | None = None for dn in deployment_names: if "/" not in dn: # User gave just deployment name, check against dep.name if dep.name == dn: found_match = True - matched_short_name = dn break else: # User gave full name, must match exactly if full_name == dn: found_match = True break if not found_match: continue - # Track short name matches for ambiguity warning - if matched_short_name: - if matched_short_name not in short_name_matches: - short_name_matches[matched_short_name] = [] - short_name_matches[matched_short_name].append(full_name)
🤖 Fix all issues with AI agents
In `@docs/v3/api-ref/cli/sdk.mdx`:
- Line 44: Remove the stray hidden control character found at Line 44 in
docs/v3/api-ref/cli/sdk.mdx by deleting the non-printable/backspace character so
the file contains only valid text; confirm the character is gone by opening the
file in a hex-aware editor or running a lint that highlights non-printable
characters.
- Around line 1-4: The frontmatter has an empty title field; replace the blank
title value with a meaningful, SEO-friendly string (e.g., "Prefect SDK" or a
concise descriptive title) by updating the title frontmatter key while
preserving other keys like sidebarTitle so the page metadata and header render
correctly.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
docs/docs.jsondocs/v3/advanced/generate-custom-sdk.mdxdocs/v3/api-ref/cli/sdk.mdxsrc/prefect/_sdk/fetcher.py
🧰 Additional context used
🧬 Code graph analysis (1)
src/prefect/_sdk/fetcher.py (1)
src/prefect/_sdk/models.py (1)
deployment_names(120-129)
🪛 Ruff (0.14.14)
src/prefect/_sdk/fetcher.py
220-220: zip() without an explicit strict= parameter
Add explicit value for parameter strict=
(B905)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (37)
- GitHub Check: Runner, Worker, Settings, Input, and CLI Tests - python:3.10, postgres:14
- GitHub Check: Database and Orchestration Tests - python:3.11, sqlite
- GitHub Check: Server Tests - python:3.14, sqlite
- GitHub Check: Runner, Worker, Settings, Input, and CLI Tests - python:3.11, postgres:14
- GitHub Check: Database and Orchestration Tests - python:3.13, postgres:14
- GitHub Check: Client Tests - python:3.14, postgres:14
- GitHub Check: Runner, Worker, Settings, Input, and CLI Tests - python:3.13, postgres:14
- GitHub Check: Database and Orchestration Tests - python:3.14, postgres:14
- GitHub Check: Client Tests - python:3.13, postgres:14
- GitHub Check: Runner, Worker, Settings, Input, and CLI Tests - python:3.12, postgres:14
- GitHub Check: Database and Orchestration Tests - python:3.13, sqlite
- GitHub Check: Database and Orchestration Tests - python:3.14, sqlite
- GitHub Check: Runner, Worker, Settings, Input, and CLI Tests - python:3.14, postgres:14
- GitHub Check: Client Tests - python:3.12, postgres:14
- GitHub Check: Database and Orchestration Tests - python:3.12, postgres:14
- GitHub Check: Server Tests - python:3.10, sqlite
- GitHub Check: Client Tests - python:3.10, postgres:14
- GitHub Check: Database and Orchestration Tests - python:3.10, sqlite
- GitHub Check: Database and Orchestration Tests - python:3.12, sqlite
- GitHub Check: Client Tests - python:3.11, postgres:14
- GitHub Check: Database and Orchestration Tests - python:3.11, postgres:14
- GitHub Check: Server Tests - python:3.14, postgres:14
- GitHub Check: Server Tests - python:3.11, postgres:14
- GitHub Check: Server Tests - python:3.10, postgres:14
- GitHub Check: Server Tests - python:3.12, sqlite
- GitHub Check: Server Tests - python:3.11, sqlite
- GitHub Check: Database and Orchestration Tests - python:3.10, postgres:14
- GitHub Check: Server Tests - python:3.13, postgres:14
- GitHub Check: Server Tests - python:3.12, postgres:14
- GitHub Check: Server Tests - python:3.13, sqlite
- GitHub Check: Benchmark
- GitHub Check: typesafety
- GitHub Check: Benchmark
- GitHub Check: Integration tests
@main - GitHub Check: Prefect Client Compatibility Tests
- GitHub Check: Test SQLite 3.31.1 Compatibility
- GitHub Check: Test SQLite 3.24.0 Compatibility
🔇 Additional comments (7)
docs/v3/api-ref/cli/sdk.mdx (1)
61-78: LGTM: options accordion is clear and concise.Nice, consistent flag descriptions and guidance.
src/prefect/_sdk/fetcher.py (3)
10-21: LGTM: module logger setup for SDK fetcher.Clear and consistent logging initialization.
212-234: LGTM: deterministic pairing of pool names to results.
pool_names_listandresultsare derived from the same source, so pairing viazipis safe here.
320-322: LGTM: debug log before auth check is useful.Helpful for tracing connection/auth issues.
docs/v3/advanced/generate-custom-sdk.mdx (1)
7-174: Great step‑by‑step guide and examples.The CLI, filtering, and Python usage sections are clear and actionable.
docs/docs.json (2)
262-268: LGTM: Advanced > Deployments grouping.Navigation placement looks appropriate.
809-809: LGTM: CLI SDK reference added to navigation.Makes the new CLI page discoverable.
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
| --- | ||
| title: " " | ||
| sidebarTitle: prefect sdk | ||
| --- |
There was a problem hiding this comment.
Add a descriptive title in frontmatter.
Line 2 is a blank title; this yields empty page metadata. Consider a meaningful title for SEO and page headers.
🛠 Proposed fix
-title: " "
+title: "Prefect SDK CLI"📝 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.
| --- | |
| title: " " | |
| sidebarTitle: prefect sdk | |
| --- | |
| --- | |
| title: "Prefect SDK CLI" | |
| sidebarTitle: prefect sdk | |
| --- |
🤖 Prompt for AI Agents
In `@docs/v3/api-ref/cli/sdk.mdx` around lines 1 - 4, The frontmatter has an empty
title field; replace the blank title value with a meaningful, SEO-friendly
string (e.g., "Prefect SDK" or a concise descriptive title) by updating the
title frontmatter key while preserving other keys like sidebarTitle so the page
metadata and header render correctly.
| Requires an active Prefect API connection (use `prefect cloud login` or configure | ||
| PREFECT_API_URL). | ||
|
|
||
There was a problem hiding this comment.
Remove the stray control character near Line 44.
Line 44 contains a hidden control character (looks like a backspace). It can cause render or lint issues; please delete it.
🤖 Prompt for AI Agents
In `@docs/v3/api-ref/cli/sdk.mdx` at line 44, Remove the stray hidden control
character found at Line 44 in docs/v3/api-ref/cli/sdk.mdx by deleting the
non-printable/backspace character so the file contains only valid text; confirm
the character is gone by opening the file in a hex-aware editor or running a
lint that highlights non-printable characters.
2 participants
Benchmark PR from agentic-review-benchmarks#1
Summary by CodeRabbit
New Features
Documentation
prefect sdk generatecommand with available flags and usage examples.✏️ Tip: You can customize this high-level summary in your review settings.