Enhance Python SDK documentation with migration guide and client sele… #652
Conversation
…ction recommendations Added a comprehensive migration guide for transitioning from v1 to v2 of the Kinde Python SDK, including code examples and client selection criteria. Expanded sections on using different client types (OAuth, AsyncOAuth, SmartOAuth) with practical implementation examples for Flask and FastAPI. Updated error handling and feature flag usage sections to reflect new patterns and best practices.
WalkthroughComprehensive expansion of Python SDK documentation, adding migration guides for v1 to v2, detailing OAuth client types, and providing framework-specific examples for Flask and FastAPI alongside serverless implementations, error handling patterns, and type-safe usage guidance. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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 |
Deploying kinde-docs-preview with
|
| Latest commit: |
02ad9f8
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://119f523a.kinde-docs-preview.pages.dev |
| Branch Preview URL: | https://update-python-sdk-documentat.kinde-docs-preview.pages.dev |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (4)
src/content/docs/developer-tools/sdks/backend/python-sdk.mdx (4)
618-681: Syntax errors: Incomplete docstrings in Flask manual implementation.Lines 620, 627, 634, 658, and 667 have docstrings ending with
""instead of""". This will causeSyntaxErrorwhen users copy this code.Additionally,
uuidis used on line 643 but not imported.Proposed fix
import asyncio from flask import Flask, request, session, redirect from kinde_sdk.auth.oauth import OAuth +import uuid app = Flask(__name__) oauth = OAuth( framework="flask", app=app ) @app.route('/login') def login(): - """Redirect to Kinde login page."" + """Redirect to Kinde login page.""" loop = asyncio.get_event_loop() login_url = loop.run_until_complete(oauth.login()) return redirect(login_url) @app.route('/register') def register(): - """Redirect to Kinde registration page."" + """Redirect to Kinde registration page.""" loop = asyncio.get_event_loop() register_url = loop.run_until_complete(oauth.register()) return redirect(register_url) @app.route('/callback') def callback(): - """Handle the OAuth callback from Kinde."" + """Handle the OAuth callback from Kinde.""" try:(Apply similar fixes to lines 658 and 667)
683-717: Missing imports in FastAPI manual implementation.
- Line 700:
Optionalfromtypingis not imported- Line 705:
HTMLResponsefromfastapi.responsesis not importedProposed fix
+from typing import Optional from fastapi import FastAPI, Request -from fastapi.responses import RedirectResponse +from fastapi.responses import RedirectResponse, HTMLResponse
888-905: Missing closing quotes in permission pattern examples.The string literals on lines 890-904 are missing their closing quotes (e.g.,
"create:todosshould be"create:todos").Proposed fix
# Resource-based permissions -"create:todos -"read:todos -"update:todos -"delete:todos +"create:todos" +"read:todos" +"update:todos" +"delete:todos" # Feature-based permissions -"can:export_data -"can:manage_users -"can:view_analytics +"can:export_data" +"can:manage_users" +"can:view_analytics" # Organization-based permissions -"org:manage_members -"org:view_billing -"org:update_settings +"org:manage_members" +"org:view_billing" +"org:update_settings"
1260-1277: Missing closing quotes in common claims examples.The string literals on lines 1262-1276 are missing their closing quotes.
Proposed fix
# User Information (ID Token) -"given_name -"family_name -"email -"picture +"given_name" +"family_name" +"email" +"picture" # Token Information (Access Token) "aud" # Audience "iss" # Issuer "exp" # Expiration time "iat" # Issued at time # Organization Information -"org_code -"org_name -"org_id +"org_code" +"org_name" +"org_id"
🤖 Fix all issues with AI agents
In @src/content/docs/developer-tools/sdks/backend/python-sdk.mdx:
- Around line 452-496: The Flask example uses uuid.uuid4() in the callback
function but never imports the uuid module; add an import for uuid at the top of
the file (alongside existing imports like Flask, request, session) so that the
callback's user_id = session.get('user_id') or str(uuid.uuid4()) call works
without NameError.
- Around line 354-368: The example cloud_function_handler uses redirect but does
not import it, causing a NameError; update the top of the module to import
redirect from the appropriate web framework (e.g., from flask import redirect if
Request is a Flask request) so that cloud_function_handler, the internal
handle_request coroutine, and calls like redirect(url, code=302) resolve
correctly; ensure the import matches the Request type used by oauth and other
handlers.
- Around line 479-495: Add explicit comments and brief notes in the examples to
indicate which client type is used and which handle_redirect signature applies:
above the callback function example add a comment like "# Using OAuth client"
and mention that OAuth.handle_redirect(code, user_id, state) manages session
internally, and in any async example add "# Using AsyncOAuth client" noting
AsyncOAuth requires "await oauth.handle_redirect(code, state)" and custom
session management; update the callback docstring or surrounding text to call
out the different parameter requirements for handle_redirect across OAuth vs
AsyncOAuth so readers know which signature to follow.
📜 Review details
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
src/content/docs/developer-tools/sdks/backend/python-sdk.mdx
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-12-27T18:42:29.479Z
Learnt from: victoreronmosele
Repo: kinde-oss/documentation PR: 647
File: src/content/docs/developer-tools/sdks/native/ios-sdk.mdx:278-297
Timestamp: 2025-12-27T18:42:29.479Z
Learning: In MDX documentation files (e.g., any API reference docs), when documenting parameters (like loginHint, connectionId), prefer listing them in the API reference Arguments section and link to detailed documentation pages instead of duplicating descriptions, format specs, or validation rules inline. This follows the 'document once, reference anywhere' principle.
Applied to files:
src/content/docs/developer-tools/sdks/backend/python-sdk.mdx
🔇 Additional comments (3)
src/content/docs/developer-tools/sdks/backend/python-sdk.mdx (3)
50-101: Migration guide is well-structured and informative.The migration section provides clear guidance for transitioning from v1 to v2 SDK, with appropriate code examples and a helpful client selection table. The inclusion of a link to the GitHub migration guide for detailed instructions is a good practice.
173-207: Client selection guide is comprehensive.The comparison table effectively highlights the differences between OAuth, AsyncOAuth, and SmartOAuth clients, helping developers make informed decisions.
1625-1834: Error handling section is comprehensive and well-documented.The error handling patterns, exception types, and best practices summary provide excellent guidance for production applications. The global exception handler example for FastAPI is particularly useful.
| def cloud_function_handler(request: Request): | ||
| """Google Cloud Function handler.""" | ||
| async def handle_request(): | ||
| if request.path == '/login': | ||
| url = await oauth.login() | ||
| return redirect(url, code=302) | ||
|
|
||
| if request.path == '/callback': | ||
| code = request.args.get('code') | ||
| state = request.args.get('state') | ||
| await oauth.handle_redirect(code, state) | ||
| return {'message': 'Authenticated'}, 200 | ||
|
|
||
| return asyncio.run(handle_request()) | ||
| ``` |
There was a problem hiding this comment.
Missing redirect import in Google Cloud Functions example.
The redirect function is used on line 359 but not imported. This will cause a NameError at runtime.
Proposed fix
from flask import Request
+from flask import redirect
from kinde_sdk.auth.async_oauth import AsyncOAuth
import asyncio🤖 Prompt for AI Agents
In @src/content/docs/developer-tools/sdks/backend/python-sdk.mdx around lines
354 - 368, The example cloud_function_handler uses redirect but does not import
it, causing a NameError; update the top of the module to import redirect from
the appropriate web framework (e.g., from flask import redirect if Request is a
Flask request) so that cloud_function_handler, the internal handle_request
coroutine, and calls like redirect(url, code=302) resolve correctly; ensure the
import matches the Request type used by oauth and other handlers.
| ```python | ||
| from flask import Flask, request, session, redirect, url_for | ||
| from kinde_sdk.auth.oauth import OAuth | ||
| import asyncio | ||
|
|
||
| app = Flask(__name__) | ||
| app.secret_key = 'your-secret-key' | ||
|
|
||
| oauth = OAuth( | ||
| framework="flask", | ||
| app=app | ||
| ) | ||
|
|
||
| @app.route('/login') | ||
| def login(): | ||
| """Redirect to Kinde login page.""" | ||
| loop = asyncio.get_event_loop() | ||
| login_url = loop.run_until_complete(oauth.login()) | ||
| return redirect(login_url) | ||
|
|
||
| @app.route('/register') | ||
| def register(): | ||
| """Redirect to Kinde registration page.""" | ||
| loop = asyncio.get_event_loop() | ||
| register_url = loop.run_until_complete(oauth.register()) | ||
| return redirect(register_url) | ||
|
|
||
| @app.route('/callback') | ||
| def callback(): | ||
| """Handle the OAuth callback from Kinde.""" | ||
| try: | ||
| code = request.args.get('code') | ||
| state = request.args.get('state') | ||
|
|
||
| if not code: | ||
| return "Authentication failed: No code provided", 400 | ||
|
|
||
| user_id = session.get('user_id') or str(uuid.uuid4()) | ||
| loop = asyncio.get_event_loop() | ||
| result = loop.run_until_complete(oauth.handle_redirect(code, user_id, state)) | ||
| session['user_id'] = user_id | ||
| return redirect(url_for('index')) | ||
| except Exception as e: | ||
| return f"Authentication failed: {str(e)}", 400 | ||
|
|
There was a problem hiding this comment.
Missing uuid import in Flask implementation example.
The code uses uuid.uuid4() on line 489 but the uuid module is not imported.
Proposed fix
from flask import Flask, request, session, redirect, url_for
from kinde_sdk.auth.oauth import OAuth
import asyncio
+import uuid🤖 Prompt for AI Agents
In @src/content/docs/developer-tools/sdks/backend/python-sdk.mdx around lines
452 - 496, The Flask example uses uuid.uuid4() in the callback function but
never imports the uuid module; add an import for uuid at the top of the file
(alongside existing imports like Flask, request, session) so that the callback's
user_id = session.get('user_id') or str(uuid.uuid4()) call works without
NameError.
| @app.route('/callback') | ||
| def callback(): | ||
| """Handle the OAuth callback from Kinde.""" | ||
| try: | ||
| code = request.args.get('code') | ||
| state = request.args.get('state') | ||
|
|
||
| if not code: | ||
| return "Authentication failed: No code provided", 400 | ||
|
|
||
| user_id = session.get('user_id') or str(uuid.uuid4()) | ||
| loop = asyncio.get_event_loop() | ||
| result = loop.run_until_complete(oauth.handle_redirect(code, user_id, state)) | ||
| session['user_id'] = user_id | ||
| return redirect(url_for('index')) | ||
| except Exception as e: | ||
| return f"Authentication failed: {str(e)}", 400 |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Search for handle_redirect definition in Python files
rg "def handle_redirect" --type=py -B 2 -A 10
# Also check if it's defined as a method in any Python implementation files
fd -e py | xargs rg -l "handle_redirect" | head -10Repository: kinde-oss/documentation
Length of output: 351
🏁 Script executed:
# Check the documentation file for all occurrences of handle_redirect
rg -n "handle_redirect" src/content/docs/developer-tools/sdks/backend/python-sdk.mdx -B 2 -A 2Repository: kinde-oss/documentation
Length of output: 1758
🏁 Script executed:
# Look for any migration guides, API docs, or comments explaining the signature
fd -e md -e mdx -e rst | xargs rg -l "handle_redirect" 2>/dev/nullRepository: kinde-oss/documentation
Length of output: 127
🏁 Script executed:
# Check if there's any SDK source code or implementation in the repo
find . -name "*kinde*" -o -name "*oauth*" | grep -E "\.(py|ts|js)$" | head -10Repository: kinde-oss/documentation
Length of output: 49
🏁 Script executed:
# Look for any imports or SDK references in the mdx file
rg -A 5 -B 5 "from kinde\|import.*kinde\|KindeSDK\|KindePythonSDK" src/content/docs/developer-tools/sdks/backend/python-sdk.mdxRepository: kinde-oss/documentation
Length of output: 49
🏁 Script executed:
# Check if there's documentation within the mdx file that explains the API
rg -i "method signature|parameters|arguments|handle_redirect.*\(" src/content/docs/developer-tools/sdks/backend/python-sdk.mdx -B 2 -A 2 | head -30Repository: kinde-oss/documentation
Length of output: 1129
🏁 Script executed:
# Check the section headings and context around handle_redirect calls
rg -n "##|handle_redirect" src/content/docs/developer-tools/sdks/backend/python-sdk.mdx | head -40Repository: kinde-oss/documentation
Length of output: 1696
🏁 Script executed:
# Get more context around each handle_redirect call with line numbers
rg -n "handle_redirect" src/content/docs/developer-tools/sdks/backend/python-sdk.mdx -B 15 -A 5 | sed -n '1,100p'Repository: kinde-oss/documentation
Length of output: 3572
🏁 Script executed:
# Look for any notes, comments, or explanations about the API signature differences
rg -i "note|important|user_id|session" src/content/docs/developer-tools/sdks/backend/python-sdk.mdx | grep -A 2 -B 2 "user_id\|session" | head -40Repository: kinde-oss/documentation
Length of output: 3136
🏁 Script executed:
# Get the "Choose your OAuth client" and "Client selection guide" sections
sed -n '173,256p' src/content/docs/developer-tools/sdks/backend/python-sdk.mdxRepository: kinde-oss/documentation
Length of output: 2994
🏁 Script executed:
# Also check the comparison table section
sed -n '197,230p' src/content/docs/developer-tools/sdks/backend/python-sdk.mdxRepository: kinde-oss/documentation
Length of output: 1168
🏁 Script executed:
# Check what clients are mentioned in the overview sections
rg -A 20 "Using the OAuth client|Using the AsyncOAuth client|Using the SmartOAuth client" src/content/docs/developer-tools/sdks/backend/python-sdk.mdx | head -80Repository: kinde-oss/documentation
Length of output: 1743
Document which client type each example uses and explain parameter differences.
The handle_redirect method has different signatures for different client types:
OAuth(framework-based):oauth.handle_redirect(code, user_id, state)- handles session management internallyAsyncOAuth(native async):await oauth.handle_redirect(code, state)- requires custom session handling
The documentation explains these client types in the "Choose your OAuth client" section, but the code examples don't identify which client is being used. Add a comment like # Using OAuth client or # Using AsyncOAuth client above each example, or expand the client selection guide to explain why the method signatures differ. This prevents confusion about which signature developers should use in their own code.
🤖 Prompt for AI Agents
In @src/content/docs/developer-tools/sdks/backend/python-sdk.mdx around lines
479 - 495, Add explicit comments and brief notes in the examples to indicate
which client type is used and which handle_redirect signature applies: above the
callback function example add a comment like "# Using OAuth client" and mention
that OAuth.handle_redirect(code, user_id, state) manages session internally, and
in any async example add "# Using AsyncOAuth client" noting AsyncOAuth requires
"await oauth.handle_redirect(code, state)" and custom session management; update
the callback docstring or surrounding text to call out the different parameter
requirements for handle_redirect across OAuth vs AsyncOAuth so readers know
which signature to follow.
Description (required)
Added a comprehensive migration guide for transitioning from v1 to v2 of the Kinde Python SDK, including code examples and client selection criteria. Expanded sections on using different client types (OAuth, AsyncOAuth, SmartOAuth) with practical implementation examples for Flask and FastAPI. Updated error handling and feature flag usage sections to reflect new patterns and best practices.
Related issues & labels (optional)
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.