Add documentation for prefect sdk generate CLI

[tomerqodo]

Benchmark PR from qodo-benchmark#551

Summary by CodeRabbit

Release Notes

• New Features

  • Added prefect sdk generate CLI command to generate custom typed Python SDKs from workspace deployments with filtering options for flows and deployments.

• Documentation

  • New comprehensive guide on generating and using custom Python SDKs for deployments.
  • Added CLI reference documentation for the SDK command.
  • Reorganized documentation structure with deployments content consolidated into dedicated section.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

The changes introduce new documentation and CLI functionality for generating custom Python SDKs from Prefect deployments. A new documentation file explains SDK generation via CLI with prerequisites and usage examples. The fetcher module adds logging and refines deployment filtering logic to support deployment name matching.

Changes

Cohort / File(s)	Summary
Documentation Structure and New Guides docs/docs.json, docs/v3/advanced/generate-custom-sdk.mdx, docs/v3/api-ref/cli/sdk.mdx	Reorganized documentation structure by moving form-building page and adding new custom SDK generation guide. New docs explain SDK generation via prefect sdk generate command, including prerequisites, CLI options (--output, --flow, --deployment filters), usage examples for synchronous/asynchronous execution, and method chaining patterns.
Deployment Fetching Logic src/prefect/_sdk/fetcher.py	Added module-level logging for authentication and fetch operations. Simplified job variables schema extraction by removing explicit type validation. Refined deployment filtering logic to match by deployment name directly rather than full name comparison. Relaxed error handling in parallel fetch operations.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Poem

🐰 A custom SDK for Prefect's embrace,
Generation made simple, keeping pace,
Deployments now typed, from fetcher to CLI,
With options and filters, reaching the sky,
Beta features hopping into the light! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description is minimal and only references a benchmark PR, failing to provide the required overview of changes or complete the provided checklist template.	Provide a detailed description of proposed changes, fill out the checklist items appropriately, and reference any related issues using 'closes' format.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly describes the main change: adding documentation for the prefect sdk generate CLI command, which is the primary focus of this PR.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

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)

19-37: Fix import order to resolve E402 CI failure.

Logger initialization between imports violates PEP 8. Move it after all import statements.

Proposed fix

 import prefect
-
-# Logger for SDK fetcher operations
-logger = logging.getLogger(__name__)
 from prefect._sdk.models import (
     DeploymentInfo,
     FlowInfo,
     SDKData,
     SDKGenerationMetadata,
     WorkPoolInfo,
 )
 from prefect.client.schemas.filters import (
     DeploymentFilter,
     DeploymentFilterName,
     FlowFilter,
     FlowFilterId,
     FlowFilterName,
 )
 from prefect.exceptions import ObjectNotFound
 from prefect.settings.context import get_current_settings
+
+# Logger for SDK fetcher operations
+logger = logging.getLogger(__name__)

---

395-420: Remove dep.name not in deployment_names from the guard condition to enable ambiguity warnings.

The guard at line 397 contradicts the inner logic. Since dep.name not in deployment_names is true, the loop condition if dep.name == dn: (line 405) can never match, making matched_short_name unreachable and preventing ambiguity warnings from triggering.

🐛 Proposed fix

-        if deployment_names and dep.name not in deployment_names:
+        if 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`:
- Around line 41-45: Remove the invisible backspace control character present
between the sentence "Requires an active Prefect API connection (use `prefect
cloud login` or configure PREFECT_API_URL)." and the following "Examples:"
heading in docs/v3/api-ref/cli/sdk.mdx; open the string containing that sentence
and delete the stray control character (the non-printing backspace) so the text
reads normally with a single newline before "Examples:".

🧹 Nitpick comments (2)

src/prefect/_sdk/fetcher.py (1)

215-221: Make zip strictness explicit.

Ruff’s B905 expects an explicit strict=. If relaxed behavior is intentional, set strict=False for clarity.

♻️ Proposed tweak

-    for name, result in zip(pool_names_list, results):
+    for name, result in zip(pool_names_list, results, strict=False):

docs/v3/api-ref/cli/sdk.mdx (1)

1-3: Consider a descriptive title instead of a blank string.

This improves metadata and search/preview behavior.

✏️ Suggested tweak

-title: " "
+title: "Prefect SDK CLI"

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9e84336 and a070df1.

📒 Files selected for processing (4)

• docs/docs.json
• docs/v3/advanced/generate-custom-sdk.mdx
• docs/v3/api-ref/cli/sdk.mdx
• src/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)

🪛 GitHub Actions: Static analysis

src/prefect/_sdk/fetcher.py

[error] 21-21: E402 Module level import not at top of file.

---

[error] 28-28: E402 Module level import not at top of file.

---

[error] 35-36: E402 Module level import not at top of file.

🪛 Ruff (0.14.13)

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: Client Tests - python:3.10, postgres:14
• GitHub Check: Database and Orchestration 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, sqlite
• GitHub Check: Database and Orchestration Tests - python:3.13, postgres:14
• GitHub Check: Database and Orchestration Tests - python:3.11, sqlite
• GitHub Check: Database and Orchestration Tests - python:3.14, postgres:14
• GitHub Check: Server Tests - python:3.14, postgres:14
• GitHub Check: Database and Orchestration Tests - python:3.12, postgres:14
• GitHub Check: Runner, Worker, Settings, Input, and CLI Tests - python:3.10, postgres:14
• GitHub Check: Client Tests - python:3.14, postgres:14
• GitHub Check: Server Tests - python:3.12, sqlite
• GitHub Check: Client Tests - python:3.12, postgres:14
• GitHub Check: Runner, Worker, Settings, Input, and CLI Tests - python:3.12, postgres:14
• GitHub Check: Database and Orchestration Tests - python:3.10, postgres:14
• GitHub Check: Database and Orchestration Tests - python:3.12, sqlite
• GitHub Check: Server Tests - python:3.13, postgres:14
• GitHub Check: Server Tests - python:3.14, sqlite
• GitHub Check: Database and Orchestration Tests - python:3.11, postgres:14
• GitHub Check: Server Tests - python:3.13, sqlite
• GitHub Check: Server Tests - python:3.11, sqlite
• GitHub Check: Runner, Worker, Settings, Input, and CLI Tests - python:3.14, postgres:14
• GitHub Check: Database and Orchestration Tests - python:3.10, sqlite
• GitHub Check: Client Tests - python:3.11, postgres:14
• GitHub Check: Server Tests - python:3.12, postgres:14
• GitHub Check: Runner, Worker, Settings, Input, and CLI Tests - python:3.13, postgres:14
• GitHub Check: Client Tests - python:3.13, postgres:14
• GitHub Check: Server Tests - python:3.10, postgres:14
• GitHub Check: Server Tests - python:3.10, sqlite
• GitHub Check: Server Tests - python:3.11, postgres:14
• GitHub Check: Benchmark
• GitHub Check: typesafety
• GitHub Check: Benchmark
• GitHub Check: Test SQLite 3.31.1 Compatibility
• GitHub Check: Prefect Client Compatibility Tests
• GitHub Check: Test SQLite 3.24.0 Compatibility
• GitHub Check: Integration tests @main

🔇 Additional comments (5)

docs/docs.json (2)

262-268: Deployments group placement looks good.

Clear grouping for the new advanced deployment docs.

---

809-809: CLI Reference entry for prefect sdk is in sync with the new docs.

Nice update to keep navigation consistent.

src/prefect/_sdk/fetcher.py (2)

178-183: Job variables schema extraction looks fine.

The simplified access is clear and consistent with the surrounding logic.

---

320-322: Auth debug log is helpful.

Nice breadcrumb for diagnosing auth issues.

docs/v3/advanced/generate-custom-sdk.mdx (1)

1-174: Clear, task‑oriented guide with practical examples.

The flow from prerequisites → CLI → usage → regeneration reads well.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Remove the stray control character.

There’s an invisible backspace character that can render oddly.

🧹 Proposed fix

-�

📝 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

	Requires an active Prefect API connection (use `prefect cloud login` or configure
	PREFECT_API_URL).
	�
	Examples:
	Requires an active Prefect API connection (use `prefect cloud login` or configure
	PREFECT_API_URL).
	Examples:

🤖 Prompt for AI Agents

In `@docs/v3/api-ref/cli/sdk.mdx` around lines 41 - 45, Remove the invisible
backspace control character present between the sentence "Requires an active
Prefect API connection (use `prefect cloud login` or configure
PREFECT_API_URL)." and the following "Examples:" heading in
docs/v3/api-ref/cli/sdk.mdx; open the string containing that sentence and delete
the stray control character (the non-printing backspace) so the text reads
normally with a single newline before "Examples:".