snakelit 0.1.0__py3-none-any.whl

snakelit/edit.py

@@ -0,0 +1,43 @@
+"""Store-backed file editors."""
+
+from __future__ import annotations
+
+import streamlit as st
+
+from .filetypes import BINARY_SUFFIXES, IMAGE_SUFFIXES, suffix
+from .types import Editors, FileStore
+
+
+def text_edit(text: str, key: str):
+    """Render an editable text area and return its current value.
+
+    The key comes from whoever calls this (the file manager passes the path),
+    so multiple editable views never collide.
+    """
+    return st.text_area("Content", value=text, key=f"{key}-text", height=420)
+
+
+def edit_for(path: str, store: FileStore, key: str, *, editors: Editors | None = None):
+    """Render ``path``'s editor and write the result back to ``store``.
+
+    The editor is chosen by suffix: a host-provided one from ``editors`` when
+    available, a plain text area for other text, nothing for images and
+    binaries.  A host editor returns the original bytes when the file did not
+    change, so nothing is written then.  Missing files start empty, so the
+    same call creates them; a successful change writes and reruns.
+    """
+    content = store.read(path) or b""
+    ext = suffix(path)
+    if editors and ext in editors:
+        edited = editors[ext](path, content, key)
+    elif ext in IMAGE_SUFFIXES or ext in BINARY_SUFFIXES:
+        return
+    else:
+        try:
+            text = content.decode("utf-8")
+        except UnicodeDecodeError:
+            return
+        edited = text_edit(text=text, key=key).encode("utf-8")
+    if edited != content:
+        store.write(path, edited)
+        st.rerun()

snakelit/editor/config.py

@@ -0,0 +1,325 @@
+"""Config editors driven by a JSON schema.
+
+``schema_config`` renders a config document as widgets and rebuilds it from the
+widget values on every rerun, so it never mutates the caller's object.  The
+schema is optional and read-only: with one, widgets and validation follow it;
+without one, the config is edited as raw YAML.  Only mappings get the form;
+other YAML documents (lists, scalars) fall back to the text editor.  Hosts
+discover or let the user choose the schema; nothing in here edits or writes it.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Callable, Mapping
+
+import streamlit as st
+
+from ..utils.st_layouts import st_container_maxheight
+from ..utils.schema import infer_type, is_schema, property_schema, validate
+from ..utils.yaml import SCIENTIFIC_FLOAT, dump as dump_yaml, load
+from .text import schema_text_editor
+
+
+def _dump(data, format: str):
+    if format == "yaml":
+        return dump_yaml(data)
+    from ..utils.json import dump as dump_json
+
+    return dump_json(data)
+
+
+def _looks_like_path(value: str):
+    if not value or "://" in value or any(char.isspace() for char in value):
+        return False
+    return "/" in value or bool(re.search(r"\.[A-Za-z][A-Za-z0-9]*$", value))
+
+
+def schema_config(
+    data: bytes,
+    errors: list[str],
+    schema: Mapping[str, Any] | None = None,
+    header="Configuration Editor",
+    *,
+    key: str = "config",
+    edit_file: Callable[[str], None] | None = None,
+    format: str = "yaml",
+):
+    """Render an editor for a config file and return the new bytes.
+
+    Widgets follow ``schema`` where it describes a key and are inferred from
+    the value elsewhere; a raw YAML editor is always offered as the
+    alternative.  ``errors`` is filled in place.  Returns ``None`` when the
+    text did not change or is not valid, so the caller can skip writing it.
+
+    With ``edit_file``, a string value that looks like a path gets a button
+    that calls it with the path string; the host decides whether to create,
+    open or ignore the file.  ``format`` is ``"yaml"`` or ``"json"`` and
+    selects the serializer (parsing uses the YAML loader for both).
+    """
+    text = data.decode("utf-8")
+    height = 420
+    probe: list[str] = []
+    config = load(text, probe)
+    if config is None and not probe:
+        config = {}
+
+    if isinstance(config, dict):
+        mode = st.radio(
+            header,
+            ["Form", "Text Editor"],
+            help="Configuration editor mode",
+            horizontal=True,
+            key=f"{key}-editor-mode",
+        )
+        if mode == "Form":
+            # Compare canonical YAML, not the source text: comments and
+            # formatting must survive an untouched form.
+            original = _dump(config, format)
+            with st_container_maxheight(f"{key}-form-container", height=height):
+                create_form(config, schema, "", key, edit_file)
+            before = len(errors)
+            errors.extend(validate(config, schema))
+            if len(errors) > before:
+                return None
+            updated = _dump(config, format)
+            return None if updated == original else updated.encode("utf-8")
+
+    # Unparseable input is still editable: the text area is the source of
+    # truth and reports its own parse/validation errors.
+    updated = schema_text_editor(text, schema, key, height=height)
+    probe.clear()
+    parsed = load(updated, probe)
+    if not probe:
+        probe.extend(validate(parsed, schema) if parsed else ())
+        if not probe:
+            return None if updated == text else updated.encode("utf-8")
+    errors.extend(probe)
+
+
+def create_form(
+    config: dict,
+    schema: Mapping[str, Any] | None,
+    path: str = "",
+    key: str = "config",
+    edit_file: Callable[[str], None] | None = None,
+):
+    """Render widgets for ``config`` in place, in configuration order.
+
+    Nested mappings recurse into a bordered container at their own position,
+    so the form follows the tree instead of collecting them into tabs.  A
+    schema entry is used when it exists; otherwise the widget is inferred from
+    the value.  No schema is constructed or modified.
+    """
+    required = set((schema or {}).get("required") or ())
+
+    for name, value in config.items():
+        subschema = property_schema(schema, name)
+        if isinstance(value, dict):
+            with st.container(border=True):
+                st.markdown(f"**{name}**")
+                if subschema is None or is_schema(subschema):
+                    create_form(value, subschema, _path(path, name), key, edit_file)
+                else:
+                    config[name] = _raw(value, name, f"{key}-{_path(path, name)}", None)
+            continue
+        config[name] = _value(
+            value,
+            subschema or infer_type(value),
+            _path(path, name),
+            key,
+            label=name,
+            required=name in required,
+            edit_file=edit_file,
+        )
+
+
+def _value(
+    value,
+    schema: Mapping[str, Any],
+    path: str,
+    key: str,
+    *,
+    label: str,
+    required: bool,
+    edit_file: Callable[[str], None] | None = None,
+):
+    widget_key = f"{key}-{path}"
+    help_text = schema.get("description")
+    caption = f"{label} *" if required else label
+    types = _types(schema)
+
+    if isinstance(schema.get("enum"), list):
+        options = list(schema["enum"])
+        if value not in options:
+            options = [value, *options]
+        return st.selectbox(
+            caption,
+            options,
+            index=options.index(value),
+            key=widget_key,
+            help=help_text,
+        )
+
+    if isinstance(value, list):
+        return _array(value, schema, caption, widget_key, help_text)
+
+    if isinstance(value, Mapping):
+        return _raw(value, caption, widget_key, help_text)
+
+    if "boolean" in types or (not types and isinstance(value, bool)):
+        return st.checkbox(caption, value=bool(value), key=widget_key, help=help_text)
+
+    if "integer" in types or "number" in types:
+        return _number(value, types, caption, widget_key, help_text)
+
+    if not types and isinstance(value, (int, float)):
+        return _number(value, ["number"], caption, widget_key, help_text)
+
+    if "string" in types or not types or value is None:
+        return _text(
+            value,
+            caption,
+            widget_key,
+            help_text,
+            nullable="null" in types,
+            edit_file=edit_file,
+        )
+
+    return _raw(value, caption, widget_key, help_text)
+
+
+def _text(
+    value,
+    caption: str,
+    key: str,
+    help_text: str | None,
+    *,
+    nullable: bool,
+    edit_file: Callable[[str], None] | None = None,
+):
+    text = "" if value is None else str(value)
+    if edit_file is None or not _looks_like_path(text):
+        edited = st.text_input(caption, value=text, key=key, help=help_text)
+    else:
+        field, action = st.columns([5, 1], vertical_alignment="bottom")
+        edited = field.text_input(caption, value=text, key=key, help=help_text)
+        action.button(
+            "Edit",
+            key=f"{key}-file",
+            help=f"Treat `{text}` as a file, and open to edit it",
+            on_click=edit_file,
+            args=(edited or text,),
+        )
+    if nullable and not edited.strip():
+        return None
+    return edited
+
+
+def _number(value, types: list[str], caption: str, key: str, help_text: str | None):
+    # Scientific-notation floats are strings by convention and must stay so.
+    if isinstance(value, str) or value is None or not types:
+        text = "" if value is None else str(value)
+        edited = st.text_input(caption, value=text, key=key, help=help_text)
+        return _parse_number(edited)
+
+    integer = "integer" in types
+    number = int(value) if integer else float(value)
+    edited = st.number_input(
+        caption,
+        value=number,
+        step=1 if integer else 0.1,
+        key=key,
+        help=help_text,
+        format="%d" if integer else None,
+    )
+    if edited == value:
+        # preserve the original object: an int must not become 2.0 just because
+        # the schema allows any number
+        return value
+    if not integer and isinstance(value, int) and float(edited).is_integer():
+        return int(edited)
+    return edited
+
+
+def _parse_number(text: str):
+    stripped = text.strip()
+    if not stripped:
+        return None
+    if SCIENTIFIC_FLOAT.match(stripped):
+        return stripped
+    try:
+        return int(stripped)
+    except ValueError:
+        pass
+    try:
+        return float(stripped)
+    except ValueError:
+        return stripped
+
+
+def _array(
+    value: list,
+    schema: Mapping[str, Any],
+    caption: str,
+    key: str,
+    help_text: str | None,
+):
+    items = schema.get("items") or {}
+    if not isinstance(value, list):
+        value = [] if value is None else [value]
+
+    if (
+        is_schema(items)
+        or "array" in _types(items)
+        or any(isinstance(item, (Mapping, list)) for item in value)
+    ):
+        parsed = _raw(value, caption, key, help_text)
+        return parsed if isinstance(parsed, list) else value
+
+    text = "\n".join("" if item is None else str(item) for item in value)
+    edited = st.text_area(
+        f"{caption} (one value per line)",
+        value=text,
+        key=key,
+        help=help_text,
+        height=min(200, 40 + 22 * max(1, len(value))),
+    )
+    parsed = []
+    for line in edited.splitlines():
+        if not line.strip():
+            continue
+        try:
+            item = load(line)
+        except Exception:  # noqa: BLE001 - shown to the user
+            st.error(f"Invalid value in {caption}: {line!r}")
+            return value
+        parsed.append(line.strip() if isinstance(item, (dict, list)) else item)
+    return parsed
+
+
+def _raw(value, caption: str, key: str, help_text: str | None):
+    edited = st.text_area(
+        f"{caption} (YAML)",
+        value=dump_yaml(value),
+        key=key,
+        help=help_text,
+        height=160,
+    )
+    errors = []
+    parsed = load(edited, errors)
+    if errors:
+        st.error(errors[0])
+        return value
+    return parsed
+
+
+def _types(schema: Mapping[str, Any]) -> list[str]:
+    declared = schema.get("type")
+    if isinstance(declared, str):
+        return [declared]
+    return list(declared or ())
+
+
+def _path(parent: str, name: str):
+    return f"{parent}.{name}" if parent else name

snakelit/editor/table.py

@@ -0,0 +1,332 @@
+"""Editable Polars-backed table widgets.
+
+``form_table`` seeds ``st.data_editor`` from the frame it is given; the
+editor's widget state carries the edits, and the caller decides where the
+returned frame goes.  ``column_controls`` renders icon add/rename/remove/move
+popovers that replace the frame before it is edited.  ``schema_table`` adds
+optional row-schema coercion and validation on top of a bytes value.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Mapping
+
+import sys
+import polars as pl
+import streamlit as st
+
+from .table_schema import coerce_frame, table_errors
+from .text import schema_text_editor
+from ..utils.table import dump, load
+from ..utils.st_layouts import st_container_maxheight
+
+Control = Callable[[str, pl.DataFrame], tuple[pl.DataFrame, Any] | None]
+"""A control returns ``(frame, payload)`` when it fired, else ``None``."""
+
+
+def schema_table(
+    data: bytes,
+    errors: list[str],
+    schema: Mapping[str, Any] | None = None,
+    header: str = "Table Editor",
+    *,
+    key: str = "table",
+    format: str = "csv",
+):
+    """Render an editor for a table and return the new bytes.
+
+    ``format`` is the table's file suffix (``csv``, ``tsv``, ``parquet`` or
+    ``xlsx``).  Text formats offer a Form/Text switch, binary formats only the
+    form.  ``errors`` is filled in place.  Returns ``None`` when the data did
+    not change or is invalid, so the caller can skip writing it.
+
+    With ``schema``, the form coerces columns to its declared dtypes and
+    validates every row; the schema is never edited.
+    """
+    height = 420
+    # A file that cannot be read is not an error yet: the text editor takes
+    # over below, so this probe keeps its failures to itself.
+    table = load(data, suffix=format, errors=[])
+    textable = format in ("csv", "tsv")
+    if table is not None:
+        if (
+            not textable
+            or st.radio(
+                header,
+                ["Form", "Text Editor"],
+                help="Table editor mode",
+                horizontal=True,
+                key=f"{key}-editor-mode",
+            )
+            == "Form"
+        ):
+            before = len(errors)
+            with st_container_maxheight(f"{key}-form-container", height=height):
+                edited = form_table(table, errors, schema, key=key)
+            if len(errors) > before:
+                return None
+            # Compare canonical bytes: coercion changes dtypes without changing
+            # the values, and an untouched form must not rewrite the table.
+            updated = dump(edited, format)
+            return None if updated == dump(table, format) else updated
+    elif not textable:
+        st.error(f"Cannot edit broken {format.upper()} table as text.")
+        return None
+
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError:
+        st.error(f"Cannot edit {format.upper()} data as text.")
+        return None
+    updated = schema_text_editor(text, schema, key, height=height)
+    before = len(errors)
+    parsed = load(updated.encode("utf-8"), suffix=format, errors=errors)
+    if parsed is None:
+        return None
+    if schema:
+        parsed, _ = coerce_frame(parsed, schema, errors)
+    errors.extend(table_errors(parsed, schema))
+    if len(errors) > before:
+        return None
+    return None if updated == text else updated.encode("utf-8")
+
+
+def form_table(
+    frame: pl.DataFrame,
+    errors: list[str],
+    schema: Mapping | None = None,
+    *,
+    key: str = "table",
+    column_config: Mapping | None = None,
+):
+    """Edit ``frame`` and return the edited frame.
+
+    With ``schema``, cells carry its declared dtypes and every row is validated;
+    the schema itself is never edited.
+    """
+    data_key = f"{key}-data"
+    if schema:
+        # input frame is loaded without schema (default strings for csv/tsv),
+        # so coerce it to the schema before comparing.
+        frame, _ = coerce_frame(frame, schema, errors)
+
+    current: pl.DataFrame | None = st.session_state.get(data_key)
+    reset = current is None or not current.equals(frame)
+    if reset:
+        # The host's frame is the truth: refresh the copy whenever it changed,
+        # so an unmounted editor or a document changed elsewhere cannot leave
+        # stale rows behind.
+        st.session_state[data_key] = frame
+    change = column_controls(key)
+    edited = editable_table(
+        key,
+        column_config=column_config,
+        reset=reset or bool(change),
+    )
+
+    if schema:
+        # strip and format the edited frame to save correctly.
+        edited, _ = coerce_frame(edited, schema, errors)
+        st.session_state[data_key] = edited
+        errors.extend(table_errors(edited, schema))
+    return edited
+
+
+def column_controls(
+    key: str,
+    *,
+    controls: Mapping[str, Control] | None = None,
+    extras: Mapping[str, Control] | None = None,
+):
+    """Render column popovers for ``st.session_state[f"{key}-data"]``.
+
+    Returns the changes applied, keyed by control name.  ``controls`` replaces
+    the default add/rename/remove/move set; ``extras`` renders more next to it.
+    """
+    changes: dict[str, Any] = {}
+    calls = dict(controls or _default_controls) | dict(extras or {})
+    holders = st.columns(len(calls))
+    for holder, call in zip(holders, calls):
+        with holder:
+            ret = calls[call](key, st.session_state[f"{key}-data"])
+        if ret is not None:
+            st.session_state[f"{key}-data"], changes[call] = ret
+    return changes
+
+
+def editable_table(
+    key: str,
+    *,
+    column_config: Mapping | None = None,
+    drop_empty: bool = True,
+    reset: bool = False,
+) -> pl.DataFrame:
+    """Render ``st.data_editor`` for ``st.session_state[f"{key}-data"]``.
+
+    The current data lives in ``{key}-data``; the edited result is written back
+    there and returned.  Edits accumulate against a separate stable base
+    (``{key}-base``) rather than re-feeding ``{key}-data`` as the editor input,
+    which would make edits lag by one run.  Pass ``reset=True`` when the table
+    is replaced programmatically (column change, upload, fill, clear) so the
+    base is re-seeded and the widget rebuilt.
+    """
+    data_key = f"{key}-data"
+    base_key = f"{key}-base"
+    revision_key = f"{key}-revision"
+    if reset or base_key not in st.session_state:
+        st.session_state[base_key] = st.session_state[data_key]
+        st.session_state[revision_key] = st.session_state.get(revision_key, 0) + 1
+    edited = st.data_editor(
+        st.session_state[base_key].to_pandas(),
+        num_rows="dynamic",
+        width="stretch",
+        hide_index=True,
+        key=f"{key}-{st.session_state[revision_key]}",
+        column_config=column_config,
+    )
+    result = _from_pandas(edited)
+    if drop_empty:
+        result = _drop_empty_rows(result)
+    st.session_state[data_key] = result
+    return result
+
+
+def _from_pandas(frame):
+    """Rebuild a Polars frame from the data editor's pandas frame.
+
+    Polars' own pandas bridge creates string columns that later panic with
+    ``capacity overflow`` when converted back to pandas under Pyodide
+    (polars 1.33).  Going through plain Python values avoids that path.
+    """
+    if sys.platform != "emscripten":
+        return pl.from_pandas(frame)
+
+    import pandas as pd
+
+    def cell(value):
+        if value is None or value is pd.NA or value is pd.NaT:
+            return None
+        if isinstance(value, float) and value != value:
+            return None
+        return value
+
+    data = {
+        name: [cell(value) for value in values]
+        for name, values in frame.to_dict(orient="list").items()
+    }
+    overrides: dict[str, type[pl.DataType]] = {}
+    for name, dtype in frame.dtypes.items():
+        if pd.api.types.is_bool_dtype(dtype):
+            overrides[name] = pl.Boolean
+        elif pd.api.types.is_unsigned_integer_dtype(dtype):
+            overrides[name] = pl.UInt64
+        elif pd.api.types.is_integer_dtype(dtype):
+            overrides[name] = pl.Int64
+        elif pd.api.types.is_float_dtype(dtype):
+            overrides[name] = pl.Float64
+        elif not pd.api.types.is_object_dtype(dtype) and pd.api.types.is_string_dtype(
+            dtype
+        ):
+            overrides[name] = pl.Utf8
+        elif pd.api.types.is_object_dtype(dtype) and not any(
+            value is not None for value in data[name]
+        ):
+            overrides[name] = pl.Utf8
+    return pl.DataFrame(data, schema_overrides=overrides)
+
+
+def _drop_empty_rows(frame: pl.DataFrame):
+    """Drop rows where every cell is null or blank.
+
+    The mask is applied while rebuilding the frame from Python values instead
+    of ``frame.filter``: Polars 1.33 under Pyodide corrupts string columns when
+    a filtered frame is converted back to pandas (``capacity overflow``).
+    """
+    if frame.height == 0 or not frame.columns:
+        return frame
+    keep = [
+        any(
+            value is not None and (not isinstance(value, str) or value.strip() != "")
+            for value in row
+        )
+        for row in frame.iter_rows()
+    ]
+    if all(keep):
+        return frame
+    data = {
+        name: [value for value, wanted in zip(frame[name].to_list(), keep) if wanted]
+        for name in frame.columns
+    }
+    return pl.DataFrame(data, schema=frame.schema)
+
+
+def _add_column(key: str, frame: pl.DataFrame):
+    options = list(frame.columns)
+    with st.popover("", icon=":material/add:", help="Add a column"):
+        name = st.text_input("Add column", key=f"{key}-new-column")
+        clicked = st.button("Add", key=f"{key}-add-column")
+    name = (name or "").strip()
+    if clicked and name and name not in options:
+        return frame.with_columns(pl.Series(name, [""] * frame.height)), name
+
+
+def _rename_column(key: str, frame: pl.DataFrame):
+    options = list(frame.columns)
+    with st.popover("", icon=":material/edit:", help="Rename a column"):
+        if options:
+            selected = st.selectbox(
+                "Select column to rename", options, key=f"{key}-rename-column"
+            )
+            renamed = st.text_input("Rename to", key=f"{key}-rename-column-text")
+            clicked = st.button("Rename", key=f"{key}-rename-column-button")
+        else:
+            st.caption("No columns to rename.")
+            selected, renamed, clicked = None, "", False
+    new_name = (renamed or "").strip()
+    if clicked and new_name and new_name not in options and selected in frame.columns:
+        return frame.rename({selected: new_name}), (selected, new_name)
+
+
+def _delete_column(key: str, frame: pl.DataFrame):
+    options = list(frame.columns)
+    with st.popover("", icon=":material/remove:", help="Remove a column"):
+        if options:
+            selected = st.selectbox(
+                "Select column to remove", options, key=f"{key}-remove-column"
+            )
+            clicked = st.button("Remove", key=f"{key}-remove-column-button")
+        else:
+            st.caption("No columns to remove.")
+            selected, clicked = None, False
+    if clicked and selected in frame.columns:
+        return frame.drop(selected), selected
+
+
+def _move_column(key: str, frame: pl.DataFrame):
+    options = list(frame.columns)
+    with st.popover("", icon=":material/swap_horiz:", help="Reorder columns"):
+        if len(options) > 1:
+            selected = st.selectbox("Move column", options, key=f"{key}-move-column")
+            target = st.selectbox(
+                "Move before", ["(end)", *options], key=f"{key}-move-target"
+            )
+            clicked = st.button("Move", key=f"{key}-move-button")
+        else:
+            st.caption("Need at least two columns to reorder.")
+            return None
+    if not clicked or selected not in options:
+        return None
+    order = [column for column in options if column != selected]
+    index = len(order) if target == "(end)" else order.index(target)
+    order.insert(index, selected)
+    if order == options:
+        return None
+    return frame.select(order), order
+
+
+_default_controls = {
+    "add": _add_column,
+    "rename": _rename_column,
+    "remove": _delete_column,
+    "move": _move_column,
+}