feat: support Python 3.9+ with optional MCP server support #28
Conversation
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
This is needed because mypy sees the Python version check as always false when running on Python 3.10+, making the subsequent code unreachable. The code is actually reachable at runtime when Python 3.10+ is used.
- Add Requirements section with Python 3.9+ for core SDK - Add installation options for optional features - Document MCP server requiring Python 3.10+ - Add note about CrewAI requiring Python 3.10+
- Rename optional dependency group from 'server' to 'mcp' for better clarity - Update CI workflows to use --without mcp instead of --without server - Update README installation instructions - Update error message in MCP server module
Use --all-extras --no-extra mcp instead of --without-group mcp for excluding optional dependencies in uv sync command.
- Add eval-type-backport dependency for Python <3.10 to handle union types - Fix mypy exclusion syntax for server.py when MCP is not available
ryoppippi
commented
Aug 26, 2025
| python_type: type = str # Default to str | ||
| if isinstance(details, dict): | ||
| type_str = details.get("type", "string") | ||
| match type_str: |
- Add TODO for zip strict parameter - Add TODO for eval-type-backport dependency
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
cubic analysis
10 issues found across 11 files
Linked issue analysis
Linked issue: ENG-10906: [ai-python]: support python3.9 for pydantic sdk
| Status | Acceptance criteria | Notes |
|---|---|---|
| ✅ | Downgrade supported Python version to >=3.9 in packaging | Changed requires-python to >=3.9 in pyproject.toml |
| ✅ | Make MCP server an optional extra requiring Python 3.10+ | Moved mcp into optional deps with python_version guard |
| ✅ | Guard MCP server code to require Python 3.10+ and surface helpful error if MCP not installed | Added runtime version check and ImportError message in server.py |
| ✅ | Replace Python 3.10-only syntax in core SDK to be compatible with Python 3.9 | Replaced match/case and | unions in core files where needed |
| ✅ | Add typing-extensions and __future__ annotations as needed for Python 3.9 compatibility | Added __future__ imports and typing_extensions TypeAlias |
| ✅ | Update CI to test Python 3.9-3.13 with appropriate dependency sets per version | Test matrix added for 3.9-3.13 and per-version extras |
| ✅ | Verify core SDK works on Python 3.9 without MCP (Test plan) | CI will run 3.9 with --without mcp and core code adjusted |
| ✅ | Verify MCP functionality works on Python 3.10+ (Test plan) | CI will run 3.10+ with all extras and server guarded for 3.10+ |
| ✅ | Update README/docs to document requirements and optional extras | README updated with Requirements and optional install snippets |
| ✅ | Update ruff and mypy config to target Python 3.9 | ruff target-version and mypy python_version set to 3.9 |
React with 👍 or 👎 to teach cubic. You can also tag @cubic-dev-ai to give feedback, ask questions, or re-run the review.
README.md
Outdated
|
|
||
| CrewAI uses LangChain tools natively, making integration seamless: | ||
|
|
||
| > **Note**: CrewAI requires Python 3.10+. Install with `pip install stackone-ai[examples]` |
There was a problem hiding this comment.
Quote extras in the inline pip install example to avoid shell globbing issues in zsh and similar shells.
Prompt for AI agents
Address the following comment on README.md at line 109:
<comment>Quote extras in the inline pip install example to avoid shell globbing issues in zsh and similar shells.</comment>
<file context>
@@ -82,10 +102,12 @@ for tool_call in response.tool_calls:
</details>
<details>
-<summary>CrewAI Integration</summary>
+<summary>CrewAI Integration (Python 3.10+)</summary>
CrewAI uses LangChain tools natively, making integration seamless:
+> **Note**: CrewAI requires Python 3.10+. Install with `pip install stackone-ai[examples]`
</file context>
Suggested change
| > **Note**: CrewAI requires Python 3.10+. Install with `pip install stackone-ai[examples]` | |
| > **Note**: CrewAI requires Python 3.10+. Install with `pip install "stackone-ai[examples]"` |
README.md
Outdated
| pip install stackone-ai[examples] | ||
|
|
||
| # Install everything | ||
| pip install stackone-ai[mcp,examples] |
There was a problem hiding this comment.
Quote combined extras in pip install to avoid shell globbing issues.
Prompt for AI agents
Address the following comment on README.md at line 44:
<comment>Quote combined extras in pip install to avoid shell globbing issues.</comment>
<file context>
@@ -18,12 +18,32 @@ StackOne AI provides a unified interface for accessing various SaaS tools throug
- CrewAI Tools
- LangGraph Tool Node
+## Requirements
+
+- Python 3.9+ (core SDK functionality)
+- Python 3.10+ (for MCP server and CrewAI examples)
+
## Installation
</file context>
Suggested change
| pip install stackone-ai[mcp,examples] | |
| pip install "stackone-ai[mcp,examples]" |
README.md
Outdated
| pip install stackone-ai[mcp] | ||
|
|
||
| # Install with CrewAI examples (requires Python 3.10+) | ||
| pip install stackone-ai[examples] |
There was a problem hiding this comment.
Quote extras in pip install to prevent shell globbing errors in some shells.
Prompt for AI agents
Address the following comment on README.md at line 41:
<comment>Quote extras in pip install to prevent shell globbing errors in some shells.</comment>
<file context>
@@ -18,12 +18,32 @@ StackOne AI provides a unified interface for accessing various SaaS tools throug
- CrewAI Tools
- LangGraph Tool Node
+## Requirements
+
+- Python 3.9+ (core SDK functionality)
+- Python 3.10+ (for MCP server and CrewAI examples)
+
## Installation
</file context>
Suggested change
| pip install stackone-ai[examples] | |
| pip install "stackone-ai[examples]" |
README.md
Outdated
|
|
||
| ```bash | ||
| # Install with MCP server support (requires Python 3.10+) | ||
| pip install stackone-ai[mcp] |
There was a problem hiding this comment.
Quote extras in pip install to avoid shell globbing (e.g., zsh) causing 'no matches found'.
Prompt for AI agents
Address the following comment on README.md at line 38:
<comment>Quote extras in pip install to avoid shell globbing (e.g., zsh) causing 'no matches found'.</comment>
<file context>
@@ -18,12 +18,32 @@ StackOne AI provides a unified interface for accessing various SaaS tools throug
- CrewAI Tools
- LangGraph Tool Node
+## Requirements
+
+- Python 3.9+ (core SDK functionality)
+- Python 3.10+ (for MCP server and CrewAI examples)
+
## Installation
</file context>
Suggested change
| pip install stackone-ai[mcp] | |
| pip install "stackone-ai[mcp]" |
The build_docs.py script requires Python 3.11+ and processes MCP examples, so we need Python 3.11 with all extras for proper documentation generation.
- Add quotes around extras in all pip install examples - Prevents 'no matches found' errors in zsh and similar shells - Affects both installation section and inline examples
- Add urllib.parse.quote to safely encode path parameters - Use safe='' to encode all special characters including '/', ':', '@' - Prevents attackers from injecting malicious hosts or internal service paths - Applies to both explicit PATH parameters and default path replacement logic
- Add matrix strategy to test both Python 3.9 and 3.11 - Configure appropriate dependency installation for each version - Python 3.9: excludes MCP extras (not supported) - Python 3.11: includes all extras for full coverage - Aligns with existing test workflow pattern for consistency
- Change from 3.9/3.11 matrix to 3.9/3.10 for better coverage - Maintains appropriate dependency configurations for each version
glebedel
reviewed
Aug 26, 2025
.github/workflows/test.yml
Outdated
Comment on lines
13
to
24
| python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"] | ||
| include: | ||
| - python-version: "3.9" | ||
| test-extras: "--all-extras --no-extra mcp" | ||
| - python-version: "3.10" | ||
| test-extras: "--all-extras" | ||
| - python-version: "3.11" | ||
| test-extras: "--all-extras" | ||
| - python-version: "3.12" | ||
| test-extras: "--all-extras" | ||
| - python-version: "3.13" | ||
| test-extras: "--all-extras" |
Contributor
There was a problem hiding this comment.
do we need all of these, can we just do 3.9 & 3.10 assuming backwards compatibility ? Maybe 3.9/3.10 & the latest LTE
Member
Author
There was a problem hiding this comment.
oh 3.14 is the latest
ryoppippi
force-pushed
the
ENG-10906-ai-python-support-python-3-9-for-pydantic-sdk
branch
from
2f29b4c to
03b8438
Compare
ryoppippi
deleted the
ENG-10906-ai-python-support-python-3-9-for-pydantic-sdk
branch
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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
[mcp]extra requiring Python 3.10+Background
Python 3.9 reaches end-of-life in October 2025, but the MCP SDK only supports Python 3.10+. To maximize compatibility while the transition happens, we've made MCP functionality optional.
Changes Made
Core Compatibility
from __future__ import annotationsfor modern type hint compatibility in Python 3.9matchstatements with if-elif chains for Python 3.9 compatibilitytyping_extensions.TypeAliasfor TypeAlias support in Python 3.9isinstance(x, dict | list)withisinstance(x, (dict, list))strict=Falseparameter fromzip()(Python 3.10+ feature)Dependency Management
mcp[cli]to optional[mcp]dependency with Python 3.10+ requirementcrewaito optional[examples]dependency with Python 3.10+ requirementeval-type-backportfor Python 3.9 Pydantic compatibilityRuntime Checks
CI/CD Updates
--all-extras --no-extra mcpto exclude MCP dependencies--all-extrasDocumentation
Breaking Changes
pip install 'stackone-ai[mcp]'pip install 'stackone-ai[examples]'Future Refactoring
Added comprehensive TODO comments throughout the codebase to make it easy to refactor when Python 3.9 support is dropped (October 2025 EOL). Search for "TODO: Remove when Python 3.9 support is dropped" to find all compatibility code that can be cleaned up.
Test Plan