llusen 0.1.0__py3-none-any.whl

llusen/__init__.py

@@ -0,0 +1,40 @@
+"""Read and change the project open in llusen from Python.
+
+    import llusen
+
+    with llusen.connect() as project:
+        orders = project.table("orders")
+        frame = orders.to_pandas()          # needs pandas
+        orders.add_column("total", "price * qty")
+
+llusen must be running, with Tools > API Enabled on. The connection is
+to this machine only, with the token llusen writes to its api.json: to
+the llusen used last, or with `connect(project=...)` to the one that
+has that project open.
+"""
+
+from ._client import (
+    Chart,
+    LlusenError,
+    NotRunning,
+    Project,
+    Table,
+    connect,
+    find_project,
+    state_dir,
+)
+from ._values import TYPES, Fault
+
+__all__ = [
+    "Chart",
+    "Fault",
+    "LlusenError",
+    "NotRunning",
+    "Project",
+    "TYPES",
+    "Table",
+    "connect",
+    "find_project",
+    "state_dir",
+]
+__version__ = "0.1.0"

llusen/_client.py

@@ -0,0 +1,642 @@
+"""The connection to llusen, and the project, tables and charts it
+reaches."""
+
+import contextlib
+import json
+import os
+import socket
+import sys
+from pathlib import Path
+from typing import Any, Iterable
+
+from . import _frames
+from ._values import from_json, to_json
+
+#: How many rows `Table.read` asks for at a time.
+READ_CHUNK = 100_000
+
+#: How long to wait for an answer, in seconds. llusen holds a call that
+#: needs formulas worked out for up to five minutes before refusing it.
+TIMEOUT = 360.0
+
+
+class LlusenError(Exception):
+    """A call llusen refused, or could not take. `code` is JSON-RPC's
+    error code; `at` is, for a formula, the (start, end) bytes of it the
+    problem is about."""
+
+    def __init__(
+        self,
+        message: str,
+        code: int | None = None,
+        at: tuple[int, int] | None = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.at = at
+
+
+class NotRunning(LlusenError, ConnectionError):
+    """llusen is not running, or its API is off (Tools > API Enabled)."""
+
+
+def state_dir(
+    platform: str | None = None, env: dict[str, str] | None = None
+) -> Path | None:
+    """The folder llusen keeps its own state in, where it writes
+    api.json: as `recent::state_dir` in the app works it out."""
+    platform = platform or sys.platform
+    env = os.environ if env is None else env
+
+    def var(name: str) -> str | None:
+        return env.get(name) or None
+
+    if platform.startswith("win"):
+        base = var("LOCALAPPDATA")
+        return Path(base) / "llusen" if base else None
+    if platform == "darwin":
+        home = var("HOME")
+        if not home:
+            return None
+        return Path(home) / "Library" / "Application Support" / "llusen"
+    state = var("XDG_STATE_HOME")
+    if state and Path(state).is_absolute():
+        return Path(state) / "llusen"
+    home = var("HOME")
+    return Path(home) / ".local" / "state" / "llusen" if home else None
+
+
+NOT_RUNNING = (
+    "llusen's API is not on: start llusen, and choose Tools > API Enabled"
+)
+
+
+def _same_file(a: Path, b: Path, platform: str | None = None) -> bool:
+    """Whether two resolved paths name one file: ignoring case on Windows
+    and macOS, whose usual file systems do, as the app does."""
+    platform = platform or sys.platform
+    if platform.startswith("win") or platform == "darwin":
+        return str(a).casefold() == str(b).casefold()
+    return a == b
+
+
+def find_project(
+    project: str | os.PathLike, folder: Path | None = None
+) -> tuple[int, str]:
+    """The API port and token of the llusen that has `project` open,
+    from the files each llusen keeps in `instances` in llusen's state
+    folder (or `folder`). Raises NotRunning if no llusen has it open, or
+    if the one that has has its API off."""
+    wanted = Path(project).expanduser().resolve()
+    folder = folder if folder is not None else state_dir()
+    found = []
+    if folder is not None:
+        for file in (folder / "instances").glob("*.json"):
+            try:
+                info = json.loads(file.read_text(encoding="utf-8"))
+            except (OSError, ValueError):
+                continue
+            if not isinstance(info, dict) or not info.get("project"):
+                continue
+            if _same_file(Path(info["project"]), wanted):
+                found.append(info)
+    if not found:
+        raise NotRunning(f"no llusen has {wanted} open")
+    # Only one should; if a crash left another, take the one used last.
+    info = max(found, key=lambda info: info.get("used") or 0)
+    api = info.get("api")
+    if not api:
+        raise NotRunning(
+            f"{wanted.name} is open in llusen, but its API is off: "
+            "choose Tools > API Enabled in its window"
+        )
+    return api["port"], api["token"]
+
+
+def connect(
+    port: int | None = None,
+    token: str | None = None,
+    info_file: str | os.PathLike | None = None,
+    timeout: float = TIMEOUT,
+    project: str | os.PathLike | None = None,
+) -> "Project":
+    """Connect to a llusen running on this machine. With `project`, the
+    llusen that has that project file open; otherwise the one used last.
+    The port and token are read from llusen's api.json (or `info_file`)
+    unless given."""
+    if project is not None and (port is None or token is None):
+        found_port, found_token = find_project(project)
+        port = found_port if port is None else port
+        token = found_token if token is None else token
+    if port is None or token is None:
+        path = Path(info_file) if info_file else None
+        if path is None:
+            folder = state_dir()
+            if folder is None:
+                raise NotRunning("cannot tell where llusen keeps api.json")
+            path = folder / "api.json"
+        try:
+            info = json.loads(path.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            raise NotRunning(NOT_RUNNING) from None
+        port = info["port"] if port is None else port
+        token = info["token"] if token is None else token
+    try:
+        sock = socket.create_connection(("127.0.0.1", port), timeout=timeout)
+    except ConnectionRefusedError:
+        # api.json left by a llusen that has gone.
+        raise NotRunning(NOT_RUNNING) from None
+    project = Project(sock)
+    try:
+        project.call("authenticate", token=token)
+    except BaseException:
+        project.close()
+        raise
+    return project
+
+
+class Project:
+    """The project open in llusen. Use as a context manager, or call
+    `close`, to close the connection. One connection is for one thread
+    at a time."""
+
+    def __init__(self, sock: socket.socket):
+        self._socket = sock
+        self._reader = sock.makefile("r", encoding="utf-8", newline="\n")
+        self._next_id = 0
+
+    def __enter__(self) -> "Project":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._reader.close()
+        self._socket.close()
+
+    def call(self, method: str, **params: Any) -> Any:
+        """Call `method` with `params` and give its result, raising
+        LlusenError if llusen refuses it. Params that are None are left
+        out."""
+        self._next_id += 1
+        message = {
+            "jsonrpc": "2.0",
+            "id": self._next_id,
+            "method": method,
+            "params": {k: v for k, v in params.items() if v is not None},
+        }
+        line = json.dumps(message, ensure_ascii=False, allow_nan=False)
+        try:
+            self._socket.sendall(line.encode("utf-8") + b"\n")
+            answer = self._reader.readline()
+        except (ConnectionError, OSError) as error:
+            raise NotRunning(f"the connection to llusen closed: {error}")
+        if not answer:
+            raise NotRunning("llusen closed the connection")
+        answer = json.loads(answer)
+        if "error" in answer:
+            error = answer["error"]
+            at = (error.get("data") or {}).get("at")
+            raise LlusenError(
+                error.get("message", "refused"),
+                error.get("code"),
+                tuple(at) if at else None,
+            )
+        return answer.get("result")
+
+    # Reading.
+
+    def describe(self) -> dict:
+        """Every table, chart and group table, as llusen describes them:
+        {"tables": [{name, kind, rows, columns, summary, ...}]}."""
+        return self.call("project")
+
+    def table_names(self) -> list[str]:
+        return [table["name"] for table in self.describe()["tables"]]
+
+    def table(self, name: str) -> "Table":
+        """Table (or group table) `name`. Nothing is read until asked."""
+        return Table(self, name)
+
+    def chart(self, name: str) -> "Chart":
+        return Chart(self, name)
+
+    # Making tables.
+
+    def new_table(
+        self,
+        name: str,
+        data: Any,
+        types: dict[str, str] | None = None,
+    ) -> "Table":
+        """A new table named `name` holding `data`: a DataFrame, or a
+        dict of column names to lists of values (all as long). Dates,
+        datetimes, times and durations are kept as such; other types
+        are worked out from the values unless named in `types` ("int",
+        "float", "bool", "text", "date", "datetime", "time" or
+        "duration")."""
+        columns = _frames.columns_of(data, types)
+        self.call("new_table", name=name, columns=columns)
+        return Table(self, name)
+
+    def new_group_table(self, name: str, grouping: str) -> "Table":
+        """A group table, grouped as `grouping` says, e.g.
+        'table("orders").group(r => ({ Item: r.item }))'."""
+        self.call("new_group_table", name=name, grouping=grouping)
+        return Table(self, name)
+
+    def new_chart(
+        self,
+        name: str,
+        table: str,
+        x: str,
+        ys: str | Iterable[str],
+        kind: str | None = None,
+    ) -> "Chart":
+        """A chart of `table`: column `x` along the bottom, a series for
+        each of `ys`, as "bar", "line" or "doughnut" (one of `ys` only;
+        else what suits `x`)."""
+        ys = [ys] if isinstance(ys, str) else list(ys)
+        self.call(
+            "new_chart", name=name, table=table, x=x, ys=ys, kind=kind
+        )
+        return Chart(self, name)
+
+    # Files.
+
+    def export(
+        self,
+        path: str | os.PathLike,
+        format: str | None = None,
+        tables: Iterable[str] | None = None,
+    ) -> dict:
+        """Write every table (or those named in `tables`) to a workbook
+        at `path`, a sheet each, with their summary values and formats;
+        charts are left out. `format` is "xlsx" or "ods", else the
+        path's extension says. The file is written by llusen, so the
+        path is on the machine llusen runs on; a relative path is taken
+        from this script's folder. A file there is replaced. Gives
+        {"path", "rows", "sheets"} once it is written."""
+        return self.call(
+            "export",
+            path=_absolute(path),
+            format=format,
+            tables=None if tables is None else list(tables),
+        )
+
+
+class _Named:
+    """A table or chart of the project, by name."""
+
+    def __init__(self, project: Project, name: str):
+        self.project = project
+        self.name = name
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.name!r})"
+
+    def describe(self) -> dict:
+        """How llusen describes it now (see `Project.describe`)."""
+        for table in self.project.describe()["tables"]:
+            if table["name"] == self.name:
+                return table
+        raise LlusenError(f"there is no table {self.name}")
+
+    def rename(self, name: str) -> None:
+        """Rename it; formulas, group tables and charts naming it
+        follow."""
+        self.project.call("rename_table", table=self.name, name=name)
+        self.name = name.strip()
+
+    def delete(self) -> None:
+        self.project.call("delete_table", table=self.name)
+
+
+class Table(_Named):
+    """A table or group table of the project. Rows are counted in the
+    order they were loaded or added, whatever the sort and filters in
+    llusen show."""
+
+    def _call(self, method: str, **params: Any) -> Any:
+        return self.project.call(method, table=self.name, **params)
+
+    @property
+    def columns(self) -> list[str]:
+        return [column["name"] for column in self.describe()["columns"]]
+
+    def __len__(self) -> int:
+        return self.describe()["rows"]
+
+    def read(
+        self,
+        columns: Iterable[str] | None = None,
+        start: int = 0,
+        count: int | None = None,
+    ) -> dict[str, list]:
+        """The values of `columns` (all if None), `count` rows from row
+        `start` (to the end if None), as {name: [values]}. Dates are
+        datetime.date, datetimes datetime.datetime, faults Fault."""
+        return {
+            column["name"]: column["values"]
+            for column in self._read(columns, start, count)
+        }
+
+    def export(
+        self, path: str | os.PathLike, format: str | None = None
+    ) -> dict:
+        """Write the table to `path`: as CSV, or as a workbook of this
+        one table if `format` (or the path's extension) is "xlsx" or
+        "ods". Rows are written in the order llusen shows them. See
+        `Project.export`. Gives {"path", "rows"} once it is written."""
+        path = _absolute(path)
+        kind = format or Path(path).suffix.lower().lstrip(".")
+        if kind in ("xlsx", "ods"):
+            return self.project.export(path, kind, [self.name])
+        return self._call("export", path=path, format=format or "csv")
+
+    def to_pandas(self, columns: Iterable[str] | None = None) -> Any:
+        """The table as a pandas DataFrame (see `_frames.to_frame`)."""
+        return _frames.to_frame(self._read(columns, 0, None))
+
+    def _read(
+        self,
+        columns: Iterable[str] | None,
+        start: int,
+        count: int | None,
+    ) -> list[dict]:
+        """Read in pieces of READ_CHUNK rows: [{name, type, values}],
+        values turned into Python's."""
+        names = None if columns is None else list(columns)
+        read: list[dict] | None = None
+        at = start
+        while True:
+            left = None if count is None else start + count - at
+            piece = READ_CHUNK if left is None else min(left, READ_CHUNK)
+            result = self._call(
+                "read", columns=names, start=at, count=piece
+            )
+            if not result["columns"]:
+                return []
+            if read is None:
+                read = [
+                    {"name": c["name"], "type": c["type"], "values": []}
+                    for c in result["columns"]
+                ]
+            for into, column in zip(read, result["columns"]):
+                kind = column["type"]
+                into["values"].extend(
+                    from_json(value, kind) for value in column["values"]
+                )
+            got = len(result["columns"][0]["values"])
+            at += got
+            done = at >= result["rows"] or got == 0
+            if done or (count is not None and at >= start + count):
+                return read
+
+    # Columns.
+
+    def add_column(
+        self,
+        name: str,
+        formula: str | None = None,
+        values: Iterable[Any] | None = None,
+        type: str | None = None,
+    ) -> None:
+        """Add a column at the end: with `formula`, or holding `values`
+        (one per row; nulls if None) of `type` (else worked out)."""
+        listed = None if values is None else list(values)
+        if listed is not None and type is None:
+            from ._values import type_of
+
+            type = type_of(listed)
+        self._call(
+            "add_column",
+            name=name,
+            formula=formula,
+            values=None if listed is None else [to_json(v) for v in listed],
+            type=type,
+        )
+
+    def set_formula(self, column: str, formula: str) -> None:
+        self._call("set_formula", column=column, formula=formula)
+
+    def remove_formula(self, column: str) -> None:
+        """Take the formula away: the column keeps its values."""
+        self._call("remove_formula", column=column)
+
+    def rename_column(self, column: str, name: str) -> None:
+        """Rename `column`; formulas reading it follow."""
+        self._call("rename_column", column=column, name=name)
+
+    def delete_columns(self, *columns: str) -> None:
+        self._call("delete_columns", columns=list(columns))
+
+    def set_format(self, column: str, format: str | None = None) -> None:
+        """Show `column` in `format`, e.g. 'currency("£", 2)', or as its
+        values are if None."""
+        self._call("set_format", column=column, format=format or "")
+
+    # Rows.
+
+    def append_rows(self, data: Any) -> int:
+        """Add rows after the last: `data` is a DataFrame, or a dict of
+        column names to lists of values (all as long). Columns left out
+        are null. Gives the first new row."""
+        columns = _frames.columns_of(data)
+        values = {column["name"]: column["values"] for column in columns}
+        return self._call("append_rows", columns=values)
+
+    def lock(
+        self,
+        clear: bool = False,
+        columns: dict[str, str] | Iterable[tuple[str, str]] | None = None,
+    ) -> dict | None:
+        """Lock the table to add live rows to it with `insert_rows`: any
+        sort and filters in llusen are lifted, and until `unlock` (or
+        this connection closes), no one else can change it.
+
+        `columns` are the columns the rows have, by name, each with its
+        type ("int", "float", "bool", "text", "date", "datetime", "time"
+        or "duration"). With
+        `clear`, the table is emptied for a new run and its plain columns
+        made those, in that order (formula columns stay, after them),
+        with no undo step; this gives what changed: {cleared, added,
+        retyped, removed}. Without, they are checked against the table's,
+        and a difference refuses the lock."""
+        if clear and columns is None:
+            raise ValueError("clear needs the columns, each with its type")
+        listed = None
+        if columns is not None:
+            pairs = columns.items() if isinstance(columns, dict) else columns
+            listed = [{"name": name, "type": kind} for name, kind in pairs]
+        return self._call(
+            "lock_table", clear=clear or None, columns=listed
+        )
+
+    def insert_rows(self, data: Any) -> int:
+        """Add rows at the end of the table, which this connection has
+        locked, as `append_rows` takes them, with no undo step. llusen
+        checks them and answers at once, with the row the first will be
+        at, then puts them in as soon as the table is free."""
+        columns = _frames.columns_of(data)
+        values = {column["name"]: column["values"] for column in columns}
+        return self._call("insert_rows", columns=values)
+
+    def unlock(self) -> None:
+        """Unlock the table, once the rows sent have gone in."""
+        self._call("unlock_table")
+
+    @contextlib.contextmanager
+    def locked(
+        self,
+        clear: bool = False,
+        columns: dict[str, str] | Iterable[tuple[str, str]] | None = None,
+    ):
+        """The table locked for the `with` block (as `lock` takes
+        `clear` and `columns`), and unlocked after, whatever happens in
+        it:
+
+            with table.locked(clear=True, columns={"price": "float"}):
+                table.insert_rows({"price": [101.5]})
+        """
+        self.lock(clear, columns)
+        try:
+            yield self
+        finally:
+            self.unlock()
+
+    @property
+    def is_locked(self) -> bool:
+        """Whether a script has the table locked to add live rows."""
+        return self.describe().get("locked", False)
+
+    def set_cells(
+        self, column: str, values: Iterable[Any], start: int = 0
+    ) -> int:
+        """Set `column` from row `start` on to `values`, all or none.
+        Gives how many were set."""
+        values = [to_json(value) for value in values]
+        return self._call(
+            "set_cells", column=column, start=start, values=values
+        )
+
+    def change_case(self, column: str, case: str) -> int:
+        """Put every cell of text column `column` in `case`: "upper",
+        "lower", "capitalize" (the first letter a capital, the rest
+        small) or "title" (each word's first letter a capital). Gives how
+        many cells changed."""
+        return self._call("change_case", column=column, case=case)
+
+    # Filters.
+
+    def set_filter(self, column: str, formula: str | None = None) -> int:
+        """Filter on `column` by `formula` (`value` is the column's cell,
+        e.g. "value > 5"), or take its filter away if None. Gives how
+        many rows show."""
+        return self._call("set_filter", column=column, formula=formula or "")
+
+    def clear_filters(self) -> None:
+        self._call("clear_filters")
+
+    # Summary values.
+
+    def summary(self) -> dict[str, Any]:
+        """The summary values, by name, worked out."""
+        values = {}
+        for value in self.describe()["summary"]:
+            values[value["name"]] = from_json(
+                value["value"], value.get("type", "")
+            )
+        return values
+
+    def add_summary(
+        self,
+        formula: str,
+        name: str | None = None,
+        format: str | None = None,
+    ) -> str:
+        """Add a summary value (value1 and so on if not named). Gives its
+        name."""
+        return self._call(
+            "add_summary", formula=formula, name=name, format=format
+        )
+
+    def set_summary_formula(self, name: str, formula: str) -> None:
+        self._call("set_summary_formula", name=name, formula=formula)
+
+    def set_summary_format(
+        self, name: str, format: str | None = None
+    ) -> None:
+        self._call("set_summary_format", name=name, format=format or "")
+
+    def delete_summary(self, name: str) -> None:
+        self._call("delete_summary", name=name)
+
+    # Group tables.
+
+    def set_grouping(self, grouping: str) -> None:
+        """Group this group table as `grouping` says."""
+        self._call("set_grouping", grouping=grouping)
+
+
+class Chart(_Named):
+    """A chart of the project."""
+
+    def notes(self) -> list[dict]:
+        """The notes: [{id, text, anchors: [{series, x}]}]."""
+        return self.describe()["notes"]
+
+    def add_note(
+        self,
+        text: str,
+        anchors: Iterable[tuple[str, Any]] = (),
+    ) -> int:
+        """Add a note, attached to the points `anchors` ((series, x)
+        pairs: x as the column along the bottom holds it), or to the
+        chart as a whole. A series of "" means every series; the
+        anchors share one series. Gives its id."""
+        points = [
+            {"series": series, "x": _anchor_x(x)} for series, x in anchors
+        ]
+        return self.project.call(
+            "add_note", chart=self.name, text=text, anchors=points
+        )
+
+    def set_settings(self, kind: str | None = None, **settings: bool) -> bool:
+        """Change the chart's kind ("bar", "line" or "doughnut") and its
+        settings menu: smooth, line_fill, line_from_zero, horizontal,
+        bar_from_zero, pie (each True or False). What is left out stays
+        as it is. Gives whether anything changed."""
+        return self.project.call(
+            "set_chart_settings", chart=self.name, kind=kind, **settings
+        )
+
+    def hidden_series(self) -> list[str]:
+        """The series hidden from the chart's key."""
+        return self.describe()["hidden"]
+
+    def set_hidden_series(self, series: Iterable[str]) -> bool:
+        """Hide `series` (column names) from the chart's key, showing
+        the rest; at least one stays shown. Gives whether anything
+        changed."""
+        return self.project.call(
+            "set_hidden_series", chart=self.name, series=list(series)
+        )
+
+
+def _absolute(path: str | os.PathLike) -> str:
+    """`path` made whole, from `~` or this script's folder: llusen's
+    folder is not the script's."""
+    return os.path.abspath(os.path.expanduser(os.fspath(path)))
+
+
+def _anchor_x(x: Any) -> str:
+    """A place along a chart's bottom as llusen writes it: a date as
+    2026-10-21, a datetime in ISO form, a time as 14:05:00, a duration
+    as 36:15:00, a number or text as it is."""
+    value = to_json(x)
+    if isinstance(value, bool):
+        return "TRUE" if value else "FALSE"
+    return str(value)

llusen/_frames.py

@@ -0,0 +1,87 @@
+"""Columns of values to and from pandas, which is optional: nothing here
+imports it until a DataFrame is asked for or given."""
+
+from typing import Any
+
+from ._values import to_json, type_of
+
+
+def is_frame(data: Any) -> bool:
+    """Whether `data` is a pandas DataFrame (without importing pandas)."""
+    return type(data).__name__ == "DataFrame" and hasattr(data, "columns")
+
+
+def columns_of(data: Any, types: dict[str, str] | None = None) -> list[dict]:
+    """`data` (a DataFrame, or a mapping of column names to lists of
+    values, in order) as llusen's columns: [{name, values, type?}]. A
+    column's type is `types[name]` if given; else datetime, date, time
+    or duration if its values are; else llusen works it out (numbers,
+    booleans, text)."""
+    types = types or {}
+    if is_frame(data):
+        pairs = [
+            (str(name), _frame_column(data[name])) for name in data.columns
+        ]
+    elif hasattr(data, "items"):
+        pairs = [(str(name), list(values)) for name, values in data.items()]
+    else:
+        raise TypeError(
+            "give the columns as a DataFrame, or a dict of column names to "
+            "lists of values"
+        )
+    columns = []
+    for name, values in pairs:
+        kind = types.get(name) or type_of(values)
+        sent = [to_json(value) for value in values]
+        column = {"name": name, "values": sent}
+        if kind is not None:
+            column["type"] = kind
+        columns.append(column)
+    return columns
+
+
+def _frame_column(series: Any) -> list:
+    """A DataFrame's column as a list of plain values, missing ones as
+    None."""
+    missing = series.isna().tolist()
+    values = series.tolist()
+    return [None if gone else value for value, gone in zip(values, missing)]
+
+
+def to_frame(columns: list[dict]) -> Any:
+    """llusen's columns, read and turned into Python values, as a
+    DataFrame: dates and datetimes as datetime64, durations as
+    timedelta64, times as datetime.time objects, whole numbers as int64
+    (Int64 if any is null), booleans as bool (boolean if any is null).
+    Faults are missing values."""
+    import pandas as pd
+
+    from ._values import Fault
+
+    frame = {}
+    for column in columns:
+        kind = column["type"]
+        values = [
+            None if isinstance(value, Fault) else value
+            for value in column["values"]
+        ]
+        has_null = any(value is None for value in values)
+        if kind in ("date", "datetime"):
+            # A UTC column's values end in Z: they stay aware, in UTC.
+            aware = any(
+                getattr(value, "tzinfo", None) is not None for value in values
+            )
+            series = pd.Series(pd.to_datetime(values, utc=aware))
+        elif kind == "duration":
+            series = pd.Series(pd.to_timedelta(values))
+        elif kind == "int":
+            series = pd.Series(values, dtype="Int64" if has_null else "int64")
+        elif kind == "float":
+            series = pd.Series(values, dtype="float64")
+        elif kind == "bool":
+            kind = "boolean" if has_null else "bool"
+            series = pd.Series(values, dtype=kind)
+        else:
+            series = pd.Series(values, dtype="object")
+        frame[column["name"]] = series
+    return pd.DataFrame(frame)

llusen/_values.py

@@ -0,0 +1,202 @@
+"""Values between Python and llusen's JSON.
+
+llusen sends whole numbers and decimals as JSON numbers, booleans and
+text as themselves, null as null, a date as "2026-10-21", a datetime
+as ISO 8601 ("2026-10-21T09:30:00", with a Z when its column is UTC),
+a time of day as "14:05" (seconds and a fraction when it has them), a
+duration as a spreadsheet shows one ("36:15:00", "-0:30"), and a cell
+a formula could not work out as {"fault": "#DIV0"}.
+"""
+
+import datetime as dt
+import math
+from typing import Any
+
+TYPES = (
+    "int",
+    "float",
+    "bool",
+    "text",
+    "date",
+    "datetime",
+    "time",
+    "duration",
+)
+
+
+class Fault:
+    """A cell a formula could not work out: #DIV0, #OVERFLOW, #TYPE,
+    #DATE or #MANY. Equal to another fault with the same tag."""
+
+    __slots__ = ("tag",)
+
+    def __init__(self, tag: str):
+        self.tag = tag
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Fault) and other.tag == self.tag
+
+    def __hash__(self) -> int:
+        return hash(self.tag)
+
+    def __repr__(self) -> str:
+        return f"Fault({self.tag!r})"
+
+    def __str__(self) -> str:
+        return self.tag
+
+
+def from_json(value: Any, kind: str) -> Any:
+    """A value llusen sent, for a column of type `kind`, as Python's:
+    a date as datetime.date, a datetime as datetime.datetime (aware,
+    in UTC, if it ends in Z), a time as datetime.time, a duration as
+    datetime.timedelta, a fault as a Fault."""
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        return Fault(value.get("fault", "#?"))
+    if kind == "date":
+        return dt.date.fromisoformat(value)
+    if kind == "datetime":
+        return dt.datetime.fromisoformat(value)
+    if kind == "time":
+        return dt.time.fromisoformat(value)
+    if kind == "duration":
+        return parse_duration(value)
+    return value
+
+
+def parse_duration(text: str) -> dt.timedelta:
+    """A duration as llusen writes it, hours:minutes with seconds and a
+    fraction if it has them ("36:15", "-0:00:01.5"), as a timedelta."""
+    negative = text.startswith("-")
+    parts = text.lstrip("-").split(":")
+    if len(parts) not in (2, 3):
+        raise ValueError(f"{text!r} is not a duration (hours:MM)")
+    whole, _, fraction = (parts[2] if len(parts) == 3 else "0").partition(
+        "."
+    )
+    micros = int((fraction + "000000")[:6]) if fraction else 0
+    length = dt.timedelta(
+        hours=int(parts[0]),
+        minutes=int(parts[1]),
+        seconds=int(whole),
+        microseconds=micros,
+    )
+    return -length if negative else length
+
+
+def format_duration(length: dt.timedelta) -> str:
+    """A timedelta as llusen takes a duration: hours:MM:SS, with a
+    fraction if it has one and a - if it is negative ("-36:15:00")."""
+    micros = (
+        length.days * 86_400 + length.seconds
+    ) * 1_000_000 + length.microseconds
+    sign = "-" if micros < 0 else ""
+    seconds, fraction = divmod(abs(micros), 1_000_000)
+    minutes, seconds = divmod(seconds, 60)
+    hours, minutes = divmod(minutes, 60)
+    text = f"{sign}{hours}:{minutes:02}:{seconds:02}"
+    if fraction:
+        text += f".{fraction:06}".rstrip("0")
+    return text
+
+
+def to_json(value: Any) -> Any:
+    """A Python value as llusen takes it. NaN, NaT and pandas' NA are
+    null; numpy's numbers are numbers; a naive datetime is sent as it
+    is, and an aware one in UTC with a Z; a time of day and a duration
+    (timedelta, pandas' Timedelta, numpy's timedelta64) as text."""
+    if value is None:
+        return None
+    # numpy scalars (numpy.int64, numpy.bool_, numpy.datetime64...) and
+    # pandas' Timestamp, without importing either.
+    kind = type(value).__name__
+    if kind in ("NaTType", "NAType"):
+        return None
+    if kind == "Timestamp":
+        value = value.to_pydatetime()
+    elif kind == "datetime64":
+        return to_json(_numpy_datetime(value))
+    elif kind == "Timedelta":
+        # Its nanoseconds are dropped: llusen keeps microseconds.
+        value = value.to_pytimedelta()
+    elif kind == "timedelta64":
+        return to_json(_numpy_timedelta(value))
+    elif not isinstance(
+        value, (bool, int, float, str, dt.date, dt.time, dt.timedelta)
+    ) and hasattr(
+        value, "item"
+    ):
+        value = value.item()
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, float):
+        return None if math.isnan(value) or math.isinf(value) else value
+    if isinstance(value, (int, str)):
+        return value
+    # datetime before date: a datetime is a date too.
+    if isinstance(value, dt.datetime):
+        if value.tzinfo is not None:
+            utc = value.astimezone(dt.timezone.utc).replace(tzinfo=None)
+            return utc.isoformat() + "Z"
+        return value.isoformat()
+    if isinstance(value, dt.date):
+        return value.isoformat()
+    if isinstance(value, dt.time):
+        if value.tzinfo is not None:
+            raise TypeError(
+                "llusen's times of day have no time zone: give "
+                f"{value} without one"
+            )
+        return value.isoformat()
+    if isinstance(value, dt.timedelta):
+        return format_duration(value)
+    raise TypeError(
+        f"llusen cannot hold {kind} values: use numbers, booleans, text, "
+        "dates, datetimes, times or durations"
+    )
+
+
+def _numpy_datetime(value: Any) -> Any:
+    """A numpy.datetime64 as a datetime.datetime, or None for NaT."""
+    if str(value) == "NaT":
+        return None
+    nanos = int(value.astype("datetime64[ns]").astype("int64"))
+    return dt.datetime(1970, 1, 1) + dt.timedelta(microseconds=nanos // 1000)
+
+
+def _numpy_timedelta(value: Any) -> Any:
+    """A numpy.timedelta64 as a datetime.timedelta, or None for NaT."""
+    if str(value) == "NaT":
+        return None
+    nanos = int(value.astype("timedelta64[ns]").astype("int64"))
+    # Towards zero, as pandas' Timedelta drops its nanoseconds.
+    micros = abs(nanos) // 1000
+    return dt.timedelta(microseconds=-micros if nanos < 0 else micros)
+
+
+def type_of(values: list) -> str | None:
+    """The llusen type to name for `values`, when llusen could not work
+    it out from the JSON alone: dates, datetimes, times and durations,
+    which JSON sends as text. None leaves it to llusen (numbers,
+    booleans, text)."""
+    for value in values:
+        if value is None or type(value).__name__ in ("NaTType", "NAType"):
+            continue
+        if isinstance(value, dt.datetime) or type(value).__name__ in (
+            "Timestamp",
+            "datetime64",
+        ):
+            return "datetime"
+        if isinstance(value, dt.date):
+            return "date"
+        if isinstance(value, dt.time):
+            return "time"
+        if isinstance(value, dt.timedelta) or type(value).__name__ in (
+            "Timedelta",
+            "timedelta64",
+        ):
+            return "duration"
+        return None
+    return None

llusen-0.1.0.dist-info/METADATA

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: llusen
+Version: 0.1.0
+Summary: Read and change the project open in llusen from Python
+License-Expression: MIT
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.2; extra == "pandas"
+Dynamic: license-file
+
+# llusen for Python
+
+Read and change the project open in llusen from Python: tables, formulas,
+filters, summary values, group tables, charts and notes; and export them
+as CSV, Excel or OpenDocument files.
+
+```python
+import llusen
+
+with llusen.connect() as project:
+    orders = project.table("orders")
+    orders.add_column("total", "price * qty")
+    orders.set_format("total", 'currency("£", 2)')
+    print(orders.summary())
+    frame = orders.to_pandas()          # with pandas installed
+```
+
+## Setting up
+
+- **Python 3.14** or later. The package uses only the standard library;
+  pandas is optional, for `to_pandas` and for giving DataFrames.
+- **Install** from PyPI: `pip install llusen`, or `pip install
+  "llusen[pandas]"` with pandas. From this folder: `pip install .`.
+- **In llusen**, choose **Tools > API Enabled**. llusen then listens on
+  this machine only, and writes its port and a token to `api.json` in its
+  state folder:
+  - Linux: `~/.local/state/llusen` (or `$XDG_STATE_HOME/llusen`);
+  - macOS: `~/Library/Application Support/llusen`;
+  - Windows: `%LOCALAPPDATA%\llusen`.
+
+  `llusen.connect()` reads that file and gives the token. API Enabled is
+  remembered, and the token is new each time it is turned on.
+
+- **Which llusen:** each project opens in a llusen of its own, with its
+  own API, turned on in its own window. `connect()` reaches the llusen
+  used last (the one whose window last had the keyboard), as `api.json`
+  names it. To reach the llusen that has a given project open, name the
+  project's file:
+
+  ```python
+  with llusen.connect(project="~/reports/sales.llu") as project:
+      ...
+  ```
+
+  If no llusen has it open, or the one that has has its API off,
+  `NotRunning` says which. `llusen.find_project(path)` gives that
+  llusen's port and token without connecting. (Each llusen lists what
+  it has open in `instances` in the state folder.)
+
+## How it works
+
+- Changes go into the project as if made in llusen. Each is one step
+  that Ctrl+Z takes back in that table, and the status bar says what the
+  script did. A table a script makes opens in a tab.
+- Rows are counted in the order they were loaded or added, from 0,
+  whatever the user's sort and filters show. Reading gives every row.
+- Reading waits until formulas are worked out, so values are never half
+  done. llusen gives up on a call after five minutes of waiting.
+- A call llusen refuses raises `LlusenError`, with llusen's own message.
+  For a formula, `error.at` is the (start, end) of the problem in it.
+- If llusen isn't running, or API Enabled is off, `connect` raises
+  `NotRunning` (a `ConnectionError`).
+
+## Exporting
+
+llusen writes the file, so the path is on the machine llusen runs on. A
+relative path, or one from `~`, is made whole from the script's folder
+first. A file already there is replaced, through a temporary file, so a
+failed write leaves it as it was. Rows go in the order llusen shows them
+(sorted, every row, whatever the filters). llusen writes on a thread of
+its own and answers once the file is complete; the status bar says so.
+The path's extension decides the kind (`.csv`, `.xlsx`, `.ods`), unless
+`format` says; a path with no extension gets the format's.
+
+## Values
+
+| llusen   | Python                        | pandas                    |
+|----------|-------------------------------|---------------------------|
+| int      | `int`                         | `int64` (`Int64` if any are missing) |
+| float    | `float`                       | `float64`                 |
+| bool     | `bool`                        | `bool` (`boolean` if any are missing) |
+| text     | `str`                         | `object`                  |
+| date     | `datetime.date`               | `datetime64`              |
+| datetime | `datetime.datetime` (UTC, aware, if the column is UTC) | `datetime64` |
+| time     | `datetime.time`               | `object` (`datetime.time`) |
+| duration | `datetime.timedelta`          | `timedelta64`             |
+| null     | `None`                        | missing                   |
+| a fault such as `#DIV0` | `llusen.Fault("#DIV0")` | missing          |
+
+When giving values, NaN, `NaT` and `pd.NA` are null; numpy's numbers are
+numbers; a naive datetime is sent as it is, and an aware one in UTC;
+pandas' `Timedelta` and numpy's `timedelta64` are durations (to the
+microsecond), and a time of day must have no time zone. A
+new column's type is worked out from its values (whole numbers make
+`int`, any decimal makes `float`), unless named in `types`.
+
+## Reference
+
+`llusen.connect(port=None, token=None, info_file=None, timeout=360,
+project=None)` gives a `Project`: with `project`, the llusen that has
+that project file open. Use it in a `with` block, or call `close()`. One
+connection is for one thread at a time.
+
+**Project**
+- `describe()`: every table as llusen describes it (columns, types,
+  formulas, formats, filters, sort, summary values, groupings, charts,
+  notes).
+- `table_names()`, `table(name)`, `chart(name)`.
+- `new_table(name, data, types=None)`: `data` is a DataFrame, or a dict
+  of column names to lists of values.
+- `new_group_table(name, grouping)`, e.g.
+  `'table("orders").group(r => ({ Item: r.item }))'`.
+- `new_chart(name, table, x, ys, kind=None)`: `ys` is a column or a list
+  of them; `kind` is `"bar"`, `"line"` or `"doughnut"` (a doughnut
+  takes one column of values).
+- `export(path, format=None, tables=None)`: every table (or those
+  named) to an Excel (`.xlsx`) or OpenDocument (`.ods`) workbook, a sheet
+  each, with summary values at the top and column formats; charts are
+  left out. Gives `{"path", "rows", "sheets"}` once written.
+- `call(method, **params)`: any API method, as llusen documents it.
+
+**Table**
+- `read(columns=None, start=0, count=None)`: `{name: [values]}`, read in
+  pieces of 100,000 rows. `to_pandas(columns=None)`.
+- `columns`, `len(table)`, `summary()` (values by name), `describe()`.
+- `add_column(name, formula=None, values=None, type=None)`,
+  `set_formula`, `remove_formula`, `rename_column`,
+  `delete_columns(*names)`, `set_format(column, format=None)`.
+- `append_rows(data)` gives the first new row; `set_cells(column,
+  values, start=0)`, all or none.
+- `change_case(column, case)` puts every cell of a text column in
+  `"upper"`, `"lower"`, `"capitalize"` (`Hello world`) or `"title"`
+  (`Hello World`) case, and gives how many changed. The formula
+  functions of the same names do it in a new column instead.
+- Live rows: `with table.locked(): table.insert_rows(data)`, or
+  `lock()`, `insert_rows(data)` and `unlock()`. While a script has a
+  table locked, rows go in at its end, many times a second if need be,
+  with no undo steps; llusen lifts any sort and filters, and no one else
+  can change the table (the user watches it fill, scrolled to the end).
+  `insert_rows` is answered at once, with the row its first will be at,
+  and its rows go in as soon as the table, and the tables reading it,
+  have worked out the last ones. `unlock` waits until all are in. The
+  lock goes if the script's connection closes. `is_locked` says whether
+  a script has it.
+- `lock(clear=False, columns=None)`: `columns` are the rows' columns and
+  types, as `{"price": "float", "side": "text"}`. With `clear=True`, the
+  table is emptied for a new run and its plain columns made exactly
+  those, in that order (formula columns stay, after them), with no undo
+  step; it gives what changed. Without, they are checked against the
+  table's, and a difference refuses the lock. `locked()` takes the same.
+- `set_filter(column, formula=None)` gives the rows shown; `value` is the
+  column's cell, as in `"value > 5"`. `clear_filters()`.
+- `add_summary(formula, name=None, format=None)` gives its name;
+  `set_summary_formula`, `set_summary_format`, `delete_summary`.
+- `set_grouping(grouping)` for a group table.
+- `export(path, format=None)`: as CSV, or as a workbook of this table if
+  the path ends in `.xlsx` or `.ods` (or `format` says so).
+- `rename(name)`, `delete()`.
+
+**Chart**
+- `notes()`, `add_note(text, anchors=())` gives its id. Each anchor is a
+  `(series, x)` pair, where `x` is a value of the column along the
+  bottom: a date, a time, a duration, a number, or text as llusen shows
+  it. A series of
+  `""` puts the note on every series at that place. A note's anchors
+  all share one series, or are all `""`.
+- `set_settings(kind=None, **settings)`: the kind (`"bar"`, `"line"`,
+  `"doughnut"`) and the settings menu, as `smooth`, `line_fill`,
+  `line_from_zero`, `horizontal`, `bar_from_zero` and `pie` (each
+  `True` or `False`); what is left out stays. Gives whether it changed.
+- `hidden_series()`, and `set_hidden_series(series)` to hide those
+  series from the key, as a click on it does, showing the rest. At
+  least one series stays shown.
+- `rename(name)`, `delete()`.
+
+## The protocol
+
+Each message is one line of JSON-RPC 2.0 on a TCP connection to
+`127.0.0.1`, with `authenticate {token}` first. See the module notes in
+`llusen-core/src/api.rs` for every method and its params, if you want to
+call llusen from another language.
+
+## Tests
+
+`python -m unittest discover -s tests` runs the tests against a stand-in
+for llusen. `examples/orders.py` is a tour against the real thing.

llusen-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+llusen/__init__.py,sha256=rOimk8k3kYFvTZG95Y8s3FYOSc07yv__iO3Jw_8Lx0A,873
+llusen/_client.py,sha256=qnh75iTkGSlXm6uxtGz6NcgeCwB8zIlBygs_Mqk8lYM,23500
+llusen/_frames.py,sha256=02Kp_-PnQ00ZvgWDGNBsXdnhQd8OAs0_o1oyUDNuWps,3267
+llusen/_values.py,sha256=ivJP_9r1X3qaF5UTuGPwsh3FzL5-O5TBpACo_f_dcF4,6917
+llusen-0.1.0.dist-info/licenses/LICENSE,sha256=OtiZ7YOoorvhkdzidnXCXc5O7-dUx24gUb84Aw2m2hY,1074
+llusen-0.1.0.dist-info/METADATA,sha256=bJ7L7IC1QJ6XX-wIR-3jpVhY56aqVU7AIhBoYaOcT_s,9553
+llusen-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+llusen-0.1.0.dist-info/top_level.txt,sha256=EEeEsnkwAFPmRJYdgTdFurgfsd_A9jIS92R6a1Wsg5U,7
+llusen-0.1.0.dist-info/RECORD,,

llusen-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

llusen-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anthony Blackshaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

llusen-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+llusen