dirsql 0.3.15__tar.gz → 0.3.17__tar.gz

{dirsql-0.3.15 → dirsql-0.3.17}/Cargo.lock

@@ -499,7 +499,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.3.15"
+version = "0.3.17"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.3.15 → dirsql-0.3.17}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.3.15
+Version: 0.3.17
 Requires-Dist: pytest>=8 ; extra == 'dev'
 Requires-Dist: pytest-describe>=2 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'
 Requires-Dist: pytest-cov>=5 ; extra == 'dev'
 Requires-Dist: ruff>=0.4 ; extra == 'dev'
 Requires-Dist: maturin>=1.0 ; extra == 'dev'
+Requires-Dist: ty==0.0.42 ; extra == 'dev'
 Provides-Extra: dev
 Summary: Ephemeral SQL index over a local directory
 Keywords: sql,filesystem,directory,sqlite,index

{dirsql-0.3.15 → dirsql-0.3.17}/dirsql/_async.py

@@ -104,14 +104,14 @@ class DirSQL:
 
     async def query(self, sql):
         """Execute a SQL query asynchronously."""
-        return await asyncio.to_thread(self._db.query, sql)
+        return await asyncio.to_thread(self._db.query, sql)  # ty:ignore[unresolved-attribute]
 
     def watch(self):
         """Start watching for file changes. Returns an async iterable of RowEvent."""
         return _WatchStream(self._db)
 
     @property
-    def __dict__(self):
+    def __dict__(self):  # ty:ignore[missing-override-decorator]
         """Resolved construction state as a JSON-serializable dict.
 
         Recomputed on each access; reads the ``.dirsql.toml`` if ``config=``

dirsql-0.3.17/dirsql/_dirsql.pyi

@@ -0,0 +1,63 @@
+"""Type stubs for the native PyO3 extension module.
+
+Mirrors the surface defined in ``packages/python/src/lib.rs``. Hand-written
+because pyo3-stub-gen would otherwise demand a build-time hook that the
+maturin / putitoutthere release pipeline does not yet run.
+
+Whenever ``src/lib.rs`` adds, renames, or removes a ``#[pyclass]``,
+``#[pymethods]``, or module-level binding, this file MUST be updated in the
+same PR -- and ``PARITY.md`` is the canonical reminder.
+"""
+
+from collections.abc import Callable
+from os import PathLike
+from typing import Any
+
+__version__: str
+
+Row = dict[str, Any]
+
+class Table:
+    """A table definition. Construct via keyword arguments only."""
+
+    ddl: str
+    glob: str
+    strict: bool
+
+    def __init__(
+        self,
+        *,
+        ddl: str,
+        glob: str,
+        extract: Callable[[str], list[Row]],
+        strict: bool = False,
+    ) -> None: ...
+
+class RowEvent:
+    """A row event produced by the watch loop."""
+
+    table: str | None
+    action: str
+    row: Row | None
+    old_row: Row | None
+    error: str | None
+    file_path: str | None
+
+    def __repr__(self) -> str: ...  # ty:ignore[missing-override-decorator]
+
+class DirSQL:
+    """Synchronous binding class. ``dirsql._async.DirSQL`` wraps it."""
+
+    def __init__(
+        self,
+        root: str | None = None,
+        *,
+        tables: list[Table] | None = None,
+        ignore: list[str] | None = None,
+        config: str | None = None,
+        persist: bool = False,
+        persist_path: str | PathLike[str] | None = None,
+    ) -> None: ...
+    def query(self, sql: str) -> list[Row]: ...
+    def _start_watcher(self) -> None: ...
+    def _poll_events(self, timeout_ms: int) -> list[RowEvent]: ...

dirsql-0.3.17/dirsql/cli/interpret/__init__.py

@@ -0,0 +1,17 @@
+"""`dirsql interpret <config>` -- long-running native config helper (#196).
+
+Loads a Python config file, takes its module-level ``app = DirSQL(...)``,
+and serves ``extract`` requests over NDJSON on stdin/stdout. One line in,
+one line out, sequential.
+
+See the individual submodules for behavior:
+- ``run`` -- subcommand entry point invoked from ``dirsql.cli.main``
+- ``load_app`` -- importlib-based config loader
+- ``write_message`` -- single-line NDJSON writer
+- ``dispatch_extract`` -- per-request handler
+
+No top-level re-exports: the function is at ``.run.run``. Re-exporting
+``run`` at the package level would shadow the submodule (so
+``from . import run`` in tests would resolve to the function and break
+``patch.object(run_module, "load_app", ...)``).
+"""

dirsql-0.3.17/dirsql/cli/interpret/dispatch_extract.py

@@ -0,0 +1,41 @@
+"""Single-request handler for the `dirsql interpret` helper.
+
+Given a parsed request line and a name->table lookup, call the user's
+``extract`` callback and return the NDJSON response payload the loop
+will write back to stdout.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def dispatch_extract(
+    req: dict[str, Any],
+    tables: dict[str, Any],
+) -> dict[str, Any]:
+    """Build the `{"type": "result", ...}` response for one extract request.
+
+    - Unknown table name -> ``ok: false`` with a name-bearing error.
+    - User's ``extract`` raising -> ``ok: false`` with ``str(exc)``.
+    - Success -> ``ok: true`` with the row list the callback returned.
+
+    ``req["id"]`` is echoed back unchanged so the caller can correlate
+    request and response.
+    """
+    rid = req.get("id")
+    name = req.get("table")
+    path = req.get("path")
+    table = tables.get(name) if isinstance(name, str) else None
+    if table is None:
+        return {
+            "type": "result",
+            "id": rid,
+            "ok": False,
+            "error": f"unknown table: {name!r}",
+        }
+    try:
+        rows = table.extract(path)
+    except Exception as exc:
+        return {"type": "result", "id": rid, "ok": False, "error": str(exc)}
+    return {"type": "result", "id": rid, "ok": True, "rows": rows}

dirsql-0.3.17/dirsql/cli/interpret/dispatch_extract_test.py

@@ -0,0 +1,92 @@
+"""Unit tests for `dispatch_extract`."""
+
+from types import SimpleNamespace
+
+from .dispatch_extract import dispatch_extract
+
+
+def _table(extract):
+    return SimpleNamespace(extract=extract)
+
+
+def describe_dispatch_extract():
+    def it_returns_ok_true_with_the_rows_extract_produced():
+        tables = {"papers": _table(lambda p: [{"title": p}])}
+        out = dispatch_extract(
+            {"type": "extract", "id": 1, "table": "papers", "path": "/x.json"},
+            tables,
+        )
+        assert out == {
+            "type": "result",
+            "id": 1,
+            "ok": True,
+            "rows": [{"title": "/x.json"}],
+        }
+
+    def it_echoes_the_request_id_verbatim_on_success():
+        tables = {"papers": _table(lambda _p: [])}
+        out = dispatch_extract(
+            {"type": "extract", "id": 99, "table": "papers", "path": "/x.json"},
+            tables,
+        )
+        assert out["id"] == 99
+
+    def it_returns_ok_false_with_the_table_name_when_the_table_is_unknown():
+        out = dispatch_extract(
+            {"type": "extract", "id": 5, "table": "ghost", "path": "/x"},
+            tables={"papers": _table(lambda _p: [])},
+        )
+        assert out["type"] == "result"
+        assert out["id"] == 5
+        assert out["ok"] is False
+        assert "ghost" in out["error"]
+
+    def it_echoes_the_request_id_verbatim_on_unknown_table():
+        out = dispatch_extract(
+            {"type": "extract", "id": 17, "table": "ghost", "path": "/x"},
+            tables={},
+        )
+        assert out["id"] == 17
+
+    def it_returns_ok_false_with_the_exception_message_when_extract_raises():
+        def boom(_p):
+            raise ValueError("synthetic")
+
+        out = dispatch_extract(
+            {"type": "extract", "id": 7, "table": "papers", "path": "/x"},
+            {"papers": _table(boom)},
+        )
+        assert out == {
+            "type": "result",
+            "id": 7,
+            "ok": False,
+            "error": "synthetic",
+        }
+
+    def it_passes_the_request_path_to_the_extract_callback():
+        seen: list[str] = []
+
+        def capture(p):
+            seen.append(p)
+            return []
+
+        dispatch_extract(
+            {"type": "extract", "id": 1, "table": "t", "path": "/abs/x.json"},
+            {"t": _table(capture)},
+        )
+        assert seen == ["/abs/x.json"]
+
+    def it_treats_a_missing_table_field_as_unknown_table():
+        out = dispatch_extract(
+            {"type": "extract", "id": 1, "path": "/x"},
+            tables={"t": _table(lambda _p: [])},
+        )
+        assert out["ok"] is False
+        assert "None" in out["error"] or "none" in out["error"].lower()
+
+    def it_passes_through_a_missing_id_field_as_none():
+        out = dispatch_extract(
+            {"type": "extract", "table": "ghost", "path": "/x"},
+            tables={},
+        )
+        assert out["id"] is None

dirsql-0.3.17/dirsql/cli/interpret/load_app.py

@@ -0,0 +1,32 @@
+"""importlib-based config loader for the `dirsql interpret` helper.
+
+The user's config is a regular Python module that constructs a
+``DirSQL`` instance and assigns it to a top-level ``app`` name. We
+import it via ``importlib.util.spec_from_file_location`` so the user
+doesn't have to put their config on ``sys.path``.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+from typing import Any
+
+
+def load_app(config_path: str) -> Any:
+    """Import ``config_path`` and return its ``app`` attribute.
+
+    Raises ``ImportError`` if the file can't be loaded as a module, and
+    ``AttributeError`` if the module loads but defines no ``app``.
+    """
+    abs_path = os.path.abspath(config_path)
+    spec = importlib.util.spec_from_file_location("_dirsql_user_config", abs_path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"could not load config: {config_path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    if not hasattr(module, "app"):
+        raise AttributeError(
+            f"{config_path}: module must define a top-level `app = DirSQL(...)`"
+        )
+    return module.app

dirsql-0.3.17/dirsql/cli/interpret/load_app_test.py

@@ -0,0 +1,85 @@
+"""Unit tests for `load_app`."""
+
+import importlib.util
+import os
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from . import load_app as load_app_mod
+from .load_app import load_app
+
+
+def describe_load_app():
+    def it_returns_the_app_attribute_of_the_loaded_module(tmp_path: Path):
+        config = tmp_path / "config.py"
+        config.write_text("app = {'sentinel': 'value'}\n")
+        result = load_app(str(config))
+        assert result == {"sentinel": "value"}
+
+    def it_resolves_relative_paths_against_the_cwd(tmp_path: Path):
+        config = tmp_path / "config.py"
+        config.write_text("app = 42\n")
+        prev = os.getcwd()
+        try:
+            os.chdir(tmp_path)
+            assert load_app("config.py") == 42
+        finally:
+            os.chdir(prev)
+
+    def it_raises_import_error_when_the_file_does_not_exist(tmp_path: Path):
+        missing = tmp_path / "nope.py"
+        with pytest.raises((ImportError, FileNotFoundError)):
+            load_app(str(missing))
+
+    def it_raises_attribute_error_with_a_path_aware_message_when_app_is_missing(
+        tmp_path: Path,
+    ):
+        config = tmp_path / "config.py"
+        config.write_text("not_the_app = 1\n")
+        with pytest.raises(AttributeError, match="must define a top-level `app"):
+            load_app(str(config))
+
+    def it_surfaces_exceptions_raised_during_module_exec(tmp_path: Path):
+        config = tmp_path / "config.py"
+        config.write_text("raise RuntimeError('synthetic boom')\n")
+        with pytest.raises(RuntimeError, match="synthetic boom"):
+            load_app(str(config))
+
+    def it_raises_import_error_when_spec_from_file_location_returns_none(
+        tmp_path: Path,
+    ):
+        with patch.object(
+            load_app_mod.importlib.util,
+            "spec_from_file_location",
+            return_value=None,
+        ):
+            with pytest.raises(ImportError, match="could not load config"):
+                load_app(str(tmp_path / "anything.py"))
+
+    def it_raises_import_error_when_spec_has_no_loader(tmp_path: Path):
+        class _SpecNoLoader:
+            loader = None
+
+        with patch.object(
+            load_app_mod.importlib.util,
+            "spec_from_file_location",
+            return_value=_SpecNoLoader(),
+        ):
+            with pytest.raises(ImportError, match="could not load config"):
+                load_app(str(tmp_path / "anything.py"))
+
+    def it_absolutizes_the_passed_path_before_loading(tmp_path: Path):
+        config = tmp_path / "config.py"
+        config.write_text("app = 1\n")
+        with patch.object(
+            importlib.util,
+            "spec_from_file_location",
+            wraps=importlib.util.spec_from_file_location,
+        ) as spec_call:
+            load_app(str(config))
+        # First positional arg after the synthetic module name is the
+        # absolute path the loader was asked to read.
+        called_path = spec_call.call_args.args[1]
+        assert called_path == os.path.abspath(str(config))

dirsql-0.3.17/dirsql/cli/interpret/run.py

@@ -0,0 +1,66 @@
+"""Subcommand entry point for `dirsql interpret <config>`.
+
+Glues the per-purpose helpers (`load_app`, `dispatch_extract`,
+`write_message`) into the long-running NDJSON loop:
+
+  handshake (helper -> caller, once on startup):
+    {"type": "config", "state": <vars(app)>}
+
+  extract request (caller -> helper):
+    {"type": "extract", "id": <int>, "table": "<name>", "path": "<abs>"}
+
+  extract response (helper -> caller):
+    {"type": "result", "id": <int>, "ok": true,  "rows": [...]}
+    {"type": "result", "id": <int>, "ok": false, "error": "<msg>"}
+
+Exits 0 when stdin closes; non-zero with a single ``dirsql interpret:``
+line on stderr if the config can't be loaded.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from .dispatch_extract import dispatch_extract
+from .load_app import load_app
+from .write_message import write_message
+
+
+def run(argv: list[str]) -> int:
+    if len(argv) != 1:
+        sys.stderr.write(
+            f"dirsql interpret: expected one config path, got {len(argv)}\n"
+        )
+        return 1
+    config_path = argv[0]
+
+    try:
+        app = load_app(config_path)
+    except Exception as exc:
+        sys.stderr.write(f"dirsql interpret: {exc}\n")
+        return 1
+
+    # Name comes from `dirsql::db::parse_table_name` -- the canonical
+    # core parser, surfaced via PyO3 on `Table.name` (#196). No regex
+    # duplication on the Python side. Tables with a name the parser
+    # couldn't extract are skipped here; the malformed DDL would also
+    # surface as a `DirSqlError::Ddl` during the SDK scan, which
+    # `await app.ready()` would re-raise -- not interpret's job to
+    # second-guess.
+    tables = {t.name: t for t in (app._tables or []) if t.name is not None}
+    write_message({"type": "config", "state": vars(app)})
+
+    for line in sys.stdin:
+        stripped = line.strip()
+        if not stripped:
+            continue
+        try:
+            req = json.loads(stripped)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(req, dict) or req.get("type") != "extract":
+            continue
+        write_message(dispatch_extract(req, tables))
+
+    return 0

dirsql-0.3.17/dirsql/cli/interpret/run_test.py

@@ -0,0 +1,172 @@
+"""Unit tests for `run`."""
+
+import io
+import json
+import sys
+from types import SimpleNamespace
+from unittest.mock import patch
+
+from . import run as run_module
+from .run import run
+
+
+def _fake_table(name: str, extract):
+    return SimpleNamespace(name=name, extract=extract)
+
+
+def _fake_app(tables: list, state: dict):
+    """Build a duck-typed `app` -- `_tables` for dispatch, `__dict__`
+    handled by overriding `vars`."""
+
+    class _App:
+        _tables = tables
+
+    a = _App()
+    # vars(a) needs to return `state` -- bind it through __dict__.
+    a.__dict__.update(state)
+    return a
+
+
+def describe_run():
+    def describe_argv_validation():
+        def it_returns_1_when_argv_has_no_config_path():
+            fake_stderr = io.StringIO()
+            with patch.object(sys, "stderr", fake_stderr):
+                assert run([]) == 1
+            assert fake_stderr.getvalue().startswith("dirsql interpret:")
+            assert "got 0" in fake_stderr.getvalue()
+
+        def it_returns_1_when_argv_has_multiple_paths():
+            fake_stderr = io.StringIO()
+            with patch.object(sys, "stderr", fake_stderr):
+                assert run(["a.py", "b.py"]) == 1
+            assert "got 2" in fake_stderr.getvalue()
+
+    def describe_load_failure():
+        def it_returns_1_and_writes_a_dirsql_prefixed_line_to_stderr():
+            fake_stderr = io.StringIO()
+            with (
+                patch.object(
+                    run_module,
+                    "load_app",
+                    side_effect=AttributeError("missing app"),
+                ),
+                patch.object(sys, "stderr", fake_stderr),
+            ):
+                assert run(["bad.py"]) == 1
+            assert fake_stderr.getvalue() == "dirsql interpret: missing app\n"
+
+    def describe_handshake():
+        def it_writes_a_config_message_with_vars_app_as_state():
+            app = _fake_app(tables=[], state={"root": "/x", "ignore": []})
+            fake_stdin = io.StringIO("")  # immediate EOF
+            written: list[dict] = []
+            with (
+                patch.object(run_module, "load_app", return_value=app),
+                patch.object(run_module, "write_message", side_effect=written.append),
+                patch.object(sys, "stdin", fake_stdin),
+            ):
+                assert run(["good.py"]) == 0
+            assert written == [
+                {"type": "config", "state": {"root": "/x", "ignore": []}}
+            ]
+
+    def describe_extract_loop():
+        def it_dispatches_one_extract_request_and_writes_the_response():
+            def extract(p):
+                return [{"row": p}]
+
+            app = _fake_app([_fake_table("papers", extract)], state={"x": 1})
+            req = {"type": "extract", "id": 1, "table": "papers", "path": "/a"}
+            fake_stdin = io.StringIO(json.dumps(req) + "\n")
+            written: list[dict] = []
+            with (
+                patch.object(run_module, "load_app", return_value=app),
+                patch.object(run_module, "write_message", side_effect=written.append),
+                patch.object(sys, "stdin", fake_stdin),
+            ):
+                assert run(["good.py"]) == 0
+            # written[0] is the handshake; written[1] is the response.
+            assert written[1] == {
+                "type": "result",
+                "id": 1,
+                "ok": True,
+                "rows": [{"row": "/a"}],
+            }
+
+        def it_skips_blank_lines_silently():
+            app = _fake_app([], state={})
+            fake_stdin = io.StringIO("\n\n   \n")
+            written: list[dict] = []
+            with (
+                patch.object(run_module, "load_app", return_value=app),
+                patch.object(run_module, "write_message", side_effect=written.append),
+                patch.object(sys, "stdin", fake_stdin),
+            ):
+                assert run(["good.py"]) == 0
+            assert written == [{"type": "config", "state": {}}]  # only handshake
+
+        def it_skips_malformed_json_silently():
+            app = _fake_app([], state={})
+            fake_stdin = io.StringIO("not json\n{also not\n")
+            written: list[dict] = []
+            with (
+                patch.object(run_module, "load_app", return_value=app),
+                patch.object(run_module, "write_message", side_effect=written.append),
+                patch.object(sys, "stdin", fake_stdin),
+            ):
+                assert run(["good.py"]) == 0
+            assert written == [{"type": "config", "state": {}}]
+
+        def it_skips_non_extract_messages_silently():
+            app = _fake_app([], state={})
+            fake_stdin = io.StringIO('{"type": "ping"}\n')
+            written: list[dict] = []
+            with (
+                patch.object(run_module, "load_app", return_value=app),
+                patch.object(run_module, "write_message", side_effect=written.append),
+                patch.object(sys, "stdin", fake_stdin),
+            ):
+                assert run(["good.py"]) == 0
+            assert written == [{"type": "config", "state": {}}]
+
+        def it_skips_non_dict_json_silently():
+            app = _fake_app([], state={})
+            fake_stdin = io.StringIO("42\n[]\n")
+            written: list[dict] = []
+            with (
+                patch.object(run_module, "load_app", return_value=app),
+                patch.object(run_module, "write_message", side_effect=written.append),
+                patch.object(sys, "stdin", fake_stdin),
+            ):
+                assert run(["good.py"]) == 0
+            assert written == [{"type": "config", "state": {}}]
+
+        def it_treats_a_none_tables_attribute_as_empty():
+            app = _fake_app(tables=None, state={})  # type: ignore[arg-type]
+            fake_stdin = io.StringIO(
+                '{"type":"extract","id":1,"table":"x","path":"/y"}\n'
+            )
+            written: list[dict] = []
+            with (
+                patch.object(run_module, "load_app", return_value=app),
+                patch.object(run_module, "write_message", side_effect=written.append),
+                patch.object(sys, "stdin", fake_stdin),
+            ):
+                assert run(["good.py"]) == 0
+            # Handshake + unknown-table response.
+            assert written[1]["ok"] is False
+            assert "x" in written[1]["error"]
+
+    def describe_exit():
+        def it_returns_0_when_stdin_closes_after_a_run():
+            app = _fake_app([_fake_table("t", lambda _p: [])], state={})
+            fake_stdin = io.StringIO(
+                '{"type":"extract","id":1,"table":"t","path":"/a"}\n'
+            )
+            with (
+                patch.object(run_module, "load_app", return_value=app),
+                patch.object(run_module, "write_message"),
+                patch.object(sys, "stdin", fake_stdin),
+            ):
+                assert run(["good.py"]) == 0

dirsql-0.3.17/dirsql/cli/interpret/write_message.py

@@ -0,0 +1,18 @@
+"""Single-line NDJSON writer for the `dirsql interpret` helper."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+
+def write_message(msg: dict[str, Any]) -> None:
+    """Write one NDJSON line to stdout and flush.
+
+    The flush is required so the orchestrator on the other side of the
+    pipe sees the message immediately; without it the buffered stream
+    would deliver lines in batches.
+    """
+    sys.stdout.write(json.dumps(msg) + "\n")
+    sys.stdout.flush()

dirsql-0.3.17/dirsql/cli/interpret/write_message_test.py

@@ -0,0 +1,30 @@
+"""Unit tests for `write_message`."""
+
+import io
+import sys
+from unittest.mock import patch
+
+from .write_message import write_message
+
+
+def describe_write_message():
+    def it_serializes_a_dict_as_one_json_line():
+        buf = io.StringIO()
+        with patch.object(sys, "stdout", buf):
+            write_message({"type": "config", "state": {}})
+        assert buf.getvalue() == '{"type": "config", "state": {}}\n'
+
+    def it_appends_a_trailing_newline():
+        buf = io.StringIO()
+        with patch.object(sys, "stdout", buf):
+            write_message({"x": 1})
+        assert buf.getvalue().endswith("\n")
+
+    def it_flushes_stdout_after_writing():
+        fake_stdout = io.StringIO()
+        with (
+            patch.object(sys, "stdout", fake_stdout),
+            patch.object(fake_stdout, "flush") as flush,
+        ):
+            write_message({"x": 1})
+            flush.assert_called_once()