bootstack 0.1.0__py3-none-any.whl

bootstack/data/types.py

@@ -0,0 +1,354 @@
+"""Type definitions and protocols for bootstack datasource module.
+
+This module defines the core protocol that all datasource implementations must follow,
+enabling consistent data management across different backends (memory, SQLite, web, etc.).
+
+The DataSourceProtocol provides a unified interface for:
+    - Data loading and configuration (load, where, order)
+    - Pagination (page, next_page, prev_page, has_next_page)
+    - CRUD operations (insert, get, update, delete)
+    - Selection management (is_selected, select/deselect records)
+    - Data export (CSV export)
+    - Index-based access (page_slice)
+    - Lifecycle and reorder (reload, move)
+
+All datasource implementations should conform to this protocol to ensure
+compatibility with datasource-aware widgets and utilities.
+"""
+
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING, Any, Dict, List, Optional, Protocol, Sequence, Mapping,
+    runtime_checkable,
+)
+
+if TYPE_CHECKING:
+    from bootstack.data.query import Column, Condition, SortKey
+
+# Type aliases for clarity
+Primitive = Any  # Can be str, int, float, bool, None, etc.
+Record = Dict[str, Any]
+
+
+@runtime_checkable
+class DataSourceProtocol(Protocol):
+    """Protocol defining the interface for data source implementations.
+
+    This protocol establishes a contract that all datasource backends must implement,
+    ensuring consistent behavior across different storage mechanisms (memory, database,
+    web API, etc.).
+
+    All datasource implementations must support:
+        - Pagination with configurable page size
+        - Filtering with `col`-based conditions (see `bootstack.data.query`)
+        - Sorting by one or more columns
+        - Full CRUD operations on records
+        - Selection tracking for multi-select scenarios
+        - CSV export capabilities
+        - Direct index-based data access
+
+    Notes:
+        - Records are represented as Dict[str, Any] with at least 'id' and 'selected' fields
+        - Filtering and sorting are expressed with the `col` expression API, not SQL
+        - All methods preserve immutability - operations return new data or modify in-place
+    """
+
+    # public attrs
+    page_size: int
+    """Number of records per page."""
+
+    # ---------- data & view config ----------
+    def load(self, records: Sequence[Primitive] | Sequence[Mapping[str, Any]]) -> DataSourceProtocol:
+        """Load data records into the datasource.
+
+        Args:
+            records: Sequence of records (dicts) or primitives (auto-wrapped)
+
+        Returns:
+            Self for method chaining
+        """
+        ...
+
+    def where(self, condition: "Condition | None" = None) -> DataSourceProtocol:
+        """Filter rows by a condition built with `col`.
+
+        Args:
+            condition: A filter condition (e.g. `col("age") >= 25`), or `None`
+                / no argument to clear the filter.
+
+        Returns:
+            Self for method chaining
+        """
+        ...
+
+    def order(self, *keys: "str | Column | SortKey") -> DataSourceProtocol:
+        """Sort rows by one or more keys.
+
+        Args:
+            keys: Column names (`"name"`), descending names (`"-name"`), or
+                `col(...)` specs (`col("salary").desc()`). With no arguments,
+                clears sorting.
+
+        Returns:
+            Self for method chaining
+        """
+        ...
+
+    # ---------- pagination ----------
+    def page(self, page: Optional[int] = None) -> List[Record]:
+        """Get records for specified page (or current page if None).
+
+        Args:
+            page: Page number (0-indexed); updates current page if provided
+
+        Returns:
+            List of record dictionaries for the page
+        """
+        ...
+
+    def next_page(self) -> List[Record]:
+        """Advance to next page and return its records.
+
+        Returns:
+            List of record dictionaries for the new page
+        """
+        ...
+
+    def prev_page(self) -> List[Record]:
+        """Move to previous page and return its records.
+
+        Returns:
+            List of record dictionaries for the new page
+        """
+        ...
+
+    def has_next_page(self) -> bool:
+        """Check if more pages exist after current page.
+
+        Returns:
+            True if next page exists, False otherwise
+        """
+        ...
+
+    @property
+    def count(self) -> int:
+        """Total number of records matching the current filter."""
+        ...
+
+    # ---------- CRUD ----------
+    def insert(self, record: Dict[str, Any]) -> int:
+        """Create new record and return its ID.
+
+        Args:
+            record: Dictionary with record data
+
+        Returns:
+            The ID assigned to the new record
+        """
+        ...
+
+    def get(self, record_id: Any) -> Optional[Record]:
+        """Retrieve single record by ID.
+
+        Args:
+            record_id: Unique identifier of the record
+
+        Returns:
+            Record dictionary or None if not found
+        """
+        ...
+
+    def update(self, record_id: Any, updates: Dict[str, Any]) -> bool:
+        """Update record fields by ID.
+
+        Args:
+            record_id: Unique identifier of the record
+            updates: Dictionary with fields to update
+
+        Returns:
+            True if record was updated, False if not found
+        """
+        ...
+
+    def delete(self, record_id: Any) -> bool:
+        """Delete record by ID.
+
+        Args:
+            record_id: Unique identifier of the record
+
+        Returns:
+            True if record was deleted, False if not found
+        """
+        ...
+
+    # ---------- selection ----------
+    def is_selected(self, record_id: Any) -> bool:
+        """Check whether a record is currently selected.
+
+        Args:
+            record_id: Unique identifier of the record
+
+        Returns:
+            True if the record is selected, False otherwise (including missing records)
+        """
+        ...
+
+    def select(self, record_id: Any) -> bool:
+        """Mark record as selected.
+
+        Args:
+            record_id: Unique identifier of the record
+
+        Returns:
+            True if record was selected, False if not found
+        """
+        ...
+
+    def deselect(self, record_id: Any) -> bool:
+        """Mark record as unselected.
+
+        Args:
+            record_id: Unique identifier of the record
+
+        Returns:
+            True if record was deselected, False if not found
+        """
+        ...
+
+    def select_all(self, current_page_only: bool = False) -> int:
+        """Select all records (optionally only current page).
+
+        Args:
+            current_page_only: If True, select only records on current page
+
+        Returns:
+            Number of records selected
+        """
+        ...
+
+    def deselect_all(self, current_page_only: bool = False) -> int:
+        """Deselect all records (optionally only current page).
+
+        Args:
+            current_page_only: If True, deselect only records on current page
+
+        Returns:
+            Number of records deselected
+        """
+        ...
+
+    def selected(self, page: Optional[int] = None) -> List[Record]:
+        """Get selected records, optionally paginated.
+
+        Args:
+            page: Optional page number for paginating selected records
+
+        Returns:
+            List of selected record dictionaries
+        """
+        ...
+
+    @property
+    def selected_count(self) -> int:
+        """Number of selected records."""
+        ...
+
+    # ---------- lifecycle / reorder ----------
+    def reload(self) -> None:
+        """Re-read data from the underlying source.
+
+        For in-memory implementations this is typically a no-op. For
+        file- or database-backed sources, this re-queries or re-reads.
+        """
+        ...
+
+    def close(self) -> None:
+        """Release any resources held by the source (a connection, file handle).
+
+        A no-op for in-memory sources. Sources are also context managers, so a
+        `with` block closes automatically. Safe to call more than once.
+        """
+        ...
+
+    def move(self, record_id: Any, target_index: int) -> bool:
+        """Reorder a record to a new position.
+
+        Args:
+            record_id: Unique identifier of the record to move
+            target_index: Zero-based destination index (clamped to valid range)
+
+        Returns:
+            True if the record was moved, False if not supported or not found
+        """
+        ...
+
+    # ---------- export ----------
+    def save(self, path: str, *, selected_only: bool = False, format: Optional[str] = None, config: Any = None) -> None:
+        """Export records to a file, format chosen by the path extension (or `format`).
+
+        Records are streamed into the writer; the active `where`/`order` view is
+        respected. Built-in formats: CSV, TSV, JSON, JSONL, XML — plus Parquet,
+        Feather, and HDF5 with the matching extra installed.
+        """
+        ...
+
+    def export_csv(self, filepath: str, include_all: bool = True) -> None:
+        """Export records to CSV file.
+
+        Args:
+            filepath: Path to output CSV file
+            include_all: If True, export all records; if False, export only selected
+        """
+        ...
+
+    # ---------- index-based paging ----------
+    def page_slice(self, start_index: int, count: int) -> List[Record]:
+        """Get records by start index and count (respects filter/sort).
+
+        Args:
+            start_index: Starting record index
+            count: Number of records to retrieve
+
+        Returns:
+            List of record dictionaries
+        """
+        ...
+
+    # ---------- row identity ----------
+    @property
+    def id_field(self) -> str:
+        """Name of the record field that holds the stable row identity."""
+        ...
+
+    def _internal_fields(self) -> "frozenset[str]":
+        """Raw-record keys that are implementation-internal and hidden from
+        users. Datasource-aware widgets strip these from columns and exports."""
+        ...
+
+    def _record_id(self, record: Any) -> Any:
+        """Stable identity of a raw record — what `get`/`update`/`delete`/
+        `select` accept and what is surfaced publicly as `id`."""
+        ...
+
+    def _public_record(self, record: Any) -> Record:
+        """User-facing copy of a raw record: internal fields stripped, `id`
+        surfaced."""
+        ...
+
+    # ---------- change broadcasting ----------
+    def on_change(self, handler: Any = None) -> Any:
+        """Subscribe to changes. Returns a `Stream` (no handler) or a
+        cancellable subscription (with handler). The handler receives a
+        `DataChangeEvent`."""
+        ...
+
+    def observe(self, condition: "Condition | None" = None, *order: Any) -> Any:
+        """Observe a live result set for a `where`/`order` query. Returns a
+        `Stream` of result sets that re-emits on relevant changes."""
+        ...
+
+    def _query(self, condition: "Condition | None", sort_keys: List[Any]) -> List[Record]:
+        """Run a one-off filtered/sorted read without disturbing the source's
+        active `where`/`order` view state. Backs `observe()`."""
+        ...

bootstack/data/writers.py

@@ -0,0 +1,232 @@
+"""Streaming record writers — the export counterpart of `readers`.
+
+A *writer* consumes a lazy iterable of record dicts and writes them to a file,
+streaming where the format allows so a large export does not materialize the
+whole dataset. Writers are keyed by file extension in a registry: the stdlib
+formats (CSV / TSV / JSON / JSONL / XML) are always available, and the optional
+columnar/scientific formats (Parquet / Feather / HDF5) register too but raise a
+clear "install the extra" error when used without their dependency.
+
+The contract mirrors the readers — `writer(path, records, config) -> None` — so
+it pairs with `read_records` for round-trips, and backs the source-level
+`save()` / `export_csv()`.
+
+Register a custom writer for your own extension::
+
+    from bootstack.data.writers import register_writer
+
+    @register_writer(".myfmt")
+    def write_myfmt(path, records, config=None):
+        with open(path, "w") as f:
+            for record in records:
+                f.write(serialize(record))
+"""
+
+from __future__ import annotations
+
+import csv
+import importlib
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING, Callable, Dict, Iterable, List, Optional
+from xml.sax.saxutils import escape as _xml_escape
+
+from bootstack.data.types import Record
+
+if TYPE_CHECKING:
+    from bootstack.data.file_source import FileSourceConfig
+
+# A writer consumes record dicts: (path, records, config) -> None.
+Writer = Callable[..., None]
+
+_WRITERS: Dict[str, Writer] = {}
+
+# Format-name aliases (FileSourceConfig.file_format) → canonical extension.
+_FORMAT_ALIASES: Dict[str, str] = {
+    "csv": ".csv",
+    "tsv": ".tsv",
+    "json": ".json",
+    "jsonl": ".jsonl",
+    "ndjson": ".jsonl",
+    "xml": ".xml",
+    "parquet": ".parquet",
+    "feather": ".feather",
+    "hdf5": ".h5",
+}
+
+
+def _norm_ext(ext: str) -> str:
+    ext = ext.lower()
+    return ext if ext.startswith(".") else "." + ext
+
+
+def register_writer(*extensions: str, writer: Optional[Writer] = None):
+    """Register a writer for one or more file extensions (decorator or direct)."""
+
+    def _apply(fn: Writer) -> Writer:
+        for ext in extensions:
+            _WRITERS[_norm_ext(ext)] = fn
+        return fn
+
+    return _apply(writer) if writer is not None else _apply
+
+
+def supported_write_extensions() -> List[str]:
+    """Return the sorted list of registered writer extensions."""
+    return sorted(_WRITERS)
+
+
+def get_writer(path_or_ext: "str | Path") -> Writer:
+    """Resolve the writer for a path or extension.
+
+    Raises:
+        ValueError: If no writer is registered for the extension.
+    """
+    suffix = Path(str(path_or_ext)).suffix or str(path_or_ext)
+    ext = _norm_ext(suffix)
+    try:
+        return _WRITERS[ext]
+    except KeyError:
+        raise ValueError(
+            f"No writer registered for {ext!r}. Supported formats: "
+            f"{', '.join(supported_write_extensions())}."
+        ) from None
+
+
+def write_records(
+    path: "str | Path",
+    records: "Iterable[Record]",
+    config: "Optional[FileSourceConfig]" = None,
+    *,
+    format: Optional[str] = None,
+) -> None:
+    """Write records to a file, choosing the writer by `format` or extension.
+
+    Args:
+        path: Destination file path.
+        records: An iterable of record dicts (consumed lazily).
+        config: Optional formatting configuration (encoding, delimiter, …).
+        format: Explicit format name overriding the path extension.
+    """
+    if format:
+        writer = get_writer(_FORMAT_ALIASES.get(format, format))
+    else:
+        writer = get_writer(path)
+    writer(path, records, config)
+
+
+def _require(module: str, extra: str):
+    """Import an optional dependency or raise a clear install hint."""
+    try:
+        return importlib.import_module(module)
+    except ImportError as exc:
+        raise ImportError(
+            f"Writing this format needs the optional {module!r} dependency. "
+            f"Install it with:  pip install bootstack[{extra}]"
+        ) from exc
+
+
+def _encoding(config: "Optional[FileSourceConfig]") -> str:
+    return getattr(config, "encoding", "utf-8") or "utf-8"
+
+
+# --------------------------------------------------------------------------- stdlib
+
+
+@register_writer(".csv", ".tsv", ".txt")
+def write_csv(path: "str | Path", records: "Iterable[Record]", config: "Optional[FileSourceConfig]" = None) -> None:
+    """Write records to CSV/TSV, streaming a row at a time.
+
+    Column headers are taken from the first record; later records are written with
+    those columns (missing fields blank, extra fields ignored).
+    """
+    delimiter = getattr(config, "delimiter", None)
+    if not delimiter:
+        delimiter = "\t" if _norm_ext(Path(path).suffix) == ".tsv" else ","
+
+    it = iter(records)
+    try:
+        first = next(it)
+    except StopIteration:
+        open(path, "w", encoding=_encoding(config)).close()  # empty export
+        return
+
+    fieldnames = list(first.keys())
+    with open(path, "w", newline="", encoding=_encoding(config)) as f:
+        writer = csv.DictWriter(f, fieldnames=fieldnames, delimiter=delimiter, extrasaction="ignore")
+        writer.writeheader()
+        writer.writerow(first)
+        for record in it:
+            writer.writerow(record)
+
+
+@register_writer(".jsonl", ".ndjson")
+def write_jsonl(path: "str | Path", records: "Iterable[Record]", config: "Optional[FileSourceConfig]" = None) -> None:
+    """Write records as line-delimited JSON (one object per line) — fully streamed."""
+    with open(path, "w", encoding=_encoding(config)) as f:
+        for record in records:
+            f.write(json.dumps(record))
+            f.write("\n")
+
+
+@register_writer(".json")
+def write_json(path: "str | Path", records: "Iterable[Record]", config: "Optional[FileSourceConfig]" = None) -> None:
+    """Write records as a JSON array, streamed element by element."""
+    with open(path, "w", encoding=_encoding(config)) as f:
+        f.write("[")
+        first = True
+        for record in records:
+            if not first:
+                f.write(", ")
+            f.write(json.dumps(record))
+            first = False
+        f.write("]")
+
+
+@register_writer(".xml")
+def write_xml(path: "str | Path", records: "Iterable[Record]", config: "Optional[FileSourceConfig]" = None) -> None:
+    """Write records as XML, streaming one record element at a time.
+
+    Each record becomes a `<record>` element (or `config.xml_record_tag`) whose
+    child elements are the record's fields.
+    """
+    record_tag = getattr(config, "xml_record_tag", None) or "record"
+    root_tag = "records"
+    with open(path, "w", encoding=_encoding(config)) as f:
+        f.write(f"<{root_tag}>")
+        for record in records:
+            f.write(f"<{record_tag}>")
+            for key, value in record.items():
+                text = "" if value is None else _xml_escape(str(value))
+                f.write(f"<{key}>{text}</{key}>")
+            f.write(f"</{record_tag}>")
+        f.write(f"</{root_tag}>")
+
+
+# --------------------------------------------------------------------------- optional
+
+
+@register_writer(".parquet")
+def write_parquet(path: "str | Path", records: "Iterable[Record]", config: "Optional[FileSourceConfig]" = None) -> None:
+    """Write records to a Parquet file (needs pyarrow)."""
+    pa = _require("pyarrow", "parquet")
+    import pyarrow.parquet as pq
+
+    pq.write_table(pa.Table.from_pylist(list(records)), str(path))
+
+
+@register_writer(".feather", ".arrow")
+def write_feather(path: "str | Path", records: "Iterable[Record]", config: "Optional[FileSourceConfig]" = None) -> None:
+    """Write records to a Feather/Arrow IPC file (needs pyarrow)."""
+    pa = _require("pyarrow", "parquet")
+    import pyarrow.feather as feather
+
+    feather.write_feather(pa.Table.from_pylist(list(records)), str(path))
+
+
+@register_writer(".h5", ".hdf5", ".hdf")
+def write_hdf5(path: "str | Path", records: "Iterable[Record]", config: "Optional[FileSourceConfig]" = None) -> None:
+    """Write records to a tabular HDF5 file (needs pandas + tables)."""
+    pd = _require("pandas", "hdf5")
+    key = getattr(config, "hdf5_key", None) or "data"
+    pd.DataFrame(list(records)).to_hdf(str(path), key=key, format="table")

bootstack/dev/__init__.py

@@ -0,0 +1,36 @@
+"""Developer tooling for bootstack — hot reload.
+
+.. warning::
+
+   **Provisional.** This module ships in 0.1.0 but is *carved out of the API
+   freeze*: unlike the ``bootstack`` compose surface, it may change in a minor
+   release while the dev workflow settles. Pin a version if you depend on it.
+
+Run an app with live reload::
+
+    bootstack dev app.py
+
+On save, a module-level ``with bs.App()`` app updates in place — the window,
+your signals, and any module-level datasources survive; only the UI the body
+built is rebuilt. State that should persist across reloads lives **above** the
+``with`` block (module level); the block body is what reloads.
+
+For multi-file apps, mark a page builder so only its region rebuilds when its
+file changes::
+
+    from bootstack.dev import reloadable
+
+    @reloadable
+    def build_dashboard(db):
+        bs.Label("Dashboard", font="heading-lg")
+        bs.DataTable(data_source=db)
+
+Outside ``bootstack dev`` everything here is inert: :func:`reloadable` returns
+the function unchanged and :func:`is_dev_mode` is False.
+"""
+from __future__ import annotations
+
+from bootstack.dev._env import is_dev_mode
+from bootstack.dev._registry import reloadable
+
+__all__ = ["reloadable", "is_dev_mode"]