docs: cleanup examples (#151)

Refactor and improve various documentation examples for clarity and organization, ensuring they effectively demonstrate SQLSpec features and integrations. Update example paths and configurations for better usability.

Author: cofin

.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
       - id: mixed-line-ending
       - id: trailing-whitespace
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.14.1"
+    rev: "v0.14.2"
     hooks:
       - id: ruff
         args: ["--fix"]

docs/examples/README.md

@@ -0,0 +1,29 @@
+# SQLSpec Example Catalog
+
+This directory now mirrors the way developers explore SQLSpec:
+
+- `shared/` contains reusable helpers for configs and demo datasets.
+- `frameworks/` groups runnable apps (Litestar for now) that rely on lightweight backends (aiosqlite, duckdb).
+- `adapters/` holds connection-focused snippets for production drivers such as asyncpg, psycopg, and oracledb.
+- `patterns/` demonstrates SQL builder usage, migrations, and multi-tenant routing.
+- `loaders/` shows how to hydrate SQL from files for quick demos.
+- `extensions/` keeps integration-specific samples (Adapter Development Kit in this pass).
+
+All scripts keep to a single entry point and stay under 75 lines so they are easy to read and embed directly into docs. Inline comments are avoided per the project standards; docstrings explain the scenario instead.
+
+## Ruff configuration
+
+`pyproject.toml` now scopes two Ruff ignore codes to `docs/examples/**/*.py`:
+
+- `T201` – Allow `print()` calls in CLI-oriented examples.
+- `INP001` – Ignore namespace-package warnings because these files intentionally live in a flat docs tree.
+
+This keeps the rest of the rule set active, so examples remain formatted and type-safe without sprinkling `# noqa` markers.
+
+## Running the smoke suite
+
+```
+make examples-smoke
+```
+
+The smoke target imports SQLite/AioSQLite/DuckDB demos (the adapters that do not need external services) via `docs/examples/run_smoke.py`. Adapter-specific files that expect a database simply print instructions rather than failing the run.

docs/examples/__init__.py

@@ -0,0 +1 @@
+"""Namespace package for runnable SQLSpec documentation examples."""

docs/examples/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapter-specific SQLSpec usage snippets."""

docs/examples/adapters/asyncpg/__init__.py

@@ -0,0 +1 @@
+"""AsyncPG connection-focused examples."""

docs/examples/adapters/asyncpg/connect_pool.py

@@ -0,0 +1,27 @@
+"""AsyncPG connection pool configured through SQLSpec."""
+
+import asyncio
+import os
+
+from sqlspec.adapters.asyncpg import AsyncpgConfig, AsyncpgPoolConfig
+
+__all__ = ("main",)
+
+
+DSN = os.getenv("SQLSPEC_ASYNCPG_DSN", "postgresql://postgres:postgres@localhost:5432/postgres")
+config = AsyncpgConfig(bind_key="docs_asyncpg", pool_config=AsyncpgPoolConfig(dsn=DSN, min_size=1, max_size=5))
+
+
+async def main() -> None:
+    """Connect to Postgres and return the server version."""
+    async with config.provide_session() as session:
+        result = await session.execute("SELECT version() AS version")
+        row = result.one_or_none()
+        if row:
+            print({"adapter": "asyncpg", "version": row["version"]})
+        else:
+            print({"adapter": "asyncpg", "version": "unknown"})
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

docs/examples/adapters/asyncpg/connect_pool.rst

@@ -0,0 +1,18 @@
+AsyncPG Connection Pool
+=======================
+
+Configure SQLSpec with the AsyncPG adapter and verify the server version. The DSN defaults to
+``postgresql://postgres:postgres@localhost:5432/postgres`` and can be overridden via the
+``SQLSPEC_ASYNCPG_DSN`` environment variable.
+
+.. code-block:: console
+
+   SQLSPEC_ASYNCPG_DSN=postgresql://user:pass@host/db \
+     uv run python docs/examples/adapters/asyncpg/connect_pool.py
+
+Source
+------
+
+.. literalinclude:: connect_pool.py
+   :language: python
+   :linenos:

docs/examples/adapters/oracledb/__init__.py

@@ -0,0 +1 @@
+"""oracledb adapter examples."""

docs/examples/adapters/oracledb/connect_async.py

@@ -0,0 +1,30 @@
+"""Async Oracle connection powered by SQLSpec."""
+
+import asyncio
+import os
+
+from sqlspec.adapters.oracledb import OracleAsyncConfig
+
+__all__ = ("main",)
+
+
+USER = os.getenv("SQLSPEC_ORACLE_USER", "system")
+PASSWORD = os.getenv("SQLSPEC_ORACLE_PASSWORD", "oracle")
+DSN = os.getenv("SQLSPEC_ORACLE_DSN", "localhost/FREE")
+config = OracleAsyncConfig(
+    bind_key="docs_oracle_async", pool_config={"user": USER, "password": PASSWORD, "dsn": DSN, "min": 1, "max": 4}
+)
+
+
+async def main() -> None:
+    """Connect to Oracle and print the current timestamp."""
+    async with config.provide_session() as session:
+        result = await session.select_one_or_none("SELECT systimestamp AS ts FROM dual")
+        if result:
+            print({"adapter": "oracledb", "timestamp": str(result["ts"])})
+        else:
+            print({"adapter": "oracledb", "timestamp": "unknown"})
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

docs/examples/adapters/oracledb/connect_async.rst

@@ -0,0 +1,17 @@
+Oracle Async Connection
+=======================
+
+Use SQLSpec's async Oracle adapter to fetch the current timestamp. Override credentials with
+``SQLSPEC_ORACLE_USER``, ``SQLSPEC_ORACLE_PASSWORD``, and ``SQLSPEC_ORACLE_DSN``.
+
+.. code-block:: console
+
+   SQLSPEC_ORACLE_USER=system SQLSPEC_ORACLE_PASSWORD=oracle SQLSPEC_ORACLE_DSN=localhost/FREE \
+     uv run python docs/examples/adapters/oracledb/connect_async.py
+
+Source
+------
+
+.. literalinclude:: connect_async.py
+   :language: python
+   :linenos: