docs: test ./usage/index.rst

docs/examples/usage/test_index_1.py

@@ -0,0 +1,20 @@
+from sqlspec import SQLSpec
+from sqlspec.adapters.sqlite import SqliteConfig
+
+spec = SQLSpec()
+db = spec.add_config(SqliteConfig())
+with spec.provide_session(db) as session:
+    _ = session.execute("""
+    CREATE TABLE users (
+        id INTEGER PRIMARY KEY,
+        name TEXT NOT NULL
+    )
+    """)
+    _ = session.execute("""INSERT INTO users VALUES (1, 'alice')""")
+with spec.provide_session(db) as session:
+    result = session.execute("SELECT * FROM users WHERE id = ?", 1)
+    user = result.one()
+
+
+def test_index_1() -> None:
+    assert user is not None

docs/examples/usage/test_index_2.py

@@ -0,0 +1,25 @@
+from sqlspec import SQLSpec, sql
+from sqlspec.adapters.sqlite import SqliteConfig
+
+spec = SQLSpec()
+db = spec.add_config(SqliteConfig())
+with spec.provide_session(db) as session:
+    _ = session.execute("""
+    CREATE TABLE users (
+        id INTEGER PRIMARY KEY,
+        name TEXT NOT NULL,
+        email TEXT,
+        active BOOLEAN NOT NULL DEFAULT 1
+    )
+    """)
+    _ = session.execute("""INSERT INTO users VALUES (1, 'alice', 'alice@example.com', 1),
+                           (2, 'bob', 'bob@example.com', 0),
+                           (3, 'carol', 'carol@examplecom', 1)""")
+
+query = sql.select("id", "name", "email").from_("users").where("active = ?")
+result = session.execute(query, True)  # noqa: FBT003
+users = result.all()
+
+
+def test_index_2() -> None:
+    assert len(users) > 0

docs/examples/usage/test_index_3.py

@@ -0,0 +1,36 @@
+from pathlib import Path
+
+from sqlspec import SQLSpec
+from sqlspec.adapters.sqlite import SqliteConfig
+from sqlspec.loader import SQLFileLoader
+
+spec = SQLSpec()
+db = spec.add_config(SqliteConfig())
+
+with spec.provide_session(db) as session:
+    _ = session.execute("""
+    CREATE TABLE users (
+        id INTEGER PRIMARY KEY,
+        username TEXT NOT NULL,
+        email TEXT,
+        active BOOLEAN NOT NULL DEFAULT 1,
+        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+        updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+    )
+    """)
+    _ = session.execute("""INSERT INTO users(id, username, email, active) VALUES (1, 'alice', 'alice
+@example.com', 1),
+                           (2, 'bob', 'bob@example.com', 0),
+                           (3, 'carol', 'carol@examplecom', 1)""")
+
+
+p = Path(__file__).parent.parent / "queries/users.sql"
+loader = SQLFileLoader()
+loader.load_sql(p)
+
+user_query = loader.get_sql("get_user_by_id")
+result = session.execute(user_query, user_id=2)
+
+
+def test_index_3() -> None:
+    assert result is not None

docs/usage/index.rst

@@ -51,39 +51,24 @@ Quick Reference
 
 **Basic Query Execution**
 
-.. code-block:: python
-
-   from sqlspec import SQLSpec
-   from sqlspec.adapters.sqlite import SqliteConfig
-
-   spec = SQLSpec()
-   db = spec.add_config(SqliteConfig())
-
-   with spec.provide_session(db) as session:
-       result = session.execute("SELECT * FROM users WHERE id = ?", 1)
-       user = result.one()
+.. literalinclude:: /examples/usage/test_index_1.py
+   :language: python
+   :caption: ``basic query execution``
+   :lines: 1-5,14-16
 
 **Using the Query Builder**
 
-.. code-block:: python
-
-   from sqlspec import sql
-
-   query = sql.select("id", "name", "email").from_("users").where("active = ?")
-   result = session.execute(query, True)
-   users = result.all()
+.. literalinclude:: /examples/usage/test_index_2.py
+   :language: python
+   :caption: ``using the query builder``
+   :lines: 1-5,19-21
 
 **Loading from SQL Files**
 
-.. code-block:: python
-
-   from sqlspec.loader import SQLFileLoader
-
-   loader = SQLFileLoader()
-   loader.load_sql("queries/users.sql")
-
-   user_query = loader.get_sql("get_user_by_id", user_id=123)
-   result = session.execute(user_query)
+.. literalinclude:: /examples/usage/test_index_3.py
+   :language: python
+   :caption: ``loading from sql files``
+   :lines: 1-8,27-32
 
 Next Steps
 ----------

pyproject.toml

@@ -322,7 +322,7 @@ markers = [
   "pymysql: marks tests using pymysql",
   "psqlpy: marks tests using psqlpy",
 ]
-testpaths = ["tests"]
+testpaths = ["tests", "docs/examples/usage"]
 
 [tool.mypy]
 exclude = ["tmp/", ".tmp/", ".bugs/"]