Merge branch 'master' into visualizing-python-plt-scatter

Author: bzaczynski

claude-api-python/README.md

@@ -0,0 +1,3 @@
+# How to Use the Claude API in Python
+
+This folder contains supporting materials for the Real Python tutorial [How to Use the Claude API in Python](https://realpython.com/claude-api-python/).

claude-api-python/basic_claude_call.py

@@ -0,0 +1,11 @@
+import anthropic
+
+client = anthropic.Anthropic()
+
+response = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "What is the Zen of Python?"}],
+)
+
+print(response.content[0].text)

claude-api-python/coding_assistant.py

@@ -0,0 +1,20 @@
+import anthropic
+
+client = anthropic.Anthropic()
+
+system_prompt = """
+You are a Python coding assistant. You only answer questions about Python.
+If the user asks about any other programming language or unrelated topic,
+politely explain that you can only help with Python questions.
+"""
+
+user_input = input("Ask me anything about Python: ")
+
+response = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    system=system_prompt,
+    messages=[{"role": "user", "content": user_input}],
+)
+
+print(f"\n{response.content[0].text}")

claude-api-python/requirements.txt

@@ -0,0 +1,2 @@
+anthropic
+pydantic

claude-api-python/structured_output_1.py

@@ -0,0 +1,38 @@
+import anthropic
+import json
+
+client = anthropic.Anthropic()
+
+response = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    system="You are a Python coding assistant.",
+    messages=[
+        {
+            "role": "user",
+            "content": "Write a Python function that adds two numbers.",
+        }
+    ],
+    output_config={
+        "format": {
+            "type": "json_schema",
+            "schema": {
+                "type": "object",
+                "properties": {
+                    "function_name": {"type": "string"},
+                    "code": {"type": "string"},
+                    "explanation": {"type": "string"},
+                },
+                "required": ["function_name", "code", "explanation"],
+                "additionalProperties": False,
+            },
+        }
+    },
+)
+
+result = json.loads(response.content[0].text)
+
+print("--- Approach 1: Handwritten JSON schema ---")
+print(f"Function: {result['function_name']}")
+print(f"\nCode:\n{result['code']}")
+print(f"\nExplanation: {result['explanation']}")

claude-api-python/structured_output_2.py

@@ -0,0 +1,32 @@
+import anthropic
+
+from pydantic import BaseModel
+
+
+class FunctionDescription(BaseModel):
+    function_name: str
+    code: str
+    explanation: str
+
+
+client = anthropic.Anthropic()
+
+response = client.messages.parse(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    system="You are a Python coding assistant.",
+    messages=[
+        {
+            "role": "user",
+            "content": "Write a Python function that adds two numbers.",
+        }
+    ],
+    output_format=FunctionDescription,
+)
+
+result = response.parsed_output
+
+print("--- Approach 2: Pydantic + client.messages.parse() ---")
+print(f"Function: {result.function_name}")
+print(f"\nCode:\n{result.code}")
+print(f"\nExplanation: {result.explanation}")

cursor-vs-windsurf-python/README.md

@@ -0,0 +1,3 @@
+# Cursor vs Windsurf: Which AI Code Editor Is Best for Python?
+
+This folder provides the prompts and Cursor/Windsurf rules files used in the Real Python tutorial [Cursor vs Windsurf: Which AI Code Editor Is Best for Python?](https://realpython.com/cursor-vs-windsurf-python/)

cursor-vs-windsurf-python/cursor/http-client-conventions.mdc

@@ -0,0 +1,11 @@
+---
+globs: "**/*.py"
+alwaysApply: false
+---
+# Instructions
+- Use type hints for all functions, return values, and dataclass fields
+- Use `httpx.AsyncClient` for HTTP requests; do not use `requests`
+  or `aiohttp`
+- Use `await asyncio.sleep()` for delays; do not use `time.sleep()`
+- Return dataclasses for HTTP responses, not raw dictionaries
+- Follow PEP 8 style conventions

cursor-vs-windsurf-python/prompts.md

@@ -0,0 +1,72 @@
+# Prompts
+
+Copy-paste these into Cursor and Windsurf in order while following the tutorial.
+
+## 1. Set up the project
+
+```
+Set up a Python project in this directory following standard Python
+packaging conventions:
+- Create a virtual environment
+- Install httpx==0.28.1 and pytest==9.0.2
+- Add a tests/ directory
+- Use the directory name as the package name
+- Only include the dependencies explicitly listed here
+```
+
+## 2. Write the async fetch function
+
+```
+Create a file called `fetcher.py` and write an async function
+called fetch_json that:
+- Takes a URL string and an optional integer max_retries (default 3)
+- Uses httpx.AsyncClient to fetch JSON from the URL
+- Retries up to max_retries times with exponential backoff (1s, 2s, 4s)
+  on any httpx.HTTPError
+- Returns the JSON response as a typed dataclass called FetchResult
+  with fields: url (str), status_code (int), and data (dict[str, Any])
+- Uses proper type hints throughout
+```
+
+## 3. Generate tests
+
+Before sending this prompt, open `fetcher.py` and replace
+`await asyncio.sleep(delay)` with `time.sleep(delay)`, then add
+`import time` at the top. Save the file.
+
+```
+Create tests/test_fetcher.py with pytest tests for fetch_json that:
+- Test successful fetch returns correct FetchResult
+- Test fetch retries twice then succeeds
+- Test fetch raises after exhausting retries
+- Test two concurrent fetches complete in <4s
+  (one with 1s+2s retry delays, one instant)
+- Test fetch can be cancelled during retry delay
+Use httpx.MockTransport for mocking.
+```
+
+## 4. Plan-mode prompt
+
+Switch each editor to its Plan mode before sending:
+
+```
+Add a retry_budget parameter to fetch_json that limits the total
+cumulative wait time across all retries.
+```
+
+## 5. Autocomplete starter snippet
+
+Type this into a file and let each editor complete it:
+
+```python
+@dataclass
+class RetryMetadata:
+    attempts_made: int
+# ...
+```
+
+## 6. Manual review (Windsurf Ask mode)
+
+```
+Review fetcher.py for bugs and lint issues and summarize what you find.
+```

cursor-vs-windsurf-python/windsurf/http-client-conventions.md

@@ -0,0 +1,10 @@
+---
+trigger: glob
+globs: "**/*.py"
+---
+# Instructions
+- Use type hints for all functions, return values, and dataclass fields
+- Use `httpx.AsyncClient` for HTTP requests; do not use `requests` or `aiohttp`
+- Use `await asyncio.sleep()` for delays; do not use `time.sleep()`
+- Return dataclasses for HTTP responses, not raw dictionaries
+- Follow PEP 8 style conventions