From b0f733257d1c9e77bbe7bc23d0bfdcb3276e036a Mon Sep 17 00:00:00 2001 From: euri10 Date: Wed, 5 Nov 2025 15:47:18 +0100 Subject: [PATCH 1/8] add testfiles --- .../usage/test_drivers_and_querying_1.py | 17 ++++++++++ .../usage/test_drivers_and_querying_10.py | 14 ++++++++ .../usage/test_drivers_and_querying_11.py | 14 ++++++++ .../usage/test_drivers_and_querying_12.py | 14 ++++++++ .../usage/test_drivers_and_querying_13.py | 24 +++++++++++++ .../usage/test_drivers_and_querying_14.py | 22 ++++++++++++ .../usage/test_drivers_and_querying_15.py | 7 ++++ .../usage/test_drivers_and_querying_16.py | 8 +++++ .../usage/test_drivers_and_querying_17.py | 8 +++++ .../usage/test_drivers_and_querying_18.py | 7 ++++ .../usage/test_drivers_and_querying_19.py | 13 +++++++ .../usage/test_drivers_and_querying_2.py | 34 +++++++++++++++++++ .../usage/test_drivers_and_querying_20.py | 11 ++++++ .../usage/test_drivers_and_querying_21.py | 15 ++++++++ .../usage/test_drivers_and_querying_22.py | 14 ++++++++ .../usage/test_drivers_and_querying_23.py | 10 ++++++ .../usage/test_drivers_and_querying_24.py | 8 +++++ .../usage/test_drivers_and_querying_25.py | 7 ++++ .../usage/test_drivers_and_querying_26.py | 7 ++++ .../usage/test_drivers_and_querying_27.py | 18 ++++++++++ .../usage/test_drivers_and_querying_28.py | 8 +++++ .../usage/test_drivers_and_querying_3.py | 17 ++++++++++ .../usage/test_drivers_and_querying_4.py | 14 ++++++++ .../usage/test_drivers_and_querying_5.py | 16 +++++++++ .../usage/test_drivers_and_querying_6.py | 14 ++++++++ .../usage/test_drivers_and_querying_7.py | 19 +++++++++++ .../usage/test_drivers_and_querying_8.py | 15 ++++++++ .../usage/test_drivers_and_querying_9.py | 22 ++++++++++++ docs/usage/drivers_and_querying.rst | 1 + 29 files changed, 398 insertions(+) create mode 100644 docs/examples/usage/test_drivers_and_querying_1.py create mode 100644 docs/examples/usage/test_drivers_and_querying_10.py create mode 100644 docs/examples/usage/test_drivers_and_querying_11.py create mode 100644 docs/examples/usage/test_drivers_and_querying_12.py create mode 100644 docs/examples/usage/test_drivers_and_querying_13.py create mode 100644 docs/examples/usage/test_drivers_and_querying_14.py create mode 100644 docs/examples/usage/test_drivers_and_querying_15.py create mode 100644 docs/examples/usage/test_drivers_and_querying_16.py create mode 100644 docs/examples/usage/test_drivers_and_querying_17.py create mode 100644 docs/examples/usage/test_drivers_and_querying_18.py create mode 100644 docs/examples/usage/test_drivers_and_querying_19.py create mode 100644 docs/examples/usage/test_drivers_and_querying_2.py create mode 100644 docs/examples/usage/test_drivers_and_querying_20.py create mode 100644 docs/examples/usage/test_drivers_and_querying_21.py create mode 100644 docs/examples/usage/test_drivers_and_querying_22.py create mode 100644 docs/examples/usage/test_drivers_and_querying_23.py create mode 100644 docs/examples/usage/test_drivers_and_querying_24.py create mode 100644 docs/examples/usage/test_drivers_and_querying_25.py create mode 100644 docs/examples/usage/test_drivers_and_querying_26.py create mode 100644 docs/examples/usage/test_drivers_and_querying_27.py create mode 100644 docs/examples/usage/test_drivers_and_querying_28.py create mode 100644 docs/examples/usage/test_drivers_and_querying_3.py create mode 100644 docs/examples/usage/test_drivers_and_querying_4.py create mode 100644 docs/examples/usage/test_drivers_and_querying_5.py create mode 100644 docs/examples/usage/test_drivers_and_querying_6.py create mode 100644 docs/examples/usage/test_drivers_and_querying_7.py create mode 100644 docs/examples/usage/test_drivers_and_querying_8.py create mode 100644 docs/examples/usage/test_drivers_and_querying_9.py diff --git a/docs/examples/usage/test_drivers_and_querying_1.py b/docs/examples/usage/test_drivers_and_querying_1.py new file mode 100644 index 00000000..0537ebb9 --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_1.py @@ -0,0 +1,17 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 1 +# Typical driver usage +from sqlspec import SQLSpec +from sqlspec.adapters.asyncpg import AsyncpgConfig + +async def example(): + spec = SQLSpec() + db = spec.add_config(AsyncpgConfig(pool_config={})) + + async with spec.provide_session(db) as session: + result = await session.execute("SELECT 1") + print(result) + +if __name__ == "__main__": + import asyncio + asyncio.run(example()) + diff --git a/docs/examples/usage/test_drivers_and_querying_10.py b/docs/examples/usage/test_drivers_and_querying_10.py new file mode 100644 index 00000000..a1774f84 --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_10.py @@ -0,0 +1,14 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 10 +from sqlspec.adapters.duckdb import DuckDBConfig + +# In-memory +config_inmemory = DuckDBConfig() + +# Persistent +config_persistent = DuckDBConfig( + pool_config={"database": "analytics.duckdb"} +) + +# with spec.provide_session(config) as session: +# session.execute(...) etc. + diff --git a/docs/examples/usage/test_drivers_and_querying_11.py b/docs/examples/usage/test_drivers_and_querying_11.py new file mode 100644 index 00000000..c10228e6 --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_11.py @@ -0,0 +1,14 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 11 +from sqlspec.adapters.oracledb import OracleDBConfig + +config = OracleDBConfig( + pool_config={ + "user": "myuser", + "password": "mypassword", + "dsn": "localhost:1521/ORCLPDB", + } +) + +# with spec.provide_session(config) as session: +# result = session.execute("SELECT * FROM employees WHERE employee_id = :id", id=100) + diff --git a/docs/examples/usage/test_drivers_and_querying_12.py b/docs/examples/usage/test_drivers_and_querying_12.py new file mode 100644 index 00000000..2c45bb1f --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_12.py @@ -0,0 +1,14 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 12 +from sqlspec.adapters.bigquery import BigQueryConfig +import datetime + +config = BigQueryConfig( + pool_config={ + "project": "my-project", + "credentials": None, + } +) + +# with spec.provide_session(config) as session: +# result = session.execute("SELECT DATE(timestamp) as date, COUNT(*) as events FROM `project.dataset.events` WHERE timestamp >= @start_date GROUP BY date", start_date=datetime.date(2025,1,1)) + diff --git a/docs/examples/usage/test_drivers_and_querying_13.py b/docs/examples/usage/test_drivers_and_querying_13.py new file mode 100644 index 00000000..b7a0db20 --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_13.py @@ -0,0 +1,24 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 13 +# SELECT query example +# result = session.execute("SELECT * FROM users WHERE id = ?", 1) + +# INSERT query example +# result = session.execute( +# "INSERT INTO users (name, email) VALUES (?, ?)", +# "Alice", +# "alice@example.com" +# ) + +# UPDATE example +# result = session.execute( +# "UPDATE users SET email = ? WHERE id = ?", +# "newemail@example.com", +# 1 +# ) +# print(f"Updated {result.rows_affected} rows") + +# DELETE example +# result = session.execute("DELETE FROM users WHERE id = ?", 1) + +# These lines are examples and require a session object to run. + diff --git a/docs/examples/usage/test_drivers_and_querying_14.py b/docs/examples/usage/test_drivers_and_querying_14.py new file mode 100644 index 00000000..d91c8afa --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_14.py @@ -0,0 +1,22 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 14 +# Batch insert example +# session.execute_many( +# "INSERT INTO users (name, email) VALUES (?, ?)", +# [ +# ("Alice", "alice@example.com"), +# ("Bob", "bob@example.com"), +# ("Charlie", "charlie@example.com"), +# ] +# ) + +# Batch update example +# session.execute_many( +# "UPDATE users SET status = ? WHERE id = ?", +# [ +# ("active", 1), +# ("inactive", 2), +# ] +# ) + +# Examples require a session object to run. + diff --git a/docs/examples/usage/test_drivers_and_querying_15.py b/docs/examples/usage/test_drivers_and_querying_15.py new file mode 100644 index 00000000..197f9f35 --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_15.py @@ -0,0 +1,7 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 15 +# SELECT and all() example +# users = session.execute("SELECT * FROM users WHERE status = ?", "active") +# returns list of dicts + +# Placeholder only + diff --git a/docs/examples/usage/test_drivers_and_querying_16.py b/docs/examples/usage/test_drivers_and_querying_16.py new file mode 100644 index 00000000..7dba6318 --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_16.py @@ -0,0 +1,8 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 16 +# select_one example +# user = session.select_one("SELECT * FROM users WHERE id = ?", 1) +# Raises NotFoundError if no results +# Raises MultipleResultsFoundError if multiple results + +# Placeholder only + diff --git a/docs/examples/usage/test_drivers_and_querying_17.py b/docs/examples/usage/test_drivers_and_querying_17.py new file mode 100644 index 00000000..add83a26 --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_17.py @@ -0,0 +1,8 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 17 +# select_one_or_none example +# user = session.select_one_or_none("SELECT * FROM users WHERE email = ?", "nobody@example.com") +# Returns dict or None +# Raises MultipleResultsFoundError if multiple results + +# Placeholder only + diff --git a/docs/examples/usage/test_drivers_and_querying_18.py b/docs/examples/usage/test_drivers_and_querying_18.py new file mode 100644 index 00000000..f1b2e164 --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_18.py @@ -0,0 +1,7 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 18 +# select_value example +# count = session.select_value("SELECT COUNT(*) FROM users") +# latest_id = session.select_value("SELECT MAX(id) FROM users") + +# Placeholder only + diff --git a/docs/examples/usage/test_drivers_and_querying_19.py b/docs/examples/usage/test_drivers_and_querying_19.py new file mode 100644 index 00000000..309ebb0f --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_19.py @@ -0,0 +1,13 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 19 +# SQLResult object usage placeholder +# result = session.execute("SELECT id, name, email FROM users") +# result.data +# result.column_names +# result.rows_affected +# result.operation_type +# user = result.one() +# user = result.one_or_none() +# value = result.scalar() + +# Placeholder only + diff --git a/docs/examples/usage/test_drivers_and_querying_2.py b/docs/examples/usage/test_drivers_and_querying_2.py new file mode 100644 index 00000000..c277c37a --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_2.py @@ -0,0 +1,34 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 2 +from sqlspec import SQLSpec +from sqlspec.adapters.asyncpg import AsyncpgConfig + +async def example_asyncpg(): + spec = SQLSpec() + db = spec.add_config( + AsyncpgConfig( + pool_config={ + "dsn": "postgresql://user:pass@localhost:5432/mydb", + "min_size": 10, + "max_size": 20, + } + ) + ) + + async with spec.provide_session(db) as session: + # Basic query + result = await session.execute("SELECT * FROM users WHERE id = $1", 1) + user = result.one() + + # Insert with RETURNING + result = await session.execute( + "INSERT INTO users (name, email) VALUES ($1, $2) RETURNING id", + "Alice", + "alice@example.com" + ) + new_id = result.scalar() + print(user, new_id) + +if __name__ == "__main__": + import asyncio + asyncio.run(example_asyncpg()) + diff --git a/docs/examples/usage/test_drivers_and_querying_20.py b/docs/examples/usage/test_drivers_and_querying_20.py new file mode 100644 index 00000000..79c89434 --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_20.py @@ -0,0 +1,11 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 20 +# Iterating results placeholder +# result = session.execute("SELECT * FROM users") +# users = result.all() +# for user in users: +# print(f"{user['name']}: {user['email']}") + +# names = [user['name'] for user in result.all()] + +# Placeholder only + diff --git a/docs/examples/usage/test_drivers_and_querying_21.py b/docs/examples/usage/test_drivers_and_querying_21.py new file mode 100644 index 00000000..9515967b --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_21.py @@ -0,0 +1,15 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 21 +from pydantic import BaseModel + +class User(BaseModel): + id: int + name: str + email: str + +# Mapping results to typed User instances +# result = session.execute("SELECT id, name, email FROM users") +# users: list[User] = result.all(schema_type=User) +# user: User = result.one(schema_type=User) + +# Placeholder only + diff --git a/docs/examples/usage/test_drivers_and_querying_22.py b/docs/examples/usage/test_drivers_and_querying_22.py new file mode 100644 index 00000000..938a1c93 --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_22.py @@ -0,0 +1,14 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 22 +# Manual transaction control example +# with spec.provide_session(config) as session: +# try: +# session.begin() +# session.execute("INSERT INTO users (name) VALUES (?)", "Alice") +# session.execute("INSERT INTO logs (action) VALUES (?)", "user_created") +# session.commit() +# except Exception: +# session.rollback() +# raise + +# Placeholder only + diff --git a/docs/examples/usage/test_drivers_and_querying_23.py b/docs/examples/usage/test_drivers_and_querying_23.py new file mode 100644 index 00000000..ccc6094c --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_23.py @@ -0,0 +1,10 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 23 +# Context manager transactions +# async with spec.provide_session(config) as session: +# async with session.begin(): +# await session.execute("UPDATE accounts SET balance = balance - 100 WHERE id = ?", 1) +# await session.execute("UPDATE accounts SET balance = balance + 100 WHERE id = ?", 2) +# # Auto-commits on success, auto-rollbacks on exception + +# Placeholder only + diff --git a/docs/examples/usage/test_drivers_and_querying_24.py b/docs/examples/usage/test_drivers_and_querying_24.py new file mode 100644 index 00000000..45c09d42 --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_24.py @@ -0,0 +1,8 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 24 +# Positional parameters examples +# session.execute("SELECT * FROM users WHERE id = ?", 1) +# session.execute("SELECT * FROM users WHERE id = $1 AND status = $2", 1, "active") +# session.execute("SELECT * FROM users WHERE id = %s", 1) + +# Placeholder only + diff --git a/docs/examples/usage/test_drivers_and_querying_25.py b/docs/examples/usage/test_drivers_and_querying_25.py new file mode 100644 index 00000000..a4d4334a --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_25.py @@ -0,0 +1,7 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 25 +# Named parameters examples +# session.execute("SELECT * FROM users WHERE id = :id AND status = :status", id=1, status="active") +# session.execute("SELECT * FROM users WHERE created_at >= @start_date", start_date=...) + +# Placeholder only + diff --git a/docs/examples/usage/test_drivers_and_querying_26.py b/docs/examples/usage/test_drivers_and_querying_26.py new file mode 100644 index 00000000..ea8c63e1 --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_26.py @@ -0,0 +1,7 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 26 +# Type coercion examples +# session.execute("INSERT INTO users (is_active) VALUES (?)", True) +# session.execute("INSERT INTO events (timestamp) VALUES (?)", datetime.datetime.now()) + +# Placeholder only + diff --git a/docs/examples/usage/test_drivers_and_querying_27.py b/docs/examples/usage/test_drivers_and_querying_27.py new file mode 100644 index 00000000..c9ffdfd4 --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_27.py @@ -0,0 +1,18 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 27 +# Script execution example +# session.execute(""" +# CREATE TABLE users ( +# id INTEGER PRIMARY KEY, +# name TEXT NOT NULL +# ); +# CREATE TABLE posts ( +# id INTEGER PRIMARY KEY, +# user_id INTEGER, +# title TEXT, +# FOREIGN KEY (user_id) REFERENCES users(id) +# ); +# CREATE INDEX idx_posts_user_id ON posts(user_id); +# """) + +# Placeholder only + diff --git a/docs/examples/usage/test_drivers_and_querying_28.py b/docs/examples/usage/test_drivers_and_querying_28.py new file mode 100644 index 00000000..de54c04f --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_28.py @@ -0,0 +1,8 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 28 +# Performance tips examples +# config = AsyncpgConfig(pool_config={"dsn": "postgresql://localhost/db", "min_size": 10, "max_size": 20}) +# session.execute_many("INSERT INTO users (name) VALUES (?)", [(name,) for name in large_list]) +# count = session.select_value("SELECT COUNT(*) FROM users") + +# Placeholder only + diff --git a/docs/examples/usage/test_drivers_and_querying_3.py b/docs/examples/usage/test_drivers_and_querying_3.py new file mode 100644 index 00000000..a08c946a --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_3.py @@ -0,0 +1,17 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 3 +from sqlspec.adapters.psycopg import PsycopgConfig + +async def example_psycopg_async(): + config = PsycopgConfig( + pool_config={ + "conninfo": "postgresql://localhost/db", + "min_size": 5, + "max_size": 10, + } + ) + + # usage would require SQLSpec etc; shown as example only + +if __name__ == "__main__": + pass + diff --git a/docs/examples/usage/test_drivers_and_querying_4.py b/docs/examples/usage/test_drivers_and_querying_4.py new file mode 100644 index 00000000..c2a69abd --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_4.py @@ -0,0 +1,14 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 4 +from sqlspec.adapters.psycopg import PsycopgConfig + +# Sync usage example (placeholder) +config = PsycopgConfig( + pool_config={ + "conninfo": "postgresql://localhost/db", + "min_size": 5, + "max_size": 10, + } +) + +# In real usage you'd create SQLSpec and call provide_session + diff --git a/docs/examples/usage/test_drivers_and_querying_5.py b/docs/examples/usage/test_drivers_and_querying_5.py new file mode 100644 index 00000000..4e2aa744 --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_5.py @@ -0,0 +1,16 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 5 +from sqlspec.adapters.psqlpy import PsqlpyConfig + +async def example_psqlpy(): + config = PsqlpyConfig( + pool_config={ + "dsn": "postgresql://localhost/db", + "max_pool_size": 20, + } + ) + + # Async usage placeholder + +if __name__ == "__main__": + pass + diff --git a/docs/examples/usage/test_drivers_and_querying_6.py b/docs/examples/usage/test_drivers_and_querying_6.py new file mode 100644 index 00000000..d46a0cd5 --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_6.py @@ -0,0 +1,14 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 6 +from sqlspec.adapters.sqlite import SqliteConfig + +# Typical sqlite sync usage - placeholder +config = SqliteConfig( + pool_config={ + "database": "myapp.db", + "timeout": 5.0, + "check_same_thread": False, + } +) + +# with spec.provide_session(config) as session: ... + diff --git a/docs/examples/usage/test_drivers_and_querying_7.py b/docs/examples/usage/test_drivers_and_querying_7.py new file mode 100644 index 00000000..f5ec3738 --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_7.py @@ -0,0 +1,19 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 7 +from sqlspec.adapters.sqlite import SqliteConfig + +def example_sync_sqlite(): + # This is a placeholder showing API usage + config = SqliteConfig( + pool_config={ + "database": "myapp.db", + "timeout": 5.0, + "check_same_thread": False, + } + ) + + # with spec.provide_session(config) as session: + # session.execute(...) etc. + +if __name__ == "__main__": + example_sync_sqlite() + diff --git a/docs/examples/usage/test_drivers_and_querying_8.py b/docs/examples/usage/test_drivers_and_querying_8.py new file mode 100644 index 00000000..bf0d4613 --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_8.py @@ -0,0 +1,15 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 8 +from sqlspec.adapters.aiosqlite import AiosqliteConfig + +async def example_aiosqlite(): + config = AiosqliteConfig( + pool_config={"database": "myapp.db"} + ) + + # async with spec.provide_session(config) as session: + # await session.execute(...) + +if __name__ == "__main__": + import asyncio + asyncio.run(example_aiosqlite()) + diff --git a/docs/examples/usage/test_drivers_and_querying_9.py b/docs/examples/usage/test_drivers_and_querying_9.py new file mode 100644 index 00000000..7396f9f1 --- /dev/null +++ b/docs/examples/usage/test_drivers_and_querying_9.py @@ -0,0 +1,22 @@ +# Example from docs/usage/drivers_and_querying.rst - code-block 9 +from sqlspec.adapters.asyncmy import AsyncmyConfig + +async def example_asyncmy(): + config = AsyncmyConfig( + pool_config={ + "host": "localhost", + "port": 3306, + "user": "myuser", + "password": "mypassword", + "database": "mydb", + "minsize": 1, + "maxsize": 10, + } + ) + + # async with spec.provide_session(config) as session: + # result = await session.execute("SELECT * FROM users WHERE id = %s", 1) + +if __name__ == "__main__": + pass + diff --git a/docs/usage/drivers_and_querying.rst b/docs/usage/drivers_and_querying.rst index 5abd8688..91c53a86 100644 --- a/docs/usage/drivers_and_querying.rst +++ b/docs/usage/drivers_and_querying.rst @@ -1,3 +1,4 @@ +Drivers and Querying ===================== Drivers and Querying ===================== From 392ebee53dc659818cfd4643968975268eaf0647 Mon Sep 17 00:00:00 2001 From: euri10 Date: Thu, 6 Nov 2025 11:10:43 +0100 Subject: [PATCH 2/8] 1 to 9 manually tested --- docs/examples/usage/conftest.py | 1 + .../usage/test_drivers_and_querying_1.py | 34 ++-- .../usage/test_drivers_and_querying_10.py | 18 +- .../usage/test_drivers_and_querying_11.py | 17 +- .../usage/test_drivers_and_querying_12.py | 17 +- .../usage/test_drivers_and_querying_13.py | 27 +-- .../usage/test_drivers_and_querying_14.py | 25 +-- .../usage/test_drivers_and_querying_15.py | 9 +- .../usage/test_drivers_and_querying_16.py | 10 +- .../usage/test_drivers_and_querying_17.py | 10 +- .../usage/test_drivers_and_querying_18.py | 9 +- .../usage/test_drivers_and_querying_19.py | 15 +- .../usage/test_drivers_and_querying_2.py | 39 ++-- .../usage/test_drivers_and_querying_20.py | 13 +- .../usage/test_drivers_and_querying_21.py | 14 +- .../usage/test_drivers_and_querying_22.py | 16 +- .../usage/test_drivers_and_querying_23.py | 12 +- .../usage/test_drivers_and_querying_24.py | 10 +- .../usage/test_drivers_and_querying_25.py | 9 +- .../usage/test_drivers_and_querying_26.py | 9 +- .../usage/test_drivers_and_querying_27.py | 20 +-- .../usage/test_drivers_and_querying_28.py | 10 +- .../usage/test_drivers_and_querying_3.py | 35 ++-- .../usage/test_drivers_and_querying_4.py | 24 +-- .../usage/test_drivers_and_querying_5.py | 33 ++-- .../usage/test_drivers_and_querying_6.py | 33 ++-- .../usage/test_drivers_and_querying_7.py | 22 +-- .../usage/test_drivers_and_querying_8.py | 26 +-- .../usage/test_drivers_and_querying_9.py | 43 +++-- docs/usage/drivers_and_querying.rst | 167 ++++-------------- 30 files changed, 302 insertions(+), 425 deletions(-) create mode 100644 docs/examples/usage/conftest.py diff --git a/docs/examples/usage/conftest.py b/docs/examples/usage/conftest.py new file mode 100644 index 00000000..ee6c6d27 --- /dev/null +++ b/docs/examples/usage/conftest.py @@ -0,0 +1 @@ +pytest_plugins = ["pytest_databases.docker.postgres", "pytest_databases.docker.mysql"] diff --git a/docs/examples/usage/test_drivers_and_querying_1.py b/docs/examples/usage/test_drivers_and_querying_1.py index 0537ebb9..98a0c386 100644 --- a/docs/examples/usage/test_drivers_and_querying_1.py +++ b/docs/examples/usage/test_drivers_and_querying_1.py @@ -1,17 +1,25 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 1 -# Typical driver usage -from sqlspec import SQLSpec -from sqlspec.adapters.asyncpg import AsyncpgConfig +# Test module converted from docs example - code-block 1 +"""Minimal smoke test for drivers_and_querying example 1.""" -async def example(): - spec = SQLSpec() - db = spec.add_config(AsyncpgConfig(pool_config={})) +from pytest_databases.docker.postgres import PostgresService - async with spec.provide_session(db) as session: - result = await session.execute("SELECT 1") - print(result) +from sqlspec import SQLSpec +from sqlspec.adapters.asyncpg import AsyncpgConfig, AsyncpgPoolConfig -if __name__ == "__main__": - import asyncio - asyncio.run(example()) +async def test_importable_1(postgres_service: PostgresService) -> None: + # Typical driver usage + spec = SQLSpec() + db = spec.add_config( + AsyncpgConfig( + pool_config=AsyncpgPoolConfig( + host=postgres_service.host, + port=postgres_service.port, + user=postgres_service.user, + password=postgres_service.password, + database=postgres_service.database, + ) + ) + ) # Config layer, registers pool + async with spec.provide_session(db) as session: # Session layer + await session.execute("SELECT 1") # Driver layer diff --git a/docs/examples/usage/test_drivers_and_querying_10.py b/docs/examples/usage/test_drivers_and_querying_10.py index a1774f84..3b5a4012 100644 --- a/docs/examples/usage/test_drivers_and_querying_10.py +++ b/docs/examples/usage/test_drivers_and_querying_10.py @@ -1,14 +1,10 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 10 -from sqlspec.adapters.duckdb import DuckDBConfig - -# In-memory -config_inmemory = DuckDBConfig() +# Test module converted from docs example - code-block 10 +"""Minimal smoke test for drivers_and_querying example 10.""" -# Persistent -config_persistent = DuckDBConfig( - pool_config={"database": "analytics.duckdb"} -) +from sqlspec.adapters.duckdb import DuckDBConfig -# with spec.provide_session(config) as session: -# session.execute(...) etc. +def test_example_10_duckdb_config() -> None: + DuckDBConfig() + config_persistent = DuckDBConfig(pool_config={"database": "analytics.duckdb"}) + assert config_persistent.pool_config["database"] == "analytics.duckdb" diff --git a/docs/examples/usage/test_drivers_and_querying_11.py b/docs/examples/usage/test_drivers_and_querying_11.py index c10228e6..a708111b 100644 --- a/docs/examples/usage/test_drivers_and_querying_11.py +++ b/docs/examples/usage/test_drivers_and_querying_11.py @@ -1,14 +1,9 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 11 -from sqlspec.adapters.oracledb import OracleDBConfig +# Test module converted from docs example - code-block 11 +"""Minimal smoke test for drivers_and_querying example 11.""" -config = OracleDBConfig( - pool_config={ - "user": "myuser", - "password": "mypassword", - "dsn": "localhost:1521/ORCLPDB", - } -) +from sqlspec.adapters.oracledb import OracleDBConfig -# with spec.provide_session(config) as session: -# result = session.execute("SELECT * FROM employees WHERE employee_id = :id", id=100) +def test_example_11_oracledb_config() -> None: + config = OracleDBConfig(pool_config={"user": "myuser", "password": "mypassword", "dsn": "localhost:1521/ORCLPDB"}) + assert "dsn" in config.pool_config diff --git a/docs/examples/usage/test_drivers_and_querying_12.py b/docs/examples/usage/test_drivers_and_querying_12.py index 2c45bb1f..a132de66 100644 --- a/docs/examples/usage/test_drivers_and_querying_12.py +++ b/docs/examples/usage/test_drivers_and_querying_12.py @@ -1,14 +1,9 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 12 -from sqlspec.adapters.bigquery import BigQueryConfig -import datetime +# Test module converted from docs example - code-block 12 +"""Minimal smoke test for drivers_and_querying example 12.""" -config = BigQueryConfig( - pool_config={ - "project": "my-project", - "credentials": None, - } -) +from sqlspec.adapters.bigquery import BigQueryConfig -# with spec.provide_session(config) as session: -# result = session.execute("SELECT DATE(timestamp) as date, COUNT(*) as events FROM `project.dataset.events` WHERE timestamp >= @start_date GROUP BY date", start_date=datetime.date(2025,1,1)) +def test_example_12_bigquery_config() -> None: + config = BigQueryConfig(pool_config={"project": "my-project", "credentials": None}) + assert config.pool_config["project"] == "my-project" diff --git a/docs/examples/usage/test_drivers_and_querying_13.py b/docs/examples/usage/test_drivers_and_querying_13.py index b7a0db20..f6ff9c30 100644 --- a/docs/examples/usage/test_drivers_and_querying_13.py +++ b/docs/examples/usage/test_drivers_and_querying_13.py @@ -1,24 +1,7 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 13 -# SELECT query example -# result = session.execute("SELECT * FROM users WHERE id = ?", 1) +# Test module converted from docs example - code-block 13 +"""Minimal smoke test for drivers_and_querying example 13.""" -# INSERT query example -# result = session.execute( -# "INSERT INTO users (name, email) VALUES (?, ?)", -# "Alice", -# "alice@example.com" -# ) - -# UPDATE example -# result = session.execute( -# "UPDATE users SET email = ? WHERE id = ?", -# "newemail@example.com", -# 1 -# ) -# print(f"Updated {result.rows_affected} rows") - -# DELETE example -# result = session.execute("DELETE FROM users WHERE id = ?", 1) - -# These lines are examples and require a session object to run. +def test_example_13_placeholder() -> None: + # Examples are documentation snippets; ensure module importable + assert True diff --git a/docs/examples/usage/test_drivers_and_querying_14.py b/docs/examples/usage/test_drivers_and_querying_14.py index d91c8afa..0b4c5a86 100644 --- a/docs/examples/usage/test_drivers_and_querying_14.py +++ b/docs/examples/usage/test_drivers_and_querying_14.py @@ -1,22 +1,7 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 14 -# Batch insert example -# session.execute_many( -# "INSERT INTO users (name, email) VALUES (?, ?)", -# [ -# ("Alice", "alice@example.com"), -# ("Bob", "bob@example.com"), -# ("Charlie", "charlie@example.com"), -# ] -# ) +# Test module converted from docs example - code-block 14 +"""Minimal smoke test for drivers_and_querying example 14.""" -# Batch update example -# session.execute_many( -# "UPDATE users SET status = ? WHERE id = ?", -# [ -# ("active", 1), -# ("inactive", 2), -# ] -# ) - -# Examples require a session object to run. +def test_example_14_placeholder() -> None: + # Batch examples are documentation-only + assert True diff --git a/docs/examples/usage/test_drivers_and_querying_15.py b/docs/examples/usage/test_drivers_and_querying_15.py index 197f9f35..c8b12dda 100644 --- a/docs/examples/usage/test_drivers_and_querying_15.py +++ b/docs/examples/usage/test_drivers_and_querying_15.py @@ -1,7 +1,6 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 15 -# SELECT and all() example -# users = session.execute("SELECT * FROM users WHERE status = ?", "active") -# returns list of dicts +# Test module converted from docs example - code-block 15 +"""Minimal smoke test for drivers_and_querying example 15.""" -# Placeholder only +def test_example_15_placeholder() -> None: + assert True diff --git a/docs/examples/usage/test_drivers_and_querying_16.py b/docs/examples/usage/test_drivers_and_querying_16.py index 7dba6318..84146423 100644 --- a/docs/examples/usage/test_drivers_and_querying_16.py +++ b/docs/examples/usage/test_drivers_and_querying_16.py @@ -1,8 +1,6 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 16 -# select_one example -# user = session.select_one("SELECT * FROM users WHERE id = ?", 1) -# Raises NotFoundError if no results -# Raises MultipleResultsFoundError if multiple results +# Test module converted from docs example - code-block 16 +"""Minimal smoke test for drivers_and_querying example 16.""" -# Placeholder only +def test_example_16_placeholder() -> None: + assert True diff --git a/docs/examples/usage/test_drivers_and_querying_17.py b/docs/examples/usage/test_drivers_and_querying_17.py index add83a26..e9d2bcb8 100644 --- a/docs/examples/usage/test_drivers_and_querying_17.py +++ b/docs/examples/usage/test_drivers_and_querying_17.py @@ -1,8 +1,6 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 17 -# select_one_or_none example -# user = session.select_one_or_none("SELECT * FROM users WHERE email = ?", "nobody@example.com") -# Returns dict or None -# Raises MultipleResultsFoundError if multiple results +# Test module converted from docs example - code-block 17 +"""Minimal smoke test for drivers_and_querying example 17.""" -# Placeholder only +def test_example_17_placeholder() -> None: + assert True diff --git a/docs/examples/usage/test_drivers_and_querying_18.py b/docs/examples/usage/test_drivers_and_querying_18.py index f1b2e164..9d2c67b1 100644 --- a/docs/examples/usage/test_drivers_and_querying_18.py +++ b/docs/examples/usage/test_drivers_and_querying_18.py @@ -1,7 +1,6 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 18 -# select_value example -# count = session.select_value("SELECT COUNT(*) FROM users") -# latest_id = session.select_value("SELECT MAX(id) FROM users") +# Test module converted from docs example - code-block 18 +"""Minimal smoke test for drivers_and_querying example 18.""" -# Placeholder only +def test_example_18_placeholder() -> None: + assert True diff --git a/docs/examples/usage/test_drivers_and_querying_19.py b/docs/examples/usage/test_drivers_and_querying_19.py index 309ebb0f..cd97beaa 100644 --- a/docs/examples/usage/test_drivers_and_querying_19.py +++ b/docs/examples/usage/test_drivers_and_querying_19.py @@ -1,13 +1,6 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 19 -# SQLResult object usage placeholder -# result = session.execute("SELECT id, name, email FROM users") -# result.data -# result.column_names -# result.rows_affected -# result.operation_type -# user = result.one() -# user = result.one_or_none() -# value = result.scalar() +# Test module converted from docs example - code-block 19 +"""Minimal smoke test for drivers_and_querying example 19.""" -# Placeholder only +def test_example_19_placeholder() -> None: + assert True diff --git a/docs/examples/usage/test_drivers_and_querying_2.py b/docs/examples/usage/test_drivers_and_querying_2.py index c277c37a..e9057721 100644 --- a/docs/examples/usage/test_drivers_and_querying_2.py +++ b/docs/examples/usage/test_drivers_and_querying_2.py @@ -1,34 +1,39 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 2 +# Test module converted from docs example - code-block 2 +"""Minimal smoke test for drivers_and_querying example 2.""" + +from pytest_databases.docker.postgres import PostgresService + from sqlspec import SQLSpec from sqlspec.adapters.asyncpg import AsyncpgConfig -async def example_asyncpg(): + +async def test_example_2_importable(postgres_service: PostgresService) -> None: spec = SQLSpec() db = spec.add_config( AsyncpgConfig( pool_config={ - "dsn": "postgresql://user:pass@localhost:5432/mydb", + "dsn": f"postgresql://{postgres_service.user}:{postgres_service.password}@{postgres_service.host}:{postgres_service.port}/{postgres_service.database}", "min_size": 10, "max_size": 20, } ) ) - async with spec.provide_session(db) as session: - # Basic query - result = await session.execute("SELECT * FROM users WHERE id = $1", 1) - user = result.one() - + create_table_query = """ + CREATE TABLE IF NOT EXISTS users ( + id SERIAL PRIMARY KEY, + name VARCHAR(100), + email VARCHAR(100) UNIQUE + ); + """ + await session.execute(create_table_query) # Insert with RETURNING result = await session.execute( - "INSERT INTO users (name, email) VALUES ($1, $2) RETURNING id", - "Alice", - "alice@example.com" + "INSERT INTO users (name, email) VALUES ($1, $2) RETURNING id", "Alice", "alice@example.com" ) new_id = result.scalar() - print(user, new_id) - -if __name__ == "__main__": - import asyncio - asyncio.run(example_asyncpg()) - + print(f"Inserted user with ID: {new_id}") + # Basic query + result = await session.execute("SELECT * FROM users WHERE id = $1", 1) + user = result.one() + print(f"User: {user}") diff --git a/docs/examples/usage/test_drivers_and_querying_20.py b/docs/examples/usage/test_drivers_and_querying_20.py index 79c89434..fc9c77ce 100644 --- a/docs/examples/usage/test_drivers_and_querying_20.py +++ b/docs/examples/usage/test_drivers_and_querying_20.py @@ -1,11 +1,6 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 20 -# Iterating results placeholder -# result = session.execute("SELECT * FROM users") -# users = result.all() -# for user in users: -# print(f"{user['name']}: {user['email']}") +# Test module converted from docs example - code-block 20 +"""Minimal smoke test for drivers_and_querying example 20.""" -# names = [user['name'] for user in result.all()] - -# Placeholder only +def test_example_20_placeholder() -> None: + assert True diff --git a/docs/examples/usage/test_drivers_and_querying_21.py b/docs/examples/usage/test_drivers_and_querying_21.py index 9515967b..9ce9fa68 100644 --- a/docs/examples/usage/test_drivers_and_querying_21.py +++ b/docs/examples/usage/test_drivers_and_querying_21.py @@ -1,15 +1,15 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 21 +# Test module converted from docs example - code-block 21 +"""Minimal smoke test for drivers_and_querying example 21.""" + from pydantic import BaseModel + class User(BaseModel): id: int name: str email: str -# Mapping results to typed User instances -# result = session.execute("SELECT id, name, email FROM users") -# users: list[User] = result.all(schema_type=User) -# user: User = result.one(schema_type=User) - -# Placeholder only +def test_example_21_pydantic_model() -> None: + u = User(id=1, name="Alice", email="a@example.com") + assert u.id == 1 diff --git a/docs/examples/usage/test_drivers_and_querying_22.py b/docs/examples/usage/test_drivers_and_querying_22.py index 938a1c93..d4288987 100644 --- a/docs/examples/usage/test_drivers_and_querying_22.py +++ b/docs/examples/usage/test_drivers_and_querying_22.py @@ -1,14 +1,6 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 22 -# Manual transaction control example -# with spec.provide_session(config) as session: -# try: -# session.begin() -# session.execute("INSERT INTO users (name) VALUES (?)", "Alice") -# session.execute("INSERT INTO logs (action) VALUES (?)", "user_created") -# session.commit() -# except Exception: -# session.rollback() -# raise +# Test module converted from docs example - code-block 22 +"""Minimal smoke test for drivers_and_querying example 22.""" -# Placeholder only +def test_example_22_placeholder() -> None: + assert True diff --git a/docs/examples/usage/test_drivers_and_querying_23.py b/docs/examples/usage/test_drivers_and_querying_23.py index ccc6094c..f3f3a55e 100644 --- a/docs/examples/usage/test_drivers_and_querying_23.py +++ b/docs/examples/usage/test_drivers_and_querying_23.py @@ -1,10 +1,6 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 23 -# Context manager transactions -# async with spec.provide_session(config) as session: -# async with session.begin(): -# await session.execute("UPDATE accounts SET balance = balance - 100 WHERE id = ?", 1) -# await session.execute("UPDATE accounts SET balance = balance + 100 WHERE id = ?", 2) -# # Auto-commits on success, auto-rollbacks on exception +# Test module converted from docs example - code-block 23 +"""Minimal smoke test for drivers_and_querying example 23.""" -# Placeholder only +def test_example_23_placeholder() -> None: + assert True diff --git a/docs/examples/usage/test_drivers_and_querying_24.py b/docs/examples/usage/test_drivers_and_querying_24.py index 45c09d42..5c8e456f 100644 --- a/docs/examples/usage/test_drivers_and_querying_24.py +++ b/docs/examples/usage/test_drivers_and_querying_24.py @@ -1,8 +1,6 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 24 -# Positional parameters examples -# session.execute("SELECT * FROM users WHERE id = ?", 1) -# session.execute("SELECT * FROM users WHERE id = $1 AND status = $2", 1, "active") -# session.execute("SELECT * FROM users WHERE id = %s", 1) +# Test module converted from docs example - code-block 24 +"""Minimal smoke test for drivers_and_querying example 24.""" -# Placeholder only +def test_example_24_placeholder() -> None: + assert True diff --git a/docs/examples/usage/test_drivers_and_querying_25.py b/docs/examples/usage/test_drivers_and_querying_25.py index a4d4334a..737c918b 100644 --- a/docs/examples/usage/test_drivers_and_querying_25.py +++ b/docs/examples/usage/test_drivers_and_querying_25.py @@ -1,7 +1,6 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 25 -# Named parameters examples -# session.execute("SELECT * FROM users WHERE id = :id AND status = :status", id=1, status="active") -# session.execute("SELECT * FROM users WHERE created_at >= @start_date", start_date=...) +# Test module converted from docs example - code-block 25 +"""Minimal smoke test for drivers_and_querying example 25.""" -# Placeholder only +def test_example_25_placeholder() -> None: + assert True diff --git a/docs/examples/usage/test_drivers_and_querying_26.py b/docs/examples/usage/test_drivers_and_querying_26.py index ea8c63e1..93bfd966 100644 --- a/docs/examples/usage/test_drivers_and_querying_26.py +++ b/docs/examples/usage/test_drivers_and_querying_26.py @@ -1,7 +1,6 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 26 -# Type coercion examples -# session.execute("INSERT INTO users (is_active) VALUES (?)", True) -# session.execute("INSERT INTO events (timestamp) VALUES (?)", datetime.datetime.now()) +# Test module converted from docs example - code-block 26 +"""Minimal smoke test for drivers_and_querying example 26.""" -# Placeholder only +def test_example_26_placeholder() -> None: + assert True diff --git a/docs/examples/usage/test_drivers_and_querying_27.py b/docs/examples/usage/test_drivers_and_querying_27.py index c9ffdfd4..e3c99745 100644 --- a/docs/examples/usage/test_drivers_and_querying_27.py +++ b/docs/examples/usage/test_drivers_and_querying_27.py @@ -1,18 +1,6 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 27 -# Script execution example -# session.execute(""" -# CREATE TABLE users ( -# id INTEGER PRIMARY KEY, -# name TEXT NOT NULL -# ); -# CREATE TABLE posts ( -# id INTEGER PRIMARY KEY, -# user_id INTEGER, -# title TEXT, -# FOREIGN KEY (user_id) REFERENCES users(id) -# ); -# CREATE INDEX idx_posts_user_id ON posts(user_id); -# """) +# Test module converted from docs example - code-block 27 +"""Minimal smoke test for drivers_and_querying example 27.""" -# Placeholder only +def test_example_27_placeholder() -> None: + assert True diff --git a/docs/examples/usage/test_drivers_and_querying_28.py b/docs/examples/usage/test_drivers_and_querying_28.py index de54c04f..ae83738c 100644 --- a/docs/examples/usage/test_drivers_and_querying_28.py +++ b/docs/examples/usage/test_drivers_and_querying_28.py @@ -1,8 +1,6 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 28 -# Performance tips examples -# config = AsyncpgConfig(pool_config={"dsn": "postgresql://localhost/db", "min_size": 10, "max_size": 20}) -# session.execute_many("INSERT INTO users (name) VALUES (?)", [(name,) for name in large_list]) -# count = session.select_value("SELECT COUNT(*) FROM users") +# Test module converted from docs example - code-block 28 +"""Minimal smoke test for drivers_and_querying example 28.""" -# Placeholder only +def test_example_28_placeholder() -> None: + assert True diff --git a/docs/examples/usage/test_drivers_and_querying_3.py b/docs/examples/usage/test_drivers_and_querying_3.py index a08c946a..7b8ffed0 100644 --- a/docs/examples/usage/test_drivers_and_querying_3.py +++ b/docs/examples/usage/test_drivers_and_querying_3.py @@ -1,17 +1,32 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 3 -from sqlspec.adapters.psycopg import PsycopgConfig +# Test module converted from docs example - code-block 3 +"""Minimal smoke test for drivers_and_querying example 3.""" -async def example_psycopg_async(): - config = PsycopgConfig( +from pytest_databases.docker.postgres import PostgresService + + +def test_example_3_importable(postgres_service: PostgresService) -> None: + from sqlspec import SQLSpec + from sqlspec.adapters.psycopg import PsycopgSyncConfig + + spec = SQLSpec() + # Async version + config = PsycopgSyncConfig( pool_config={ - "conninfo": "postgresql://localhost/db", + "conninfo": f"postgresql://{postgres_service.user}:{postgres_service.password}@{postgres_service.host}:{postgres_service.port}/{postgres_service.database}", "min_size": 5, "max_size": 10, } ) - # usage would require SQLSpec etc; shown as example only - -if __name__ == "__main__": - pass - + with spec.provide_session(config) as session: + create_table_query = """ + CREATE TABLE IF NOT EXISTS users ( + id SERIAL PRIMARY KEY, + name VARCHAR(100), + email VARCHAR(100) UNIQUE + ); + """ + session.execute(create_table_query) + # Insert with RETURNING + session.execute("INSERT INTO users (name, email) VALUES (%s, %s) RETURNING id", "Alice", "alice@example.com") + session.execute("SELECT * FROM users") diff --git a/docs/examples/usage/test_drivers_and_querying_4.py b/docs/examples/usage/test_drivers_and_querying_4.py index c2a69abd..f54ce3c6 100644 --- a/docs/examples/usage/test_drivers_and_querying_4.py +++ b/docs/examples/usage/test_drivers_and_querying_4.py @@ -1,14 +1,16 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 4 -from sqlspec.adapters.psycopg import PsycopgConfig +# Test module converted from docs example - code-block 4 +"""Minimal smoke test for drivers_and_querying example 4.""" -# Sync usage example (placeholder) -config = PsycopgConfig( - pool_config={ - "conninfo": "postgresql://localhost/db", - "min_size": 5, - "max_size": 10, - } -) +from pytest_databases.docker.postgres import PostgresService -# In real usage you'd create SQLSpec and call provide_session +from sqlspec.adapters.psycopg import PsycopgSyncConfig + +def test_example_4_construct_config(postgres_service: PostgresService) -> None: + config = PsycopgSyncConfig( + pool_config={ + "conninfo": f"postgresql://{postgres_service.user}:{postgres_service.password}@{postgres_service.host}:{postgres_service.port}/{postgres_service.database}" + } + ) + + assert config is not None diff --git a/docs/examples/usage/test_drivers_and_querying_5.py b/docs/examples/usage/test_drivers_and_querying_5.py index 4e2aa744..8b90e6d6 100644 --- a/docs/examples/usage/test_drivers_and_querying_5.py +++ b/docs/examples/usage/test_drivers_and_querying_5.py @@ -1,16 +1,29 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 5 +# Test module converted from docs example - code-block 5 +"""Minimal smoke test for drivers_and_querying example 5.""" + +from pytest_databases.docker.postgres import PostgresService + +from sqlspec import SQLSpec from sqlspec.adapters.psqlpy import PsqlpyConfig -async def example_psqlpy(): + +async def test_example_5_construct_config(postgres_service: PostgresService) -> None: + spec = SQLSpec() config = PsqlpyConfig( pool_config={ - "dsn": "postgresql://localhost/db", - "max_pool_size": 20, + "dsn": f"postgresql://{postgres_service.user}:{postgres_service.password}@{postgres_service.host}:{postgres_service.port}/{postgres_service.database}" } ) - - # Async usage placeholder - -if __name__ == "__main__": - pass - + assert config is not None + async with spec.provide_session(config) as session: + create_table_query = """ CREATE TABLE IF NOT EXISTS users ( + id SERIAL PRIMARY KEY, + name VARCHAR(100), + email VARCHAR(100) UNIQUE + ); """ + await session.execute(create_table_query) + # Insert with RETURNING + await session.execute( + "INSERT INTO users (name, email) VALUES ($1, $2) RETURNING id", "Alice", "alice@example.com" + ) + await session.execute("SELECT * FROM users WHERE id = $1", 1) diff --git a/docs/examples/usage/test_drivers_and_querying_6.py b/docs/examples/usage/test_drivers_and_querying_6.py index d46a0cd5..d304dede 100644 --- a/docs/examples/usage/test_drivers_and_querying_6.py +++ b/docs/examples/usage/test_drivers_and_querying_6.py @@ -1,14 +1,27 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 6 +# Test module converted from docs example - code-block 6 +"""Minimal smoke test for drivers_and_querying example 6.""" + +from sqlspec import SQLSpec from sqlspec.adapters.sqlite import SqliteConfig -# Typical sqlite sync usage - placeholder -config = SqliteConfig( - pool_config={ - "database": "myapp.db", - "timeout": 5.0, - "check_same_thread": False, - } -) -# with spec.provide_session(config) as session: ... +def test_example_6_sqlite_config() -> None: + spec = SQLSpec() + + config = SqliteConfig(pool_config={"database": "myapp.db", "timeout": 5.0, "check_same_thread": False}) + + with spec.provide_session(config) as session: + # Create table + session.execute(""" + CREATE TABLE IF NOT EXISTS users ( + id INTEGER PRIMARY KEY, + name TEXT NOT NULL + ) + """) + + # Insert with parameters + session.execute("INSERT INTO users (name) VALUES (?)", "Alice") + # Query + result = session.execute("SELECT * FROM users") + result.all() diff --git a/docs/examples/usage/test_drivers_and_querying_7.py b/docs/examples/usage/test_drivers_and_querying_7.py index f5ec3738..8ee74316 100644 --- a/docs/examples/usage/test_drivers_and_querying_7.py +++ b/docs/examples/usage/test_drivers_and_querying_7.py @@ -1,19 +1,9 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 7 -from sqlspec.adapters.sqlite import SqliteConfig - -def example_sync_sqlite(): - # This is a placeholder showing API usage - config = SqliteConfig( - pool_config={ - "database": "myapp.db", - "timeout": 5.0, - "check_same_thread": False, - } - ) +# Test module converted from docs example - code-block 7 +"""Minimal smoke test for drivers_and_querying example 7.""" - # with spec.provide_session(config) as session: - # session.execute(...) etc. +from sqlspec.adapters.sqlite import SqliteConfig -if __name__ == "__main__": - example_sync_sqlite() +def test_example_7_sync_sqlite() -> None: + config = SqliteConfig(pool_config={"database": "myapp.db", "timeout": 5.0, "check_same_thread": False}) + assert config.pool_config["database"] == "myapp.db" diff --git a/docs/examples/usage/test_drivers_and_querying_8.py b/docs/examples/usage/test_drivers_and_querying_8.py index bf0d4613..7a18570e 100644 --- a/docs/examples/usage/test_drivers_and_querying_8.py +++ b/docs/examples/usage/test_drivers_and_querying_8.py @@ -1,15 +1,19 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 8 -from sqlspec.adapters.aiosqlite import AiosqliteConfig +# Test module converted from docs example - code-block 8 +"""Minimal smoke test for drivers_and_querying example 8.""" -async def example_aiosqlite(): - config = AiosqliteConfig( - pool_config={"database": "myapp.db"} - ) - # async with spec.provide_session(config) as session: - # await session.execute(...) +async def test_example_8_aiosqlite_config() -> None: + from sqlspec import SQLSpec + from sqlspec.adapters.aiosqlite import AiosqliteConfig -if __name__ == "__main__": - import asyncio - asyncio.run(example_aiosqlite()) + config = AiosqliteConfig(pool_config={"database": "myapp.db"}) + spec = SQLSpec() + async with spec.provide_session(config) as session: + create_table_query = """CREATE TABLE IF NOT EXISTS users ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + name TEXT NOT NULL + );""" + await session.execute(create_table_query) + await session.execute("INSERT INTO users (name) VALUES (?)", "Bob") + await session.execute("SELECT * FROM users") diff --git a/docs/examples/usage/test_drivers_and_querying_9.py b/docs/examples/usage/test_drivers_and_querying_9.py index 7396f9f1..53038cbf 100644 --- a/docs/examples/usage/test_drivers_and_querying_9.py +++ b/docs/examples/usage/test_drivers_and_querying_9.py @@ -1,22 +1,37 @@ -# Example from docs/usage/drivers_and_querying.rst - code-block 9 -from sqlspec.adapters.asyncmy import AsyncmyConfig +# Test module converted from docs example - code-block 9 +"""Minimal smoke test for drivers_and_querying example 9.""" + +from pytest_databases.docker.mysql import MySQLService + + +async def test_example_9_asyncmy_config(mysql_service: MySQLService) -> None: + from sqlspec import SQLSpec + from sqlspec.adapters.asyncmy import AsyncmyConfig + + spec = SQLSpec() -async def example_asyncmy(): config = AsyncmyConfig( pool_config={ - "host": "localhost", - "port": 3306, - "user": "myuser", - "password": "mypassword", - "database": "mydb", + "host": mysql_service.host, + "port": mysql_service.port, + "user": mysql_service.user, + "password": mysql_service.password, + "database": mysql_service.db, "minsize": 1, "maxsize": 10, } ) - # async with spec.provide_session(config) as session: - # result = await session.execute("SELECT * FROM users WHERE id = %s", 1) - -if __name__ == "__main__": - pass - + async with spec.provide_session(config) as session: + create_table_query = """CREATE TABLE IF NOT EXISTS users ( + id INT PRIMARY KEY, + name VARCHAR(100), + email VARCHAR(100) + );""" + await session.execute(create_table_query) + # insert a user + await session.execute( + "INSERT INTO users (id, name, email) VALUES (%s, %s, %s)", (1, "John Doe", "john.doe@example.com") + ) + # query the user + await session.execute("SELECT * FROM users WHERE id = %s", 1) diff --git a/docs/usage/drivers_and_querying.rst b/docs/usage/drivers_and_querying.rst index 91c53a86..dd717c69 100644 --- a/docs/usage/drivers_and_querying.rst +++ b/docs/usage/drivers_and_querying.rst @@ -51,14 +51,10 @@ SQLSpec drivers follow a layered architecture: 3. **Driver Layer**: Query execution and result handling 4. **Session Layer**: Transaction management -.. code-block:: python - - # Typical driver usage - spec = SQLSpec() - db = spec.add_config(AsyncpgConfig(pool_config={...})) # Config layer, registers pool - - async with spec.provide_session(db) as session: # Session layer - result = await session.execute("SELECT 1") # Driver layer +.. literalinclude:: /examples/test_drivers_and_querying_1.py + :language: python + :lines: 15-29 + :dedent: 2 PostgreSQL Drivers ------------------ @@ -68,34 +64,10 @@ asyncpg (Recommended for Async) Async PostgreSQL driver with native connection pooling. -.. code-block:: python - - from sqlspec import SQLSpec - from sqlspec.adapters.asyncpg import AsyncpgConfig - - spec = SQLSpec() - db = spec.add_config( - AsyncpgConfig( - pool_config={ - "dsn": "postgresql://user:pass@localhost:5432/mydb", - "min_size": 10, - "max_size": 20, - } - ) - ) - - async with spec.provide_session(db) as session: - # Basic query - result = await session.execute("SELECT * FROM users WHERE id = $1", 1) - user = result.one() - - # Insert with RETURNING - result = await session.execute( - "INSERT INTO users (name, email) VALUES ($1, $2) RETURNING id", - "Alice", - "alice@example.com" - ) - new_id = result.scalar() +.. literalinclude:: /examples/test_drivers_and_querying_2.py + :language: python + :lines: 11-35 + :dedent: 2 **Features**: @@ -110,25 +82,15 @@ psycopg (Sync/Async) Official PostgreSQL adapter with both sync and async support. -.. code-block:: python - - from sqlspec.adapters.psycopg import PsycopgConfig +.. literalinclude:: /examples/test_drivers_and_querying_3.py + :language: python + :lines: 8-32 + :dedent: 2 - # Async version - config = PsycopgConfig( - pool_config={ - "conninfo": "postgresql://localhost/db", - "min_size": 5, - "max_size": 10, - } - ) - - async with spec.provide_session(config) as session: - result = await session.execute("SELECT * FROM users") - - # Sync version (use psycopg sync config) - with spec.provide_session(config) as session: - result = session.execute("SELECT * FROM users") +.. literalinclude:: /examples/test_drivers_and_querying_4.py + :language: python + :lines: 10-12 + :dedent: 2 **Features**: @@ -143,19 +105,10 @@ psqlpy (High Performance Async) Rust-based async PostgreSQL driver for maximum performance. -.. code-block:: python - - from sqlspec.adapters.psqlpy import PsqlpyConfig - - config = PsqlpyConfig( - pool_config={ - "dsn": "postgresql://localhost/db", - "max_pool_size": 20, - } - ) - - async with spec.provide_session(config) as session: - result = await session.execute("SELECT * FROM users WHERE id = $1", 1) +.. literalinclude:: /examples/test_drivers_and_querying_5.py + :language: python + :lines: 11-25 + :dedent: 2 **Features**: @@ -171,36 +124,15 @@ sqlite3 (Synchronous) Python's built-in SQLite adapter. -.. code-block:: python - - from sqlspec.adapters.sqlite import SqliteConfig - - config = SqliteConfig( - pool_config={ - "database": "myapp.db", - "timeout": 5.0, - "check_same_thread": False, - } - ) +.. literalinclude:: /examples/test_drivers_and_querying_6.py + :language: python + :lines: 9-27 + :dedent: 2 - with spec.provide_session(config) as session: - # Create table - session.execute(""" - CREATE TABLE IF NOT EXISTS users ( - id INTEGER PRIMARY KEY, - name TEXT NOT NULL - ) - """) - - # Insert with parameters - session.execute( - "INSERT INTO users (name) VALUES (?)", - "Alice" - ) - - # Query - result = session.execute("SELECT * FROM users") - users = result.all() +.. literalinclude:: /examples/test_drivers_and_querying_7.py + :language: python + :lines: 8-9 + :dedent: 2 **Features**: @@ -214,20 +146,10 @@ aiosqlite (Asynchronous) Async wrapper around sqlite3. -.. code-block:: python - - from sqlspec.adapters.aiosqlite import AiosqliteConfig - - config = AiosqliteConfig( - pool_config={"database": "myapp.db"} - ) - - async with spec.provide_session(config) as session: - await session.execute( - "INSERT INTO users (name) VALUES (?)", - "Bob" - ) - result = await session.execute("SELECT * FROM users") +.. literalinclude:: /examples/test_drivers_and_querying_8.py + :language: python + :lines: 7-25 + :dedent: 2 **Features**: @@ -243,27 +165,10 @@ asyncmy (Asynchronous) Pure Python async MySQL/MariaDB driver. -.. code-block:: python - - from sqlspec.adapters.asyncmy import AsyncmyConfig - - config = AsyncmyConfig( - pool_config={ - "host": "localhost", - "port": 3306, - "user": "myuser", - "password": "mypassword", - "database": "mydb", - "minsize": 1, - "maxsize": 10, - } - ) - - async with spec.provide_session(config) as session: - result = await session.execute( - "SELECT * FROM users WHERE id = %s", - 1 - ) +.. literalinclude:: /examples/test_drivers_and_querying_9.py + :language: python + :lines: 9-38 + :dedent: 2 **Features**: From 5be2e0845e30154eba0f953eaa3676f7b2c04ed8 Mon Sep 17 00:00:00 2001 From: euri10 Date: Thu, 6 Nov 2025 11:27:33 +0100 Subject: [PATCH 3/8] 10 and 11 --- docs/examples/usage/conftest.py | 2 +- .../usage/test_drivers_and_querying_10.py | 27 ++++++++-- .../usage/test_drivers_and_querying_11.py | 32 ++++++++++-- docs/usage/drivers_and_querying.rst | 52 +++---------------- 4 files changed, 61 insertions(+), 52 deletions(-) diff --git a/docs/examples/usage/conftest.py b/docs/examples/usage/conftest.py index ee6c6d27..309b68d4 100644 --- a/docs/examples/usage/conftest.py +++ b/docs/examples/usage/conftest.py @@ -1 +1 @@ -pytest_plugins = ["pytest_databases.docker.postgres", "pytest_databases.docker.mysql"] +pytest_plugins = ["pytest_databases.docker.postgres", "pytest_databases.docker.mysql", "pytest_databases.docker.oracle"] diff --git a/docs/examples/usage/test_drivers_and_querying_10.py b/docs/examples/usage/test_drivers_and_querying_10.py index 3b5a4012..9deb0a76 100644 --- a/docs/examples/usage/test_drivers_and_querying_10.py +++ b/docs/examples/usage/test_drivers_and_querying_10.py @@ -5,6 +5,27 @@ def test_example_10_duckdb_config() -> None: - DuckDBConfig() - config_persistent = DuckDBConfig(pool_config={"database": "analytics.duckdb"}) - assert config_persistent.pool_config["database"] == "analytics.duckdb" + from sqlspec import SQLSpec + + spec = SQLSpec() + # In-memory + config = DuckDBConfig() + + # Persistent + config = DuckDBConfig(pool_config={"database": "analytics.duckdb"}) + + with spec.provide_session(config) as session: + # Create table from Parquet + session.execute(""" + CREATE TABLE users AS + SELECT * FROM read_parquet('users.parquet') + """) + + # Analytical query + session.execute(""" + SELECT date_trunc('day', created_at) as day, + count(*) as user_count + FROM users + GROUP BY day + ORDER BY day + """) diff --git a/docs/examples/usage/test_drivers_and_querying_11.py b/docs/examples/usage/test_drivers_and_querying_11.py index a708111b..3e1b5e07 100644 --- a/docs/examples/usage/test_drivers_and_querying_11.py +++ b/docs/examples/usage/test_drivers_and_querying_11.py @@ -1,9 +1,33 @@ # Test module converted from docs example - code-block 11 """Minimal smoke test for drivers_and_querying example 11.""" -from sqlspec.adapters.oracledb import OracleDBConfig +from pytest_databases.docker.oracle import OracleService -def test_example_11_oracledb_config() -> None: - config = OracleDBConfig(pool_config={"user": "myuser", "password": "mypassword", "dsn": "localhost:1521/ORCLPDB"}) - assert "dsn" in config.pool_config +def test_example_11_oracledb_config(oracle_service: OracleService) -> None: + from sqlspec import SQLSpec + from sqlspec.adapters.oracledb import OracleSyncConfig + + spec = SQLSpec() + config = OracleSyncConfig( + pool_config={ + "user": oracle_service.user, + "password": oracle_service.password, + "host": oracle_service.host, + "port": oracle_service.port, + "service_name": oracle_service.service_name, + } + ) + + with spec.provide_session(config) as session: + create_table_sql = """CREATE TABLE employees ( + employee_id NUMBER PRIMARY KEY, + first_name VARCHAR2(50), + last_name VARCHAR2(50) + )""" + session.execute(create_table_sql) + session.execute(""" + INSERT INTO employees (employee_id, first_name, last_name) VALUES (100, 'John', 'Doe') + """) + + session.execute("SELECT * FROM employees WHERE employee_id = :id", id=100) diff --git a/docs/usage/drivers_and_querying.rst b/docs/usage/drivers_and_querying.rst index dd717c69..1673bcf7 100644 --- a/docs/usage/drivers_and_querying.rst +++ b/docs/usage/drivers_and_querying.rst @@ -185,33 +185,10 @@ DuckDB (Analytical Database) In-process analytical database optimized for OLAP workloads. -.. code-block:: python - - from sqlspec.adapters.duckdb import DuckDBConfig - - # In-memory - config = DuckDBConfig() - - # Persistent - config = DuckDBConfig( - pool_config={"database": "analytics.duckdb"} - ) - - with spec.provide_session(config) as session: - # Create table from Parquet - session.execute(""" - CREATE TABLE users AS - SELECT * FROM read_parquet('users.parquet') - """) - - # Analytical query - result = session.execute(""" - SELECT date_trunc('day', created_at) as day, - count(*) as user_count - FROM users - GROUP BY day - ORDER BY day - """) +.. literalinclude:: /examples/test_drivers_and_querying_10.py + :language: python + :lines: 8-34 + :dedent: 2 **Features**: @@ -225,23 +202,10 @@ Oracle Database Oracle database support with python-oracledb. -.. code-block:: python - - from sqlspec.adapters.oracledb import OracleDBConfig - - config = OracleDBConfig( - pool_config={ - "user": "myuser", - "password": "mypassword", - "dsn": "localhost:1521/ORCLPDB", - } - ) - - with spec.provide_session(config) as session: - result = session.execute( - "SELECT * FROM employees WHERE employee_id = :id", - id=100 - ) +.. literalinclude:: /examples/test_drivers_and_querying_11.py + :language: python + :lines: 8-33 + :dedent: 2 **Features**: From e893c05c2b43f8e97b0a0a0c602487582487bb08 Mon Sep 17 00:00:00 2001 From: euri10 Date: Fri, 7 Nov 2025 07:25:11 +0100 Subject: [PATCH 4/8] tmp --- docs/examples/usage/conftest.py | 42 ++++++++++++++++++- .../usage/test_drivers_and_querying_12.py | 31 ++++++++++++-- 2 files changed, 68 insertions(+), 5 deletions(-) diff --git a/docs/examples/usage/conftest.py b/docs/examples/usage/conftest.py index 309b68d4..008d5c16 100644 --- a/docs/examples/usage/conftest.py +++ b/docs/examples/usage/conftest.py @@ -1 +1,41 @@ -pytest_plugins = ["pytest_databases.docker.postgres", "pytest_databases.docker.mysql", "pytest_databases.docker.oracle"] +pytest_plugins = ["pytest_databases.docker.postgres", "pytest_databases.docker.mysql", + "pytest_databases.docker.oracle", "pytest_databases.docker.bigquery"] + +from collections.abc import Generator +from typing import Any + +import pytest +from google.api_core.client_options import ClientOptions +from google.auth.credentials import AnonymousCredentials +from pytest_databases.docker.bigquery import BigQueryService + +from sqlspec.adapters.bigquery.config import BigQueryConfig +from sqlspec.adapters.bigquery.driver import BigQueryDriver + + +@pytest.fixture +def table_schema_prefix(bigquery_service: "BigQueryService") -> str: + """Create a table schema prefix.""" + return f"`{bigquery_service.project}`.`{bigquery_service.dataset}`" + + +@pytest.fixture +def bigquery_config(bigquery_service: "BigQueryService", table_schema_prefix: str) -> BigQueryConfig: + """Create a BigQuery config object.""" + return BigQueryConfig( + connection_config={ + "project": bigquery_service.project, + "dataset_id": table_schema_prefix, + "client_options": ClientOptions(api_endpoint=f"http://{bigquery_service.host}:{bigquery_service.port}"), + "credentials": AnonymousCredentials(), # type: ignore[no-untyped-call] + } + ) + + +@pytest.fixture +def bigquery_session(bigquery_config: BigQueryConfig) -> Generator[BigQueryDriver, Any, None]: + """Create a BigQuery sync session.""" + + with bigquery_config.provide_session() as session: + yield session + diff --git a/docs/examples/usage/test_drivers_and_querying_12.py b/docs/examples/usage/test_drivers_and_querying_12.py index a132de66..78437a3e 100644 --- a/docs/examples/usage/test_drivers_and_querying_12.py +++ b/docs/examples/usage/test_drivers_and_querying_12.py @@ -1,9 +1,32 @@ # Test module converted from docs example - code-block 12 """Minimal smoke test for drivers_and_querying example 12.""" -from sqlspec.adapters.bigquery import BigQueryConfig +from sqlspec.adapters.bigquery import BigQueryDriver -def test_example_12_bigquery_config() -> None: - config = BigQueryConfig(pool_config={"project": "my-project", "credentials": None}) - assert config.pool_config["project"] == "my-project" + +def test_example_12_bigquery_config(bigquery_session: BigQueryDriver) -> None: + + + from sqlspec import SQLSpec + spec = SQLSpec() + + result = bigquery_session.execute("SELECT 1 AS value") + + # Create the test table + + create_table_query = """ + CREATE TABLE events ( + timestamp TIMESTAMP, + event_type STRING + ) + """ + bigquery_session.execute_script(create_table_query) + + result = bigquery_session.execute(""" + SELECT DATE(timestamp) as date, + COUNT(*) as events + FROM events + WHERE timestamp >= @start_date + GROUP BY date + """, start_date=datetime.date(2025, 1, 1)) From 738924b28c7313bd61079d039c773ac4ffc7a2d8 Mon Sep 17 00:00:00 2001 From: euri10 Date: Fri, 7 Nov 2025 09:13:51 +0100 Subject: [PATCH 5/8] hanging bigquery ? --- docs/examples/queries/users.parquet | Bin 0 -> 4525 bytes docs/examples/usage/conftest.py | 24 +++++++++++++++--- .../usage/test_drivers_and_querying_10.py | 8 +++--- .../usage/test_drivers_and_querying_11.py | 2 +- .../usage/test_drivers_and_querying_12.py | 19 ++++++++------ .../usage/test_drivers_and_querying_5.py | 4 +-- 6 files changed, 40 insertions(+), 17 deletions(-) create mode 100644 docs/examples/queries/users.parquet diff --git a/docs/examples/queries/users.parquet b/docs/examples/queries/users.parquet new file mode 100644 index 0000000000000000000000000000000000000000..cf99d16b7a17b15e80d895d7db26cfa8ae43d076 GIT binary patch literal 4525 zcmchbd2kcg9miM3$d<7ILu5-}z$oBADjc200&}cnBulXk2++mhXeHT_Ev=m+|P$AB2*fLtH}QZN7v1bJW(7z~Dhd@vNqz~f*T7!C@+ z6JP`w37!PM0CF%26oRLK0w{qBsDTD(K@k`Yih(XGJ#`GpaxBTR1U=)xcrXD>1T@eC z11JTPfDxEL888D2cp8+03Q!3qgDGGtu!3n|I+y`$zz!V130z<%m<48oIiLzW1Kfbg zN-yzH{N-&?F+~>YLxG$~U$Iau%#)-)7?h+7TFi2&5nc3VXJgoV!_x!OED)p(T)6O= zi6bPvmn>oq`HKg?xWud9;wW6btom>NX&k@tMStm&YbrOds6AZ!?wsALgT`&=*uCr6 zBiHWz^5DjBnS8+SnqP|?4UXCH(dL+Chili_?G4AT&pU8&cVi~} z6QVyJ^+l?b;tWa!)IbBYpa_fx#o~-qU7FZMDWtt9B~Sr1&;Ttc0;55(w3n2{X!lUV z4y3A8;+M(8Bhg^2J7{6o9g1Mr9Y({hI~2pNJLq8d6KHh0^wuR&D7yHzil`B3+=}UR z5+T2I|L2eBVutw3jB@dI{&d>i^M;S2M)tDR-pZw@iTj6cI1fEk=g<5ax^ZIN69=I= z2m0G?L*HJuW9$KF@umew_d-uG0|W0s2g=v3`2f0S;hsA;pnujk-}nyt+TF#U-GfT= zH%t@smET?S*os|f-jqK-Mc}`^R&a^_hwgK9Z1H5}pMd(ASF*N3U$|dTv>B=@{Eqn% zx?WR%=_Yi4#`)e?p_5Fv5y@-x+UMRN<5xx3>_lJx{?|WVgpT*DXd?B_7<;*jIJWJ7`97(W=(26|PN?#ne;bK= z>)v%|NZzT*zk5GJd(+DM7w$lhO-P2fK!cL^-v0u+YxuB%LnrS3zUeSRR} zh-(+E-w%B=ec>dsj#NKm=}qW_!160^3Rb5tKE8G6!5g#Hn!AfHqg$lCTJi%l^69Df zu0aofa#K#C|JUWRs>9H)yp5`Fp#R=ndN^A&W~DB*UJ z%?swe$L{8Kv8g23bbM;$iHjze9N3+Ee`2qtmX)eDO_%4E4}JAqc+C1fBZdw5y`|s- z(MszM$@W#(dM-U${kZGo8}D9<>^r~gOpi6sP8h5hk=Jjj;EU`v(+gkHRG+%H$oTrH zA@5{x2e!0aOG$)LkKY$^i-kDBho?wV0$xg-iHB6y9r6vQ%JVo=bYyrUK6lLLt#ZeL z%lhS&pdUN0Ss=}mmK0EV;#8@Y684o658@Q`=j`m0^OmUKs<0sa=lx_!<@hb3#3>YR zeIX?yh0+52eqlN?PiD(JT!8#c&HZzJD=OI7w_u+ruj>=6lh2&18PaxcAB5i~P2Ty3 zSvhC33XTmbXzGVNI$o_wq5sL*ZoWKs{6I^TbGOAz#ex zb;sN=pD**VFb}Xb*0p!oLKv@4)daZzE}WjjF8xNIX)OE(#&L|v&neJ zWXW2)W3fnpiO0Bgo{#)x+;sI3Zc%~(CgP4H$(n?d?ntCQLHsoMBGEuSOL|qRLPeoM zM&4@)tnFZ-x=<}!KuI!bt97z{41at`R%bj#uHu?fnx>}$ay?Dc8d_gN8)>?RHq>x^ zdVRa`1nHdAIzE{;@NL{VFWk79rV}*YgAykO4H2|4Lmlk(qs^gU+-0(99IDC&rpy*& z*owg9fS&OsEfKd}TW7AVuQ9V0KNIo>&4EOXIi&S7_8G(`?zJ~Y%MEnEqqh1z>{Rs8 ziI#SQ$6zipmrhDl81N2Tsc<=HGTvBiQ$)=MOD&^nR5EsLHJQWZ@CQ9f*c)Srr?Y=o zC>Uf+)@mkXjJc-4&ZJc`rUdbmaN>QZqq5pt7EEws28)sj1>xWNAYLWo&}$uPtJY&8 zank`tWtr=;S1R~?ltHh_2p?8I$rX7AnNVee%Y?d+m<$%1ZIUxK*Cou*+a3afRG=ThwLL#hrF#kgH)RSjWxB>QPJ7OQ}=%9Qp@iac`-!B_8C~Azsu- zQCT}RKx)g_Z3?H|>i3!^wXQ++v;>K}&0Ks9iG8Qq8CvYfT6Pr+Ym2+>B>x%we5@_z zDGRo(Z-X-w4m#C8C!Wfr%WhP-?AB_hgMY7!xN1Ei8}hQ%IaEfz7G1@M+QCNQCUxb% z$4>QfnJ|~b8pe03sx-#p9;M>Zwd21>zqibqblWXT_~zEtr{=#?J|maH;>7PJ!zbWM{*``JD2QqT-=?Vg7boG@2U0NPPcGF4~`D(a str: @@ -39,3 +43,17 @@ def bigquery_session(bigquery_config: BigQueryConfig) -> Generator[BigQueryDrive with bigquery_config.provide_session() as session: yield session +@pytest.fixture +async def postgres_session_async(postgres_service: "PostgresService") -> Generator[Any, Any, None]: + """Create a Postgres async session.""" + from sqlspec.adapters.asyncpg import AsyncpgConfig + + config = AsyncpgConfig( + pool_config={ + "dsn": f"postgresql://{postgres_service.user}:{postgres_service.password}@{postgres_service.host}:{postgres_service.port}/{postgres_service.database}", + "min_size": 1, + "max_size": 5, + } + ) + async with config.provide_session() as session: + yield session diff --git a/docs/examples/usage/test_drivers_and_querying_10.py b/docs/examples/usage/test_drivers_and_querying_10.py index 9deb0a76..d0446f92 100644 --- a/docs/examples/usage/test_drivers_and_querying_10.py +++ b/docs/examples/usage/test_drivers_and_querying_10.py @@ -1,6 +1,8 @@ # Test module converted from docs example - code-block 10 """Minimal smoke test for drivers_and_querying example 10.""" +from pathlib import Path + from sqlspec.adapters.duckdb import DuckDBConfig @@ -16,9 +18,9 @@ def test_example_10_duckdb_config() -> None: with spec.provide_session(config) as session: # Create table from Parquet - session.execute(""" - CREATE TABLE users AS - SELECT * FROM read_parquet('users.parquet') + session.execute(f""" + CREATE TABLE if not exists users AS + SELECT * FROM read_parquet('{Path(__file__).parent.parent / "queries/users.parquet"}') """) # Analytical query diff --git a/docs/examples/usage/test_drivers_and_querying_11.py b/docs/examples/usage/test_drivers_and_querying_11.py index 3e1b5e07..5eca661a 100644 --- a/docs/examples/usage/test_drivers_and_querying_11.py +++ b/docs/examples/usage/test_drivers_and_querying_11.py @@ -20,7 +20,7 @@ def test_example_11_oracledb_config(oracle_service: OracleService) -> None: ) with spec.provide_session(config) as session: - create_table_sql = """CREATE TABLE employees ( + create_table_sql = """CREATE TABLE if not exists employees ( employee_id NUMBER PRIMARY KEY, first_name VARCHAR2(50), last_name VARCHAR2(50) diff --git a/docs/examples/usage/test_drivers_and_querying_12.py b/docs/examples/usage/test_drivers_and_querying_12.py index 78437a3e..b3ffd825 100644 --- a/docs/examples/usage/test_drivers_and_querying_12.py +++ b/docs/examples/usage/test_drivers_and_querying_12.py @@ -1,32 +1,35 @@ # Test module converted from docs example - code-block 12 """Minimal smoke test for drivers_and_querying example 12.""" - from sqlspec.adapters.bigquery import BigQueryDriver -def test_example_12_bigquery_config(bigquery_session: BigQueryDriver) -> None: - +def test_example_12_bigquery_config(bigquery_session: "BigQueryDriver") -> None: + import datetime from sqlspec import SQLSpec - spec = SQLSpec() - result = bigquery_session.execute("SELECT 1 AS value") + SQLSpec() + + bigquery_session.execute("SELECT 1 AS value") # Create the test table create_table_query = """ - CREATE TABLE events ( + CREATE TABLE if not exists events ( timestamp TIMESTAMP, event_type STRING ) """ bigquery_session.execute_script(create_table_query) - result = bigquery_session.execute(""" + bigquery_session.execute( + """ SELECT DATE(timestamp) as date, COUNT(*) as events FROM events WHERE timestamp >= @start_date GROUP BY date - """, start_date=datetime.date(2025, 1, 1)) + """, + start_date=datetime.date(2025, 1, 1), + ) diff --git a/docs/examples/usage/test_drivers_and_querying_5.py b/docs/examples/usage/test_drivers_and_querying_5.py index 8b90e6d6..bf8bb8a1 100644 --- a/docs/examples/usage/test_drivers_and_querying_5.py +++ b/docs/examples/usage/test_drivers_and_querying_5.py @@ -16,7 +16,7 @@ async def test_example_5_construct_config(postgres_service: PostgresService) -> ) assert config is not None async with spec.provide_session(config) as session: - create_table_query = """ CREATE TABLE IF NOT EXISTS users ( + create_table_query = """CREATE TABLE IF NOT EXISTS users ( id SERIAL PRIMARY KEY, name VARCHAR(100), email VARCHAR(100) UNIQUE @@ -24,6 +24,6 @@ async def test_example_5_construct_config(postgres_service: PostgresService) -> await session.execute(create_table_query) # Insert with RETURNING await session.execute( - "INSERT INTO users (name, email) VALUES ($1, $2) RETURNING id", "Alice", "alice@example.com" + "INSERT INTO users (name, email) VALUES ($1, $2) ETURNING id", "Alice", "alice@example.com" ) await session.execute("SELECT * FROM users WHERE id = $1", 1) From fc86eec11c9794090067b9efc897eda17a0767eb Mon Sep 17 00:00:00 2001 From: euri10 Date: Mon, 10 Nov 2025 07:32:24 +0100 Subject: [PATCH 6/8] tmp --- docs/examples/usage/conftest.py | 53 ---------------- .../usage/test_drivers_and_querying_12.py | 61 +++++++++++-------- .../usage/test_drivers_and_querying_13.py | 26 +++++++- 3 files changed, 61 insertions(+), 79 deletions(-) diff --git a/docs/examples/usage/conftest.py b/docs/examples/usage/conftest.py index ea6546bb..874e6d40 100644 --- a/docs/examples/usage/conftest.py +++ b/docs/examples/usage/conftest.py @@ -1,59 +1,6 @@ -from collections.abc import Generator -from typing import Any - -import pytest -from google.api_core.client_options import ClientOptions -from google.auth.credentials import AnonymousCredentials -from pytest_databases.docker.bigquery import BigQueryService - -from sqlspec.adapters.bigquery.config import BigQueryConfig -from sqlspec.adapters.bigquery.driver import BigQueryDriver - pytest_plugins = [ "pytest_databases.docker.postgres", "pytest_databases.docker.mysql", "pytest_databases.docker.oracle", "pytest_databases.docker.bigquery", ] - - -@pytest.fixture -def table_schema_prefix(bigquery_service: "BigQueryService") -> str: - """Create a table schema prefix.""" - return f"`{bigquery_service.project}`.`{bigquery_service.dataset}`" - - -@pytest.fixture -def bigquery_config(bigquery_service: "BigQueryService", table_schema_prefix: str) -> BigQueryConfig: - """Create a BigQuery config object.""" - return BigQueryConfig( - connection_config={ - "project": bigquery_service.project, - "dataset_id": table_schema_prefix, - "client_options": ClientOptions(api_endpoint=f"http://{bigquery_service.host}:{bigquery_service.port}"), - "credentials": AnonymousCredentials(), # type: ignore[no-untyped-call] - } - ) - - -@pytest.fixture -def bigquery_session(bigquery_config: BigQueryConfig) -> Generator[BigQueryDriver, Any, None]: - """Create a BigQuery sync session.""" - - with bigquery_config.provide_session() as session: - yield session - -@pytest.fixture -async def postgres_session_async(postgres_service: "PostgresService") -> Generator[Any, Any, None]: - """Create a Postgres async session.""" - from sqlspec.adapters.asyncpg import AsyncpgConfig - - config = AsyncpgConfig( - pool_config={ - "dsn": f"postgresql://{postgres_service.user}:{postgres_service.password}@{postgres_service.host}:{postgres_service.port}/{postgres_service.database}", - "min_size": 1, - "max_size": 5, - } - ) - async with config.provide_session() as session: - yield session diff --git a/docs/examples/usage/test_drivers_and_querying_12.py b/docs/examples/usage/test_drivers_and_querying_12.py index b3ffd825..54294802 100644 --- a/docs/examples/usage/test_drivers_and_querying_12.py +++ b/docs/examples/usage/test_drivers_and_querying_12.py @@ -1,35 +1,48 @@ # Test module converted from docs example - code-block 12 """Minimal smoke test for drivers_and_querying example 12.""" -from sqlspec.adapters.bigquery import BigQueryDriver +from sqlspec.adapters.bigquery.driver import BigQueryDriver -def test_example_12_bigquery_config(bigquery_session: "BigQueryDriver") -> None: +def test_example_12_bigquery_config(bigquery_service: BigQueryDriver) -> None: import datetime - from sqlspec import SQLSpec - - SQLSpec() - - bigquery_session.execute("SELECT 1 AS value") - - # Create the test table + from google.api_core.client_options import ClientOptions + from google.auth.credentials import AnonymousCredentials - create_table_query = """ - CREATE TABLE if not exists events ( - timestamp TIMESTAMP, - event_type STRING + from sqlspec import SQLSpec + from sqlspec.adapters.bigquery.config import BigQueryConfig + + config = BigQueryConfig( + connection_config={ + "project": bigquery_service.project, + "dataset_id": bigquery_service.dataset, + "client_options": ClientOptions(api_endpoint=f"http://{bigquery_service.host}:{bigquery_service.port}"), + "credentials": AnonymousCredentials(), # type: ignore[no-untyped-call] + } ) - """ - bigquery_session.execute_script(create_table_query) + spec = SQLSpec() + with spec.provide_session(config) as bigquery_session: + bigquery_session.execute("SELECT 1 AS value") + + # Create the test table - bigquery_session.execute( + create_table_query = """ + CREATE or replace TABLE events ( + timestamp TIMESTAMP, + event_type STRING + ) """ - SELECT DATE(timestamp) as date, - COUNT(*) as events - FROM events - WHERE timestamp >= @start_date - GROUP BY date - """, - start_date=datetime.date(2025, 1, 1), - ) + bigquery_session.execute_script(create_table_query) + + print("Executing test query...") + bigquery_session.execute( + """ + SELECT DATE(timestamp) as date, + COUNT(*) as events + FROM events + WHERE timestamp >= @start_date + GROUP BY date + """, + start_date=datetime.date(2025, 1, 1), + ) diff --git a/docs/examples/usage/test_drivers_and_querying_13.py b/docs/examples/usage/test_drivers_and_querying_13.py index f6ff9c30..3ee55908 100644 --- a/docs/examples/usage/test_drivers_and_querying_13.py +++ b/docs/examples/usage/test_drivers_and_querying_13.py @@ -1,7 +1,29 @@ # Test module converted from docs example - code-block 13 """Minimal smoke test for drivers_and_querying example 13.""" +from sqlspec import SQLSpec +from sqlspec.adapters.sqlite import SqliteConfig + def test_example_13_placeholder() -> None: - # Examples are documentation snippets; ensure module importable - assert True + spec = SQLSpec() + config = SqliteConfig(pool_config={"database": ":memory:", "timeout": 5.0, "check_same_thread": False}) + with spec.provide_session(config) as session: + create_table_query = ( + """create table if not exists users (id default int primary key, name varchar(128), email text)""" + ) + + session.execute(create_table_query) + # Examples are documentation snippets; ensure module importable + result = session.execute("SELECT * FROM users WHERE id = ?", 1) + + # INSERT query + result = session.execute("INSERT INTO users (name, email) VALUES (?, ?)", "Alice", "alice@example.com") + + # UPDATE query + result = session.execute("UPDATE users SET email = ? WHERE id = ?", "newemail@example.com", 1) + print(f"Updated {result.rows_affected} rows") + + # DELETE query + result = session.execute("DELETE FROM users WHERE id = ?", 1) + config.close_pool() From 46e2ff617ddb048093fafd1551fc81daf834776e Mon Sep 17 00:00:00 2001 From: euri10 Date: Mon, 10 Nov 2025 15:27:29 +0100 Subject: [PATCH 7/8] tmp --- .../usage/test_drivers_and_querying_1.py | 6 +- .../usage/test_drivers_and_querying_10.py | 3 +- .../usage/test_drivers_and_querying_13.py | 9 +- .../usage/test_drivers_and_querying_14.py | 58 ++++++- .../usage/test_drivers_and_querying_15.py | 2 +- .../usage/test_drivers_and_querying_2.py | 6 +- .../usage/test_drivers_and_querying_3.py | 4 +- .../usage/test_drivers_and_querying_4.py | 28 ++- .../usage/test_drivers_and_querying_6.py | 3 +- .../usage/test_drivers_and_querying_7.py | 4 +- docs/usage/drivers_and_querying.rst | 160 ++++++++---------- 11 files changed, 167 insertions(+), 116 deletions(-) diff --git a/docs/examples/usage/test_drivers_and_querying_1.py b/docs/examples/usage/test_drivers_and_querying_1.py index 98a0c386..033581d9 100644 --- a/docs/examples/usage/test_drivers_and_querying_1.py +++ b/docs/examples/usage/test_drivers_and_querying_1.py @@ -3,11 +3,11 @@ from pytest_databases.docker.postgres import PostgresService -from sqlspec import SQLSpec -from sqlspec.adapters.asyncpg import AsyncpgConfig, AsyncpgPoolConfig - async def test_importable_1(postgres_service: PostgresService) -> None: + from sqlspec import SQLSpec + from sqlspec.adapters.asyncpg import AsyncpgConfig, AsyncpgPoolConfig + # Typical driver usage spec = SQLSpec() db = spec.add_config( diff --git a/docs/examples/usage/test_drivers_and_querying_10.py b/docs/examples/usage/test_drivers_and_querying_10.py index d0446f92..a04c60e4 100644 --- a/docs/examples/usage/test_drivers_and_querying_10.py +++ b/docs/examples/usage/test_drivers_and_querying_10.py @@ -3,11 +3,10 @@ from pathlib import Path -from sqlspec.adapters.duckdb import DuckDBConfig - def test_example_10_duckdb_config() -> None: from sqlspec import SQLSpec + from sqlspec.adapters.duckdb import DuckDBConfig spec = SQLSpec() # In-memory diff --git a/docs/examples/usage/test_drivers_and_querying_13.py b/docs/examples/usage/test_drivers_and_querying_13.py index 3ee55908..8da583d6 100644 --- a/docs/examples/usage/test_drivers_and_querying_13.py +++ b/docs/examples/usage/test_drivers_and_querying_13.py @@ -1,11 +1,11 @@ # Test module converted from docs example - code-block 13 """Minimal smoke test for drivers_and_querying example 13.""" -from sqlspec import SQLSpec -from sqlspec.adapters.sqlite import SqliteConfig - def test_example_13_placeholder() -> None: + from sqlspec import SQLSpec + from sqlspec.adapters.sqlite import SqliteConfig + spec = SQLSpec() config = SqliteConfig(pool_config={"database": ":memory:", "timeout": 5.0, "check_same_thread": False}) with spec.provide_session(config) as session: @@ -13,7 +13,7 @@ def test_example_13_placeholder() -> None: """create table if not exists users (id default int primary key, name varchar(128), email text)""" ) - session.execute(create_table_query) + _ = session.execute(create_table_query) # Examples are documentation snippets; ensure module importable result = session.execute("SELECT * FROM users WHERE id = ?", 1) @@ -26,4 +26,3 @@ def test_example_13_placeholder() -> None: # DELETE query result = session.execute("DELETE FROM users WHERE id = ?", 1) - config.close_pool() diff --git a/docs/examples/usage/test_drivers_and_querying_14.py b/docs/examples/usage/test_drivers_and_querying_14.py index 0b4c5a86..b9cb8d2c 100644 --- a/docs/examples/usage/test_drivers_and_querying_14.py +++ b/docs/examples/usage/test_drivers_and_querying_14.py @@ -1,7 +1,57 @@ -# Test module converted from docs example - code-block 14 -"""Minimal smoke test for drivers_and_querying example 14.""" +"for drivers_and_querying example 14.""" + +import pytest def test_example_14_placeholder() -> None: - # Batch examples are documentation-only - assert True + from sqlspec import SQLSpec + from sqlspec.adapters.sqlite import SqliteConfig + + spec = SQLSpec() + config = SqliteConfig(pool_config={"database": ":memory:", "timeout": 5.0, "check_same_thread": False}) + with spec.provide_session(config) as session: + create_table_query = """create table if not exists users (id default int primary key, name varchar(128), email text, status varchar(32))""" + + _ = session.execute(create_table_query) + # Batch examples are documentation-only + + # Batch insert + session.execute_many( + "INSERT INTO users (id, name, email, status) VALUES (?, ?, ?, ?)", + [ + (1, "Alice", "alice@example.com", "active"), + (2, "Bob", "bob@example.com", "inactive"), + (3, "Charlie", "charlie@example.com", "active"), + ], + ) + # Batch update + session.execute_many("UPDATE users SET status = ? WHERE id = ?", [("inactive", 1), ("active", 2)]) + results = session.select("SELECT * FROM users") + print(results) + # Returns list of dictionaries: [{"id": 1, "name": "Alice", ...}, ...] + user = session.select_one("SELECT * FROM users WHERE id = ?", 1) + print(user) + # Returns single dictionary: {"id": 1, "name": "Alice", ...} + # Raises NotFoundError if no results + # Raises MultipleResultsFoundError if multiple results + user = session.select_one_or_none("SELECT * FROM users WHERE email = ?", "nobody@example.com") + # Returns dictionary or None + # Raises MultipleResultsFoundError if multiple results + count = session.select_value("SELECT COUNT(*) FROM users") + # Returns: 3 + latest_id = session.select_value("SELECT MAX(id) FROM users") + # Returns: 3 + result = session.execute("SELECT id, name, email FROM users") + # Access raw data + result.data # List of dictionaries + result.column_names # ["id", "name", "email"] + result.rows_affected # For INSERT/UPDATE/DELETE + result.operation_type # "SELECT", "INSERT", etc. + # Convenience methods + with pytest.raises(ValueError): + user = result.one() # Single row (raises if not exactly 1) + with pytest.raises(ValueError): + user = result.one_or_none() # Single row or None + with pytest.raises(ValueError): + value = result.scalar() # First column of first row + diff --git a/docs/examples/usage/test_drivers_and_querying_15.py b/docs/examples/usage/test_drivers_and_querying_15.py index c8b12dda..ce29eda9 100644 --- a/docs/examples/usage/test_drivers_and_querying_15.py +++ b/docs/examples/usage/test_drivers_and_querying_15.py @@ -3,4 +3,4 @@ def test_example_15_placeholder() -> None: - assert True + pass diff --git a/docs/examples/usage/test_drivers_and_querying_2.py b/docs/examples/usage/test_drivers_and_querying_2.py index e9057721..aaaa0cca 100644 --- a/docs/examples/usage/test_drivers_and_querying_2.py +++ b/docs/examples/usage/test_drivers_and_querying_2.py @@ -3,11 +3,11 @@ from pytest_databases.docker.postgres import PostgresService -from sqlspec import SQLSpec -from sqlspec.adapters.asyncpg import AsyncpgConfig - async def test_example_2_importable(postgres_service: PostgresService) -> None: + from sqlspec import SQLSpec + from sqlspec.adapters.asyncpg import AsyncpgConfig + spec = SQLSpec() db = spec.add_config( AsyncpgConfig( diff --git a/docs/examples/usage/test_drivers_and_querying_3.py b/docs/examples/usage/test_drivers_and_querying_3.py index 7b8ffed0..8025f60e 100644 --- a/docs/examples/usage/test_drivers_and_querying_3.py +++ b/docs/examples/usage/test_drivers_and_querying_3.py @@ -4,12 +4,12 @@ from pytest_databases.docker.postgres import PostgresService -def test_example_3_importable(postgres_service: PostgresService) -> None: +def test_example_3_sync(postgres_service: PostgresService) -> None: from sqlspec import SQLSpec from sqlspec.adapters.psycopg import PsycopgSyncConfig spec = SQLSpec() - # Async version + # Sync version config = PsycopgSyncConfig( pool_config={ "conninfo": f"postgresql://{postgres_service.user}:{postgres_service.password}@{postgres_service.host}:{postgres_service.port}/{postgres_service.database}", diff --git a/docs/examples/usage/test_drivers_and_querying_4.py b/docs/examples/usage/test_drivers_and_querying_4.py index f54ce3c6..43497bad 100644 --- a/docs/examples/usage/test_drivers_and_querying_4.py +++ b/docs/examples/usage/test_drivers_and_querying_4.py @@ -3,14 +3,32 @@ from pytest_databases.docker.postgres import PostgresService -from sqlspec.adapters.psycopg import PsycopgSyncConfig +async def test_example_4_async(postgres_service: PostgresService) -> None: + from sqlspec import SQLSpec + from sqlspec.adapters.psycopg import PsycopgAsyncConfig -def test_example_4_construct_config(postgres_service: PostgresService) -> None: - config = PsycopgSyncConfig( + spec = SQLSpec() + # Async version + config = PsycopgAsyncConfig( pool_config={ - "conninfo": f"postgresql://{postgres_service.user}:{postgres_service.password}@{postgres_service.host}:{postgres_service.port}/{postgres_service.database}" + "conninfo": f"postgresql://{postgres_service.user}:{postgres_service.password}@{postgres_service.host}:{postgres_service.port}/{postgres_service.database}", + "min_size": 5, + "max_size": 10, } ) - assert config is not None + async with spec.provide_session(config) as session: + create_table_query = """ + CREATE TABLE IF NOT EXISTS users ( + id SERIAL PRIMARY KEY, + name VARCHAR(100), + email VARCHAR(100) UNIQUE + ); + """ + await session.execute(create_table_query) + # Insert with RETURNING + await session.execute( + "INSERT INTO users (name, email) VALUES (%s, %s) RETURNING id", "Alice", "alice@example.com" + ) + await session.execute("SELECT * FROM users") diff --git a/docs/examples/usage/test_drivers_and_querying_6.py b/docs/examples/usage/test_drivers_and_querying_6.py index d304dede..75b17ccb 100644 --- a/docs/examples/usage/test_drivers_and_querying_6.py +++ b/docs/examples/usage/test_drivers_and_querying_6.py @@ -2,10 +2,11 @@ """Minimal smoke test for drivers_and_querying example 6.""" from sqlspec import SQLSpec -from sqlspec.adapters.sqlite import SqliteConfig def test_example_6_sqlite_config() -> None: + from sqlspec.adapters.sqlite import SqliteConfig + spec = SQLSpec() config = SqliteConfig(pool_config={"database": "myapp.db", "timeout": 5.0, "check_same_thread": False}) diff --git a/docs/examples/usage/test_drivers_and_querying_7.py b/docs/examples/usage/test_drivers_and_querying_7.py index 8ee74316..f0e84446 100644 --- a/docs/examples/usage/test_drivers_and_querying_7.py +++ b/docs/examples/usage/test_drivers_and_querying_7.py @@ -1,9 +1,9 @@ # Test module converted from docs example - code-block 7 """Minimal smoke test for drivers_and_querying example 7.""" -from sqlspec.adapters.sqlite import SqliteConfig - def test_example_7_sync_sqlite() -> None: + from sqlspec.adapters.sqlite import SqliteConfig + config = SqliteConfig(pool_config={"database": "myapp.db", "timeout": 5.0, "check_same_thread": False}) assert config.pool_config["database"] == "myapp.db" diff --git a/docs/usage/drivers_and_querying.rst b/docs/usage/drivers_and_querying.rst index 1673bcf7..cf7d6875 100644 --- a/docs/usage/drivers_and_querying.rst +++ b/docs/usage/drivers_and_querying.rst @@ -51,10 +51,11 @@ SQLSpec drivers follow a layered architecture: 3. **Driver Layer**: Query execution and result handling 4. **Session Layer**: Transaction management -.. literalinclude:: /examples/test_drivers_and_querying_1.py +.. literalinclude:: /examples/usage/test_drivers_and_querying_1.py :language: python - :lines: 15-29 + :lines: 8-25 :dedent: 2 + :caption: `driver architecture` PostgreSQL Drivers ------------------ @@ -64,10 +65,11 @@ asyncpg (Recommended for Async) Async PostgreSQL driver with native connection pooling. -.. literalinclude:: /examples/test_drivers_and_querying_2.py +.. literalinclude:: /examples/usage/test_drivers_and_querying_2.py :language: python - :lines: 11-35 + :lines: 8-39 :dedent: 2 + :caption: `asyncpg` **Features**: @@ -82,15 +84,23 @@ psycopg (Sync/Async) Official PostgreSQL adapter with both sync and async support. -.. literalinclude:: /examples/test_drivers_and_querying_3.py - :language: python - :lines: 8-32 - :dedent: 2 +.. tab-set:: -.. literalinclude:: /examples/test_drivers_and_querying_4.py - :language: python - :lines: 10-12 - :dedent: 2 + .. tab-item:: Sync + + .. literalinclude:: /examples/usage/test_drivers_and_querying_3.py + :language: python + :lines: 8-32 + :dedent: 2 + :caption: `psycopg sync` + + .. tab-item:: Async + + .. literalinclude:: /examples/usage/test_drivers_and_querying_4.py + :language: python + :lines: 8-34 + :dedent: 2 + :caption: `psycopg async` **Features**: @@ -105,10 +115,11 @@ psqlpy (High Performance Async) Rust-based async PostgreSQL driver for maximum performance. -.. literalinclude:: /examples/test_drivers_and_querying_5.py +.. literalinclude:: /examples/usage/test_drivers_and_querying_5.py :language: python - :lines: 11-25 + :lines: 11-29 :dedent: 2 + :caption: `psqlpy` **Features**: @@ -124,15 +135,17 @@ sqlite3 (Synchronous) Python's built-in SQLite adapter. -.. literalinclude:: /examples/test_drivers_and_querying_6.py +.. literalinclude:: /examples/usage/test_drivers_and_querying_6.py :language: python - :lines: 9-27 + :lines: 8-27 :dedent: 2 + :caption: `sqlite config` -.. literalinclude:: /examples/test_drivers_and_querying_7.py +.. literalinclude:: /examples/usage/test_drivers_and_querying_7.py :language: python - :lines: 8-9 + :lines: 6-9 :dedent: 2 + :caption: `sqlite` **Features**: @@ -146,10 +159,11 @@ aiosqlite (Asynchronous) Async wrapper around sqlite3. -.. literalinclude:: /examples/test_drivers_and_querying_8.py +.. literalinclude:: /examples/usage/test_drivers_and_querying_8.py :language: python - :lines: 7-25 + :lines: 6-19 :dedent: 2 + :caption: `aiosqlite` **Features**: @@ -165,10 +179,11 @@ asyncmy (Asynchronous) Pure Python async MySQL/MariaDB driver. -.. literalinclude:: /examples/test_drivers_and_querying_9.py +.. literalinclude:: /examples/usage/test_drivers_and_querying_9.py :language: python - :lines: 9-38 + :lines: 8-37 :dedent: 2 + :caption: `asyncmy` **Features**: @@ -185,10 +200,11 @@ DuckDB (Analytical Database) In-process analytical database optimized for OLAP workloads. -.. literalinclude:: /examples/test_drivers_and_querying_10.py +.. literalinclude:: /examples/usage/test_drivers_and_querying_10.py :language: python - :lines: 8-34 + :lines: 8-32 :dedent: 2 + :caption: `duckdb` **Features**: @@ -202,10 +218,11 @@ Oracle Database Oracle database support with python-oracledb. -.. literalinclude:: /examples/test_drivers_and_querying_11.py +.. literalinclude:: /examples/usage/test_drivers_and_querying_11.py :language: python :lines: 8-33 :dedent: 2 + :caption: `oracle` **Features**: @@ -256,100 +273,67 @@ execute() Execute any SQL statement and return results. -.. code-block:: python - - # SELECT query - result = session.execute("SELECT * FROM users WHERE id = ?", 1) - - # INSERT query - result = session.execute( - "INSERT INTO users (name, email) VALUES (?, ?)", - "Alice", - "alice@example.com" - ) - - # UPDATE query - result = session.execute( - "UPDATE users SET email = ? WHERE id = ?", - "newemail@example.com", - 1 - ) - print(f"Updated {result.rows_affected} rows") - - # DELETE query - result = session.execute("DELETE FROM users WHERE id = ?", 1) +.. literalinclude:: /examples/usage/test_drivers_and_querying_13.py + :language: python + :lines: 9-28 + :dedent: 2 + :caption: `execute` execute_many() ^^^^^^^^^^^^^^ Execute a statement with multiple parameter sets (batch insert/update). -.. code-block:: python - - # Batch insert - session.execute_many( - "INSERT INTO users (name, email) VALUES (?, ?)", - [ - ("Alice", "alice@example.com"), - ("Bob", "bob@example.com"), - ("Charlie", "charlie@example.com"), - ] - ) +.. literalinclude:: /examples/usage/test_drivers_and_querying_14.py + :language: python + :lines: 6-27 + :dedent: 2 + :caption: `execute_many` - # Batch update - session.execute_many( - "UPDATE users SET status = ? WHERE id = ?", - [ - ("active", 1), - ("inactive", 2), - ] - ) select() ^^^^^^^^ Execute a SELECT query and return all rows. -.. code-block:: python - - users = session.execute("SELECT * FROM users WHERE status = ?", "active") - # Returns list of dictionaries: [{"id": 1, "name": "Alice", ...}, ...] +.. literalinclude:: /examples/usage/test_drivers_and_querying_14.py + :language: python + :lines: 28-30 + :dedent: 4 + :caption: `select` select_one() ^^^^^^^^^^^^ Execute a SELECT query expecting exactly one result. -.. code-block:: python - - user = session.select_one("SELECT * FROM users WHERE id = ?", 1) - # Returns single dictionary: {"id": 1, "name": "Alice", ...} - # Raises NotFoundError if no results - # Raises MultipleResultsFoundError if multiple results +.. literalinclude:: /examples/usage/test_drivers_and_querying_14.py + :language: python + :lines: 31-35 + :dedent: 2 + :caption: `select_one` select_one_or_none() ^^^^^^^^^^^^^^^^^^^^ Execute a SELECT query returning one or no results. -.. code-block:: python - - user = session.select_one_or_none("SELECT * FROM users WHERE email = ?", "nobody@example.com") - # Returns dictionary or None - # Raises MultipleResultsFoundError if multiple results +.. literalinclude:: /examples/usage/test_drivers_and_querying_14.py + :language: python + :lines: 36-38 + :dedent: 2 + :caption: `select_one_or_none` select_value() ^^^^^^^^^^^^^^ Execute a SELECT query returning a single scalar value. -.. code-block:: python - - count = session.select_value("SELECT COUNT(*) FROM users") - # Returns: 42 - - latest_id = session.select_value("SELECT MAX(id) FROM users") - # Returns: 100 +.. literalinclude:: /examples/usage/test_drivers_and_querying_14.py + :language: python + :lines: 39-42 + :dedent: 2 + :caption: `select_value` Working with Results -------------------- From 058b7daa549f991a32af1054d5e1954f035a7608 Mon Sep 17 00:00:00 2001 From: euri10 Date: Tue, 11 Nov 2025 17:12:29 +0100 Subject: [PATCH 8/8] removed hardcoded lines and replaced with comments --- ...g_1.py => usage_drivers_and_querying_1.py} | 2 + ...10.py => usage_drivers_and_querying_10.py} | 2 + ...11.py => usage_drivers_and_querying_11.py} | 2 + ...12.py => usage_drivers_and_querying_12.py} | 2 + ...13.py => usage_drivers_and_querying_13.py} | 2 + ...14.py => usage_drivers_and_querying_14.py} | 3 +- ...15.py => usage_drivers_and_querying_15.py} | 0 ...16.py => usage_drivers_and_querying_16.py} | 0 ...17.py => usage_drivers_and_querying_17.py} | 0 ...18.py => usage_drivers_and_querying_18.py} | 0 ...19.py => usage_drivers_and_querying_19.py} | 0 ...g_2.py => usage_drivers_and_querying_2.py} | 2 + ...20.py => usage_drivers_and_querying_20.py} | 0 ...21.py => usage_drivers_and_querying_21.py} | 0 ...22.py => usage_drivers_and_querying_22.py} | 0 ...23.py => usage_drivers_and_querying_23.py} | 0 ...24.py => usage_drivers_and_querying_24.py} | 0 ...25.py => usage_drivers_and_querying_25.py} | 0 ...26.py => usage_drivers_and_querying_26.py} | 0 ...27.py => usage_drivers_and_querying_27.py} | 0 ...28.py => usage_drivers_and_querying_28.py} | 0 ...g_3.py => usage_drivers_and_querying_3.py} | 0 ...g_4.py => usage_drivers_and_querying_4.py} | 0 ...g_5.py => usage_drivers_and_querying_5.py} | 0 ...g_6.py => usage_drivers_and_querying_6.py} | 0 ...g_7.py => usage_drivers_and_querying_7.py} | 0 ...g_8.py => usage_drivers_and_querying_8.py} | 0 ...g_9.py => usage_drivers_and_querying_9.py} | 0 docs/usage/drivers_and_querying.rst | 105 ++++++++++-------- 29 files changed, 71 insertions(+), 49 deletions(-) rename docs/examples/usage/{test_drivers_and_querying_1.py => usage_drivers_and_querying_1.py} (96%) rename docs/examples/usage/{test_drivers_and_querying_10.py => usage_drivers_and_querying_10.py} (96%) rename docs/examples/usage/{test_drivers_and_querying_11.py => usage_drivers_and_querying_11.py} (96%) rename docs/examples/usage/{test_drivers_and_querying_12.py => usage_drivers_and_querying_12.py} (97%) rename docs/examples/usage/{test_drivers_and_querying_13.py => usage_drivers_and_querying_13.py} (96%) rename docs/examples/usage/{test_drivers_and_querying_14.py => usage_drivers_and_querying_14.py} (98%) rename docs/examples/usage/{test_drivers_and_querying_15.py => usage_drivers_and_querying_15.py} (100%) rename docs/examples/usage/{test_drivers_and_querying_16.py => usage_drivers_and_querying_16.py} (100%) rename docs/examples/usage/{test_drivers_and_querying_17.py => usage_drivers_and_querying_17.py} (100%) rename docs/examples/usage/{test_drivers_and_querying_18.py => usage_drivers_and_querying_18.py} (100%) rename docs/examples/usage/{test_drivers_and_querying_19.py => usage_drivers_and_querying_19.py} (100%) rename docs/examples/usage/{test_drivers_and_querying_2.py => usage_drivers_and_querying_2.py} (97%) rename docs/examples/usage/{test_drivers_and_querying_20.py => usage_drivers_and_querying_20.py} (100%) rename docs/examples/usage/{test_drivers_and_querying_21.py => usage_drivers_and_querying_21.py} (100%) rename docs/examples/usage/{test_drivers_and_querying_22.py => usage_drivers_and_querying_22.py} (100%) rename docs/examples/usage/{test_drivers_and_querying_23.py => usage_drivers_and_querying_23.py} (100%) rename docs/examples/usage/{test_drivers_and_querying_24.py => usage_drivers_and_querying_24.py} (100%) rename docs/examples/usage/{test_drivers_and_querying_25.py => usage_drivers_and_querying_25.py} (100%) rename docs/examples/usage/{test_drivers_and_querying_26.py => usage_drivers_and_querying_26.py} (100%) rename docs/examples/usage/{test_drivers_and_querying_27.py => usage_drivers_and_querying_27.py} (100%) rename docs/examples/usage/{test_drivers_and_querying_28.py => usage_drivers_and_querying_28.py} (100%) rename docs/examples/usage/{test_drivers_and_querying_3.py => usage_drivers_and_querying_3.py} (100%) rename docs/examples/usage/{test_drivers_and_querying_4.py => usage_drivers_and_querying_4.py} (100%) rename docs/examples/usage/{test_drivers_and_querying_5.py => usage_drivers_and_querying_5.py} (100%) rename docs/examples/usage/{test_drivers_and_querying_6.py => usage_drivers_and_querying_6.py} (100%) rename docs/examples/usage/{test_drivers_and_querying_7.py => usage_drivers_and_querying_7.py} (100%) rename docs/examples/usage/{test_drivers_and_querying_8.py => usage_drivers_and_querying_8.py} (100%) rename docs/examples/usage/{test_drivers_and_querying_9.py => usage_drivers_and_querying_9.py} (100%) diff --git a/docs/examples/usage/test_drivers_and_querying_1.py b/docs/examples/usage/usage_drivers_and_querying_1.py similarity index 96% rename from docs/examples/usage/test_drivers_and_querying_1.py rename to docs/examples/usage/usage_drivers_and_querying_1.py index 033581d9..ce661ff8 100644 --- a/docs/examples/usage/test_drivers_and_querying_1.py +++ b/docs/examples/usage/usage_drivers_and_querying_1.py @@ -5,6 +5,7 @@ async def test_importable_1(postgres_service: PostgresService) -> None: + # start-example from sqlspec import SQLSpec from sqlspec.adapters.asyncpg import AsyncpgConfig, AsyncpgPoolConfig @@ -23,3 +24,4 @@ async def test_importable_1(postgres_service: PostgresService) -> None: ) # Config layer, registers pool async with spec.provide_session(db) as session: # Session layer await session.execute("SELECT 1") # Driver layer + # end-example diff --git a/docs/examples/usage/test_drivers_and_querying_10.py b/docs/examples/usage/usage_drivers_and_querying_10.py similarity index 96% rename from docs/examples/usage/test_drivers_and_querying_10.py rename to docs/examples/usage/usage_drivers_and_querying_10.py index a04c60e4..30d68df5 100644 --- a/docs/examples/usage/test_drivers_and_querying_10.py +++ b/docs/examples/usage/usage_drivers_and_querying_10.py @@ -5,6 +5,7 @@ def test_example_10_duckdb_config() -> None: + # start-example from sqlspec import SQLSpec from sqlspec.adapters.duckdb import DuckDBConfig @@ -30,3 +31,4 @@ def test_example_10_duckdb_config() -> None: GROUP BY day ORDER BY day """) + # end-example diff --git a/docs/examples/usage/test_drivers_and_querying_11.py b/docs/examples/usage/usage_drivers_and_querying_11.py similarity index 96% rename from docs/examples/usage/test_drivers_and_querying_11.py rename to docs/examples/usage/usage_drivers_and_querying_11.py index 5eca661a..9a7cbd99 100644 --- a/docs/examples/usage/test_drivers_and_querying_11.py +++ b/docs/examples/usage/usage_drivers_and_querying_11.py @@ -5,6 +5,7 @@ def test_example_11_oracledb_config(oracle_service: OracleService) -> None: + # start-example from sqlspec import SQLSpec from sqlspec.adapters.oracledb import OracleSyncConfig @@ -31,3 +32,4 @@ def test_example_11_oracledb_config(oracle_service: OracleService) -> None: """) session.execute("SELECT * FROM employees WHERE employee_id = :id", id=100) + # end-example diff --git a/docs/examples/usage/test_drivers_and_querying_12.py b/docs/examples/usage/usage_drivers_and_querying_12.py similarity index 97% rename from docs/examples/usage/test_drivers_and_querying_12.py rename to docs/examples/usage/usage_drivers_and_querying_12.py index 54294802..878afd85 100644 --- a/docs/examples/usage/test_drivers_and_querying_12.py +++ b/docs/examples/usage/usage_drivers_and_querying_12.py @@ -5,6 +5,7 @@ def test_example_12_bigquery_config(bigquery_service: BigQueryDriver) -> None: + # start-example import datetime from google.api_core.client_options import ClientOptions @@ -46,3 +47,4 @@ def test_example_12_bigquery_config(bigquery_service: BigQueryDriver) -> None: """, start_date=datetime.date(2025, 1, 1), ) + # end-example diff --git a/docs/examples/usage/test_drivers_and_querying_13.py b/docs/examples/usage/usage_drivers_and_querying_13.py similarity index 96% rename from docs/examples/usage/test_drivers_and_querying_13.py rename to docs/examples/usage/usage_drivers_and_querying_13.py index 8da583d6..e1d77ce1 100644 --- a/docs/examples/usage/test_drivers_and_querying_13.py +++ b/docs/examples/usage/usage_drivers_and_querying_13.py @@ -3,6 +3,7 @@ def test_example_13_placeholder() -> None: + # start-example from sqlspec import SQLSpec from sqlspec.adapters.sqlite import SqliteConfig @@ -26,3 +27,4 @@ def test_example_13_placeholder() -> None: # DELETE query result = session.execute("DELETE FROM users WHERE id = ?", 1) + # end-example diff --git a/docs/examples/usage/test_drivers_and_querying_14.py b/docs/examples/usage/usage_drivers_and_querying_14.py similarity index 98% rename from docs/examples/usage/test_drivers_and_querying_14.py rename to docs/examples/usage/usage_drivers_and_querying_14.py index b9cb8d2c..5d8120bc 100644 --- a/docs/examples/usage/test_drivers_and_querying_14.py +++ b/docs/examples/usage/usage_drivers_and_querying_14.py @@ -4,6 +4,7 @@ def test_example_14_placeholder() -> None: + # start-example from sqlspec import SQLSpec from sqlspec.adapters.sqlite import SqliteConfig @@ -54,4 +55,4 @@ def test_example_14_placeholder() -> None: user = result.one_or_none() # Single row or None with pytest.raises(ValueError): value = result.scalar() # First column of first row - + # end-example diff --git a/docs/examples/usage/test_drivers_and_querying_15.py b/docs/examples/usage/usage_drivers_and_querying_15.py similarity index 100% rename from docs/examples/usage/test_drivers_and_querying_15.py rename to docs/examples/usage/usage_drivers_and_querying_15.py diff --git a/docs/examples/usage/test_drivers_and_querying_16.py b/docs/examples/usage/usage_drivers_and_querying_16.py similarity index 100% rename from docs/examples/usage/test_drivers_and_querying_16.py rename to docs/examples/usage/usage_drivers_and_querying_16.py diff --git a/docs/examples/usage/test_drivers_and_querying_17.py b/docs/examples/usage/usage_drivers_and_querying_17.py similarity index 100% rename from docs/examples/usage/test_drivers_and_querying_17.py rename to docs/examples/usage/usage_drivers_and_querying_17.py diff --git a/docs/examples/usage/test_drivers_and_querying_18.py b/docs/examples/usage/usage_drivers_and_querying_18.py similarity index 100% rename from docs/examples/usage/test_drivers_and_querying_18.py rename to docs/examples/usage/usage_drivers_and_querying_18.py diff --git a/docs/examples/usage/test_drivers_and_querying_19.py b/docs/examples/usage/usage_drivers_and_querying_19.py similarity index 100% rename from docs/examples/usage/test_drivers_and_querying_19.py rename to docs/examples/usage/usage_drivers_and_querying_19.py diff --git a/docs/examples/usage/test_drivers_and_querying_2.py b/docs/examples/usage/usage_drivers_and_querying_2.py similarity index 97% rename from docs/examples/usage/test_drivers_and_querying_2.py rename to docs/examples/usage/usage_drivers_and_querying_2.py index aaaa0cca..d7c5be05 100644 --- a/docs/examples/usage/test_drivers_and_querying_2.py +++ b/docs/examples/usage/usage_drivers_and_querying_2.py @@ -5,6 +5,7 @@ async def test_example_2_importable(postgres_service: PostgresService) -> None: + # start-example from sqlspec import SQLSpec from sqlspec.adapters.asyncpg import AsyncpgConfig @@ -37,3 +38,4 @@ async def test_example_2_importable(postgres_service: PostgresService) -> None: result = await session.execute("SELECT * FROM users WHERE id = $1", 1) user = result.one() print(f"User: {user}") + # end-example diff --git a/docs/examples/usage/test_drivers_and_querying_20.py b/docs/examples/usage/usage_drivers_and_querying_20.py similarity index 100% rename from docs/examples/usage/test_drivers_and_querying_20.py rename to docs/examples/usage/usage_drivers_and_querying_20.py diff --git a/docs/examples/usage/test_drivers_and_querying_21.py b/docs/examples/usage/usage_drivers_and_querying_21.py similarity index 100% rename from docs/examples/usage/test_drivers_and_querying_21.py rename to docs/examples/usage/usage_drivers_and_querying_21.py diff --git a/docs/examples/usage/test_drivers_and_querying_22.py b/docs/examples/usage/usage_drivers_and_querying_22.py similarity index 100% rename from docs/examples/usage/test_drivers_and_querying_22.py rename to docs/examples/usage/usage_drivers_and_querying_22.py diff --git a/docs/examples/usage/test_drivers_and_querying_23.py b/docs/examples/usage/usage_drivers_and_querying_23.py similarity index 100% rename from docs/examples/usage/test_drivers_and_querying_23.py rename to docs/examples/usage/usage_drivers_and_querying_23.py diff --git a/docs/examples/usage/test_drivers_and_querying_24.py b/docs/examples/usage/usage_drivers_and_querying_24.py similarity index 100% rename from docs/examples/usage/test_drivers_and_querying_24.py rename to docs/examples/usage/usage_drivers_and_querying_24.py diff --git a/docs/examples/usage/test_drivers_and_querying_25.py b/docs/examples/usage/usage_drivers_and_querying_25.py similarity index 100% rename from docs/examples/usage/test_drivers_and_querying_25.py rename to docs/examples/usage/usage_drivers_and_querying_25.py diff --git a/docs/examples/usage/test_drivers_and_querying_26.py b/docs/examples/usage/usage_drivers_and_querying_26.py similarity index 100% rename from docs/examples/usage/test_drivers_and_querying_26.py rename to docs/examples/usage/usage_drivers_and_querying_26.py diff --git a/docs/examples/usage/test_drivers_and_querying_27.py b/docs/examples/usage/usage_drivers_and_querying_27.py similarity index 100% rename from docs/examples/usage/test_drivers_and_querying_27.py rename to docs/examples/usage/usage_drivers_and_querying_27.py diff --git a/docs/examples/usage/test_drivers_and_querying_28.py b/docs/examples/usage/usage_drivers_and_querying_28.py similarity index 100% rename from docs/examples/usage/test_drivers_and_querying_28.py rename to docs/examples/usage/usage_drivers_and_querying_28.py diff --git a/docs/examples/usage/test_drivers_and_querying_3.py b/docs/examples/usage/usage_drivers_and_querying_3.py similarity index 100% rename from docs/examples/usage/test_drivers_and_querying_3.py rename to docs/examples/usage/usage_drivers_and_querying_3.py diff --git a/docs/examples/usage/test_drivers_and_querying_4.py b/docs/examples/usage/usage_drivers_and_querying_4.py similarity index 100% rename from docs/examples/usage/test_drivers_and_querying_4.py rename to docs/examples/usage/usage_drivers_and_querying_4.py diff --git a/docs/examples/usage/test_drivers_and_querying_5.py b/docs/examples/usage/usage_drivers_and_querying_5.py similarity index 100% rename from docs/examples/usage/test_drivers_and_querying_5.py rename to docs/examples/usage/usage_drivers_and_querying_5.py diff --git a/docs/examples/usage/test_drivers_and_querying_6.py b/docs/examples/usage/usage_drivers_and_querying_6.py similarity index 100% rename from docs/examples/usage/test_drivers_and_querying_6.py rename to docs/examples/usage/usage_drivers_and_querying_6.py diff --git a/docs/examples/usage/test_drivers_and_querying_7.py b/docs/examples/usage/usage_drivers_and_querying_7.py similarity index 100% rename from docs/examples/usage/test_drivers_and_querying_7.py rename to docs/examples/usage/usage_drivers_and_querying_7.py diff --git a/docs/examples/usage/test_drivers_and_querying_8.py b/docs/examples/usage/usage_drivers_and_querying_8.py similarity index 100% rename from docs/examples/usage/test_drivers_and_querying_8.py rename to docs/examples/usage/usage_drivers_and_querying_8.py diff --git a/docs/examples/usage/test_drivers_and_querying_9.py b/docs/examples/usage/usage_drivers_and_querying_9.py similarity index 100% rename from docs/examples/usage/test_drivers_and_querying_9.py rename to docs/examples/usage/usage_drivers_and_querying_9.py diff --git a/docs/usage/drivers_and_querying.rst b/docs/usage/drivers_and_querying.rst index cf7d6875..6e65262a 100644 --- a/docs/usage/drivers_and_querying.rst +++ b/docs/usage/drivers_and_querying.rst @@ -51,9 +51,10 @@ SQLSpec drivers follow a layered architecture: 3. **Driver Layer**: Query execution and result handling 4. **Session Layer**: Transaction management -.. literalinclude:: /examples/usage/test_drivers_and_querying_1.py +.. literalinclude:: /examples/usage/usage_drivers_and_querying_1.py :language: python - :lines: 8-25 + :start-after: # start-example + :end-before: # end-example :dedent: 2 :caption: `driver architecture` @@ -65,9 +66,10 @@ asyncpg (Recommended for Async) Async PostgreSQL driver with native connection pooling. -.. literalinclude:: /examples/usage/test_drivers_and_querying_2.py +.. literalinclude:: /examples/usage/usage_drivers_and_querying_2.py :language: python - :lines: 8-39 + :start-after: # start-example + :end-before: # end-example :dedent: 2 :caption: `asyncpg` @@ -88,17 +90,19 @@ Official PostgreSQL adapter with both sync and async support. .. tab-item:: Sync - .. literalinclude:: /examples/usage/test_drivers_and_querying_3.py + .. literalinclude:: /examples/usage/usage_drivers_and_querying_3.py :language: python - :lines: 8-32 + :start-after: # start-example + :end-before: # end-example :dedent: 2 :caption: `psycopg sync` .. tab-item:: Async - .. literalinclude:: /examples/usage/test_drivers_and_querying_4.py + .. literalinclude:: /examples/usage/usage_drivers_and_querying_4.py :language: python - :lines: 8-34 + :start-after: # start-example + :end-before: # end-example :dedent: 2 :caption: `psycopg async` @@ -115,9 +119,10 @@ psqlpy (High Performance Async) Rust-based async PostgreSQL driver for maximum performance. -.. literalinclude:: /examples/usage/test_drivers_and_querying_5.py +.. literalinclude:: /examples/usage/usage_drivers_and_querying_5.py :language: python - :lines: 11-29 + :start-after: # start-example + :end-before: # end-example :dedent: 2 :caption: `psqlpy` @@ -135,15 +140,17 @@ sqlite3 (Synchronous) Python's built-in SQLite adapter. -.. literalinclude:: /examples/usage/test_drivers_and_querying_6.py +.. literalinclude:: /examples/usage/usage_drivers_and_querying_6.py :language: python - :lines: 8-27 + :start-after: # start-example + :end-before: # end-example :dedent: 2 :caption: `sqlite config` -.. literalinclude:: /examples/usage/test_drivers_and_querying_7.py +.. literalinclude:: /examples/usage/usage_drivers_and_querying_7.py :language: python - :lines: 6-9 + :start-after: # start-example + :end-before: # end-example :dedent: 2 :caption: `sqlite` @@ -159,9 +166,10 @@ aiosqlite (Asynchronous) Async wrapper around sqlite3. -.. literalinclude:: /examples/usage/test_drivers_and_querying_8.py +.. literalinclude:: /examples/usage/usage_drivers_and_querying_8.py :language: python - :lines: 6-19 + :start-after: # start-example + :end-before: # end-example :dedent: 2 :caption: `aiosqlite` @@ -179,9 +187,10 @@ asyncmy (Asynchronous) Pure Python async MySQL/MariaDB driver. -.. literalinclude:: /examples/usage/test_drivers_and_querying_9.py +.. literalinclude:: /examples/usage/usage_drivers_and_querying_9.py :language: python - :lines: 8-37 + :start-after: # start-example + :end-before: # end-example :dedent: 2 :caption: `asyncmy` @@ -200,9 +209,10 @@ DuckDB (Analytical Database) In-process analytical database optimized for OLAP workloads. -.. literalinclude:: /examples/usage/test_drivers_and_querying_10.py +.. literalinclude:: /examples/usage/usage_drivers_and_querying_10.py :language: python - :lines: 8-32 + :start-after: # start-example + :end-before: # end-example :dedent: 2 :caption: `duckdb` @@ -218,9 +228,10 @@ Oracle Database Oracle database support with python-oracledb. -.. literalinclude:: /examples/usage/test_drivers_and_querying_11.py +.. literalinclude:: /examples/usage/usage_drivers_and_querying_11.py :language: python - :lines: 8-33 + :start-after: # start-example + :end-before: # end-example :dedent: 2 :caption: `oracle` @@ -273,9 +284,10 @@ execute() Execute any SQL statement and return results. -.. literalinclude:: /examples/usage/test_drivers_and_querying_13.py +.. literalinclude:: /examples/usage/usage_drivers_and_querying_13.py :language: python - :lines: 9-28 + :start-after: # start-example + :end-before: # end-example :dedent: 2 :caption: `execute` @@ -284,9 +296,10 @@ execute_many() Execute a statement with multiple parameter sets (batch insert/update). -.. literalinclude:: /examples/usage/test_drivers_and_querying_14.py +.. literalinclude:: /examples/usage/usage_drivers_and_querying_14.py :language: python - :lines: 6-27 + :start-after: # start-example-1 + :end-before: # end-example-1 :dedent: 2 :caption: `execute_many` @@ -296,9 +309,10 @@ select() Execute a SELECT query and return all rows. -.. literalinclude:: /examples/usage/test_drivers_and_querying_14.py +.. literalinclude:: /examples/usage/usage_drivers_and_querying_14.py :language: python - :lines: 28-30 + :start-after: # start-example-2 + :end-before: # end-example-2 :dedent: 4 :caption: `select` @@ -307,9 +321,10 @@ select_one() Execute a SELECT query expecting exactly one result. -.. literalinclude:: /examples/usage/test_drivers_and_querying_14.py +.. literalinclude:: /examples/usage/usage_drivers_and_querying_14.py :language: python - :lines: 31-35 + :start-after: # start-example-3 + :end-before: # end-example-3 :dedent: 2 :caption: `select_one` @@ -318,9 +333,10 @@ select_one_or_none() Execute a SELECT query returning one or no results. -.. literalinclude:: /examples/usage/test_drivers_and_querying_14.py +.. literalinclude:: /examples/usage/usage_drivers_and_querying_14.py :language: python - :lines: 36-38 + :start-after: # start-example-4 + :end-before: # end-example-4 :dedent: 2 :caption: `select_one_or_none` @@ -329,9 +345,10 @@ select_value() Execute a SELECT query returning a single scalar value. -.. literalinclude:: /examples/usage/test_drivers_and_querying_14.py +.. literalinclude:: /examples/usage/usage_drivers_and_querying_14.py :language: python - :lines: 39-42 + :start-after: # start-example-5 + :end-before: # end-example-5 :dedent: 2 :caption: `select_value` @@ -343,20 +360,12 @@ SQLResult Object All queries return a ``SQLResult`` object with rich result information. -.. code-block:: python - - result = session.execute("SELECT id, name, email FROM users") - - # Access raw data - result.data # List of dictionaries - result.column_names # ["id", "name", "email"] - result.rows_affected # For INSERT/UPDATE/DELETE - result.operation_type # "SELECT", "INSERT", etc. - - # Convenience methods - user = result.one() # Single row (raises if not exactly 1) - user = result.one_or_none() # Single row or None - value = result.scalar() # First column of first row +.. literalinclude:: /examples/usage/usage_drivers_and_querying_14.py + :language: python + :start-after: # start-example-6 + :end-before: # end-example-6 + :dedent: 2 + :caption: `SQLResult object` Iterating Results ^^^^^^^^^^^^^^^^^