Fix Python syntax errors in v2 documentation examples

README.md

@@ -52,6 +52,27 @@ When contributing, please follow these guidelines:
 - Keep the documentation clear, concise, and easy to understand.
 - Use proper formatting and adhere to the existing document structure.
 - Test your changes locally before submitting a pull request.
+- **Validate Python code examples** before submitting to ensure they use proper syntax.
+
+### Validating Python Examples
+
+Before submitting changes to Python code examples, run the validation script to ensure all Python code blocks are syntactically valid:
+
+```bash
+# Validate all Python examples in the repository
+python3 scripts/validate_python_syntax.py
+
+# Validate a specific file
+python3 scripts/validate_python_syntax.py advanced-scraping-guide.mdx
+
+# Validate a specific directory
+python3 scripts/validate_python_syntax.py snippets/
+```
+
+This helps catch common syntax errors like:
+- Unquoted dictionary keys (use `{"key": "value"}` not `{ key: 'value' }`)
+- JavaScript-style semicolons in Python code
+- Invalid Python syntax that would confuse users
 
 ## Contact
 

advanced-scraping-guide.mdx

@@ -129,14 +129,14 @@ from firecrawl import Firecrawl
 firecrawl = Firecrawl(api_key='fc-YOUR-API-KEY')
 
 doc = firecrawl.scrape('https://example.com', {
-  actions: [
-    { type: 'wait', milliseconds: 1000 },
-    { type: 'click', selector: '#accept' },
-    { type: 'scroll', direction: 'down' },
-    { type: 'write', selector: '#q', text: 'firecrawl' },
-    { type: 'press', key: 'Enter' }
+  "actions": [
+    {"type": "wait", "milliseconds": 1000},
+    {"type": "click", "selector": "#accept"},
+    {"type": "scroll", "direction": "down"},
+    {"type": "write", "selector": "#q", "text": "firecrawl"},
+    {"type": "press", "key": "Enter"}
   ],
-  formats: ['markdown']
+  "formats": ['markdown']
 })
 
 print(doc.markdown)

es/advanced-scraping-guide.mdx

@@ -153,14 +153,14 @@ from firecrawl import Firecrawl
 firecrawl = Firecrawl(api_key='fc-YOUR-API-KEY')
 
 doc = firecrawl.scrape('https://example.com', {
-  actions: [
-    { type: 'wait', milliseconds: 1000 },
-    { type: 'click', selector: '#accept' },
-    { type: 'scroll', direction: 'down' },
-    { type: 'write', selector: '#q', text: 'firecrawl' },
-    { type: 'press', key: 'Enter' }
+  "actions": [
+    {"type": "wait", "milliseconds": 1000},
+    {"type": "click", "selector": "#accept"},
+    {"type": "scroll", "direction": "down"},
+    {"type": "write", "selector": "#q", "text": "firecrawl"},
+    {"type": "press", "key": "Enter"}
   ],
-  formats: ['markdown']
+  "formats": ['markdown']
 })
 
 print(doc.markdown)
@@ -528,4 +528,4 @@ curl -X POST https://api.firecrawl.dev/v2/map \
 
 Consulta la referencia de la API: [Documentación del endpoint /map](https://docs.firecrawl.dev/api-reference/endpoint/map)
 
-¡Gracias por leer!
+¡Gracias por leer!

fr/advanced-scraping-guide.mdx

@@ -153,14 +153,14 @@ from firecrawl import Firecrawl
 firecrawl = Firecrawl(api_key='fc-YOUR-API-KEY')
 
 doc = firecrawl.scrape('https://example.com', {
-  actions: [
-    { type: 'wait', milliseconds: 1000 },
-    { type: 'click', selector: '#accept' },
-    { type: 'scroll', direction: 'down' },
-    { type: 'write', selector: '#q', text: 'firecrawl' },
-    { type: 'press', key: 'Enter' }
+  "actions": [
+    {"type": "wait", "milliseconds": 1000},
+    {"type": "click", "selector": "#accept"},
+    {"type": "scroll", "direction": "down"},
+    {"type": "write", "selector": "#q", "text": "firecrawl"},
+    {"type": "press", "key": "Enter"}
   ],
-  formats: ['markdown']
+  "formats": ['markdown']
 })
 
 print(doc.markdown)
@@ -526,4 +526,4 @@ curl -X POST https://api.firecrawl.dev/v2/map \
 
 Voici la référence de l’API correspondante : [Documentation du point de terminaison /map](https://docs.firecrawl.dev/api-reference/endpoint/map)
 
-Merci de votre lecture !
+Merci de votre lecture !

ja/advanced-scraping-guide.mdx

@@ -153,14 +153,14 @@ from firecrawl import Firecrawl
 firecrawl = Firecrawl(api_key='fc-YOUR-API-KEY')
 
 doc = firecrawl.scrape('https://example.com', {
-  actions: [
-    { type: 'wait', milliseconds: 1000 },
-    { type: 'click', selector: '#accept' },
-    { type: 'scroll', direction: 'down' },
-    { type: 'write', selector: '#q', text: 'firecrawl' },
-    { type: 'press', key: 'Enter' }
+  "actions": [
+    {"type": "wait", "milliseconds": 1000},
+    {"type": "click", "selector": "#accept"},
+    {"type": "scroll", "direction": "down"},
+    {"type": "write", "selector": "#q", "text": "firecrawl"},
+    {"type": "press", "key": "Enter"}
   ],
-  formats: ['markdown']
+  "formats": ['markdown']
 })
 
 print(doc.markdown)
@@ -526,4 +526,4 @@ curl -X POST https://api.firecrawl.dev/v2/map \
 
 該当するAPIリファレンスはこちら: [Map Endpoint Documentation](https://docs.firecrawl.dev/api-reference/endpoint/map)
 
-お読みいただきありがとうございました。
+お読みいただきありがとうございました。

pt-BR/advanced-scraping-guide.mdx

@@ -153,14 +153,14 @@ from firecrawl import Firecrawl
 firecrawl = Firecrawl(api_key='fc-YOUR-API-KEY')
 
 doc = firecrawl.scrape('https://example.com', {
-  actions: [
-    { type: 'wait', milliseconds: 1000 },
-    { type: 'click', selector: '#accept' },
-    { type: 'scroll', direction: 'down' },
-    { type: 'write', selector: '#q', text: 'firecrawl' },
-    { type: 'press', key: 'Enter' }
+  "actions": [
+    {"type": "wait", "milliseconds": 1000},
+    {"type": "click", "selector": "#accept"},
+    {"type": "scroll", "direction": "down"},
+    {"type": "write", "selector": "#q", "text": "firecrawl"},
+    {"type": "press", "key": "Enter"}
   ],
-  formats: ['markdown']
+  "formats": ['markdown']
 })
 
 print(doc.markdown)
@@ -526,4 +526,4 @@ curl -X POST https://api.firecrawl.dev/v2/map \
 
 Aqui está a referência da API correspondente: [Documentação do endpoint /map](https://docs.firecrawl.dev/api-reference/endpoint/map)
 
-Obrigado pela leitura!
+Obrigado pela leitura!

scripts/validate_python_syntax.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""
+Validate Python syntax in markdown documentation files.
+
+This script extracts Python code blocks from MDX/markdown files and verifies
+they are syntactically valid. Run this before submitting PRs to catch Python
+syntax errors in documentation examples.
+
+Usage:
+    python3 scripts/validate_python_syntax.py [file_or_directory]
+
+Examples:
+    python3 scripts/validate_python_syntax.py
+
+    python3 scripts/validate_python_syntax.py advanced-scraping-guide.mdx
+
+    python3 scripts/validate_python_syntax.py snippets/
+"""
+import re
+import ast
+import sys
+from pathlib import Path
+from typing import List, Tuple
+
+def extract_python_blocks(content: str) -> List[str]:
+    """Extract Python code blocks from markdown content."""
+    pattern = r'```python.*?\n(.*?)```'
+    matches = re.findall(pattern, content, re.DOTALL)
+    return matches
+
+def validate_python_code(code: str) -> Tuple[bool, str]:
+    """Check if Python code is syntactically valid."""
+    try:
+        ast.parse(code)
+        return True, ""
+    except SyntaxError as e:
+        return False, str(e)
+
+def find_python_files(path: Path) -> List[Path]:
+    """Find all MDX and markdown files that might contain Python code."""
+    if path.is_file():
+        return [path]
+
+    patterns = ['**/*.mdx', '**/*.md']
+    files = []
+    for pattern in patterns:
+        files.extend(path.glob(pattern))
+    return sorted(set(files))
+
+def main(target_path: str = None):
+    """Validate Python syntax in documentation files."""
+    if target_path:
+        base_path = Path(target_path)
+        if not base_path.exists():
+            print(f"❌ Path not found: {target_path}")
+            return 1
+    else:
+        base_path = Path.cwd()
+
+    files = find_python_files(base_path)
+
+    if not files:
+        print(f"⚠️  No markdown/MDX files found in {base_path}")
+        return 1
+
+    all_valid = True
+    total_blocks = 0
+    files_with_python = 0
+
+    for filepath in files:
+        try:
+            content = filepath.read_text()
+        except Exception as e:
+            print(f"❌ Error reading {filepath}: {e}")
+            continue
+
+        blocks = extract_python_blocks(content)
+
+        if not blocks:
+            continue
+
+        files_with_python += 1
+        print(f"\n📄 {filepath.relative_to(base_path if base_path.is_dir() else base_path.parent)}")
+
+        for i, block in enumerate(blocks, 1):
+            total_blocks += 1
+            is_valid, error = validate_python_code(block)
+            if is_valid:
+                print(f"  ✅ Block {i}: Valid Python syntax")
+            else:
+                print(f"  ❌ Block {i}: Invalid Python syntax")
+                print(f"     Error: {error}")
+                print(f"     Code preview:\n{block[:200]}...")
+                all_valid = False
+
+    print(f"\n{'='*60}")
+    print(f"Files checked: {len(files)}")
+    print(f"Files with Python blocks: {files_with_python}")
+    print(f"Total Python blocks validated: {total_blocks}")
+
+    if total_blocks == 0:
+        print("⚠️  No Python code blocks found")
+        return 0
+
+    if all_valid:
+        print("✅ All Python code blocks are syntactically valid!")
+        return 0
+    else:
+        print("❌ Some Python code blocks have syntax errors!")
+        return 1
+
+if __name__ == "__main__":
+    target = sys.argv[1] if len(sys.argv) > 1 else None
+    sys.exit(main(target))

snippets/es/v2/scrape/actions/python.mdx

@@ -4,16 +4,16 @@ from firecrawl import Firecrawl
 firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")
 
 doc = firecrawl.scrape('https://example.com/login', {
-  formats=['markdown'],
-  actions=[
-    { type: 'write', text: 'john@example.com' },
-    { type: 'press', key: 'Tab' },
-    { type: 'write', text: 'secret' },
-    { type: 'click', selector: 'button[type="submit"]' },
-    { type: 'wait', milliseconds: 1500 },
-    { type: 'screenshot', fullPage: true },
+  "formats": ['markdown'],
+  "actions": [
+    {"type": "write", "text": "john@example.com"},
+    {"type": "press", "key": "Tab"},
+    {"type": "write", "text": "secret"},
+    {"type": "click", "selector": "button[type=\"submit\"]"},
+    {"type": "wait", "milliseconds": 1500},
+    {"type": "screenshot", "fullPage": True},
   ],
-});
+})
 
-print(doc.markdown, doc.screenshot);
+print(doc.markdown, doc.screenshot)
 ```

snippets/fr/v2/scrape/actions/python.mdx

@@ -4,16 +4,16 @@ from firecrawl import Firecrawl
 firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")
 
 doc = firecrawl.scrape('https://example.com/login', {
-  formats=['markdown'],
-  actions=[
-    { type: 'write', text: 'john@example.com' },
-    { type: 'press', key: 'Tab' },
-    { type: 'write', text: 'secret' },
-    { type: 'click', selector: 'button[type="submit"]' },
-    { type: 'wait', milliseconds: 1500 },
-    { type: 'screenshot', fullPage: true },
+  "formats": ['markdown'],
+  "actions": [
+    {"type": "write", "text": "john@example.com"},
+    {"type": "press", "key": "Tab"},
+    {"type": "write", "text": "secret"},
+    {"type": "click", "selector": "button[type=\"submit\"]"},
+    {"type": "wait", "milliseconds": 1500},
+    {"type": "screenshot", "fullPage": True},
   ],
-});
+})
 
-print(doc.markdown, doc.screenshot);
+print(doc.markdown, doc.screenshot)
 ```

snippets/ja/v2/scrape/actions/python.mdx

@@ -4,16 +4,16 @@ from firecrawl import Firecrawl
 firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")
 
 doc = firecrawl.scrape('https://example.com/login', {
-  formats=['markdown'],
-  actions=[
-    { type: 'write', text: 'john@example.com' },
-    { type: 'press', key: 'Tab' },
-    { type: 'write', text: 'secret' },
-    { type: 'click', selector: 'button[type="submit"]' },
-    { type: 'wait', milliseconds: 1500 },
-    { type: 'screenshot', fullPage: true },
+  "formats": ['markdown'],
+  "actions": [
+    {"type": "write", "text": "john@example.com"},
+    {"type": "press", "key": "Tab"},
+    {"type": "write", "text": "secret"},
+    {"type": "click", "selector": "button[type=\"submit\"]"},
+    {"type": "wait", "milliseconds": 1500},
+    {"type": "screenshot", "fullPage": True},
   ],
-});
+})
 
-print(doc.markdown, doc.screenshot);
+print(doc.markdown, doc.screenshot)
 ```

snippets/pt-BR/v2/scrape/actions/python.mdx

@@ -4,16 +4,16 @@ from firecrawl import Firecrawl
 firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")
 
 doc = firecrawl.scrape('https://example.com/login', {
-  formats=['markdown'],
-  actions=[
-    { type: 'write', text: 'john@example.com' },
-    { type: 'press', key: 'Tab' },
-    { type: 'write', text: 'secret' },
-    { type: 'click', selector: 'button[type="submit"]' },
-    { type: 'wait', milliseconds: 1500 },
-    { type: 'screenshot', fullPage: true },
+  "formats": ['markdown'],
+  "actions": [
+    {"type": "write", "text": "john@example.com"},
+    {"type": "press", "key": "Tab"},
+    {"type": "write", "text": "secret"},
+    {"type": "click", "selector": "button[type=\"submit\"]"},
+    {"type": "wait", "milliseconds": 1500},
+    {"type": "screenshot", "fullPage": True},
   ],
-});
+})
 
-print(doc.markdown, doc.screenshot);
+print(doc.markdown, doc.screenshot)
 ```