bootstack.data.DataSourceProtocol#
- class bootstack.data.DataSourceProtocol(*args, **kwargs)#
Bases:
ProtocolProtocol 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 (seebootstack.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
colexpression API, not SQLAll methods preserve immutability - operations return new data or modify in-place
- close()#
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
withblock closes automatically. Safe to call more than once.
- delete(record_id)#
Delete record by ID.
- deselect(record_id)#
Mark record as unselected.
- deselect_all(current_page_only=False)#
Deselect all records (optionally only current page).
- export_csv(filepath, include_all=True)#
Export records to CSV file.
- get(record_id)#
Retrieve single record by ID.
- has_next_page()#
Check if more pages exist after current page.
- Returns:
True if next page exists, False otherwise
- Return type:
- insert(record)#
Create new record and return its ID.
- is_selected(record_id)#
Check whether a record is currently selected.
- load(records)#
Load data records into the datasource.
- move(record_id, target_index)#
Reorder a record to a new position.
- next_page()#
Advance to next page and return its records.
- observe(condition=None, *order)#
Observe a live result set for a
where/orderquery. Returns aStreamof result sets that re-emits on relevant changes.
- on_change(handler=None)#
Subscribe to changes. Returns a
Stream(no handler) or a cancellable subscription (with handler). The handler receives aDataChangeEvent.
- order(*keys)#
Sort rows by one or more keys.
- page(page=None)#
Get records for specified page (or current page if None).
- page_slice(start_index, count)#
Get records by start index and count (respects filter/sort).
- prev_page()#
Move to previous page and return its records.
- reload()#
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.
- save(path, *, selected_only=False, format=None, config=None)#
Export records to a file, format chosen by the path extension (or
format).Records are streamed into the writer; the active
where/orderview is respected. Built-in formats: CSV, TSV, JSON, JSONL, XML — plus Parquet, Feather, and HDF5 with the matching extra installed.
- select(record_id)#
Mark record as selected.
- select_all(current_page_only=False)#
Select all records (optionally only current page).
- selected(page=None)#
Get selected records, optionally paginated.
- update(record_id, updates)#
Update record fields by ID.