chore: import upstream snapshot with attribution

tests/example_modules/README.md

@@ -0,0 +1,3 @@
+# docs examples imports
+
+This directory is added to `sys.path` in `tests/test_examples.py::test_docs_examples` to augment some of the examples.

tests/example_modules/bank_database.py

@@ -0,0 +1,86 @@
+from __future__ import annotations as _annotations
+
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import Any
+
+DB_SCHEMA = """
+CREATE TABLE customers (
+    id INT PRIMARY KEY,
+    name TEXT NOT NULL
+);
+
+INSERT INTO customers (id, name) VALUES (123, 'John'), (456, 'Bob'), (789, 'Charlie');
+
+CREATE TABLE balances (
+    id SERIAL PRIMARY KEY,
+    customer_id INT NOT NULL REFERENCES customers(id),
+    balance FLOAT NOT NULL,
+    pending_balance FLOAT NOT NULL
+);
+
+INSERT INTO balances (customer_id, balance, pending_balance) VALUES (123, 123.45, 123.45);
+"""
+
+
+# pyright: reportUnknownVariableType=false
+# pyright: reportUnknownMemberType=false
+@dataclass
+class DatabaseConnPostgres:
+    _conn: Any
+
+    @classmethod
+    @asynccontextmanager
+    async def connect(cls):
+        import asyncpg
+
+        server_dsn = 'postgres://postgres:postgres@localhost:5432'
+        database = 'bank'
+        conn = await asyncpg.connect(server_dsn)
+        try:
+            db_exists = await conn.fetchval('SELECT 1 FROM pg_database WHERE datname = $1', database)
+            if not db_exists:
+                await conn.execute(f'CREATE DATABASE {database}')
+        finally:
+            await conn.close()
+
+        conn = await asyncpg.connect(f'{server_dsn}/{database}')
+        try:
+            if not db_exists:
+                await conn.execute(DB_SCHEMA)
+
+            yield cls(conn)
+        finally:
+            await conn.close()
+
+    async def customer_name(self, *, id: int) -> str | None:
+        return await self._conn.fetchval('SELECT name FROM customers WHERE id = $1', id)
+
+    async def customer_balance(self, *, id: int, include_pending: bool) -> float:
+        row = await self._conn.fetchrow('SELECT balance, pending_balance FROM balances WHERE customer_id = $1', id)
+        if row is None:
+            raise ValueError('Customer not found')
+        else:
+            return row['pending_balance' if include_pending else 'balance']
+
+
+@dataclass
+class DatabaseConnNoop:
+    @classmethod
+    @asynccontextmanager
+    async def connect(cls):
+        yield cls()
+
+    async def customer_name(self, *, id: int) -> str | None:
+        if id == 123:
+            return 'John'
+
+    async def customer_balance(self, *, id: int, include_pending: bool) -> float:
+        if id == 123:
+            return 123.45
+        else:
+            raise ValueError('Customer not found')
+
+
+# to keep tests running quickly we use a no-op database connection for tests
+DatabaseConn = DatabaseConnNoop

tests/example_modules/fake_database.py

@@ -0,0 +1,29 @@
+from __future__ import annotations as _annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class FakeTable:
+    def get(self, name: str) -> int | None:
+        if name == 'John Doe':
+            return 123
+
+
+@dataclass
+class DatabaseConn:
+    users: FakeTable = field(default_factory=FakeTable)
+    _forecasts: dict[int, str] = field(default_factory=dict[int, str])
+
+    async def execute(self, query: str) -> list[dict[str, Any]]:
+        return [{'id': 123, 'name': 'John Doe'}]
+
+    async def store_forecast(self, user_id: int, forecast: str) -> None:
+        self._forecasts[user_id] = forecast
+
+    async def get_forecast(self, user_id: int) -> str | None:
+        return self._forecasts.get(user_id)
+
+
+class QueryError(RuntimeError):
+    pass

tests/example_modules/mcp_server.py

@@ -0,0 +1,32 @@
+from typing import Any
+
+from mcp.server.fastmcp import Context, FastMCP
+from mcp.server.session import ServerSessionT
+from mcp.shared.context import LifespanContextT, RequestT
+
+mcp = FastMCP('Pydantic AI MCP Server')
+
+
+@mcp.tool()
+async def get_weather_forecast(location: str) -> str:
+    """Get the weather forecast for a location."""
+    return f'The weather in {location} is sunny and 26 degrees Celsius.'
+
+
+@mcp.tool()
+async def echo_deps(ctx: Context[ServerSessionT, LifespanContextT, RequestT]) -> dict[str, Any]:
+    """Echo the run context.
+
+    Args:
+        ctx: Context object containing request and session information.
+
+    Returns:
+        Dictionary with an echo message and the deps.
+    """
+
+    deps: Any = getattr(ctx.request_context.meta, 'deps')
+    return {'echo': 'This is an echo message', 'deps': deps}
+
+
+if __name__ == '__main__':
+    mcp.run()

tests/example_modules/weather_service.py

@@ -0,0 +1,18 @@
+from __future__ import annotations as _annotations
+
+from datetime import date
+from typing import Any
+
+
+class WeatherService:
+    def get_historic_weather(self, location: str, forecast_date: date) -> str:
+        return 'Sunny with a chance of rain'
+
+    def get_forecast(self, location: str, forecast_date: date) -> str:
+        return 'Rainy with a chance of sun'
+
+    async def __aenter__(self) -> WeatherService:
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        pass