dirsql 0.2.5__tar.gz → 0.2.7__tar.gz

{dirsql-0.2.5 → dirsql-0.2.7}/PKG-INFO

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

dirsql-0.2.7/docs/.claude/CLAUDE.md

@@ -0,0 +1,3 @@
+# dirsql docs
+
+@../AGENTS.md

dirsql-0.2.7/docs/.vitepress/config.ts

@@ -0,0 +1,63 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  title: 'dirsql',
+  description: 'Ephemeral SQL index over a local directory. Watches a filesystem, ingests structured files into an in-memory SQLite database, and exposes a SQL query interface.',
+  base: '/dirsql/',
+
+  themeConfig: {
+    search: {
+      provider: 'local'
+    },
+
+    nav: [
+      { text: 'Getting Started', link: '/getting-started' },
+      { text: 'Guide', link: '/guide/tables' },
+      { text: 'Reference', link: '/api/' },
+      { text: 'Migrations', link: '/migrations' },
+      { text: 'GitHub', link: 'https://github.com/thekevinscott/dirsql' }
+    ],
+
+    sidebar: [
+      {
+        text: 'Tutorials',
+        items: [
+          { text: 'Getting Started', link: '/getting-started' }
+        ]
+      },
+      {
+        text: 'How-to Guides',
+        items: [
+          { text: 'Configuration File', link: '/guide/config' },
+          { text: 'Defining Tables', link: '/guide/tables' },
+          { text: 'Querying', link: '/guide/querying' },
+          { text: 'File Watching', link: '/guide/watching' },
+          { text: 'Async API', link: '/guide/async' },
+          { text: 'Command-Line Interface', link: '/guide/cli' },
+          { text: 'Collaboration with CRDTs', link: '/guide/crdt' }
+        ]
+      },
+      {
+        text: 'Reference',
+        items: [
+          { text: 'API Reference', link: '/api/' },
+          { text: 'Migrations', link: '/migrations' }
+        ]
+      },
+    ],
+
+    outline: {
+      level: [2, 3],
+      label: 'On this page'
+    },
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/thekevinscott/dirsql' }
+    ],
+
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright 2024-present'
+    }
+  }
+})

dirsql-0.2.7/docs/.vitepress/theme/index.ts

@@ -0,0 +1,154 @@
+import DefaultTheme from 'vitepress/theme'
+import type { Theme } from 'vitepress'
+
+/**
+ * Language tab persistence for VitePress code groups.
+ *
+ * VitePress code groups render as:
+ *   .vp-code-group
+ *     .tabs
+ *       input[type=radio]  (hidden, controls checked state)
+ *       label[for=...]     (visible tab)
+ *       input
+ *       label
+ *       ...
+ *     .blocks
+ *       div.language-python.active   (visible block)
+ *       div.language-typescript      (hidden block)
+ *       ...
+ *
+ * Tab switching is driven by click events on the hidden inputs.
+ * Active blocks are toggled via the .active CSS class.
+ */
+
+import { STORAGE_KEY, parseLanguageFromUrl } from './lang'
+
+const getLanguageFromUrl = (): string | null =>
+  parseLanguageFromUrl(window.location.search, window.location.hash)
+
+/**
+ * Given a code group element, return parallel arrays of inputs, labels, and blocks.
+ */
+function getGroupParts(group: Element) {
+  const inputs = Array.from(group.querySelectorAll<HTMLInputElement>('.tabs input'))
+  const labels = Array.from(group.querySelectorAll<HTMLLabelElement>('.tabs label'))
+  const blocks = group.querySelector('.blocks')
+  const blockChildren = blocks
+    ? Array.from(blocks.children) as HTMLElement[]
+    : []
+  return { inputs, labels, blocks: blockChildren }
+}
+
+function applyStoredLanguage() {
+  const lang = localStorage.getItem(STORAGE_KEY)
+  if (!lang) return
+
+  document.querySelectorAll('.vp-code-group').forEach((group) => {
+    const { inputs, labels, blocks } = getGroupParts(group)
+
+    const idx = labels.findIndex(
+      (label) => label.textContent?.trim().toLowerCase() === lang
+    )
+    if (idx < 0) return
+
+    const input = inputs[idx]
+    if (!input || input.checked) return
+
+    // Check the radio button (drives CSS styling via input:checked + label)
+    input.checked = true
+
+    // Toggle .active class on blocks (drives visibility)
+    blocks.forEach((block, j) => {
+      block.classList.toggle('active', j === idx)
+    })
+  })
+}
+
+function observeTabClicks() {
+  // VitePress code groups use click events on inputs, not change events.
+  window.addEventListener('click', (e) => {
+    const el = e.target as HTMLElement
+    if (!el.matches('.vp-code-group input')) return
+
+    // input -> .tabs -> .vp-code-group
+    const group = el.parentElement?.parentElement
+    if (!group) return
+
+    const { inputs, labels } = getGroupParts(group)
+    const idx = inputs.indexOf(el as HTMLInputElement)
+    if (idx < 0 || !labels[idx]) return
+
+    const lang = labels[idx].textContent?.trim().toLowerCase()
+    if (!lang) return
+
+    localStorage.setItem(STORAGE_KEY, lang)
+
+    // Sync all other code groups on the same page
+    document.querySelectorAll('.vp-code-group').forEach((otherGroup) => {
+      if (otherGroup === group) return
+      const other = getGroupParts(otherGroup)
+      const otherIdx = other.labels.findIndex(
+        (l) => l.textContent?.trim().toLowerCase() === lang
+      )
+      if (otherIdx < 0) return
+      const otherInput = other.inputs[otherIdx]
+      if (!otherInput || otherInput.checked) return
+      otherInput.checked = true
+      other.blocks.forEach((block, j) => {
+        block.classList.toggle('active', j === otherIdx)
+      })
+    })
+  })
+}
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp() {
+    if (typeof window === 'undefined') return
+
+    // URL flag wins over any previously stored preference, but we only persist
+    // once we've confirmed the value matches a real tab -- typos shouldn't
+    // poison localStorage. `pendingUrlLang` is consumed the first time a
+    // matching render arrives.
+    let pendingUrlLang: string | null = getLanguageFromUrl()
+    const consumePendingLang = () => {
+      if (!pendingUrlLang) return
+      const matches = Array.from(
+        document.querySelectorAll<HTMLLabelElement>('.vp-code-group .tabs label')
+      ).some((l) => l.textContent?.trim().toLowerCase() === pendingUrlLang)
+      if (!matches) return
+      localStorage.setItem(STORAGE_KEY, pendingUrlLang)
+      pendingUrlLang = null
+    }
+    window.addEventListener('hashchange', () => {
+      pendingUrlLang = getLanguageFromUrl()
+      consumePendingLang()
+      applyStoredLanguage()
+    })
+
+    observeTabClicks()
+
+    // Use MutationObserver to apply stored preference after VitePress renders
+    const observer = new MutationObserver(() => {
+      consumePendingLang()
+      applyStoredLanguage()
+    })
+
+    const tryObserve = () => {
+      const content = document.querySelector('.VPContent')
+      if (content) {
+        observer.observe(content, { childList: true, subtree: true })
+        consumePendingLang()
+        applyStoredLanguage()
+      } else {
+        requestAnimationFrame(tryObserve)
+      }
+    }
+
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', tryObserve)
+    } else {
+      tryObserve()
+    }
+  },
+} satisfies Theme

dirsql-0.2.7/docs/.vitepress/theme/lang.ts

@@ -0,0 +1,33 @@
+/**
+ * Pure helpers for the code-group language URL flag.
+ * Extracted from theme/index.ts so they can be unit tested without a DOM.
+ */
+
+export const STORAGE_KEY = 'dirsql-preferred-lang'
+export const URL_PARAM = 'lang'
+
+/**
+ * Read a language preference from a URL's search and/or hash components.
+ * Accepts the `window.location.search`/`window.location.hash` strings
+ * (with or without their leading `?` / `#`). The query form takes
+ * precedence over the hash form. Returns the lowercased language name,
+ * or null when no flag is present.
+ */
+export function parseLanguageFromUrl(
+  search: string,
+  hash: string
+): string | null {
+  try {
+    const query = new URLSearchParams(search).get(URL_PARAM)
+    if (query) return query.trim().toLowerCase()
+
+    const stripped = hash.replace(/^#/, '')
+    if (stripped) {
+      const fromHash = new URLSearchParams(stripped).get(URL_PARAM)
+      if (fromHash) return fromHash.trim().toLowerCase()
+    }
+  } catch {
+    // URL APIs can throw on exotic inputs; fall through to null.
+  }
+  return null
+}

dirsql-0.2.7/docs/AGENTS.md

@@ -0,0 +1,51 @@
+# Documentation Development
+
+Instructions for agents working on `dirsql` documentation.
+
+## Stack
+
+The docs site uses [VitePress](https://vitepress.dev/). Source files are in `docs/` at the project root.
+
+## Running locally
+
+```bash
+cd docs
+pnpm install
+pnpm dev
+```
+
+This starts a local dev server (default: `http://localhost:5173/dirsql/`). The site hot-reloads on file changes.
+
+## Building
+
+```bash
+cd docs
+pnpm build
+```
+
+The build must succeed before pushing. VitePress will fail on broken links, missing assets, and syntax errors in markdown.
+
+## Testing changes
+
+Before pushing any docs changes:
+
+1. Run `pnpm build` in `docs/` and confirm it exits cleanly
+2. Spot-check the built output with `pnpm preview`
+3. Verify sidebar navigation, code blocks, and internal links render correctly
+
+## Structure
+
+The docs follow the [Diataxis](https://diataxis.fr/) framework:
+
+- **Tutorials** (`getting-started.md`) -- learning-oriented, step-by-step
+- **How-to Guides** (`guide/`) -- task-oriented, practical recipes
+- **Reference** (`api/`) -- information-oriented, API details
+- **Explanation** (`architecture.md`) -- understanding-oriented, design decisions
+
+## Conventions
+
+- Wrap `dirsql` in backticks in all prose text
+- Use VitePress [code group](https://vitepress.dev/guide/markdown#code-groups) syntax (`::: code-group`) for multi-language examples with `Python`, `Rust`, and `TypeScript` tabs
+- Internal links use relative paths (e.g., `./guide/tables.md`)
+- The VitePress config is at `docs/.vitepress/config.ts`
+- The site is deployed under the `/dirsql/` base path

dirsql-0.2.7/docs/api/index.md

@@ -0,0 +1,232 @@
+---
+canonical: https://thekevinscott.github.io/dirsql/api/
+---
+
+# API Reference
+
+> Online: <https://thekevinscott.github.io/dirsql/api/>
+
+## DirSQL
+
+### Import
+
+::: code-group
+
+```python [Python]
+from dirsql import DirSQL
+```
+
+```rust [Rust]
+use dirsql::DirSQL;
+```
+
+```typescript [TypeScript]
+import { DirSQL } from 'dirsql';
+```
+
+:::
+
+### Constructor
+
+::: code-group
+
+```python [Python]
+DirSQL(
+    root: str | None = None,
+    *,
+    tables: list[Table] | None = None,
+    ignore: list[str] | None = None,
+    config: str | None = None,
+)
+```
+
+```rust [Rust]
+DirSQL::builder()
+    .root(root)                 // optional
+    .tables(tables)             // optional; append with .table(t)
+    .ignore(patterns)           // optional
+    .config(config_toml_path)   // optional
+    .build()                    // -> Result<DirSQL>
+```
+
+```typescript [TypeScript]
+new DirSQL(configPath: string)
+// or
+new DirSQL({
+    root?: string,
+    tables?: TableDef[],
+    ignore?: string[],
+    config?: string,
+})
+```
+
+:::
+
+Creates an in-memory SQLite index over the given directory. At least one of `root` or `config` must be supplied.
+
+When both `root` and `config` are supplied -- or when `config` declares `[dirsql].root` -- the explicit `root` wins and a warning is emitted on stderr. A `[dirsql].root` declared in the config file is resolved relative to the config file's parent directory.
+
+In Python, the constructor starts scanning in a background thread and returns immediately. Call `await db.ready()` before querying. In Rust, `.build()` scans synchronously; use `.build_async()` (via `AsyncDirSQL`) for the tokio-driven equivalent. In TypeScript, scanning starts immediately and `db.ready` resolves when the scan finishes.
+
+**Parameters:**
+
+- `root` -- Path to the directory to index. Optional if `config` is supplied.
+- `tables` -- List of `Table` definitions. Each defines a SQLite table, a glob pattern, and an extract function.
+- `ignore` -- Optional list of glob patterns. Files matching any ignore pattern are skipped regardless of table globs.
+- `config` -- Optional path to a `.dirsql.toml` config file. Its `[[table]]` entries are appended to any programmatic `tables`; its `[dirsql].ignore` patterns are appended to any explicit `ignore`; its optional `[dirsql].root` supplies the root directory when `root` is not passed explicitly.
+
+### Methods
+
+#### `ready`
+
+::: code-group
+
+```python [Python]
+await db.ready() -> None
+```
+
+```rust [Rust]
+db.ready().await -> Result<()>
+```
+
+```typescript [TypeScript]
+await db.ready  // awaitable property
+```
+
+:::
+
+Wait for the initial scan to complete. Re-raises any exception from the scan. Safe to call multiple times.
+
+#### `query`
+
+::: code-group
+
+```python [Python]
+await db.query(sql: str) -> list[dict]
+```
+
+```rust [Rust]
+db.query(sql: &str) -> Result<Vec<HashMap<String, Value>>>
+```
+
+```typescript [TypeScript]
+await db.query(sql: string): Promise<Record<string, unknown>[]>
+```
+
+:::
+
+Execute a SQL query against the in-memory database. Returns results keyed by column name. Internal tracking columns (`_dirsql_file_path`, `_dirsql_row_index`) are excluded from results.
+
+#### `watch`
+
+::: code-group
+
+```python [Python]
+async for event in db.watch():  # AsyncIterator[RowEvent]
+    ...
+```
+
+```rust [Rust]
+let mut stream = db.watch();  // impl Stream<Item = RowEvent>
+while let Some(event) = stream.next().await { ... }
+```
+
+```typescript [TypeScript]
+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.
+
+---
+
+## Table
+
+### Import
+
+::: code-group
+
+```python [Python]
+from dirsql import Table
+```
+
+```rust [Rust]
+use dirsql::Table;
+```
+
+```typescript [TypeScript]
+import { Table } from 'dirsql';
+```
+
+:::
+
+### Constructor
+
+::: code-group
+
+```python [Python]
+Table(*, ddl: str, glob: str, extract: Callable[[str, str], list[dict]])
+```
+
+```rust [Rust]
+Table::new(ddl: &str, glob: &str, extract: fn(&str, &str) -> Vec<Value>)
+```
+
+```typescript [TypeScript]
+new Table({ ddl: string, glob: string, extract: (path: string, content: string) => Record<string, unknown>[] })
+```
+
+:::
+
+Defines a mapping from files to SQLite table rows.
+
+**Parameters:**
+
+- `ddl` -- A `CREATE TABLE` statement. The table name is parsed from this DDL.
+- `glob` -- A glob pattern matched against file paths relative to the root directory.
+- `extract` -- A callable `(path, content) -> list[dict]`. Receives the relative file path and file content as strings. Returns a list of dicts/maps mapping column names to values. Return an empty list to skip a file.
+
+**Attributes:**
+
+- `ddl` -- The DDL string (read-only).
+- `glob` -- The glob pattern (read-only).
+
+---
+
+## RowEvent
+
+### Import
+
+::: code-group
+
+```python [Python]
+from dirsql import RowEvent
+```
+
+```rust [Rust]
+use dirsql::RowEvent;
+```
+
+```typescript [TypeScript]
+import { RowEvent } from 'dirsql';
+```
+
+:::
+
+Emitted by the watch stream. Represents a change to a row in the database caused by a filesystem event.
+
+**Attributes:**
+
+| Attribute | Python | Rust | TypeScript |
+|-----------|--------|------|------------|
+| Table name | `table: str` | `table: String` | `table: string` |
+| Action | `action: str` | `action: Action` | `action: string` |
+| Current/new row | `row: dict \| None` | `row: Option<HashMap>` | `row?: Record` |
+| Previous row | `old_row: dict \| None` | `old_row: Option<HashMap>` | `oldRow?: Record` |
+| Error message | `error: str \| None` | `error: Option<String>` | `error?: string` |
+| File path | `file_path: str \| None` | `file_path: Option<String>` | `filePath?: string` |
+
+Action values: `"insert"`, `"update"`, `"delete"`, `"error"`.