dirsql 0.3.12__tar.gz → 0.3.13__tar.gz

{dirsql-0.3.12 → dirsql-0.3.13}/Cargo.lock

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

{dirsql-0.3.12 → dirsql-0.3.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.3.12
+Version: 0.3.13
 Requires-Dist: pytest>=8 ; extra == 'dev'
 Requires-Dist: pytest-describe>=2 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'

{dirsql-0.3.12 → dirsql-0.3.13}/dirsql/_async.py

@@ -3,6 +3,7 @@
 import asyncio
 
 from dirsql._dirsql import DirSQL as _RustDirSQL
+from dirsql.resolve_config import resolve_config
 
 
 class _WatchStream:
@@ -108,3 +109,19 @@ class DirSQL:
     def watch(self):
         """Start watching for file changes. Returns an async iterable of RowEvent."""
         return _WatchStream(self._db)
+
+    @property
+    def __dict__(self):
+        """Resolved construction state as a JSON-serializable dict.
+
+        Recomputed on each access; reads the ``.dirsql.toml`` if ``config=``
+        was supplied. Works before ``await db.ready()``.
+        """
+        return resolve_config(
+            self._root,
+            self._tables,
+            self._ignore,
+            self._config,
+            self._persist,
+            self._persist_path,
+        )

dirsql-0.3.13/dirsql/resolve_config.py

@@ -0,0 +1,43 @@
+"""Synchronous config resolver for `DirSQL.__dict__`.
+
+Mirrors `DirSQLBuilder::resolve` in the Rust core: explicit kwargs win for
+scalars; tables and ignore lists are concatenated; persist is OR-ed;
+path-valued config fields resolve relative to the config file's parent.
+"""
+
+import os
+import tomllib
+
+
+def resolve_config(root, tables, ignore, config, persist, persist_path):
+    """Merge kwargs with a `.dirsql.toml` into the serialized state shape."""
+    cfg, cfg_tables, cfg_dir = {}, [], None
+    if config is not None:
+        with open(config, "rb") as f:
+            doc = tomllib.load(f)
+        cfg = doc.get("dirsql") or {}
+        cfg_tables = doc.get("table") or []
+        cfg_dir = os.path.dirname(os.path.abspath(config))
+
+    def _abs(p):
+        return p if os.path.isabs(p) else os.path.join(cfg_dir, p)
+
+    return {
+        "root": root or (_abs(cfg["root"]) if "root" in cfg else cfg_dir),
+        "tables": [
+            {"ddl": t.ddl, "glob": t.glob, "strict": bool(t.strict)}
+            for t in (tables or [])
+        ]
+        + [
+            {
+                "ddl": e.get("ddl"),
+                "glob": e.get("glob"),
+                "strict": bool(e.get("strict")),
+            }
+            for e in cfg_tables
+        ],
+        "ignore": list(ignore or []) + list(cfg.get("ignore") or []),
+        "persist": bool(persist or cfg.get("persist")),
+        "persist_path": persist_path
+        or (_abs(cfg["persist_path"]) if "persist_path" in cfg else None),
+    }

dirsql-0.3.13/dirsql/resolve_config_test.py

@@ -0,0 +1,231 @@
+"""Unit tests for `resolve_config`."""
+
+import os
+import tempfile
+
+import pytest
+
+from dirsql.resolve_config import resolve_config
+
+
+class _FakeTable:
+    """Stand-in for the PyO3 `Table` class. `resolve_config` only reads
+    `ddl`, `glob`, `strict`, so we don't need the real binding here."""
+
+    def __init__(self, ddl, glob, strict=False):
+        self.ddl = ddl
+        self.glob = glob
+        self.strict = strict
+
+
+@pytest.fixture
+def cfg_dir():
+    with tempfile.TemporaryDirectory() as d:
+        yield d
+
+
+def _write(path, body):
+    with open(path, "w") as f:
+        f.write(body)
+
+
+def describe_resolve_config():
+    def describe_without_a_config_file():
+        def it_forwards_the_root_kwarg(cfg_dir):
+            out = resolve_config("/abs/data", None, None, None, False, None)
+            assert out == {
+                "root": "/abs/data",
+                "tables": [],
+                "ignore": [],
+                "persist": False,
+                "persist_path": None,
+            }
+
+        def it_serializes_a_programmatic_table_with_default_strict():
+            out = resolve_config(
+                "/r",
+                [_FakeTable("x", "*")],
+                None,
+                None,
+                False,
+                None,
+            )
+            assert out["tables"] == [{"ddl": "x", "glob": "*", "strict": False}]
+
+        def it_serializes_a_programmatic_table_with_strict_true():
+            out = resolve_config(
+                "/r",
+                [_FakeTable("x", "*", strict=True)],
+                None,
+                None,
+                False,
+                None,
+            )
+            assert out["tables"][0]["strict"] is True
+
+        def it_forwards_the_ignore_kwarg():
+            out = resolve_config("/r", None, ["**/skip/**"], None, False, None)
+            assert out["ignore"] == ["**/skip/**"]
+
+        def it_forwards_persist_and_persist_path_kwargs():
+            out = resolve_config(
+                "/r",
+                None,
+                None,
+                None,
+                True,
+                "/abs/cache.db",
+            )
+            assert out["persist"] is True
+            assert out["persist_path"] == "/abs/cache.db"
+
+    def describe_with_a_config_file():
+        def it_resolves_a_relative_dirsql_root_against_the_config_parent(cfg_dir):
+            path = os.path.join(cfg_dir, ".dirsql.toml")
+            _write(path, '[dirsql]\nroot = "data"\n')
+            out = resolve_config(None, None, None, path, False, None)
+            assert out["root"] == os.path.join(cfg_dir, "data")
+            assert os.path.isabs(out["root"])
+
+        def it_preserves_an_absolute_dirsql_root_verbatim(cfg_dir):
+            path = os.path.join(cfg_dir, ".dirsql.toml")
+            _write(path, '[dirsql]\nroot = "/other/abs/path"\n')
+            out = resolve_config(None, None, None, path, False, None)
+            assert out["root"] == "/other/abs/path"
+
+        def it_defaults_root_to_config_parent_when_dirsql_root_is_absent(cfg_dir):
+            path = os.path.join(cfg_dir, ".dirsql.toml")
+            _write(path, '[dirsql]\nignore = ["x"]\n')
+            out = resolve_config(None, None, None, path, False, None)
+            assert out["root"] == cfg_dir
+
+        def it_defaults_root_to_config_parent_when_dirsql_section_is_absent(cfg_dir):
+            path = os.path.join(cfg_dir, ".dirsql.toml")
+            _write(
+                path, '[[table]]\nddl = "CREATE TABLE t (x TEXT)"\nglob = "*.json"\n'
+            )
+            out = resolve_config(None, None, None, path, False, None)
+            assert out["root"] == cfg_dir
+
+        def it_reads_table_entries_with_strict_defaulting_to_false(cfg_dir):
+            path = os.path.join(cfg_dir, ".dirsql.toml")
+            _write(
+                path,
+                '[[table]]\nddl = "CREATE TABLE t (x TEXT)"\nglob = "*.json"\n',
+            )
+            out = resolve_config(None, None, None, path, False, None)
+            assert out["tables"] == [
+                {"ddl": "CREATE TABLE t (x TEXT)", "glob": "*.json", "strict": False}
+            ]
+
+        def it_respects_strict_true_on_a_table_entry(cfg_dir):
+            path = os.path.join(cfg_dir, ".dirsql.toml")
+            _write(
+                path,
+                '[[table]]\nddl = "CREATE TABLE t (x TEXT)"\nglob = "*.json"\nstrict = true\n',
+            )
+            out = resolve_config(None, None, None, path, False, None)
+            assert out["tables"][0]["strict"] is True
+
+        def it_returns_empty_tables_when_no_table_entries_declared(cfg_dir):
+            path = os.path.join(cfg_dir, ".dirsql.toml")
+            _write(path, "[dirsql]\nignore = []\n")
+            out = resolve_config(None, None, None, path, False, None)
+            assert out["tables"] == []
+
+        def it_forwards_dirsql_ignore(cfg_dir):
+            path = os.path.join(cfg_dir, ".dirsql.toml")
+            _write(path, '[dirsql]\nignore = ["node_modules/**"]\n')
+            out = resolve_config(None, None, None, path, False, None)
+            assert out["ignore"] == ["node_modules/**"]
+
+        def it_flips_persist_on_when_dirsql_persist_is_true(cfg_dir):
+            path = os.path.join(cfg_dir, ".dirsql.toml")
+            _write(path, "[dirsql]\npersist = true\n")
+            out = resolve_config(None, None, None, path, False, None)
+            assert out["persist"] is True
+
+        def it_resolves_a_relative_persist_path_against_the_config_dir(cfg_dir):
+            path = os.path.join(cfg_dir, ".dirsql.toml")
+            _write(
+                path,
+                '[dirsql]\npersist = true\npersist_path = "cache/dirsql.db"\n',
+            )
+            out = resolve_config(None, None, None, path, False, None)
+            assert out["persist_path"] == os.path.join(cfg_dir, "cache/dirsql.db")
+
+        def it_preserves_an_absolute_persist_path_verbatim(cfg_dir):
+            path = os.path.join(cfg_dir, ".dirsql.toml")
+            _write(path, '[dirsql]\npersist_path = "/var/cache/dirsql.db"\n')
+            out = resolve_config(None, None, None, path, False, None)
+            assert out["persist_path"] == "/var/cache/dirsql.db"
+
+        def it_leaves_persist_path_none_when_absent(cfg_dir):
+            path = os.path.join(cfg_dir, ".dirsql.toml")
+            _write(path, '[dirsql]\nignore = ["x"]\n')
+            out = resolve_config(None, None, None, path, False, None)
+            assert out["persist_path"] is None
+
+    def describe_merging_kwargs_with_a_config_file():
+        def it_explicit_root_wins_over_dirsql_root(cfg_dir):
+            path = os.path.join(cfg_dir, ".dirsql.toml")
+            _write(path, '[dirsql]\nroot = "from-config"\n')
+            out = resolve_config("/from-kwarg", None, None, path, False, None)
+            assert out["root"] == "/from-kwarg"
+
+        def it_concatenates_programmatic_then_config_tables(cfg_dir):
+            path = os.path.join(cfg_dir, ".dirsql.toml")
+            _write(
+                path,
+                '[[table]]\nddl = "CREATE TABLE c (x TEXT)"\nglob = "c/*"\n',
+            )
+            out = resolve_config(
+                "/r",
+                [_FakeTable("p-ddl", "p/*")],
+                None,
+                path,
+                False,
+                None,
+            )
+            assert [t["ddl"] for t in out["tables"]] == [
+                "p-ddl",
+                "CREATE TABLE c (x TEXT)",
+            ]
+
+        def it_concatenates_ignore_kwargs_first_then_config_ignore(cfg_dir):
+            path = os.path.join(cfg_dir, ".dirsql.toml")
+            _write(path, '[dirsql]\nignore = ["from-config/**"]\n')
+            out = resolve_config(
+                "/r",
+                None,
+                ["from-kwarg/**"],
+                path,
+                False,
+                None,
+            )
+            assert out["ignore"] == ["from-kwarg/**", "from-config/**"]
+
+        def it_ors_persist_across_kwarg_true_and_config_absent(cfg_dir):
+            path = os.path.join(cfg_dir, ".dirsql.toml")
+            _write(path, '[dirsql]\nignore = ["x"]\n')
+            out = resolve_config("/r", None, None, path, True, None)
+            assert out["persist"] is True
+
+        def it_ors_persist_across_kwarg_absent_and_config_true(cfg_dir):
+            path = os.path.join(cfg_dir, ".dirsql.toml")
+            _write(path, "[dirsql]\npersist = true\n")
+            out = resolve_config("/r", None, None, path, False, None)
+            assert out["persist"] is True
+
+        def it_explicit_persist_path_wins_over_config_persist_path(cfg_dir):
+            path = os.path.join(cfg_dir, ".dirsql.toml")
+            _write(path, '[dirsql]\npersist_path = "from-config.db"\n')
+            out = resolve_config(
+                "/r",
+                None,
+                None,
+                path,
+                False,
+                "/from-kwarg.db",
+            )
+            assert out["persist_path"] == "/from-kwarg.db"

{dirsql-0.3.12 → dirsql-0.3.13}/docs/api/index.md

@@ -141,6 +141,26 @@ for await (const event of db.watch()) {  // AsyncIterable<RowEvent>
 
 Returns an async iterable of `RowEvent` objects. The file watcher starts automatically on first iteration. The iterator never terminates on its own.
 
+#### `serialization`
+
+::: code-group
+
+```python [Python]
+vars(db) -> dict
+```
+
+```rust [Rust]
+db.config() -> DirSQLConfig
+```
+
+```typescript [TypeScript]
+JSON.stringify(db)  // via db.toJSON()
+```
+
+:::
+
+Returns the resolved construction state as a JSON-compatible value with fields `root`, `tables`, `ignore`, `persist`, `persist_path` (camelCase `persistPath` in TypeScript). Each table is `{ ddl, glob, strict }`. Excludes the original `config` path (already merged into `root` / `tables` / `ignore`), per-table `extract`, and per-table `name`. Available immediately after construction in Python and TypeScript; Rust's sync `build()` returns a ready instance.
+
 ---
 
 ## Table

{dirsql-0.3.12 → dirsql-0.3.13}/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.3.12"
+version = "0.3.13"
 edition.workspace = true
 publish = false
 readme = "README.md"

{dirsql-0.3.12/packages/rust → dirsql-0.3.13/packages/python}/docs/api/index.md

@@ -141,6 +141,26 @@ for await (const event of db.watch()) {  // AsyncIterable<RowEvent>
 
 Returns an async iterable of `RowEvent` objects. The file watcher starts automatically on first iteration. The iterator never terminates on its own.
 
+#### `serialization`
+
+::: code-group
+
+```python [Python]
+vars(db) -> dict
+```
+
+```rust [Rust]
+db.config() -> DirSQLConfig
+```
+
+```typescript [TypeScript]
+JSON.stringify(db)  // via db.toJSON()
+```
+
+:::
+
+Returns the resolved construction state as a JSON-compatible value with fields `root`, `tables`, `ignore`, `persist`, `persist_path` (camelCase `persistPath` in TypeScript). Each table is `{ ddl, glob, strict }`. Excludes the original `config` path (already merged into `root` / `tables` / `ignore`), per-table `extract`, and per-table `name`. Available immediately after construction in Python and TypeScript; Rust's sync `build()` returns a ready instance.
+
 ---
 
 ## Table

dirsql-0.3.13/packages/python/tests/integration/test_serialization.py

@@ -0,0 +1,237 @@
+"""Integration tests for DirSQL config serialization (#194)."""
+
+import json
+import os
+import tempfile
+
+import pytest
+
+from dirsql import DirSQL, Table
+
+
+@pytest.fixture
+def empty_dir():
+    with tempfile.TemporaryDirectory() as d:
+        yield d
+
+
+def _noop_extract(_path):
+    return []
+
+
+def describe_DirSQL_serialization():
+    def describe_top_level_shape():
+        @pytest.mark.asyncio
+        async def it_exposes_resolved_state_via_vars(empty_dir):
+            """`vars(db)` returns the resolved runtime state as a dict."""
+            db = DirSQL(
+                empty_dir,
+                tables=[
+                    Table(
+                        ddl="CREATE TABLE items (name TEXT)",
+                        glob="items/*.json",
+                        extract=_noop_extract,
+                    )
+                ],
+                ignore=["**/skip/**"],
+            )
+
+            state = vars(db)
+            assert isinstance(state, dict)
+            assert set(state.keys()) == {
+                "root",
+                "tables",
+                "ignore",
+                "persist",
+                "persist_path",
+            }
+
+        @pytest.mark.asyncio
+        async def it_returns_json_serializable_dict(empty_dir):
+            """`json.dumps(vars(db))` succeeds with the resolved state."""
+            db = DirSQL(
+                empty_dir,
+                tables=[
+                    Table(
+                        ddl="CREATE TABLE items (name TEXT)",
+                        glob="items/*.json",
+                        extract=_noop_extract,
+                    )
+                ],
+            )
+
+            payload = json.dumps(vars(db))
+            parsed = json.loads(payload)
+            assert parsed["root"] == empty_dir
+            assert isinstance(parsed["tables"], list)
+            assert len(parsed["tables"]) == 1
+            assert parsed["tables"][0]["ddl"] == "CREATE TABLE items (name TEXT)"
+            assert parsed["tables"][0]["glob"] == "items/*.json"
+            assert parsed["tables"][0]["strict"] is False
+            assert parsed["ignore"] == []
+            assert parsed["persist"] is False
+            assert parsed["persist_path"] is None
+
+        @pytest.mark.asyncio
+        async def it_works_before_ready(empty_dir):
+            """`vars(db)` is available immediately, before the scan finishes."""
+            db = DirSQL(
+                empty_dir,
+                tables=[
+                    Table(
+                        ddl="CREATE TABLE items (name TEXT)",
+                        glob="items/*.json",
+                        extract=_noop_extract,
+                    )
+                ],
+            )
+            # Read state before awaiting ready -- must not raise.
+            state = vars(db)
+            assert state["root"] == empty_dir
+            # And still works after ready, with the same shape.
+            await db.ready()
+            assert vars(db) == state
+
+    def describe_table_shape():
+        @pytest.mark.asyncio
+        async def it_excludes_extract_from_tables(empty_dir):
+            """Each serialized table must NOT include the `extract` closure."""
+            db = DirSQL(
+                empty_dir,
+                tables=[
+                    Table(
+                        ddl="CREATE TABLE items (name TEXT)",
+                        glob="items/*.json",
+                        extract=_noop_extract,
+                    )
+                ],
+            )
+
+            state = vars(db)
+            assert state["tables"]
+            for t in state["tables"]:
+                assert "extract" not in t
+
+        @pytest.mark.asyncio
+        async def it_excludes_name_from_tables(empty_dir):
+            """Each serialized table must NOT include a `name` field."""
+            db = DirSQL(
+                empty_dir,
+                tables=[
+                    Table(
+                        ddl="CREATE TABLE items (name TEXT)",
+                        glob="items/*.json",
+                        extract=_noop_extract,
+                    )
+                ],
+            )
+
+            state = vars(db)
+            for t in state["tables"]:
+                assert "name" not in t
+
+    def describe_defaults():
+        @pytest.mark.asyncio
+        async def it_defaults_strict_to_false(empty_dir):
+            db = DirSQL(
+                empty_dir,
+                tables=[
+                    Table(
+                        ddl="CREATE TABLE items (name TEXT)",
+                        glob="items/*.json",
+                        extract=_noop_extract,
+                    )
+                ],
+            )
+            state = vars(db)
+            assert state["tables"][0]["strict"] is False
+
+        @pytest.mark.asyncio
+        async def it_defaults_persist_to_false_and_persist_path_to_none(empty_dir):
+            db = DirSQL(
+                empty_dir,
+                tables=[
+                    Table(
+                        ddl="CREATE TABLE items (name TEXT)",
+                        glob="items/*.json",
+                        extract=_noop_extract,
+                    )
+                ],
+            )
+            state = vars(db)
+            assert state["persist"] is False
+            assert state["persist_path"] is None
+
+    def describe_persist_overrides():
+        @pytest.mark.asyncio
+        async def it_reflects_persist_true_and_custom_persist_path(empty_dir):
+            persist_path = os.path.join(empty_dir, "custom-cache.db")
+            db = DirSQL(
+                empty_dir,
+                tables=[
+                    Table(
+                        ddl="CREATE TABLE items (name TEXT)",
+                        glob="items/*.json",
+                        extract=_noop_extract,
+                    )
+                ],
+                persist=True,
+                persist_path=persist_path,
+            )
+            state = vars(db)
+            assert state["persist"] is True
+            assert state["persist_path"] == persist_path
+
+    def describe_ignore_patterns():
+        @pytest.mark.asyncio
+        async def it_includes_ignore_list(empty_dir):
+            db = DirSQL(
+                empty_dir,
+                tables=[
+                    Table(
+                        ddl="CREATE TABLE items (name TEXT)",
+                        glob="items/*.json",
+                        extract=_noop_extract,
+                    )
+                ],
+                ignore=["**/skip/**", "**/temp/**"],
+            )
+            state = vars(db)
+            assert state["ignore"] == ["**/skip/**", "**/temp/**"]
+
+    def describe_config_file():
+        @pytest.mark.asyncio
+        async def it_merges_root_tables_ignore_from_config(empty_dir):
+            """A `.dirsql.toml` config feeds into the serialized state."""
+            cfg_path = os.path.join(empty_dir, ".dirsql.toml")
+            with open(cfg_path, "w") as f:
+                f.write(
+                    "[dirsql]\n"
+                    'root = "data"\n'
+                    'ignore = ["node_modules/**"]\n'
+                    "persist = true\n"
+                    'persist_path = "cache.db"\n'
+                    "\n"
+                    "[[table]]\n"
+                    'ddl = "CREATE TABLE items (_path TEXT)"\n'
+                    'glob = "*.json"\n'
+                    "strict = true\n"
+                )
+            # Create the directory the config expects so the background
+            # scan doesn't blow up later -- we don't await ready() here,
+            # but the underlying Rust constructor still needs it on its
+            # own thread.
+            os.makedirs(os.path.join(empty_dir, "data"), exist_ok=True)
+
+            db = DirSQL(config=cfg_path)
+            state = vars(db)
+            assert state["root"] == os.path.join(empty_dir, "data")
+            assert state["ignore"] == ["node_modules/**"]
+            assert state["persist"] is True
+            assert state["persist_path"] == os.path.join(empty_dir, "cache.db")
+            assert len(state["tables"]) == 1
+            assert state["tables"][0] == {
+                "ddl": "CREATE TABLE items (_path TEXT)",
+                "glob": "*.json",
+                "strict": True,
+            }

{dirsql-0.3.12/packages/python → dirsql-0.3.13/packages/rust}/docs/api/index.md

@@ -141,6 +141,26 @@ for await (const event of db.watch()) {  // AsyncIterable<RowEvent>
 
 Returns an async iterable of `RowEvent` objects. The file watcher starts automatically on first iteration. The iterator never terminates on its own.
 
+#### `serialization`
+
+::: code-group
+
+```python [Python]
+vars(db) -> dict
+```
+
+```rust [Rust]
+db.config() -> DirSQLConfig
+```
+
+```typescript [TypeScript]
+JSON.stringify(db)  // via db.toJSON()
+```
+
+:::
+
+Returns the resolved construction state as a JSON-compatible value with fields `root`, `tables`, `ignore`, `persist`, `persist_path` (camelCase `persistPath` in TypeScript). Each table is `{ ddl, glob, strict }`. Excludes the original `config` path (already merged into `root` / `tables` / `ignore`), per-table `extract`, and per-table `name`. Available immediately after construction in Python and TypeScript; Rust's sync `build()` returns a ready instance.
+
 ---
 
 ## Table