Repository navigation
Description
🔴 Required Information
Describe the Bug:
Multiple README documentation files under contributing/samples/ contain invalid Python syntax in sample code blocks or incorrect Markdown code-fence language specifiers.
Specifically:
- Mislabelled Language Tags: Shell installation commands and database connection strings are tagged with
python instead ofbash or ```text. - Python Syntax Errors: Several sample snippets contain invalid Python syntax such as missing commas between parameters, positional ellipsis (
...) placed after keyword arguments, and an orphanedelifblock with no precedingif.
These syntax errors break Python AST parsing (including ADK's adk-verify-snippets verification tool) and cause immediate SyntaxError when developers attempt to run or adapt these sample snippets.
Steps to Reproduce:
- Mislabelled Shell Commands & URLs:
contributing/samples/integrations/langchain_youtube_search_agent/README.md: The bash commanduv pip install youtube_searchis fenced as ```python.contributing/samples/context_management/postgres_session_service/README.md: The connection URLpostgresql+asyncpg://username:password@host:port/databaseis fenced as ```python.
- Python Syntax Errors (Missing commas / Invalid argument ordering):
contributing/samples/core/hello_world/README.md(lines 56–68): Missing comma after...between kwargs inAgent(name='hello_world_agent', ... generate_content_config=...).contributing/samples/hitl/tool_confirmation/README.md(lines 40–45): An isolatedelifstatement without an enclosingifblock.contributing/samples/hitl/tool_confirmation/README.md(lines 58–63): Missing comma after...beforetools=[...].contributing/samples/hitl/request_input_tool/README.md(lines 42–46): Positional...placed after keyword argumenttools=[...].contributing/samples/multi_agent/single_turn_sub_agent/README.md(lines 35–43 & 48–51): Positional...placed after keyword arguments.contributing/samples/multi_agent/task_sub_agent/README.md(lines 36–42 & 47–52): Positional...placed after keyword arguments.
Expected Behavior:
- Shell commands should be fenced with
bash orsh. - URIs and plain text formats should be fenced with ```text.
- All code blocks tagged with ```python should be syntactically valid Python code (or properly annotated with
<!-- verify-snippets: ignore -->if intended as illustrative pseudo-code fragments).
Observed Behavior:
Parsing these snippets via ast.parse() or executing them raises:
SyntaxError: invalid syntax. Perhaps you forgot a comma?SyntaxError: positional argument follows keyword argumentSyntaxError: invalid syntax(on orphanedelif)
Environment Details:
- ADK Library Version:
mainbranch (commitHEAD) - Desktop OS: Windows / Linux / macOS
- Python Version: Python 3.11+
Model Information:
- Are you using LiteLLM: No
- Which model is being used: N/A (Documentation issue)
🟡 Optional Information
Minimal Reproduction Code:
import ast
# Example 1: Missing comma in hello_world/README.md
code_1 = """
root_agent = Agent(
name='hello_world_agent',
...
generate_content_config=types.GenerateContentConfig()
)
"""
ast.parse(code_1)
# Raises: SyntaxError: invalid syntax. Perhaps you forgot a comma?
# Example 2: Positional ellipsis following kwargs in single_turn_sub_agent/README.md
code_2 = """
phone_recommender = Agent(
name="phone_recommender",
mode="single_turn",
input_schema=UserPreferences,
output_schema=PhoneRecommendation,
tools=[check_phone_price],
...
)
"""
ast.parse(code_2)
# Raises: SyntaxError: positional argument follows keyword argumentHow often has this issue occurred?:
Always (100%)
Willingness to contribute:
Yes! I have forked the repository and would like to submit a Pull Request to fix these code fences and sample snippets.
Activity
docs: fix syntax errors and language tags in sample READMEs