sqlspec 0.9.0__py3-none-any.whl → 0.9.1__py3-none-any.whl

{sqlspec-0.9.0.dist-info → sqlspec-0.9.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlspec
-Version: 0.9.0
+Version: 0.9.1
 Summary: SQL Experiments in Python
 Author-email: Cody Fincher <cody@litestar.dev>
 Maintainer-email: Litestar Developers <hello@litestar.dev>
@@ -83,6 +83,145 @@ SQLSpec is an experimental Python library designed to streamline and modernize y
 
 SQLSpec is a work in progress. While it offers a solid foundation for modern SQL interactions, it does not yet include every feature you might find in a mature ORM or database toolkit. The focus is on building a robust, flexible core that can be extended over time.
 
+## Examples
+
+We've talked about what SQLSpec is not, so let's look at what it can do.
+
+These are just a few of the examples that demonstrate SQLSpec's flexibility and each of the bundled adapters offer the same config and driver interfaces.
+
+### DuckDB LLM
+
+This is a quick implementation using some of the built in Secret and Extension management features of SQLSpec's DuckDB integration.
+
+It allows you to communicate with any compatible OpenAPI conversations endpoint (such as Ollama).  This examples:
+
+- auto installs the `open_prompt` DuckDB extensions
+- automatically creates the correct `open_prompt` comptaible secret required to use the extension
+
+```py
+# /// script
+# dependencies = [
+#   "sqlspec[duckdb,performance]",
+# ]
+# ///
+import os
+
+from sqlspec import SQLSpec
+from sqlspec.adapters.duckdb import DuckDBConfig
+from pydantic import BaseModel
+
+class ChatMessage(BaseModel):
+    message: str
+
+sql = SQLSpec()
+etl_config = sql.add_config(
+    DuckDBConfig(
+        extensions=[{"name": "open_prompt"}],
+        secrets=[
+            {
+                "secret_type": "open_prompt",
+                "name": "open_prompt",
+                "value": {
+                    "api_url": "http://127.0.0.1:11434/v1/chat/completions",
+                    "model_name": "gemma3:1b",
+                    "api_timeout": "120",
+                },
+            }
+        ],
+    )
+)
+with sql.provide_session(etl_config) as session:
+    result = session.select_one("SELECT open_prompt(?)", data.message, schema_type=ChatMessage)
+    print(result) # result is a ChatMessage pydantic model
+```
+
+### DuckDB Gemini Embeddings
+
+In this example, we are again using DuckDB.  However, we are going to use the built in to call the Google Gemini embeddings service directly from the database.
+
+This example will
+
+- auto installs the `http_client` and `vss` (vector similarity search) DuckDB extensions
+- when a connection is created, it ensures that the `generate_embeddings` macro exists in the DuckDB database.
+- Execute a simple query to call the Google API
+
+```py
+# /// script
+# dependencies = [
+#   "sqlspec[duckdb,performance]",
+# ]
+# ///
+import os
+
+from sqlspec import SQLSpec
+from sqlspec.adapters.duckdb import DuckDBConfig
+
+EMBEDDING_MODEL = "gemini-embedding-exp-03-07"
+GOOGLE_API_KEY = os.environ.get("GOOGLE_API_KEY")
+API_URL = (
+    f"https://generativelanguage.googleapis.com/v1beta/models/{EMBEDDING_MODEL}:embedContent?key=${GOOGLE_API_KEY}"
+)
+
+sql = SQLSpec()
+etl_config = sql.add_config(
+    DuckDBConfig(
+        extensions=[{"name": "vss"}, {"name": "http_client"}],
+        on_connection_create=lambda connection: connection.execute(f"""
+            CREATE IF NOT EXISTS MACRO generate_embedding(q) AS (
+                WITH  __request AS (
+                    SELECT http_post(
+                        '{API_URL}',
+                        headers => MAP {{
+                            'accept': 'application/json',
+                        }},
+                        params => MAP {{
+                            'model': 'models/{EMBEDDING_MODEL}',
+                            'parts': [{{ 'text': q }}],
+                            'taskType': 'SEMANTIC_SIMILARITY'
+                        }}
+                    ) AS response
+                )
+                SELECT *
+                FROM __request,
+            );
+        """),
+    )
+)
+with sql.provide_session(etl_config) as session:
+    result = session.select_one("SELECT generate_embedding('example text')")
+    print(result) # result is a dictionary when `schema_type` is omitted.
+```
+
+### Basic Litestar Integration
+
+In this example we are going to demonstrate how to create a basic configuration that integrates into Litestar.
+
+```py
+# /// script
+# dependencies = [
+#   "sqlspec[aiosqlite]",
+#   "litestar[standard]",
+# ]
+# ///
+
+from aiosqlite import Connection
+from litestar import Litestar, get
+
+from sqlspec.adapters.aiosqlite import AiosqliteConfig, AiosqliteDriver
+from sqlspec.extensions.litestar import SQLSpec
+
+
+@get("/")
+async def simple_sqlite(db_session: AiosqliteDriver) -> dict[str, str]:
+    return await db_session.select_one("SELECT 'Hello, world!' AS greeting")
+
+
+sqlspec = SQLSpec(config=DatabaseConfig(
+    config=[AiosqliteConfig(), commit_mode="autocommit")],
+)
+app = Litestar(route_handlers=[simple_sqlite], plugins=[sqlspec])
+```
+
 ## Inspiration and Future Direction
 
 SQLSpec originally drew inspiration from features found in the `aiosql` library.  This is a great library for working with and executed SQL stored in files.  It's unclear how much of an overlap there will be between the two libraries, but it's possible that some features will be contributed back to `aiosql` where appropriate.
@@ -121,7 +260,7 @@ This list is not final. If you have a driver you'd like to see added, please ope
 - `sqlspec/`:
     - `adapters/`: Contains all database drivers and associated configuration.
     - `extensions/`:
-        - `litestar/`: Future home of `litestar` integration.
+        - `litestar/`: Litestar framework integration ✅
         - `fastapi/`: Future home of `fastapi` integration.
         - `flask/`: Future home of `flask` integration.
         - `*/`: Future home of your favorite framework integration 🔌 ✨

{sqlspec-0.9.0.dist-info → sqlspec-0.9.1.dist-info}/RECORD

@@ -2,7 +2,7 @@ sqlspec/__init__.py,sha256=dsOivB7SmZhOcWkZQT12L4LHC6fQhWBk2s_3j85KkgQ,316
 sqlspec/__metadata__.py,sha256=hNP3wXvtk8fQVPKGjRLpZ9mP-gaPJqzrmgm3UqpDIXQ,460
 sqlspec/_serialization.py,sha256=tSwWwFImlYviC6ARdXRz0Bp4QXbCdc8cKGgZr33OglY,2657
 sqlspec/_typing.py,sha256=6ukndnNu_XWKf2OW-HP1x1L7YmqohMwjg2HF4Hq3xdU,7111
-sqlspec/base.py,sha256=vYXMVrdxEhaRfeAD4MVz9izY_mbCg5G3rbNchJ7vp0Q,24539
+sqlspec/base.py,sha256=-FM0xIFZSKYv4pGC3dsbiKWv_8oMAKz-UZqhRJIdE2o,35007
 sqlspec/exceptions.py,sha256=EyS7B9qyyTo78CdkC5iQDYFW9eXILDA6xiSS4ABr0Ws,4033
 sqlspec/filters.py,sha256=Gqwt4VQ7e8ffphkuR-jBfqW4m0OWGGUPiYWyEQ0Xn7M,3620
 sqlspec/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -11,51 +11,51 @@ sqlspec/typing.py,sha256=AI-72LFQcwwPoW5oEdEFkNHzxnWQv6I7lxcZRoZd88U,15428
 sqlspec/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sqlspec/adapters/adbc/__init__.py,sha256=_mIoHMCXYWLCqGtnN8YEylhkNt3goTAvZgsT1dfEL6g,155
 sqlspec/adapters/adbc/config.py,sha256=e2lrNsr8VN6R1ZBY16qusNj_W7npy7jp730NXCnhbBI,9866
-sqlspec/adapters/adbc/driver.py,sha256=lP9YEf5sUmeWRBULVZurfiRvE1sMuYdGzvCibzQPALw,16255
+sqlspec/adapters/adbc/driver.py,sha256=KpGxVhKf-6LoYNWfmng5VUR01GNjhHnOXBIkXznDwuE,19843
 sqlspec/adapters/aiosqlite/__init__.py,sha256=TQME6tGSPswTkZBjW2oH39lbxpzSwwWG5SQfgFpSe00,185
 sqlspec/adapters/aiosqlite/config.py,sha256=EjDJq9-Jn6MKnqlpL4ZwXYxaCKD0wE5GxrSYa2Ck1bA,4788
-sqlspec/adapters/aiosqlite/driver.py,sha256=D6kTpRxcfD_NSH7ThcVq2VbYZz0iriCh_CMjPQBl_Z8,11466
+sqlspec/adapters/aiosqlite/driver.py,sha256=yjsPhpJR-9c7AVzBDGi6GyGMzRW87Bls2F02c8WhCSA,15161
 sqlspec/adapters/asyncmy/__init__.py,sha256=w0hjokFrsBgYS0EnIv8Dorb7jz8M3ZBZYKMUXCUYEQg,247
 sqlspec/adapters/asyncmy/config.py,sha256=5ILV46FWjc9Cy46aMuhinpfc70b_708h9ubHj9HRCmE,9412
-sqlspec/adapters/asyncmy/driver.py,sha256=RICHrYxv2jOUk0m4bex0k2YVc5GMnSnOdrMIp4p4fNo,8507
+sqlspec/adapters/asyncmy/driver.py,sha256=Mjrb0ZWVwroCI-F9pNMDQsjFn2a1Kme2iyO9NJ5d0TM,12202
 sqlspec/adapters/asyncpg/__init__.py,sha256=iR-vJYxImcw5hLaDgMqPLLRxW_vOYylEpemSg5G4dP4,261
 sqlspec/adapters/asyncpg/config.py,sha256=DH6ZLkL4iHmRbW80VFQK1kzWIFRyGkFAZdtF3_f13AQ,9987
-sqlspec/adapters/asyncpg/driver.py,sha256=G6CSo3k1EzmPTZr2cCnTchR7J_O-1_uNC5eKylFMysY,18557
+sqlspec/adapters/asyncpg/driver.py,sha256=7Zp-lxA3EqAgon5HdaKEtBl35S82WuMwSj-P1zh74HM,22333
 sqlspec/adapters/duckdb/__init__.py,sha256=b_4QWZC0emTsbuBjcDZrxoEc83hGuBMx7Wwha3fFTAE,167
 sqlspec/adapters/duckdb/config.py,sha256=GJTzKp1cEFhKSe94n5wOXvrT4Sz3Md8mKRxmCBnfvsM,15731
-sqlspec/adapters/duckdb/driver.py,sha256=e91Iu84FbZ7NefqxkhmWZcwICav0lxJpAxxD08sFqUk,10160
+sqlspec/adapters/duckdb/driver.py,sha256=NDgWlK6as96Vt_wCS7L8sI4wNjG0YwHfzg9q5OseYxU,13801
 sqlspec/adapters/oracledb/__init__.py,sha256=g54_WLVzZhvD1sLC2uV0nfUs6WnYUJv2vqvvG34L7v0,398
-sqlspec/adapters/oracledb/driver.py,sha256=1YCj0pyaIMB-WXi_2w0ywRR0DlAlz5Q6k4gjGkY2yDE,23081
+sqlspec/adapters/oracledb/driver.py,sha256=7lSALyAiT-4SXKx1e7m3Pzli8SwZvTLyif-Zacc--Bc,30439
 sqlspec/adapters/oracledb/config/__init__.py,sha256=emx5jWXqw3ifoW-m_tNI7sTz_duq2vRkubc0J2QqEQ4,306
 sqlspec/adapters/oracledb/config/_asyncio.py,sha256=hu4o5q_d1O7svR_XrylWcmMrvmBzOp0T1m_Ybrbbr_o,7293
 sqlspec/adapters/oracledb/config/_common.py,sha256=UJZL2DQQZM3uOn1E1A_gnsB8nX3-yCDXGd66PDI29_s,5691
 sqlspec/adapters/oracledb/config/_sync.py,sha256=wvmC8bX2FhSD3W-k4RUBXnMP6cvEThsO6-vA-q5flUY,7016
 sqlspec/adapters/psqlpy/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sqlspec/adapters/psqlpy/config.py,sha256=SFa40Fp0HyrAAT49nNoH9gYovzk0iEhm6qMmqS9OgDI,10590
-sqlspec/adapters/psqlpy/driver.py,sha256=8DnLXFwIUkGtlu-xpj2O4lAaERIIRVVbNgkL6GQ7Qgk,12844
+sqlspec/adapters/psqlpy/config.py,sha256=f6A4jxOQdd8GHhmaIX4g8mbGXQFamRbgsKXecaZ1o60,10157
+sqlspec/adapters/psqlpy/driver.py,sha256=ykbozMFMJ4k7v2q-9moAnRzY2H14Mv21s2_z_mC8oLE,16838
 sqlspec/adapters/psycopg/__init__.py,sha256=_aCZRfDiC4lXM5UdkYEQEHZq-bqY1nyS_sioTM91Ul0,408
-sqlspec/adapters/psycopg/driver.py,sha256=4hQfw_hHuzZJYz1gKVECRAAdchop-ZIVWg9fZjY-NUM,21296
+sqlspec/adapters/psycopg/driver.py,sha256=edz1j_4v5ZGJidO5MzKqS4PNuXHJcV9fkoyyYh06bsA,28135
 sqlspec/adapters/psycopg/config/__init__.py,sha256=TIFGht0TdHKC7NTJwaJPpG-6-BRRGzWfc2Bu756R-A4,310
 sqlspec/adapters/psycopg/config/_async.py,sha256=6YpxNLxHwvI7r7ZBKKjWnd0xbEG1i4HLOOimiiDUr6w,6631
 sqlspec/adapters/psycopg/config/_common.py,sha256=UqqvqPE9zlSO9G_Gh6fI190cHfCDG98S0GaznGAHpdU,2181
 sqlspec/adapters/psycopg/config/_sync.py,sha256=QIybrGVkuu45GlAcYBzpcsRq7VW6EnHff4fcNATAgsw,6443
 sqlspec/adapters/sqlite/__init__.py,sha256=cGsMyN4_ZWApbhtwmYG18PYEBRiO-NdOU6eecBxTwRQ,167
 sqlspec/adapters/sqlite/config.py,sha256=m2TV-3jcjxIeMSCTsvvrTm50L6uE3007WVPluvqIX3Q,4447
-sqlspec/adapters/sqlite/driver.py,sha256=quh0Bazho05QVRWxy_Jww02I6HKLFg8Q0jUWMtfBjEU,11293
+sqlspec/adapters/sqlite/driver.py,sha256=W-upeHQAiBRKqd-NBbOlgPuc1BLvSuEdt3BryWeVI1U,13749
 sqlspec/extensions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sqlspec/extensions/litestar/__init__.py,sha256=vJf0co-AUM75c7ZLil_TUCYilVNDtmVsdeVLbm9_xn8,512
 sqlspec/extensions/litestar/_utils.py,sha256=UgwFxqLnjDw9S8G0H24DP2GsbMGas81W1lfhfTY68m8,1969
 sqlspec/extensions/litestar/config.py,sha256=zq_mlwNubDhRAtAivi2d5S5ippJ1A5xhw19XC6yPC60,4443
 sqlspec/extensions/litestar/handlers.py,sha256=6FNqIEWHUltnNuhcp8QNktK0j6-UB4isMpzoP7qCc3g,7932
-sqlspec/extensions/litestar/plugin.py,sha256=TOXz5Np17DbNaPhPp09-88reDHE29kmMjmRe4W5_-zE,4904
+sqlspec/extensions/litestar/plugin.py,sha256=_W-wTrGsvNu9iMVXfhuYzJUxBZp-9oEp8GcJvm_oMhU,4942
 sqlspec/utils/__init__.py,sha256=nVIUuMaHhhC1vXydoSBvnc-xTArqwWJaAtpjHhiM84Q,159
 sqlspec/utils/deprecation.py,sha256=4pwGxoQYI3dAc3L1lh4tszZG6e2jp5m4e0ICk8SJx5M,3886
 sqlspec/utils/fixtures.py,sha256=ni51rAuen6S1wuSi1kUwn6Qh25B-XrewPEsjV8G4gQ0,2029
 sqlspec/utils/module_loader.py,sha256=tmMy9JcTTQETcwT8Wt8adCIuqr4zinQnPbCiBJ6JTSQ,2703
 sqlspec/utils/sync_tools.py,sha256=xxHZ-5rnTrPEUNr7gxQUVvJd0NGJeO_MgisR8X7sI3c,10425
 sqlspec/utils/text.py,sha256=Ya-fWBcfkQRhguNs7MNFIYtAUiArBo62w8sRPHavMWM,1476
-sqlspec-0.9.0.dist-info/METADATA,sha256=zKfhk4Zk5WwoRzWlGqFTERFpN5kDOaFW77k7gU52tBo,9616
-sqlspec-0.9.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-sqlspec-0.9.0.dist-info/licenses/LICENSE,sha256=MdujfZ6l5HuLz4mElxlu049itenOR3gnhN1_Nd3nVcM,1078
-sqlspec-0.9.0.dist-info/licenses/NOTICE,sha256=Lyir8ozXWov7CyYS4huVaOCNrtgL17P-bNV-5daLntQ,1634
-sqlspec-0.9.0.dist-info/RECORD,,
+sqlspec-0.9.1.dist-info/METADATA,sha256=tk5LLeFdKAV99QguC9jnTD6BT6obRTSdfQLUGdmGanw,13935
+sqlspec-0.9.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+sqlspec-0.9.1.dist-info/licenses/LICENSE,sha256=MdujfZ6l5HuLz4mElxlu049itenOR3gnhN1_Nd3nVcM,1078
+sqlspec-0.9.1.dist-info/licenses/NOTICE,sha256=Lyir8ozXWov7CyYS4huVaOCNrtgL17P-bNV-5daLntQ,1634
+sqlspec-0.9.1.dist-info/RECORD,,