dirsql 0.4.131__tar.gz → 0.4.132__tar.gz

{dirsql-0.4.131 → dirsql-0.4.132}/Cargo.lock

@@ -573,7 +573,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql"
-version = "0.4.131"
+version = "0.4.132"
 dependencies = [
  "assert_cmd",
  "axum",
@@ -625,7 +625,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.4.131"
+version = "0.4.132"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.4.131 → dirsql-0.4.132}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.4.131
+Version: 0.4.132
 Requires-Dist: bin-shim>=0.1
 Summary: Ephemeral SQL index over a local directory
 Keywords: sql,filesystem,directory,sqlite,index

{dirsql-0.4.131 → dirsql-0.4.132}/dirsql/_async.py

@@ -207,9 +207,13 @@ class DirSQL:
         if self._init_error is not None:
             raise self._init_error
 
-    async def query(self, sql):
+    async def query(self, sql, params=None):
         """Execute a SQL query asynchronously.
 
+        ``params`` binds values to the statement's placeholders through
+        SQLite, never into the SQL text: a sequence fills ``?`` placeholders
+        in order, a mapping fills ``:name`` placeholders by name.
+
         Awaits :meth:`ready` first, so calling ``query`` before an explicit
         ``await db.ready()`` waits for the background scan (and re-raises any
         initialization error) instead of failing on a still-``None`` ``_db``.
@@ -217,7 +221,7 @@ class DirSQL:
         await self.ready()
         db = self._db
         assert db is not None  # ready() returned, so _init_bg set _db
-        return await asyncio.to_thread(db.query, sql)
+        return await asyncio.to_thread(db.query, sql, params)
 
     async def scan_failures(self):
         """The files the initial scan could not index.

{dirsql-0.4.131 → dirsql-0.4.132}/dirsql/_dirsql.pyi

@@ -9,7 +9,7 @@ Whenever ``src/lib.rs`` adds, renames, or removes a ``#[pyclass]``,
 same PR -- and ``PARITY.md`` is the canonical reminder.
 """
 
-from collections.abc import Callable
+from collections.abc import Callable, Mapping, Sequence
 from os import PathLike
 from typing import Any, TypedDict
 
@@ -84,7 +84,9 @@ class DirSQL:
         extensions: list[ExtensionSpec] | None = None,
         suppress_config_extensions: bool = False,
     ) -> None: ...
-    def query(self, sql: str) -> list[Row]: ...
+    def query(
+        self, sql: str, params: Sequence[Any] | Mapping[str, Any] | None = None
+    ) -> list[Row]: ...
     def scan_failures(self) -> list[ScanFailure]: ...
     def _start_watcher(self) -> None: ...
     def _poll_events(self, timeout_ms: int) -> list[RowEvent]: ...

{dirsql-0.4.131/packages/rust → dirsql-0.4.132}/docs/reference/sdk.md

@@ -208,7 +208,7 @@ observe construction errors before issuing a query.
 ::: code-group
 
 ```python [Python]
-await db.query(sql: str) -> list[dict]
+await db.query(sql: str, params: Sequence | Mapping | None = None) -> list[dict]
 ```
 
 ```typescript [TypeScript]
@@ -218,12 +218,64 @@ await db.query(sql: string) -> Record<string, unknown>[]
 
 ```rust [Rust]
 db.query(sql: &str) -> Result<Vec<Row>>   // Row = HashMap<String, Value>
+db.query_with(sql: &str, params: &Params) -> Result<Vec<Row>>
 ```
 
 :::
 
 Executes a SQL query and returns rows keyed by column name.
 
+**Bind parameters.** `params` reaches SQLite's own parameter binding; the
+values never enter the SQL text, so text holding quotes needs no escaping.
+A sequence fills `?` placeholders in order; a mapping fills `:name`
+placeholders, keyed by the name without its prefix. It works for path-tables
+and declared tables alike:
+
+::: code-group
+
+```python [Python]
+await db.query(
+    "SELECT path FROM './*.json' WHERE content ->> 'advice' = :advice",
+    {"advice": text},
+)
+await db.query("SELECT * FROM notes WHERE author = ? AND year = ?", ("ann", 2024))
+```
+
+```rust [Rust]
+use dirsql::{Params, Value};
+use std::collections::HashMap;
+
+db.query_with(
+    "SELECT path FROM './*.json' WHERE content ->> 'advice' = :advice",
+    &Params::Named(HashMap::from([("advice".into(), Value::Text(text))])),
+)?;
+db.query_with(
+    "SELECT * FROM notes WHERE author = ?",
+    &Params::Positional(vec![Value::Text("ann".into())]),
+)?;
+// query_ordered_with and query_each_with bind the same way;
+// AsyncDirSQL::query_with is the async twin.
+```
+
+:::
+
+TypeScript does not take bind parameters yet.
+
+- Values bind as SQLite's native types. Python accepts `None`, `int`
+  (`bool` binds as `0`/`1`), `float`, `str`, `bytes` and `bytearray`;
+  anything else raises `TypeError` rather than being stringified, and an
+  `int` outside the signed 64-bit range raises `OverflowError`. Rust binds a
+  `Value`.
+- The params must fit the placeholders exactly, or the query fails with an
+  error naming the problem: a wrong count for a sequence, a placeholder name
+  the mapping lacks, a mapping key no placeholder uses, or a sequence for
+  named placeholders (and a mapping for `?`). Python raises a
+  `RuntimeError` for these, and a `TypeError` when `params` is neither a
+  sequence nor a mapping (a `str` counts as neither). Rust returns
+  `DbError::Params`.
+- Without `params`, a statement with placeholders fails the same way: a
+  placeholder is never left unbound.
+
 - **Read-only.** Each statement is classified by SQLite itself
   (`sqlite3_stmt_readonly`); anything classified as a write — `INSERT`,
   `UPDATE`, `DELETE`, `DROP`, `CREATE`, `ALTER`, `VACUUM`, … — is rejected

{dirsql-0.4.131 → dirsql-0.4.132}/packages/python/Cargo.toml

@@ -4,7 +4,7 @@ name = "dirsql-py-ext"
 # pypi/maturin handler can rewrite it via `write-version` before
 # `maturin build`. `pyproject.toml` declares `dynamic = ["version"]`
 # and maturin reads this field. Mirrors `packages/rust/Cargo.toml`.
-version = "0.4.131"
+version = "0.4.132"
 # abi3 note: the `abi3-py310` pyo3 feature (below) builds ONE stable-ABI
 # `cp310-abi3` wheel per platform that loads on every CPython >= 3.10
 # (matching `pyproject.toml`'s `requires-python = ">=3.10"`), instead of

dirsql-0.4.132/packages/python/changelog.d/2026-11-04-query-bind-params.md

@@ -0,0 +1 @@
+**Added** `await db.query(sql, params)` binds `params` to the statement's placeholders through SQLite: a sequence fills `?` placeholders in order, a mapping fills `:name` placeholders by name. Values never enter the SQL text, so text holding quotes needs no escaping. Works for path-tables and declared tables alike. Values bind as SQLite's native types (`None`, `int`, `bool`, `float`, `str`, `bytes`, `bytearray`); any other type raises `TypeError`. A wrong parameter count, a missing or unused name, or the wrong container raises an error naming the problem.

{dirsql-0.4.131 → dirsql-0.4.132}/packages/python/docs/reference/sdk.md

@@ -208,7 +208,7 @@ observe construction errors before issuing a query.
 ::: code-group
 
 ```python [Python]
-await db.query(sql: str) -> list[dict]
+await db.query(sql: str, params: Sequence | Mapping | None = None) -> list[dict]
 ```
 
 ```typescript [TypeScript]
@@ -218,12 +218,64 @@ await db.query(sql: string) -> Record<string, unknown>[]
 
 ```rust [Rust]
 db.query(sql: &str) -> Result<Vec<Row>>   // Row = HashMap<String, Value>
+db.query_with(sql: &str, params: &Params) -> Result<Vec<Row>>
 ```
 
 :::
 
 Executes a SQL query and returns rows keyed by column name.
 
+**Bind parameters.** `params` reaches SQLite's own parameter binding; the
+values never enter the SQL text, so text holding quotes needs no escaping.
+A sequence fills `?` placeholders in order; a mapping fills `:name`
+placeholders, keyed by the name without its prefix. It works for path-tables
+and declared tables alike:
+
+::: code-group
+
+```python [Python]
+await db.query(
+    "SELECT path FROM './*.json' WHERE content ->> 'advice' = :advice",
+    {"advice": text},
+)
+await db.query("SELECT * FROM notes WHERE author = ? AND year = ?", ("ann", 2024))
+```
+
+```rust [Rust]
+use dirsql::{Params, Value};
+use std::collections::HashMap;
+
+db.query_with(
+    "SELECT path FROM './*.json' WHERE content ->> 'advice' = :advice",
+    &Params::Named(HashMap::from([("advice".into(), Value::Text(text))])),
+)?;
+db.query_with(
+    "SELECT * FROM notes WHERE author = ?",
+    &Params::Positional(vec![Value::Text("ann".into())]),
+)?;
+// query_ordered_with and query_each_with bind the same way;
+// AsyncDirSQL::query_with is the async twin.
+```
+
+:::
+
+TypeScript does not take bind parameters yet.
+
+- Values bind as SQLite's native types. Python accepts `None`, `int`
+  (`bool` binds as `0`/`1`), `float`, `str`, `bytes` and `bytearray`;
+  anything else raises `TypeError` rather than being stringified, and an
+  `int` outside the signed 64-bit range raises `OverflowError`. Rust binds a
+  `Value`.
+- The params must fit the placeholders exactly, or the query fails with an
+  error naming the problem: a wrong count for a sequence, a placeholder name
+  the mapping lacks, a mapping key no placeholder uses, or a sequence for
+  named placeholders (and a mapping for `?`). Python raises a
+  `RuntimeError` for these, and a `TypeError` when `params` is neither a
+  sequence nor a mapping (a `str` counts as neither). Rust returns
+  `DbError::Params`.
+- Without `params`, a statement with placeholders fails the same way: a
+  placeholder is never left unbound.
+
 - **Read-only.** Each statement is classified by SQLite itself
   (`sqlite3_stmt_readonly`); anything classified as a write — `INSERT`,
   `UPDATE`, `DELETE`, `DROP`, `CREATE`, `ALTER`, `VACUUM`, … — is rejected

dirsql-0.4.132/packages/python/e2e-attestations/bot-1575-bind-params-1104.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/query_contract_test.py tests/e2e/on_file_query_test.py tests/e2e/declared_table_name_test.py tests/e2e/use_case_join_test.py tests/e2e/stat_speed_test.py -x -q",
+  "ran_at": 1793806695,
+  "exit_code": 0,
+  "commit": "7fec72fd59d31d22b5aa0d2331e545eddc5eee0e",
+  "branch": "bot/1575-bind-params-1104"
+}

dirsql-0.4.132/packages/python/migrations.d/2026-11-04-query-bind-params.md

@@ -0,0 +1,25 @@
+### Bind parameters in `query`
+
+#### Summary
+
+`await db.query(sql, params)` binds values to the statement's placeholders through SQLite rather than the SQL text. Existing calls without params keep working. Nothing breaks.
+
+#### Required changes
+
+_None._ Hand-quoted SQL keeps working; to bind instead:
+
+| Before | After |
+|---|---|
+| `await db.query(f"... WHERE a = {quote(text)}")` | `await db.query("... WHERE a = :a", {"a": text})` |
+
+#### Deprecations removed
+
+_None._
+
+#### Behavior changes without code changes
+
+A query whose placeholders get no values still fails, but with dirsql's message (`the query has 1 parameter(s), but 0 value(s) were given`) instead of SQLite's `Wrong number of parameters passed to query`.
+
+#### Verification
+
+`await DirSQL(".").query("SELECT :x AS x", {"x": "it's"})` returns `[{"x": "it's"}]`.

{dirsql-0.4.131 → dirsql-0.4.132}/packages/python/src/lib.rs

@@ -13,10 +13,13 @@
 #[cfg(feature = "extension-module")]
 mod python {
     use ::dirsql::extension_resolution::{self, ConfigSource, PlanEntry};
-    use ::dirsql::{DirSQL, Extension, Row, RowEvent, Table, Value, flatten_row_event};
-    use pyo3::exceptions::{PyOverflowError, PyRuntimeError, PyValueError};
+    use ::dirsql::{DirSQL, Extension, Params, Row, RowEvent, Table, Value, flatten_row_event};
+    use pyo3::exceptions::{PyOverflowError, PyRuntimeError, PyTypeError, PyValueError};
     use pyo3::prelude::*;
-    use pyo3::types::{PyBool, PyByteArray, PyBytes, PyDict, PyInt, PyList};
+    use pyo3::types::{
+        PyBool, PyByteArray, PyBytes, PyDict, PyFloat, PyInt, PyList, PyMapping, PySequence,
+        PyString,
+    };
     use std::collections::HashMap;
     use std::path::{Path, PathBuf};
     use std::time::Duration;
@@ -191,10 +194,17 @@ mod python {
             Ok(Self { inner })
         }
 
-        fn query(&self, py: Python<'_>, sql: String) -> PyResult<Py<PyList>> {
+        #[pyo3(signature = (sql, params=None))]
+        fn query(
+            &self,
+            py: Python<'_>,
+            sql: String,
+            params: Option<Bound<'_, PyAny>>,
+        ) -> PyResult<Py<PyList>> {
+            let params = py_to_params(params.as_ref())?;
             let db = self.inner.clone();
             let result = py
-                .detach(move || db.query_ordered(&sql))
+                .detach(move || db.query_ordered_with(&sql, &params))
                 .map_err(to_py_err)?;
 
             let list = PyList::empty(py);
@@ -371,6 +381,69 @@ mod python {
     }
 
     /// The range-error message for a Python int that does not fit `i64`.
+    fn py_to_params(params: Option<&Bound<'_, PyAny>>) -> PyResult<Params> {
+        let Some(params) = params.filter(|p| !p.is_none()) else {
+            return Ok(Params::default());
+        };
+        // A str or bytes is a sequence too; binding it character by
+        // character is never what the caller meant.
+        let textual = params.is_instance_of::<PyString>()
+            || params.is_instance_of::<PyBytes>()
+            || params.is_instance_of::<PyByteArray>();
+        if !textual {
+            if let Ok(mapping) = params.cast::<PyMapping>() {
+                let mut named = HashMap::new();
+                for item in mapping.items()?.iter() {
+                    let (key, value): (Bound<'_, PyAny>, Bound<'_, PyAny>) = item.extract()?;
+                    let key: String = key
+                        .extract()
+                        .map_err(|_| PyTypeError::new_err("params mapping keys must be str"))?;
+                    named.insert(key, param_to_value(&value)?);
+                }
+                return Ok(Params::Named(named));
+            }
+            if let Ok(sequence) = params.cast::<PySequence>() {
+                let values = sequence
+                    .try_iter()?
+                    .map(|value| param_to_value(&value?))
+                    .collect::<PyResult<Vec<_>>>()?;
+                return Ok(Params::Positional(values));
+            }
+        }
+        Err(PyTypeError::new_err(format!(
+            "params must be a sequence or a mapping, not {}",
+            params.get_type().name()?
+        )))
+    }
+
+    fn param_to_value(value: &Bound<'_, PyAny>) -> PyResult<Value> {
+        if value.is_none() {
+            return Ok(Value::Null);
+        }
+        if value.is_instance_of::<PyBool>() {
+            return Ok(Value::Integer(i64::from(value.extract::<bool>()?)));
+        }
+        if value.is_instance_of::<PyInt>() {
+            return value
+                .extract::<i64>()
+                .map(Value::Integer)
+                .map_err(|_| PyOverflowError::new_err(int_overflow_message(&value.to_string())));
+        }
+        if value.is_instance_of::<PyFloat>() {
+            return Ok(Value::Real(value.extract()?));
+        }
+        if value.is_instance_of::<PyString>() {
+            return Ok(Value::Text(value.extract()?));
+        }
+        if value.is_instance_of::<PyBytes>() || value.is_instance_of::<PyByteArray>() {
+            return Ok(Value::Blob(value.extract()?));
+        }
+        Err(PyTypeError::new_err(format!(
+            "unsupported parameter type: {}",
+            value.get_type().name()?
+        )))
+    }
+
     fn int_overflow_message(repr: &str) -> String {
         format!("integer {repr} exceeds the 64-bit signed range dirsql can store")
     }

{dirsql-0.4.131 → dirsql-0.4.132}/packages/rust/Cargo.toml

@@ -6,7 +6,7 @@ description = "Ephemeral SQL index over a local directory"
 # version stays for the binding crates (publish = false). The literal
 # intentionally lags the published version: putitoutthere rewrites it to
 # the planned release version at build time and never commits it back.
-version = "0.4.131"
+version = "0.4.132"
 edition.workspace = true
 # Literal `license` (not `license.workspace = true`) because
 # putitoutthere's preflight check reads `[package].license` directly

{dirsql-0.4.131 → dirsql-0.4.132/packages/rust}/docs/reference/sdk.md

@@ -208,7 +208,7 @@ observe construction errors before issuing a query.
 ::: code-group
 
 ```python [Python]
-await db.query(sql: str) -> list[dict]
+await db.query(sql: str, params: Sequence | Mapping | None = None) -> list[dict]
 ```
 
 ```typescript [TypeScript]
@@ -218,12 +218,64 @@ await db.query(sql: string) -> Record<string, unknown>[]
 
 ```rust [Rust]
 db.query(sql: &str) -> Result<Vec<Row>>   // Row = HashMap<String, Value>
+db.query_with(sql: &str, params: &Params) -> Result<Vec<Row>>
 ```
 
 :::
 
 Executes a SQL query and returns rows keyed by column name.
 
+**Bind parameters.** `params` reaches SQLite's own parameter binding; the
+values never enter the SQL text, so text holding quotes needs no escaping.
+A sequence fills `?` placeholders in order; a mapping fills `:name`
+placeholders, keyed by the name without its prefix. It works for path-tables
+and declared tables alike:
+
+::: code-group
+
+```python [Python]
+await db.query(
+    "SELECT path FROM './*.json' WHERE content ->> 'advice' = :advice",
+    {"advice": text},
+)
+await db.query("SELECT * FROM notes WHERE author = ? AND year = ?", ("ann", 2024))
+```
+
+```rust [Rust]
+use dirsql::{Params, Value};
+use std::collections::HashMap;
+
+db.query_with(
+    "SELECT path FROM './*.json' WHERE content ->> 'advice' = :advice",
+    &Params::Named(HashMap::from([("advice".into(), Value::Text(text))])),
+)?;
+db.query_with(
+    "SELECT * FROM notes WHERE author = ?",
+    &Params::Positional(vec![Value::Text("ann".into())]),
+)?;
+// query_ordered_with and query_each_with bind the same way;
+// AsyncDirSQL::query_with is the async twin.
+```
+
+:::
+
+TypeScript does not take bind parameters yet.
+
+- Values bind as SQLite's native types. Python accepts `None`, `int`
+  (`bool` binds as `0`/`1`), `float`, `str`, `bytes` and `bytearray`;
+  anything else raises `TypeError` rather than being stringified, and an
+  `int` outside the signed 64-bit range raises `OverflowError`. Rust binds a
+  `Value`.
+- The params must fit the placeholders exactly, or the query fails with an
+  error naming the problem: a wrong count for a sequence, a placeholder name
+  the mapping lacks, a mapping key no placeholder uses, or a sequence for
+  named placeholders (and a mapping for `?`). Python raises a
+  `RuntimeError` for these, and a `TypeError` when `params` is neither a
+  sequence nor a mapping (a `str` counts as neither). Rust returns
+  `DbError::Params`.
+- Without `params`, a statement with placeholders fails the same way: a
+  placeholder is never left unbound.
+
 - **Read-only.** Each statement is classified by SQLite itself
   (`sqlite3_stmt_readonly`); anything classified as a write — `INSERT`,
   `UPDATE`, `DELETE`, `DROP`, `CREATE`, `ALTER`, `VACUUM`, … — is rejected