duckboard 0.1.0__tar.gz

duckboard-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Duckboard local state
+.duckboard/
+
+# Temp / debug artifacts
+debug_*.py
+tmp_*/
+tmp_*
+followers.json
+
+# Mangled test output (from failed Windows path writes)
+Users*/

duckboard-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to duckboard are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [0.1.0] - 2026-08-20
+
+### Added
+- `DuckboardSession` core engine with DuckDB connection management
+- `FileCatalog` — register files as queryable DuckDB views
+- Supported formats: CSV, TSV, PSV (pipe-separated), Parquet, JSON, JSONL, NDJSON
+- `formatter.py` — box-drawing terminal output with numeric right-alignment,
+  NULL rendering, 50-row display cap, and row count footer
+- Interactive REPL (`repl.py`) with:
+  - Semicolon-terminated multiline SQL
+  - `:command` dispatch
+  - readline history via `pyreadline3` (optional dep, Windows)
+  - Clean exit on `:quit`, `:q`, `exit`, `quit`, Ctrl+D
+- REPL commands: `:load`, `:tables`, `:schema`, `:save`, `:unload`, `:pwd`
+- `:load` — quoted path support, optional `as name` (defaults to filename stem)
+- `:save` — auto-detect format from extension, explicit `--csv/--parquet/--json` override
+- Large export warning prompt (2,000+ rows)
+- Windows path normalization throughout (backslash → forward slash)
+- `cli.py` entrypoint with `--version` and `--help`
+- 45 tests passing across catalog, session, formatter, REPL, commands, CLI, and smoke test
+
+## [Unreleased] - v0.2.0
+
+### Planned
+- CSV/PSV/TSV validation on `:load` (column count mismatch detection)
+- No-header detection with `--no-header` flag and column name prompt
+- Malformed row storage in `_errors_{name}` session table
+- `:export_errors <table>` and `:export_clean <table>` commands
+- `:tables` warning indicator for tables with errors

duckboard-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.5
+Name: duckboard
+Version: 0.1.0
+Summary: File-first local SQL workspace for CSV, PSV, Parquet, and JSON — powered by DuckDB.
+Project-URL: Homepage, https://github.com/OmUniyal/duckboard
+Project-URL: Repository, https://github.com/OmUniyal/duckboard
+Project-URL: Issues, https://github.com/OmUniyal/duckboard/issues
+Author: Om Uniyal
+License-Expression: MIT
+Keywords: analytics,cli,csv,duckdb,parquet,repl,sql
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: duckdb>=1.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Provides-Extra: readline
+Requires-Dist: pyreadline3>=3.0; (sys_platform == 'win32') and extra == 'readline'
+Description-Content-Type: text/markdown
+
+# duckboard
+
+File-first local SQL workspace for CSV, Parquet, PSV, and JSON — powered by [DuckDB](https://duckdb.org/).
+
+Load files once, query by name with plain SQL, export results. Terminal-native alternative to spinning up a notebook for quick file questions.
+
+> **Status:** Alpha — core functionality complete, PyPI release coming soon.
+
+## Install
+
+```powershell
+pip install duckboard
+```
+
+**Development install:**
+
+```powershell
+git clone https://github.com/OmUniyal/duckboard
+cd duckboard
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```powershell
+duckboard
+```
+
+```
+duckboard> :load examples/sample.csv as sample
+duckboard> SELECT color, COUNT(*) AS n FROM sample GROUP BY 1;
+┌────────┬───┐
+│ color  │ n │
+├────────┼───┤
+│ blue   │ 1 │
+│ green  │ 1 │
+│ red    │ 2 │
+└────────┴───┘
+(3 rows)
+duckboard> :save results.csv
+Saved 3 rows to results.csv
+duckboard> :quit
+Bye.
+```
+
+## Supported file formats
+
+| Extension              | Format  |
+|------------------------|---------|
+| `.csv`, `.tsv`         | CSV     |
+| `.psv`                 | PSV (pipe-separated) |
+| `.parquet`             | Parquet |
+| `.json`, `.jsonl`, `.ndjson` | JSON |
+
+## REPL commands
+
+| Command | Description |
+|---------|-------------|
+| `:load "path/to/file.ext" [as name]` | Load a file as a queryable table. Name defaults to filename stem. |
+| `:tables` | List all loaded tables with format and path. |
+| `:schema <table>` | Show column names, types, and nullability for a table. |
+| `:save "path/to/output.ext" [--csv\|--parquet\|--json]` | Save last query result to a file. Format auto-detected from extension; use flag to override. |
+| `:unload <table>` | Remove a loaded table from the session. |
+| `:pwd` | Show current working directory. |
+| `:quit` / `:q` / `exit` / `quit` / `Ctrl+D` | Exit duckboard. |
+
+## Notes
+
+- Queries display a maximum of 50 rows in the terminal. Full results are always exported via `:save`.
+- Large exports (2,000+ rows) prompt for confirmation before writing.
+- On Windows, use forward slashes in paths: `:load data/sales.csv` not `:load data\sales.csv`.
+- Multi-line SQL is supported — statements execute on semicolon.
+
+## Project layout
+
+```
+src/duckboard/
+├── session.py      # DuckboardSession — owns DuckDB connection + state
+├── catalog.py      # Registered file → view mappings
+├── repl.py         # Interactive REPL loop
+├── commands.py     # :load, :tables, :schema, :save, :unload, :pwd
+├── formatter.py    # Box-drawing table output for query results
+├── cli.py          # CLI entry point
+└── exceptions.py   # DuckboardError hierarchy
+```
+
+## License
+
+MIT

duckboard-0.1.0/README.md

@@ -0,0 +1,91 @@
+# duckboard
+
+File-first local SQL workspace for CSV, Parquet, PSV, and JSON — powered by [DuckDB](https://duckdb.org/).
+
+Load files once, query by name with plain SQL, export results. Terminal-native alternative to spinning up a notebook for quick file questions.
+
+> **Status:** Alpha — core functionality complete, PyPI release coming soon.
+
+## Install
+
+```powershell
+pip install duckboard
+```
+
+**Development install:**
+
+```powershell
+git clone https://github.com/OmUniyal/duckboard
+cd duckboard
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```powershell
+duckboard
+```
+
+```
+duckboard> :load examples/sample.csv as sample
+duckboard> SELECT color, COUNT(*) AS n FROM sample GROUP BY 1;
+┌────────┬───┐
+│ color  │ n │
+├────────┼───┤
+│ blue   │ 1 │
+│ green  │ 1 │
+│ red    │ 2 │
+└────────┴───┘
+(3 rows)
+duckboard> :save results.csv
+Saved 3 rows to results.csv
+duckboard> :quit
+Bye.
+```
+
+## Supported file formats
+
+| Extension              | Format  |
+|------------------------|---------|
+| `.csv`, `.tsv`         | CSV     |
+| `.psv`                 | PSV (pipe-separated) |
+| `.parquet`             | Parquet |
+| `.json`, `.jsonl`, `.ndjson` | JSON |
+
+## REPL commands
+
+| Command | Description |
+|---------|-------------|
+| `:load "path/to/file.ext" [as name]` | Load a file as a queryable table. Name defaults to filename stem. |
+| `:tables` | List all loaded tables with format and path. |
+| `:schema <table>` | Show column names, types, and nullability for a table. |
+| `:save "path/to/output.ext" [--csv\|--parquet\|--json]` | Save last query result to a file. Format auto-detected from extension; use flag to override. |
+| `:unload <table>` | Remove a loaded table from the session. |
+| `:pwd` | Show current working directory. |
+| `:quit` / `:q` / `exit` / `quit` / `Ctrl+D` | Exit duckboard. |
+
+## Notes
+
+- Queries display a maximum of 50 rows in the terminal. Full results are always exported via `:save`.
+- Large exports (2,000+ rows) prompt for confirmation before writing.
+- On Windows, use forward slashes in paths: `:load data/sales.csv` not `:load data\sales.csv`.
+- Multi-line SQL is supported — statements execute on semicolon.
+
+## Project layout
+
+```
+src/duckboard/
+├── session.py      # DuckboardSession — owns DuckDB connection + state
+├── catalog.py      # Registered file → view mappings
+├── repl.py         # Interactive REPL loop
+├── commands.py     # :load, :tables, :schema, :save, :unload, :pwd
+├── formatter.py    # Box-drawing table output for query results
+├── cli.py          # CLI entry point
+└── exceptions.py   # DuckboardError hierarchy
+```
+
+## License
+
+MIT

duckboard-0.1.0/examples/sample.csv

@@ -0,0 +1,5 @@
+id,color,amount
+1,red,10.5
+2,blue,20.0
+3,red,15.25
+4,green,8.0

duckboard-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "duckboard"
+version = "0.1.0"
+description = "File-first local SQL workspace for CSV, PSV, Parquet, and JSON — powered by DuckDB."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "Om Uniyal" },
+]
+keywords = ["duckdb", "sql", "csv", "parquet", "cli", "repl", "analytics"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "duckdb>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=5.0.0",
+    "ruff>=0.5.0",
+    "mypy>=1.10.0",
+]
+readline = ["pyreadline3>=3.0; sys_platform == 'win32'"]
+
+[project.scripts]
+duckboard = "duckboard.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/OmUniyal/duckboard"
+Repository = "https://github.com/OmUniyal/duckboard"
+Issues = "https://github.com/OmUniyal/duckboard/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/duckboard"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

duckboard-0.1.0/src/duckboard/__init__.py

@@ -0,0 +1,11 @@
+"""duckboard: file-first local SQL workspace powered by DuckDB."""
+
+from duckboard.exceptions import DuckboardError
+from duckboard.session import DuckboardSession
+
+__version__ = "0.0.0"
+
+__all__ = [
+    "DuckboardSession",
+    "DuckboardError",
+]

duckboard-0.1.0/src/duckboard/catalog.py

@@ -0,0 +1,105 @@
+"""File catalog — register paths as queryable table/view names."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+import duckdb
+
+from duckboard.exceptions import CatalogError
+
+_NAME_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+_CSV_EXTENSIONS = {".csv", ".tsv"}
+_PSV_EXTENSIONS = {".psv"}
+_PARQUET_EXTENSIONS = {".parquet"}
+_JSON_EXTENSIONS = {".json", ".jsonl", ".ndjson"}
+
+
+@dataclass(frozen=True)
+class CatalogEntry:
+    """One registered file."""
+
+    name: str
+    path: Path
+    format: str  # "csv", "psv", "parquet", or "json"
+
+
+def _validate_name(name: str) -> None:
+    if not _NAME_PATTERN.match(name):
+        raise CatalogError(
+            f"Invalid table name {name!r}. Use letters, numbers, underscore; "
+            "must not start with a number."
+        )
+
+
+def _detect_format(path: Path) -> str:
+    ext = path.suffix.lower()
+    if ext in _CSV_EXTENSIONS:
+        return "csv"
+    if ext in _PSV_EXTENSIONS:
+        return "psv"
+    if ext in _PARQUET_EXTENSIONS:
+        return "parquet"
+    if ext in _JSON_EXTENSIONS:
+        return "json"
+    raise CatalogError(
+        f"Unsupported file type {ext!r} for {path}. "
+        "Supported: .csv, .tsv, .psv, .parquet, .json, .jsonl, .ndjson"
+    )
+
+
+def _read_function(fmt: str, path: Path) -> str:
+    """Return DuckDB read_* SQL for a file path."""
+    # Forward slashes keep Windows paths safe inside SQL string literals.
+    path_literal = str(path.resolve()).replace("\\", "/").replace("'", "''")
+    if fmt == "csv":
+        return f"read_csv_auto('{path_literal}')"
+    if fmt == "psv":
+        return f"read_csv_auto('{path_literal}', sep='|')"
+    if fmt == "parquet":
+        return f"read_parquet('{path_literal}')"
+    if fmt == "json":
+        return f"read_json_auto('{path_literal}')"
+    raise CatalogError(f"Unknown format: {fmt}")
+
+
+class FileCatalog:
+    """Register files as DuckDB views queryable by name."""
+
+    def __init__(self, conn: duckdb.DuckDBPyConnection) -> None:
+        self._conn = conn
+        self._entries: dict[str, CatalogEntry] = {}
+
+    def load(self, name: str, path: str | Path) -> CatalogEntry:
+        _validate_name(name)
+
+        resolved = Path(path).expanduser().resolve()
+        if not resolved.is_file():
+            raise CatalogError(f"File not found: {resolved}")
+
+        fmt = _detect_format(resolved)
+        read_fn = _read_function(fmt, resolved)
+
+        self._conn.execute(f"CREATE OR REPLACE VIEW {name} AS SELECT * FROM {read_fn}")
+
+        entry = CatalogEntry(name=name, path=resolved, format=fmt)
+        self._entries[name] = entry
+        return entry
+
+    def list_tables(self) -> list[CatalogEntry]:
+        return sorted(self._entries.values(), key=lambda e: e.name)
+
+    def get(self, name: str) -> CatalogEntry:
+        try:
+            return self._entries[name]
+        except KeyError as exc:
+            raise CatalogError(f"Table {name!r} is not loaded.") from exc
+
+    def unload(self, name: str) -> None:
+        if name not in self._entries:
+            raise CatalogError(f"No table named '{name}' is loaded.")
+        self._conn.execute(f"DROP VIEW IF EXISTS {name}")
+        del self._entries[name]

duckboard-0.1.0/src/duckboard/cli.py

@@ -0,0 +1,62 @@
+"""CLI entrypoint — parses args and launches the REPL."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from duckboard import __version__
+
+from duckboard.repl import run_repl
+from duckboard.session import DuckboardSession
+
+
+HELP_EPILOG = """
+REPL commands:
+  :load "path/to/file.ext" [as name]        Load a file as a queryable table
+  :tables                                    List all loaded tables
+  :schema <table>                            Show column types for a table
+  :save "path/to/output.ext"                 Save last query result to file
+         [--csv|--parquet|--json]
+  :unload <table>                            Remove a loaded table
+  :pwd                                       Show current working directory
+  :quit / :q / exit / quit / Ctrl+D         Exit duckboard
+
+links:
+  Repo:  https://github.com/OmUniyal/duckboard
+
+examples:
+  duckboard                  Launch the interactive REPL
+  duckboard --version        Print version and exit
+"""
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="duckboard",
+        description=(
+            "duckboard — file-first local SQL workspace powered by DuckDB.\n\n"
+            "Load CSV, Parquet, and JSON files and query them with plain SQL\n"
+            "in an interactive terminal session. No database setup required."
+        ),
+        epilog=HELP_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"duckboard {__version__}",
+    )
+    return parser
+
+
+def main() -> None:
+    parser = _build_parser()
+    parser.parse_args()
+
+    with DuckboardSession() as session:
+        run_repl(session)
+
+
+if __name__ == "__main__":
+    main()