"""The editable document: current expression, history and edit operations. :class:`Document` is the single source of truth shared by every front end (Jupyter widget, Pyodide page, HTTP server). Front ends talk to it through :meth:`Document.handle`, which takes a JSON-able message and returns a JSON-able snapshot, so the same JavaScript works everywhere. """ from __future__ import annotations import re from typing import Any, Callable, Dict, Iterable, List, Optional, Tuple as TypingTuple, Union import io import keyword import logging import tokenize import sympy from sympy import Add, Basic, Dummy, Function, IndexedBase, Integer, MatrixSymbol, Mul, Symbol, Tuple, sympify from sympy.core.function import AppliedUndef from sympy.core.symbol import Str from sympy.matrices.expressions import MatrixExpr from sympy.matrices import MatrixBase from sympy.tensor.array import NDimArray from sympy.parsing.sympy_parser import ( convert_xor, implicit_multiplication_application, parse_expr, standard_transformations, ) from collections import OrderedDict from .addons import Addon, installed, load_addon from .ops import KINDS, KIND_LABELS, Op, get_ops, node_kind, node_kinds, with_kind from .printer import ( PLACEHOLDER_RE, Path, Placeholder, annotate, annotate_str, delete_at, format_path, get_at, is_placeholder, delete_range, extract_range, insert_at, is_insertable, is_rangeable, replace_range, parse_path, plain_latex, rebuild, replace_at, view_parts, ) from .printer import exact_srepr as srepr # a MatAdd's term order must survive the round trip __all__ = ["Document", "SYMBOL_TYPES", "Interrupted", "interrupt_thread"] class Interrupted(Exception): """Raised inside a computation the user interrupted (see :func:`interrupt_thread`); :meth:`Document.handle` reports it like any other error, with the document unchanged.""" def interrupt_thread(ident: int) -> bool: """Raise :class:`Interrupted` asynchronously in the thread ``ident`` (``threading.get_ident()`` of the thread running a ``Document`` message). SymPy is pure Python, so the exception is delivered at the next bytecode the thread executes. Returns whether a thread was found. Not available in Pyodide (no threads there: the runtime is restarted instead).""" import ctypes res = ctypes.pythonapi.PyThreadState_SetAsyncExc(ctypes.c_ulong(ident), ctypes.py_object(Interrupted)) if res > 1: # more than one thread affected: undo (should not happen) ctypes.pythonapi.PyThreadState_SetAsyncExc(ctypes.c_ulong(ident), None) return False return res == 1 #: Types a name can be declared as (see :meth:`Document.declare`). SYMBOL_TYPES = ("Symbol", "MatrixSymbol", "Matrix", "Function") PathLike = Union[str, Path] def _split_args(text: str) -> List[str]: """Split ``"x, (a, b), f(1, 2)"`` on top-level commas.""" out, depth, cur = [], 0, [] for ch in text: if ch in "([{": depth += 1 elif ch in ")]}": depth -= 1 if ch == "," and depth == 0: out.append("".join(cur)) cur = [] else: cur.append(ch) if "".join(cur).strip(): out.append("".join(cur)) return [a.strip() for a in out if a.strip()] #: Names offered first in the function box (any callable of sympy works). COMMON_FUNCTIONS = ( "simplify", "expand", "factor", "cancel", "apart", "together", "collect", "trigsimp", "expand_trig", "powsimp", "logcombine", "expand_log", "radsimp", "nsimplify", "refine", "diff", "integrate", "series", "limit", "summation", "solve", "solveset", "roots", "subs", "evalf", "N", "doit", "rewrite", "sqrt", "exp", "log", "Abs", "sin", "cos", "tan", "asin", "acos", "atan", "sinh", "cosh", "tanh", "conjugate", "re", "im", "arg", "gamma", "factorial", "binomial", "Rational", "Poly", "degree", "LC", "gcd", "lcm", "primitive", "sqf", "discriminant", "resultant", "det", "inv", "T", "transpose", "trace", "rank", "eigenvals", "eigenvects", "nullspace", "rref", "norm", "Matrix", "eye", "zeros", "ones", ) #: Parameter prompts for functions whose Python signature does not say enough #: (``*args``): name -> list of (label, kind) with kind "symbol" or "text". PARAM_HINTS: Dict[str, List] = { # name -> [(label, kind, optional, gap-fill default)] "subs": [("old", "text", False, None), ("new", "text", False, None)], "diff": [("variable", "symbol", False, None), ("n (times)", "text", True, None)], "integrate": [("variable", "symbol", False, None), ("lower limit", "text", True, None), ("upper limit", "text", True, None)], "series": [("variable", "symbol", False, None), ("x0", "text", True, "0"), ("n (order)", "text", True, None)], "limit": [("variable", "symbol", False, None), ("x0", "text", False, None), ("dir", "text", True, None)], "solve": [("symbol", "symbol", False, None)], "solveset": [("symbol", "symbol", False, None), ("domain", "text", True, None)], "roots": [("symbol", "symbol", False, None)], "collect": [("symbol", "symbol", False, None)], "apart": [("symbol", "symbol", False, None)], "rewrite": [("function", "text", False, None)], "summation": [("variable", "symbol", False, None), ("lower", "text", False, None), ("upper", "text", False, None)], "evalf": [("n (digits)", "text", True, None)], "N": [("n (digits)", "text", True, None)], "Poly": [("generator", "symbol", False, None)], "degree": [("generator", "symbol", False, None)], "LC": [("generator", "symbol", False, None)], } SYMBOL_PARAM_NAMES = {"symbol", "symbols", "x", "var", "variable", "variables", "gen", "gens", "sym", "syms", "s", "dep", "wrt"} #: Structural plumbing left out of the methods menu: not mathematics, or #: nothing an expression could become (assumption queries are skipped by #: their ``is_`` prefix). METHOD_SKIP = { "args", "func", "free_symbols", "expr_free_symbols", "bound_symbols", "canonical_variables", "assumptions0", "default_assumptions", "sort_key", "class_key", "compare", "dummy_eq", "match", "matches", "has", "has_free", "has_xfree", "find", "count", "obj", "rows", "cols", "shape", "kind", "copy", "copyin_list", "copyin_matrix", "tolist", "todok", "todod", "table", "iter_items", "iter_values", "flat", "could_extract_minus_sign", "fromiter", "zeros", "ones", "eye", } _TYPE_METHODS_CACHE: Dict[type, List[Dict[str, Any]]] = {} def _over_contents(fn, target, args): """``fn(target, *args)``, falling back to the same call over the node's contents for a container that refuses a bare expression: ``Matrix(x)`` is an error, ``Matrix([[x]])`` is the 1x1 matrix holding it. Applying or wrapping in Matrix, Array or a set means the latter.""" try: return fn(target, *args) except Exception: for contents in ([[target]], [target]): try: return fn(contents, *args) except Exception: continue raise def _as_basic(result: Any) -> Any: """A call's result as one SymPy object, containers included: a tuple becomes a ``Tuple`` (``as_numer_denom`` is an ordered pair), a list or a set a ``FiniteSet`` (``solve`` gives the set of solutions), a dict a ``Dict`` - all the way down. ``factor_list`` returns a tuple holding a list of tuples: sympified as it came, that was a ``Tuple`` with a plain list inside, which nothing could print.""" if isinstance(result, Basic): return result if isinstance(result, dict): return sympy.Dict({_as_basic(k): _as_basic(v) for k, v in result.items()}) if isinstance(result, (set, frozenset)): return sympy.FiniteSet(*[_as_basic(r) for r in result]) if isinstance(result, list): return sympy.FiniteSet(*[_as_basic(r) for r in result]) if isinstance(result, tuple): return Tuple(*[_as_basic(r) for r in result]) return sympify(result) def _rebuilt(expr: Basic) -> Basic: """``expr`` built again from the leaves up through its constructors, as SymPy would have built it (``xreplace`` skips them).""" if not isinstance(expr, Basic) or not expr.args: return expr return rebuild(expr, [_rebuilt(a) for a in expr.args]) def _well_formed(expr: Basic) -> None: """Refuse the mixtures SymPy's operators refuse but its constructors let through: a matrix among the terms of a plain ``Add`` (``M + 1``), a matrix as an exponent (``2**M``).""" from sympy import preorder_traversal matrixish = lambda a: isinstance(a, (MatrixBase, MatrixExpr)) for node in preorder_traversal(expr): if isinstance(node, Add) and not isinstance(node, sympy.MatAdd) and any(matrixish(a) for a in node.args): raise TypeError("a matrix cannot be added to a scalar") if isinstance(node, sympy.Pow) and matrixish(node.exp): raise TypeError("a matrix cannot be an exponent") def render_step(expr: Basic, printer_settings: Optional[Dict[str, Any]] = None) -> Dict[str, Any]: """One step of a history as the viewer wants it: ``{"latex", "nodes"}``, the annotated LaTeX of ``expr`` and its node table by path. Two of these are all it takes to show a change as a diff, which is why this is a plain function: :class:`History` builds steps from expressions that never went through an editor.""" tex, nodes = annotate(expr, **(printer_settings or {})) return {"latex": tex, "nodes": {format_path(p): {"src": str(n), "type": type(n).__name__, "nargs": len(n.args)} for p, n in nodes.items()}} def type_methods(cls: type) -> List[Dict[str, Any]]: """The public methods and properties of ``cls`` (a SymPy class), as ``[{"name", "doc", "property"}]``, sorted by name - what the methods menu offers. Assumption queries (``is_*``), dunders and the structural plumbing in ``METHOD_SKIP`` are left out; only what a class from ``sympy`` itself defines counts.""" import functools import inspect cached = _TYPE_METHODS_CACHE.get(cls) if cached is not None: return cached out = [] for name in dir(cls): if name.startswith("_") or name.startswith("is_") or name in METHOD_SKIP: continue if not any(name in k.__dict__ for k in cls.__mro__ if (getattr(k, "__module__", "") or "").startswith("sympy")): continue try: attr = getattr(cls, name) except Exception: continue prop = isinstance(attr, (property, functools.cached_property)) if not prop and not callable(attr): continue fn = attr.fget if isinstance(attr, property) else attr.func if isinstance(attr, functools.cached_property) else attr doc = (inspect.getdoc(fn) or "").strip().split("\n", 1)[0][:120] out.append({"name": name, "doc": doc, "property": prop}) out.sort(key=lambda entry: entry["name"]) # A class that is itself callable - Lambda - is applied to arguments, and # nothing in `dir` says so (`__call__` is a dunder): offer it first. if any("__call__" in k.__dict__ for k in cls.__mro__ if (getattr(k, "__module__", "") or "").startswith("sympy")): out.insert(0, {"name": "__call__", "label": "( ) apply", "property": False, "doc": f"Apply this {cls.__name__} to arguments: f(2)"}) _TYPE_METHODS_CACHE[cls] = out return out def function_signature(name: str, target: Optional[Basic] = None) -> Dict[str, Any]: """Parameter prompts for ``name`` (a sympy callable, or a method/attribute of ``target`` when ``name`` starts with ``.``): ``{"name", "params": [{"name", "kind": "symbol"|"text", "default"}], "doc", "callable"}``.""" import inspect dotted = name.startswith(".") bare = name.lstrip(".") if not dotted and callable(getattr(sympy, bare, None)): fn = getattr(sympy, bare) skip = 1 elif target is not None and (not bare.startswith("_") or bare == "__call__") and hasattr(target, bare): fn = getattr(target, bare) skip = 0 if not callable(fn): return {"name": name, "params": [], "doc": f"attribute of {type(target).__name__}", "callable": False} else: raise ValueError(f"Unknown SymPy function or method: {bare!r}") if bare == "__call__": # applying the node itself (a Lambda): `inspect` only sees *args, and # an optional parameter would apply it to nothing at all return {"name": name, "params": [{"name": "arguments", "kind": "text", "default": None, "optional": False, "varargs": True}], "doc": f"Apply this {type(target).__name__} to arguments", "callable": True, "hinted": True} doc = (inspect.getdoc(fn) or "").strip().split("\n", 1)[0][:160] if bare in PARAM_HINTS: params = [{"name": label, "kind": kind, "default": fill, "optional": optional} for label, kind, optional, fill in PARAM_HINTS[bare]] return {"name": name, "params": params, "doc": doc, "callable": True, "hinted": True} params = [] try: sig = inspect.signature(fn) except (TypeError, ValueError): return {"name": name, "params": [{"name": "arguments", "kind": "text", "default": None, "optional": True}], "doc": doc, "callable": True, "hinted": False} for i, prm in enumerate(sig.parameters.values()): if i < skip or prm.name in ("self", "cls"): continue if prm.kind == prm.VAR_KEYWORD: continue if prm.kind == prm.VAR_POSITIONAL: params.append({"name": prm.name, "kind": "symbol" if prm.name in SYMBOL_PARAM_NAMES else "text", "default": None, "optional": True, "varargs": True}) continue default = None if prm.default is inspect.Parameter.empty else repr(prm.default) kind = "symbol" if prm.name in SYMBOL_PARAM_NAMES else "text" params.append({"name": prm.name, "kind": kind, "default": default, "optional": default is not None}) return {"name": name, "params": params[:6], "doc": doc, "callable": True, "hinted": False} def sympy_functions() -> List[str]: """Names of SymPy's public callables, the common ones first.""" names = [n for n in dir(sympy) if not n.startswith("_") and callable(getattr(sympy, n, None))] rest = sorted(n for n in names if n not in COMMON_FUNCTIONS) return [n for n in COMMON_FUNCTIONS if n in names or n in ("subs", "evalf", "doit", "rewrite", "det", "inv", "T", "transpose", "trace", "rank", "eigenvals", "eigenvects", "nullspace", "rref", "norm", "degree", "LC")] + rest #: The unevaluated form of a SymPy function or method called from the #: function box, by name: ``Derivative(f, x)`` for ``diff(x)``... (see #: :meth:`Document.call`). LAZY_FORMS: Dict[str, Callable] = { "diff": lambda e, *a: sympy.Derivative(e, *a), "integrate": lambda e, *a: sympy.Integral(e, *a), "limit": lambda e, *a: sympy.Limit(e, *a), "summation": lambda e, *a: sympy.Sum(e, *a), "product": lambda e, *a: sympy.Product(e, *a), "subs": lambda e, *a: sympy.Subs(e, *a), "det": lambda e: sympy.Determinant(e), "inv": lambda e: sympy.Inverse(e), "inverse": lambda e: sympy.Inverse(e), "transpose": lambda e: sympy.Transpose(e), "T": lambda e: sympy.Transpose(e), "trace": lambda e: sympy.Trace(e), "adjoint": lambda e: sympy.Adjoint(e), "conjugate": lambda e: sympy.conjugate(e, evaluate=False), "sqrt": lambda e: sympy.Pow(e, sympy.Rational(1, 2), evaluate=False), "exp": lambda e: sympy.exp(e, evaluate=False), } #: Functions of :mod:`sympy` that are constructors in disguise (they build #: a ``Pow``, a ``Mul``...): called with evaluation off when unevaluated. #: What can be typed for the operator between two arguments (see #: ``Document.operator``): nothing means juxtaposition, a product. OPERATORS = "+-*/^=<>&|" UNEVALUATED_CONSTRUCTORS = frozenset({"cbrt", "root", "real_root", "Rational", "Mul", "Add", "Pow"}) class Document: """An editable SymPy expression with undo history. Parameters ---------- expr A SymPy object or a string (``sympify``-d; ``srepr`` output round-trips). printer_settings Extra :func:`sympy.latex` settings. parser ``"strict"`` (default) or ``"implicit"`` (allows ``2x``, ``sin x``). ops Mapping of op name to :class:`~sympy_editor.ops.Op`; defaults to the global registry. max_history Maximum number of undo steps kept. symbols Symbol-like objects (``Symbol``, ``MatrixSymbol``, undefined ``Function``; ``srepr`` strings are accepted too) put in scope for typed input before they occur in the expression; see :meth:`declare`. history, index, labels A saved undo history (expressions or ``srepr`` strings, oldest first), the position of the current expression in it and what produced each step, as given by :meth:`export`; ``expr`` is ignored when a history is given. addons The add-ons switched *on* to start with: :class:`~sympy_editor.addons.Addon` objects, names of installed add-ons (``"tree"``) or module names (``"sympy_editor_tree"``): node types, transformations, data and methods of their own, and a front end each (see ``sympy_editor.addons``). :meth:`enable` and :meth:`disable` switch them at any time. available What can be switched on besides: the same kinds of specs, off to start with. None (the default) means every installed add-on. addon_state ``{name: data}`` from :meth:`export`: what each add-on kept about the document it was exported from, given back to it (``restore_state``) once it is on. """ def __init__( self, expr: Union[Basic, str], *, printer_settings: Optional[Dict[str, Any]] = None, parser: str = "strict", ops: Optional[Dict[str, Op]] = None, max_history: int = 200, symbols=(), history=None, index: Optional[int] = None, labels=None, addons=(), available=None, addon_state=None, ): if parser not in ("strict", "implicit"): raise ValueError("parser must be 'strict' or 'implicit'") self.printer_settings = dict(printer_settings or {}) self.parser = parser self.ops: Dict[str, Op] = dict(ops) if ops is not None else get_ops() #: This document's kind table and labels: the global ones plus the #: kinds of the add-ons that are on (see :meth:`enable`). self.kinds: "OrderedDict[str, tuple]" = OrderedDict(KINDS) self.kind_labels: Dict[str, str] = dict(KIND_LABELS) #: The add-ons that are on, by name; a dict per add-on (on or off) #: for whatever it keeps about this document. self.addons: Dict[str, Addon] = {} self.addon_state: Dict[str, Dict[str, Any]] = {} #: What can be switched on: name -> spec, loaded on demand into #: ``_loaded`` (name -> Addon, or the error that loading raised). self._catalog: Dict[str, Any] = {} self._loaded: Dict[str, Any] = {} if available is None: self._catalog.update(installed()) else: # Names and module names go in as they are and load on demand: # one that cannot be loaded here (a page built with an add-on # this Python does not have) is listed with its error, and the # document exists all the same. for spec in available: if isinstance(spec, Addon): self._catalog[spec.name] = spec self._loaded[spec.name] = spec else: self._catalog[str(spec)] = str(spec) # Add-ons come first (their names read srepr strings back); what a # session kept for them is given back at the end, once there is an # expression to parse in the context of (restore_state may parse). self._pending_state: Dict[str, Any] = dict(addon_state or {}) self._ready = False for spec in addons or (): self.enable(spec) self.max_history = max_history #: Type names whose method lists snapshots have already carried. self._methods_sent: set = set() self._history: List[Basic] = [] #: What produced each step of the history (None for the start, or an #: edit made from Python): set by ``handle`` from the message. self._labels: List[Optional[str]] = [] self._action_label: Optional[str] = None self._index = -1 self._seq = 0 self._listeners: List[Callable[[Basic], None]] = [] #: Declared names (see :meth:`declare`): name -> object. self.declared: Dict[str, Any] = {} self.last_note: Optional[str] = None for obj in symbols: if isinstance(obj, str): # srepr text; Str is not exported by SymPy < 1.14 obj = sympify(obj, locals={"Str": Str}) self.declared[self._symbol_name(obj)] = obj if history: steps = [self._coerce(e) for e in history] if labels is not None and len(labels) > len(steps): raise ValueError(f"{len(labels)} labels for {len(steps)} history steps") self._history = steps[-self.max_history:] given = list(labels or [])[-len(self._history):] self._labels = [None] * (len(self._history) - len(given)) + [None if not l else str(l) for l in given] self._index = len(self._history) - 1 if index is None else max(0, min(int(index), len(self._history) - 1)) else: self._commit(self._coerce(expr)) self._ready = True for name, addon in list(self.addons.items()): if name in self._pending_state: addon.restore_state(self, self._pending_state.pop(name)) def export(self) -> Dict[str, Any]: """The state that :class:`Document` takes back: ``{"history": [srepr, ...], "index", "symbols": [srepr of the declared names][, "addon_state": {name: data}]}`` (a session's editing history, kept by the front end).""" out = {"history": [srepr(e) for e in self._history], "index": self._index, "labels": list(self._labels), "symbols": [srepr(obj) for obj in self.declared.values()]} # What the add-ons that are on keep about this document (a rule set), # by name: given back through restore_state when the session is opened. state = {} for name, addon in self.addons.items(): data = addon.export_state(self) if data is not None: state[name] = data if state: out["addon_state"] = state return out # -- add-ons -------------------------------------------------------------- def _load(self, spec) -> Addon: """The Addon a spec (a catalogue name, a module name or an object) stands for, cached by name; a failure is cached too and re-raised.""" if isinstance(spec, str) and spec in self._loaded: got = self._loaded[spec] if isinstance(got, Exception): raise got return got if isinstance(spec, str) and spec in self._catalog and not isinstance(self._catalog[spec], str): return self._catalog[spec] try: addon = load_addon(self._catalog.get(spec, spec) if isinstance(spec, str) else spec) except Exception as exc: if isinstance(spec, str): self._loaded[spec] = exc raise self._loaded[addon.name] = addon self._catalog.setdefault(addon.name, addon) return addon def enable(self, spec) -> Addon: """Switch an add-on on: a catalogue name (see :meth:`available_addons`), a module name or an :class:`Addon`. Its kinds join this document's table, its ops the menus, and its methods answer; the state it kept while off (``addon_state``) is still there.""" addon = self._load(spec) if addon.name in self.addons: return addon addon.activate() for kind, types in addon.kinds.items(): self.kinds = with_kind(self.kinds, kind, types) self.kind_labels[kind] = addon.kind_labels.get(kind) or kind.capitalize() for op in addon.ops: self.ops.setdefault(op.name, op) self.addons[addon.name] = addon self.addon_state.setdefault(addon.name, {}) self._catalog.setdefault(addon.name, addon) if self._ready and addon.name in self._pending_state: addon.restore_state(self, self._pending_state.pop(addon.name)) return addon def disable(self, name: str) -> None: """Switch an add-on off: its ops, kinds and methods go; its state stays for the next :meth:`enable`. Unknown or off already: nothing.""" addon = self.addons.pop(name, None) if addon is None: return for op in addon.ops: if self.ops.get(op.name) is op: del self.ops[op.name] still = {k for a in self.addons.values() for k in a.kinds} for kind in addon.kinds: if kind not in still and kind not in KINDS: self.kinds.pop(kind, None) self.kind_labels.pop(kind, None) def available_addons(self) -> List[Dict[str, Any]]: """The add-ons this document can switch on or off: ``[{"name", "label", "on", "requires"[, "error"]}]`` - the ones it started with, plus what ``available`` named (every installed add-on by default). One that cannot be loaded is listed with its error.""" out = [] for key in list(self._catalog): try: addon = self._load(key) except Exception as exc: out.append({"name": key, "label": key, "on": False, "requires": [], "error": f"{type(exc).__name__}: {exc}"}) continue if key != addon.name: # a module name given as `available`: known by the add-on's name from now on self._catalog.pop(key, None) self._loaded.pop(key, None) self._catalog[addon.name] = addon self._loaded[addon.name] = addon if any(entry["name"] == addon.name for entry in out): continue out.append({"name": addon.name, "label": addon.label or addon.name, "on": addon.name in self.addons, "requires": list(addon.requires)}) return out # -- state -------------------------------------------------------------- @property def expr(self) -> Basic: """The current expression.""" return self._history[self._index] @expr.setter def expr(self, value) -> None: self.set(value) def set(self, expr: Union[Basic, str]) -> Basic: """Replace the whole expression (recorded in history).""" return self._commit(self._coerce(expr)) @property def can_undo(self) -> bool: return self._index > 0 @property def can_redo(self) -> bool: return self._index < len(self._history) - 1 def undo(self) -> Basic: if self.can_undo: self._index -= 1 self._notify() return self.expr def redo(self) -> Basic: if self.can_redo: self._index += 1 self._notify() return self.expr def goto(self, index: int) -> Basic: """Make step ``index`` of the history (0 = oldest) the current expression, like a series of undos or redos.""" index = int(index) if not 0 <= index < len(self._history): raise ValueError(f"No history step {index} (there are {len(self._history)})") if index != self._index: self._index = index self._notify() return self.expr def python_script(self, title: Optional[str] = None) -> str: """A Python script reproducing the history with SymPy alone: the declarations of every name used by any step, then one ``expr = ...`` per step with what produced it as a comment, all collected in ``steps`` (``steps[i]`` is step ``i + 1``).""" from sympy.printing.python import PythonPrinter printer = PythonPrinter() names: Dict[str, Any] = {} for e in self._history: for s in e.atoms(Symbol, MatrixSymbol, IndexedBase): if not isinstance(s, Dummy): names.setdefault(self._symbol_name(s), s) for f in e.atoms(AppliedUndef): names.setdefault(f.func.__name__, f.func) # plain symbols first: a matrix symbol's shape may use them order = sorted(names, key=lambda k: (0 if type(names[k]) is Symbol else 1, k)) quote = '"' * 3 n = len(self._history) lines = [quote + (title or "SymPy Editor history").replace(quote, "'" * 3), "", f"Generated by sympy-editor: {n} step{'s' if n != 1 else ''}.", "Run it to rebuild every step (``steps``), or import it.", quote, "", "from sympy import *", ""] for name in order: lines.append(f"{name} = {self._declaration(names[name])}") lines += ["", "steps = []"] for i, e in enumerate(self._history): label = self._labels[i] if i < len(self._labels) else None what = label or ("start" if i == 0 else "edit") lines += ["", f"# Step {i + 1}: {what}" + (" (current)" if i == self._index else ""), f"expr = {self._python(printer, e)}", "steps.append(expr)"] lines += ["", 'if __name__ == "__main__":', " for i, e in enumerate(steps, 1):", ' print(f"Step {i}: {e}")', ""] return "\n".join(lines) @staticmethod def _declaration(obj: Any) -> str: """Python source constructing ``obj`` (a name used in the history).""" if isinstance(obj, MatrixSymbol): return f"MatrixSymbol({obj.name!r}, {obj.rows}, {obj.cols})" if isinstance(obj, IndexedBase): return f"IndexedBase({str(obj.label)!r})" if isinstance(obj, Symbol): return srepr(obj) # Symbol('x', positive=True) if isinstance(obj, type): return f"Function({obj.__name__!r})" return srepr(obj) @staticmethod def _python(printer: Any, expr: Basic) -> str: """``expr`` as Python source: SymPy's ``PythonPrinter`` (``Rational(1, 2)`` rather than ``1/2``), an ``Integer`` made a SymPy object.""" text = printer.doprint(expr) return f"Integer({text})" if isinstance(expr, Integer) else text def history_labels(self) -> Dict[str, Any]: """The history for the front end's list: ``{"labels": [str of every step, oldest first], "index", "steps": [{"latex", "nodes"}]}`` - ``steps`` carry the annotated LaTeX and the node table of each step, so consecutive steps can be shown as a diff (renders are cached per expression).""" steps = [] for e in self._history: step = self._render_cache_get(e) if self.addons: # A copy: the add-ons' data is not cached with the render (an # add-on may be switched on or off between two requests). step = dict(step) for addon in self.addons.values(): addon.contribute_step(self, step, e) steps.append(step) return {"labels": [str(e) for e in self._history], "index": self._index, "steps": steps, "actions": list(self._labels)} def _render_cache_get(self, expr: Basic) -> Dict[str, Any]: cache = self.__dict__.setdefault("_render_cache", {}) try: hit = cache.get(expr) except TypeError: # unhashable hit = None if hit is None: hit = render_step(expr, self.printer_settings) try: if len(cache) > 400: cache.clear() cache[expr] = hit except TypeError: pass return hit def on_change(self, callback: Callable[[Basic], None]) -> Callable[[Basic], None]: """Call ``callback(expr)`` after every change. Returns ``callback``.""" self._listeners.append(callback) return callback # -- the view tree ------------------------------------------------------ # The path functions of ``printer`` bound to the printer settings, which # decide the virtual parts of the view tree (``root_notation``...). def _get_at(self, expr, path): return get_at(expr, path, self.printer_settings) def _replace_at(self, expr, path, new): return replace_at(expr, path, new, self.printer_settings) def _delete_at(self, expr, path): return delete_at(expr, path, self.printer_settings) def _insert_at(self, expr, path, index, new): return insert_at(expr, path, index, new, self.printer_settings) def _extract_range(self, expr, path, indices): return extract_range(expr, path, indices, self.printer_settings) def _replace_range(self, expr, path, indices, new): return replace_range(expr, path, indices, new, self.printer_settings) def _delete_range(self, expr, path, indices): return delete_range(expr, path, indices, self.printer_settings) def _parts(self, node) -> Optional[List[Tuple[str, Basic]]]: return view_parts(node, self.printer_settings) # -- editing ------------------------------------------------------------ def get(self, path: PathLike) -> Basic: return self._get_at(self.expr, self._path(path)) def replace(self, path: PathLike, new: Union[Basic, str], children=None) -> Basic: """Replace the node at ``path`` with ``new`` (parsed if a string, in the context of the node being replaced: new names in a matrix slot become ``MatrixSymbol``s of its shape). A path may address a virtual part of the view tree (the ``1`` of ``1/n`` is ``/n``, the denominator ``2 e`` of ``1/(2e)`` is ``/d``, the product after the minus of ``- 2 x`` is ``/neg``; see :func:`~sympy_editor.printer.view_parts`): the node is rebuilt around the new part. ``children``: argument indices of the node at ``path`` (an ``Add``, ``Mul``...) - the *range* of arguments they form is replaced by ``new`` instead of the node itself. """ p = self._path(path) context = self._get_at(self.expr, p) if children is not None: context = self._extract_range(self.expr, p, children) if isinstance(new, str): new_expr = self.parse(new, context=context) else: new_expr = sympify(new) if children is not None: return self._commit(self._replace_range(self.expr, p, children, new_expr)) return self._commit(self._replace_at(self.expr, p, new_expr)) def delete(self, path: PathLike, children=None) -> Basic: """Remove the node at ``path`` from its parent's arguments (or, with ``children``, those arguments of the node at ``path``).""" if children is not None: return self._commit(self._delete_range(self.expr, self._path(path), children)) return self._commit(self._delete_at(self.expr, self._path(path))) def insert(self, path: PathLike, index: int, new: Union[Basic, str], left: Optional[int] = None, right: Optional[int] = None, attach: Optional[str] = None) -> Basic: """Type at a caret between the arguments of the node at ``path``. ``left``/``right`` are the indices of the arguments next to the caret (``index`` is where a plain new argument would go) and ``attach`` (``"left"``/``"right"``) which of them the caret belongs to. The text is *spliced* between its neighbours like in a text editor: an operator typed at a junction is used as written, a missing one means juxtaposition (multiplication) with the attached neighbour, and ``+``/``-`` bind at the level of the sum - in a product they split it at the caret (``x*z`` with ``+y+`` typed between gives ``x + y + z``). ``,`` makes a new argument. A SymPy object is inserted as is. """ p = self._path(path) parent = self._get_at(self.expr, p) args = parent.args if not isinstance(new, str): return self._commit(self._insert_at(self.expr, p, int(index), sympify(new))) text = new.strip() if not text: raise ValueError("Empty input") ops = "+-*/^," lead = text[0] if text[0] in ops else "" trail = text[-1] if text[-1] in ops else "" def parse(src, context=None): return self.parse(src, context=context if context is not None else parent) if lead == "," or trail == ",": return self._commit(self._insert_at(self.expr, p, int(index), parse(text.strip(",").strip()))) n = len(args) L = left if left is not None and 0 <= left < n else None R = right if right is not None and 0 <= right < n else None if text in OPERATORS and L is not None and R is not None: return self.operator(p, L, R, text) # just an operator between two arguments: change it is_sum, is_prod = bool(parent.is_Add), bool(parent.is_Mul) if not (is_sum or is_prod) or (L is None and R is None): # Function arguments, sets, or no neighbours: one neighbour at most. if lead in ("+", "-") and L is None and R is None: if is_sum: return self._commit(self._insert_at(self.expr, p, int(index), parse(text))) return self._commit(self._replace_at(self.expr, p, parent + parse(text))) if L is None and R is None: if lead == "*": # "* c" with nothing next to the caret: multiply the node return self._commit(self._replace_at(self.expr, p, parent * parse(text[1:].strip()))) return self._commit(self._insert_at(self.expr, p, int(index), parse(text))) side, k = ("left", L) if (L is not None and attach != "right") else ("right", R if R is not None else L) nb = args[k] # Only one neighbour takes part: an operator on the far side of # the text would dangle ("x*y*" is "x*y"). if side == "left" and trail in ("*", "/", "^"): text, trail = text[:-1].rstrip(), "" elif side == "right" and lead in ("*", "/", "^"): text, lead = text[1:].lstrip(), "" if not text: raise ValueError("Empty input") if lead == "*" and side == "left": combined = f"({nb})*{text[1:].strip()}" elif trail == "*" and side == "right": combined = f"{text[:-1].strip()}*({nb})" elif lead in ("/", "^") and side == "left": combined = f"({nb}){text}" elif lead in ("+", "-"): combined = f"({nb}){text}" elif trail in ("+", "-"): combined = f"{text}({nb})" else: combined = f"({nb})*({text})" if side == "left" else f"({text})*({nb})" return self._commit(self._replace_at(self.expr, p + (k,), parse(combined, nb))) # Sums and products: splice the text between its neighbours. def piece(indices): sub = args[indices[0]] if len(indices) == 1 else rebuild(parent, [args[i] for i in indices]) return f"({sub})" # An operator written at either end joins the neighbour on that side # whichever one the caret is attached to ("*y*" between x and z is # x*y*z); without one, the text joins the attached neighbour only. if lead in ("+", "-"): left_idx = (list(range(0, L + 1)) if is_prod else [L]) if L is not None else [] elif lead: left_idx = [L] if L is not None else [] else: left_idx = [L] if L is not None and attach != "right" else [] if trail in ("+", "-"): right_idx = (list(range(R, n)) if is_prod else [R]) if R is not None else [] elif trail: right_idx = [R] if R is not None else [] else: right_idx = [R] if R is not None and (attach == "right" or not left_idx) else [] combined = text if left_idx: combined = piece(left_idx) + ("" if lead else "*") + combined if right_idx: combined = combined + ("" if trail else "*") + piece(right_idx) new_expr = parse(combined) consumed = sorted(set(left_idx + right_idx)) if not consumed: return self._commit(self._insert_at(self.expr, p, int(index), new_expr)) return self._commit(self._replace_range(self.expr, p, consumed, new_expr)) def operator(self, path: PathLike, left: int, right: int, op: str, lazy: bool = False) -> Basic: """Change the operator shown between two neighbouring arguments (``left`` and ``right`` are their indices) of the node at ``path``. ``op`` is one of ``OPERATORS``; ``""`` (the operator deleted) means juxtaposition, a product. In a sum, ``*``/``/``/``^`` bind the two terms (``x + y + z`` with ``*`` at the first ``+`` gives ``x*y + z``) and ``-`` negates the right one; in a product, ``+``/``-`` split it at the operator (``x*y*z`` at the first factor gives ``x + y*z``) since a sum binds looser than the product it is typed into. A relation or a logical connective needs the two arguments to be the whole node. The ``-`` shown before a negative term counts as the operator: with ``*`` typed over it, ``x - y`` gives ``x*y``. With ``lazy`` nothing is evaluated (``2 + 3`` with ``*`` stays ``2*3``). Unchanged when the operator is already what is asked.""" p = self._path(path) parent = self._get_at(self.expr, p) args = parent.args n = len(args) try: L, R = int(left), int(right) except (TypeError, ValueError): raise ValueError("No operator there") from None if not (0 <= L < n and 0 <= R < n) or L == R: raise ValueError("No operator there") op = (op or "").strip() or "*" if op not in OPERATORS: raise ValueError(f"Not an operator: {op!r}") is_sum = bool(parent.is_Add) or isinstance(parent, sympy.MatAdd) is_prod = bool(parent.is_Mul) or isinstance(parent, sympy.MatMul) a, b = args[L], args[R] shown_minus = is_sum and b.could_extract_minus_sign() if shown_minus: b = -b if op == "+" and is_sum and not shown_minus: return self.expr if op == "-" and is_sum and shown_minus: return self.expr if op == "*" and is_prod: return self.expr pair = {L, R} whole = pair == set(range(n)) def build(cls, *items): if lazy: with sympy.evaluate(False): return cls(*items) return cls(*items) if is_prod and op in ("+", "-"): split = max(L, R) head = rebuild(parent, args[:split]) tail = rebuild(parent, args[split:]) new = build(Add, head, tail if op == "+" else build(Mul, -1, tail)) return self._commit(self._replace_at(self.expr, p, new)) if is_sum and op in ("+", "-"): new = b if op == "+" else build(Mul, -1, b) return self._commit(self._replace_at(self.expr, p + (R,), new)) first, second = (a, b) if L < R else (b, a) if op in ("+", "-"): # a power, a relation...: the two become a sum new = build(Add, first, second if op == "+" else build(Mul, -1, second)) elif op == "*": new = build(Mul, first, second) elif op == "/": new = build(Mul, first, build(sympy.Pow, second, -1)) elif op == "^": new = build(sympy.Pow, first, second) else: rel = {"=": sympy.Eq, "<": sympy.Lt, ">": sympy.Gt, "&": sympy.And, "|": sympy.Or}[op] if not whole: raise ValueError(f"{op!r} needs two sides: it can only replace the operator of a node with two arguments") new = build(rel, first, second) if whole: return self._commit(self._replace_at(self.expr, p, new)) return self._commit(self._replace_range(self.expr, p, sorted(pair), new)) def apply(self, path: PathLike, op: Union[str, Callable], children=None, args=None, lazy: bool = False) -> Basic: """Apply a registered op (by name) or a callable to the node at ``path`` (or, with ``children``, to the range of those arguments of it). ``args`` are the values an op with ``params`` asks for - source strings (or SymPy objects), parsed in the expression's namespace and passed after the expression: ``apply(p, "permutedims", args=["(1, 0)"])`` calls the op as ``func(array, Tuple(1, 0))``. ``lazy`` asks for the op's unevaluated form (``Determinant(M)`` rather than the determinant computed); an op without one is applied as usual, and ``last_note`` says so.""" spec = None if isinstance(op, str): try: spec = self.ops[op] except KeyError: raise ValueError(f"Unknown operation: {op!r}") from None func = spec.func if lazy: if spec.lazy is not None: func = spec.lazy else: self.last_note = f"{spec.label} has no unevaluated form: applied" else: func = op p = self._path(path) target = self._extract_range(self.expr, p, children) if children is not None else self._get_at(self.expr, p) values = [] for i, raw in enumerate(args or []): if isinstance(raw, Basic): values.append(raw) continue text = str(raw).strip() if not text: if spec is not None and i < len(spec.params) and spec.params[i].get("optional"): continue name = spec.params[i]["name"] if spec is not None and i < len(spec.params) else f"argument {i + 1}" raise ValueError(f"{(spec.label if spec else op)} needs {name}") values.append(self.parse(text, context=target)) if spec is not None: missing = [prm["name"] for prm in spec.params[len(values):] if not prm.get("optional")] if missing: raise ValueError(f"{spec.label} needs {', '.join(missing)}") result = sympify(func(target, *values, doc=self) if spec is not None and spec.context else func(target, *values)) if children is not None: return self._commit(self._replace_range(self.expr, p, children, result)) return self._commit(self._replace_at(self.expr, p, result)) def call(self, path: PathLike, func: str, children=None, lazy: bool = False) -> Basic: """Apply a SymPy function or a method to the node at ``path`` (or to the range ``children`` of it): ``func`` is ``"diff(x)"``, ``"series(x, 0, 5)"``, ``"subs(x, 1)"``, ``"factor"``, ``".T"``, ``".det()"``... ``"(2)"`` (or ``".__call__(2)"``) applies the node itself, which is how a ``Lambda`` is evaluated at a point. A name that is a SymPy function is called as ``name(node, *args)``; a name starting with ``.`` (or that is only an attribute of the node) is looked up on the node. Extra arguments are parsed in the expression's namespace. ``lazy`` asks for the unevaluated form: ``diff``/``integrate``/ ``det``... build ``Derivative``/``Integral``/``Determinant``... (:data:`LAZY_FORMS`), a SymPy class - a function like ``sin``, a constructor like ``sqrt`` - is called with evaluation off (``sin(0)`` stays ``sin(0)``); anything else (``simplify``, ``series``...) has no such form and runs as usual, and ``last_note`` says so. """ m = re.match(r"^\s*(\.?)([A-Za-z_][A-Za-z_0-9]*)?\s*(?:$(.*)$)?\s*$", func or "", re.S) if not m or (not m.group(2) and m.group(3) is None): raise ValueError(f"Not a function call: {func!r} (try diff(x), series(x, 0, 5), .T or (2) on a Lambda)") dotted, name, argsrc = m.group(1), m.group(2) or "", m.group(3) p = self._path(path) target = self._extract_range(self.expr, p, children) if children is not None else self._get_at(self.expr, p) args = [self.parse(a, context=target) for a in _split_args(argsrc)] if argsrc else [] fn = None if not name or name == "__call__": # "(2)" or the "( ) apply" entry of the methods menu: the node is # itself the function - a Lambda applied to its arguments. if not callable(target): raise ValueError(f"{type(target).__name__} is not a function: it cannot be called") if lazy: with sympy.evaluate(False): result = target(*args) else: result = target(*args) elif lazy and name in LAZY_FORMS and not name.startswith("_"): result = LAZY_FORMS[name](target, *args) elif not dotted and not name.startswith("_") and callable(getattr(sympy, name, None)): fn = getattr(sympy, name) if lazy and (isinstance(fn, type) or name in UNEVALUATED_CONSTRUCTORS): with sympy.evaluate(False): result = _over_contents(fn, target, args) else: if lazy: self.last_note = f"{name} has no unevaluated form: applied" result = _over_contents(fn, target, args) elif not name.startswith("_") and hasattr(target, name): if lazy: self.last_note = f"{name} has no unevaluated form: applied" attr = getattr(target, name) result = attr(*args) if callable(attr) else attr else: raise ValueError(f"Unknown SymPy function or method: {name!r}") result = _as_basic(result) if not isinstance(result, Basic): raise ValueError(f"{name} returned {type(result).__name__}, not an expression") if children is not None: return self._commit(self._replace_range(self.expr, p, children, result)) return self._commit(self._replace_at(self.expr, p, result)) def isolate(self, path: PathLike, children=None) -> Basic: """Make the node at ``path`` (or the range ``children`` of it) the whole expression, dropping everything around it.""" p = self._path(path) sub = self._extract_range(self.expr, p, children) if children is not None else self._get_at(self.expr, p) return self._commit(sub) # -- explicit matrices: rows, columns, shape ---------------------------- MATRIX_OPS = ("insert_row", "insert_col", "delete_row", "delete_col", "resize", "reshape") def _enclosing_matrix(self, path: PathLike): """The explicit matrix at ``path`` or around it: ``(matrix path, matrix, cell)``, ``cell`` being the ``(row, col)`` of the entry the path is in, or ``None`` when the path is the matrix itself.""" p = self._path(path) for k in range(len(p), -1, -1): try: node = self._get_at(self.expr, p[:k]) except Exception: continue if not isinstance(node, MatrixBase): continue rel = p[k:] cell = None # args are (rows, cols, entries): a Tuple of the entries in reading # order for a dense matrix, a Dict of {(row, col): entry} for a sparse one if len(rel) >= 2 and rel[0] == 2 and isinstance(rel[1], int): entries = node.args[2] try: if isinstance(entries, sympy.Dict): key = entries.args[rel[1]].args[0] cell = (int(key.args[0]), int(key.args[1])) else: cell = divmod(int(rel[1]), int(node.cols)) except Exception: cell = None return p[:k], node, cell raise ValueError("Not a matrix, nor inside one") def _fresh_placeholders(self): """An endless supply of empty slots (``_1``, ``_2``...) whose names are not in the expression yet.""" taken = {s.name for s in self.expr.atoms(Symbol) if PLACEHOLDER_RE.match(s.name)} n = 1 while True: if f"_{n}" not in taken: taken.add(f"_{n}") yield Placeholder(f"_{n}") n += 1 def edit_matrix(self, path: PathLike, op: str, rows: Optional[int] = None, cols: Optional[int] = None) -> Basic: """Change the shape of the explicit matrix at ``path`` or around it - ``path`` may be an entry of the matrix, or anything inside one. ``op`` is one of :data:`MATRIX_OPS`: ``"insert_row"`` / ``"insert_col"`` add a row (column) after the one the path is in - at the end when the path is the matrix itself; ``"delete_row"`` / ``"delete_col"`` remove the row (column) the path is in - the last one for the matrix itself; ``"resize"`` makes it ``rows`` x ``cols``, keeping what fits from the top-left corner; ``"reshape"`` lays the same entries out in another shape (SymPy's ``Matrix.reshape``, in reading order), so it takes only a ``rows`` x ``cols`` that multiplies to the number of entries there already are - nothing is added and nothing is lost. New entries (the insertions, and what ``resize`` cannot fill) are empty slots (placeholders, ``_1``, ``_2``...). The matrix keeps its class (dense or sparse, mutable or not); a matrix never loses its last row or column. """ if op not in self.MATRIX_OPS: raise ValueError(f"Unknown matrix operation {op!r}; one of {', '.join(self.MATRIX_OPS)}") mpath, mat, cell = self._enclosing_matrix(path) r, c = int(mat.rows), int(mat.cols) grid = [list(row) for row in mat.tolist()] fresh = self._fresh_placeholders() if op == "insert_row": at = cell[0] + 1 if cell else r grid.insert(at, [next(fresh) for _ in range(c)]) elif op == "insert_col": at = cell[1] + 1 if cell else c for row in grid: row.insert(at, next(fresh)) elif op == "delete_row": if r <= 1: raise ValueError("The matrix has a single row: delete the matrix itself instead") del grid[cell[0] if cell else r - 1] elif op == "delete_col": if c <= 1: raise ValueError("The matrix has a single column: delete the matrix itself instead") at = cell[1] if cell else c - 1 for row in grid: del row[at] else: try: nr, nc = int(rows), int(cols) # type: ignore[arg-type] except (TypeError, ValueError): raise ValueError(f"{op} needs the numbers of rows and columns") from None if nr < 1 or nc < 1: raise ValueError("A matrix needs at least one row and one column") if op == "reshape": # The same entries in another shape: only a shape that holds # them all, and no empty slot - what SymPy's reshape does. if nr * nc != r * c: raise ValueError(f"{r}x{c} has {r * c} entries and {nr}x{nc} holds {nr * nc}: a reshape keeps every " f"entry, so the two must agree ({self._shapes_for(r * c)})") new = mat.reshape(nr, nc) return self._commit(self._replace_at(self.expr, mpath, new)) grid = [[grid[i][j] if i < r and j < c else next(fresh) for j in range(nc)] for i in range(nr)] new = type(mat)(grid) return self._commit(self._replace_at(self.expr, mpath, new)) @staticmethod def _shapes_for(count: int) -> str: """The shapes ``count`` entries can be laid out in, for a message.""" return ", ".join(f"{r}x{count // r}" for r in range(1, count + 1) if count % r == 0) def insert_row(self, path: PathLike) -> Basic: """A new row of empty slots after the one at ``path`` (see :meth:`edit_matrix`).""" return self.edit_matrix(path, "insert_row") def insert_col(self, path: PathLike) -> Basic: """A new column of empty slots after the one at ``path``.""" return self.edit_matrix(path, "insert_col") def delete_row(self, path: PathLike) -> Basic: """Remove the row of the matrix that ``path`` is in.""" return self.edit_matrix(path, "delete_row") def delete_col(self, path: PathLike) -> Basic: """Remove the column of the matrix that ``path`` is in.""" return self.edit_matrix(path, "delete_col") def resize_matrix(self, path: PathLike, rows: int, cols: int) -> Basic: """Make the matrix at (or around) ``path`` ``rows`` x ``cols``, keeping what fits from the top-left corner (see :meth:`edit_matrix`).""" return self.edit_matrix(path, "resize", rows, cols) def reshape_matrix(self, path: PathLike, rows: int, cols: int) -> Basic: """The same entries of the matrix at (or around) ``path`` laid out as ``rows`` x ``cols`` (``Matrix.reshape``); the shape must hold exactly the entries there are.""" return self.edit_matrix(path, "reshape", rows, cols) def _keep_candidates(self, node: Basic) -> List[TypingTuple[Union[int, str], Basic]]: """What ``unwrap`` could leave in the node's place, as (``keep`` key, value): the virtual parts of a node shown as a fraction or after a minus sign, otherwise the arguments that are expressions (the limits of an integral are a ``Tuple``, not something that can stand alone). More than one means there is a real choice to offer - ``x**2`` can leave the base or the exponent - rather than a natural default.""" parts = self._parts(node) or () source: Iterable[TypingTuple[Union[int, str], Any]] = ( [(name, value) for name, value in parts] if parts else list(enumerate(node.args))) return [(key, value) for key, value in source if isinstance(value, Basic) and not isinstance(value, Tuple)] def unwrap(self, path: PathLike, keep: Union[int, str, None] = None) -> Basic: """Remove the node at ``path`` but keep one of its arguments in its place: ``cos(x)`` becomes ``x``, ``Integral(f, (x, a, b))`` becomes ``f``, ``x**2`` becomes ``x``. ``keep`` is the index of the argument to keep - or the name of a virtual part (``"n"``, ``"d"``, ``"neg"``) for a node shown as a fraction or after a minus sign; by default the natural one (the function body, the base, the first argument, the product after the sign). A sum, a product with several terms or a fraction needs ``keep``. """ p = self._path(path) node = self._get_at(self.expr, p) parts = dict(self._parts(node) or ()) args = node.args if not args and not parts: raise ValueError(f"{node} has nothing inside to keep") if keep is None: if parts and "neg" in parts: keep = "neg" elif parts: raise ValueError(f"{node} is a fraction: select the numerator or denominator to keep, press ↑, then Backspace") elif isinstance(node, (Add, Mul)) and len(args) > 1: # MatAdd/MatMul are Add/Mul too raise ValueError(f"{type(node).__name__} has {len(args)} terms: select the one to keep, press ↑, then Backspace " "(or Delete the others)") else: keep = 0 if isinstance(keep, str) and not keep.lstrip("-").isdigit(): if keep not in parts: raise ValueError(f"Invalid part {keep!r} for {node}") kept = parts[keep] else: if not 0 <= int(keep) < len(args): raise ValueError(f"Invalid argument {keep} for {node}") kept = args[int(keep)] if isinstance(kept, Tuple): raise ValueError(f"Cannot keep {kept}: it is not an expression") return self._commit(self._replace_at(self.expr, p, kept)) def wrap(self, path: PathLike, func: str, args: str = "", children=None) -> Basic: """Put the node at ``path`` (or the range ``children`` of it) inside a function - the inverse of :meth:`unwrap`. ``x`` wrapped in ``"cos"`` becomes ``cos(x)``, in ``"sqrt"`` ``sqrt(x)``; ``"Integral"`` with ``args="x"`` gives ``Integral(x, x)``. ``func`` is a SymPy function, a function already in the expression or declared, or any other name - an unknown one becomes an undefined ``Function``, so ``"f"`` gives ``f(x)``. ``args`` holds any further arguments, parsed in the expression's namespace and placed after the node. Nothing is evaluated: wrapping ``4`` in ``sqrt`` gives ``sqrt(4)``, not ``2`` - this builds the expression, :meth:`call` computes with it. """ if not (func or "").strip(): raise ValueError("No function to wrap in (cos, sqrt, Integral, f...)") m = re.match(r"^\s*([A-Za-z_][A-Za-z_0-9]*)\s*(?:$(.*)$)?\s*$", func or "", re.S) if not m: raise ValueError(f"Not a function name: {func!r} (wrap in cos, sqrt, Integral, f...)") name, in_call = m.group(1), m.group(2) argsrc = ", ".join(a for a in ((args or "").strip(), (in_call or "").strip()) if a) p = self._path(path) target = self._extract_range(self.expr, p, children) if children is not None else self._get_at(self.expr, p) extra = [self.parse(a, context=target) for a in _split_args(argsrc)] if argsrc else [] known = self.namespace().get(name) fn = known if callable(known) else getattr(sympy, name, None) if not callable(fn) or name.startswith("_"): fn = Function(name) # not a function anywhere: an undefined one, f(x) try: result = sympify(_over_contents(fn, target, extra)) # Wrapping builds, it does not compute: when the node is no longer # inside what came back (sqrt of 4 is 2, cos of 0 is 1), keep the # application unevaluated so the editor shows what was asked for. if target not in getattr(result, "args", ()): with sympy.evaluate(False): result = sympify(_over_contents(fn, target, extra)) except Exception as exc: # noqa: BLE001 - a wrong number of arguments, mostly raise ValueError(f"Cannot wrap in {name}: {exc}") from None if not isinstance(result, Basic): raise ValueError(f"{name} returned {type(result).__name__}, not an expression") if children is not None: return self._commit(self._replace_range(self.expr, p, children, result)) return self._commit(self._replace_at(self.expr, p, result)) def extend(self, path: PathLike, side: str, src: str) -> Basic: """Type next to the node at ``path`` (an entry of a matrix, the base of a power...): ``src`` is combined with the node - after it for ``side="after"``, before it otherwise. An operator in ``src`` at the junction is used (``"+ 1"`` gives ``node + 1``); without one the two are multiplied (``"y"`` after ``x`` gives ``x*y``).""" p = self._path(path) node = self._get_at(self.expr, p) text = (src or "").strip() if not text: raise ValueError("Empty input") node_src = f"({node})" if side == "after": joiner = " " if text[0] in "+-*/^" else "*" combined = node_src + joiner + text else: joiner = " " if text[-1] in "+-*/^(" else "*" combined = text + joiner + node_src return self._commit(self._replace_at(self.expr, p, self.parse(combined, context=node))) def used_symbols(self) -> Dict[str, Any]: """Symbols, matrix symbols, indexed bases and undefined functions occurring in the current expression, by name.""" ns: Dict[str, Any] = {} for s in self.expr.atoms(Symbol, MatrixSymbol, IndexedBase): if not isinstance(s, Dummy): ns.setdefault(self._symbol_name(s), s) for f in self.expr.atoms(AppliedUndef): ns.setdefault(f.func.__name__, f.func) return ns def namespace(self) -> Dict[str, Any]: """Names available to typed input: everything occurring in the expression (assumptions included) plus the declared names.""" ns = self.used_symbols() for name, obj in self.declared.items(): ns.setdefault(name, obj) for addon in self.addons.values(): for name, obj in addon.namespace().items(): ns.setdefault(name, obj) return ns @staticmethod def _symbol_name(obj) -> str: if isinstance(obj, IndexedBase): return str(obj.label) if isinstance(obj, type): # undefined function class return obj.__name__ return str(obj.name) def parse(self, src: str, context: Optional[Basic] = None) -> Basic: """Parse user input in the context of the current expression. ``context`` is the node the input replaces, if any. When it is a matrix (a ``MatrixExpr`` or an explicit matrix), names that do not occur in the expression are read as ``MatrixSymbol``s of its shape rather than as plain symbols - so typing ``C.T`` over ``B`` in ``A*B`` works, and ``C`` in a matrix product is a matrix. """ src = (src or "").strip() if not src: raise ValueError("Empty input") transformations = standard_transformations + (convert_xor,) if self.parser == "implicit": transformations = transformations + (implicit_multiplication_application,) local = self.namespace() # `name` in backticks is a variable even if SymPy has a function or a # constant of that name (`sin`, `E`, `gamma`...); the backticks go. for name in set(re.findall(r"`([A-Za-z_][A-Za-z_0-9]*)`", src)): local.setdefault(name, Symbol(name)) src = re.sub(r"`([A-Za-z_][A-Za-z_0-9]*)`", r"\1", src) shape = getattr(context, "shape", None) if isinstance(context, (MatrixExpr, MatrixBase)) else None new_names = self._new_names(src, local) for name in new_names: if PLACEHOLDER_RE.match(name): local[name] = Placeholder(name) # an empty slot (\int leaves Integral(_1, _2)) continue if shape is not None and len(shape) == 2: local[name] = MatrixSymbol(name, *shape) continue # An add-on may read a new name as a node of its own (a wildcard). for addon in self.addons.values(): made = addon.make_symbol(name) if made is not None: local[name] = made break self.last_note = self._collision_note(src, local) try: return sympify(parse_expr(src, local_dict=local, transformations=transformations)) except Exception as exc: # SyntaxError, TokenError, TypeError, ... raise ValueError(f"Could not parse {src!r}: {exc}") from None @staticmethod def _collision_note(src: str, local: Dict[str, Any]) -> Optional[str]: """A hint when a typed name that is not a known symbol was read as one of SymPy's functions or constants (``E``, ``I``, ``gamma``...).""" try: tokens = list(tokenize.generate_tokens(io.StringIO(src).readline)) except (tokenize.TokenError, SyntaxError): return None taken = [] for i, tok in enumerate(tokens): if tok.type != tokenize.NAME or keyword.iskeyword(tok.string) or tok.string in local: continue prev = tokens[i - 1].string if i else "" nxt = tokens[i + 1].string if i + 1 < len(tokens) else "" if prev == "." or nxt == "(": # attributes and calls are meant as functions continue obj = getattr(sympy, tok.string, None) if obj is not None and tok.string not in taken: taken.append(tok.string) if not taken: return None names = ", ".join(taken) return (f"{names}: read as SymPy's {'constant/function' if len(taken) == 1 else 'constants/functions'}; " f"for a variable write `{taken[0]}` in backticks or declare it in Symbols") @staticmethod def _new_names(src: str, local: Dict[str, Any]) -> List[str]: """The identifiers in ``src`` that ``parse_expr`` would turn into new symbols: not in ``local``, not SymPy names (``sin``, ``pi``, ``I``...), not attribute names (``.T``) and not called (``f(x)``).""" try: tokens = list(tokenize.generate_tokens(io.StringIO(src).readline)) except (tokenize.TokenError, SyntaxError): return [] names: List[str] = [] prev = "" for i, tok in enumerate(tokens): nxt = tokens[i + 1].string if i + 1 < len(tokens) else "" if (tok.type == tokenize.NAME and not keyword.iskeyword(tok.string) and prev != "." and nxt != "(" and tok.string not in local and not hasattr(sympy, tok.string) and tok.string not in names): names.append(tok.string) prev = tok.string return names # -- symbols ------------------------------------------------------------ def symbol_info(self) -> List[Dict[str, Any]]: """The names in the expression with what they stand for, for the front end's symbols panel: ``[{"name": "A", "type": "MatrixSymbol", "shape": ["2", "2"]}, {"name": "x", "type": "Symbol", "assumptions": ["positive"]}, ...]``.""" out: List[Dict[str, Any]] = [] used = self.used_symbols() for name, obj in sorted(self.namespace().items()): info: Dict[str, Any] = {"name": name, "used": name in used} if isinstance(obj, MatrixSymbol): info.update(type="MatrixSymbol", shape=[str(obj.rows), str(obj.cols)]) elif isinstance(obj, IndexedBase): info["type"] = "IndexedBase" elif isinstance(obj, Symbol): info.update(type="Symbol", assumptions=sorted( k for k, v in obj.assumptions0.items() if v and k != "commutative")) elif isinstance(obj, type): info["type"] = "Function" elif isinstance(obj, MatrixBase): info.update(type="Matrix", shape=[str(d) for d in obj.shape]) else: info["type"] = type(obj).__name__ out.append(info) return out def _make(self, name: str, kind: str, rows: Any, cols: Any, assumptions: Any, old: Any = None) -> Any: """The object a name is (re)declared as.""" if isinstance(assumptions, str): assumptions = [a.strip() for a in assumptions.split(",")] if isinstance(assumptions, dict): flags = {str(k): bool(v) for k, v in assumptions.items() if v is not None} else: flags = {str(a): True for a in (assumptions or []) if str(a).strip()} if kind == "Symbol": return Symbol(name, **flags) if kind == "Function": return Function(name) if kind in ("MatrixSymbol", "Matrix"): old_shape = getattr(old, "shape", (2, 2)) ns = self.namespace() r = sympify(rows, locals=ns) if rows not in (None, "") else old_shape[0] c = sympify(cols, locals=ns) if cols not in (None, "") else old_shape[1] new = MatrixSymbol(name, r, c) return new.as_explicit() if kind == "Matrix" else new raise ValueError(f"Unknown symbol type {kind!r}; use one of {', '.join(SYMBOL_TYPES)}") def declare(self, name: str, kind: str = "Symbol", rows: Any = None, cols: Any = None, assumptions: Any = None) -> Any: """Put ``name`` in scope for typed input as a ``Symbol`` (with ``assumptions``, e.g. ``["positive"]``), a ``MatrixSymbol`` / explicit ``Matrix`` of ``rows`` x ``cols`` or an undefined ``Function``. A name already in the expression is changed everywhere (see :meth:`retype`).""" name = (name or "").strip() if not name.isidentifier(): raise ValueError(f"Invalid symbol name: {name!r}") if name in self.namespace(): return self.retype(name, kind, rows, cols, assumptions) new = self._make(name, kind, rows, cols, assumptions) self.declared[name] = new return new def undeclare(self, name: str) -> None: """Forget a declared name (it must not occur in the expression).""" if name in self.used_symbols(): raise ValueError(f"{name} occurs in the expression; remove it there first") if name not in self.declared: raise ValueError(f"No declared symbol named {name!r}") del self.declared[name] def retype(self, name: str, kind: str, rows: Any = None, cols: Any = None, assumptions: Any = None) -> Basic: """Change what ``name`` stands for, everywhere in the expression: ``"Symbol"``, ``"MatrixSymbol"`` (``rows`` x ``cols``, symbolic dimensions allowed) or ``"Matrix"`` (an explicit ``rows`` x ``cols`` matrix of ``name[i, j]`` elements). Ancestors are rebuilt, so a product of two names becomes a ``MatMul`` when both become matrices; the reverse (a matrix back to a scalar under a transpose, say) fails with SymPy's error, which ``handle`` reports.""" ns = self.namespace() if name not in ns: raise ValueError(f"No symbol named {name!r} in the expression") old = ns[name] new = self._make(name, kind, rows, cols, assumptions, old) if new == old: return self.expr if name not in self.used_symbols(): self.declared[name] = new return self.expr if isinstance(old, type) or isinstance(new, type): raise ValueError(f"{name} is used as a {'function' if isinstance(old, type) else 'symbol'}; " "remove those uses before changing it") new_expr = self._coerce(self.expr.xreplace({old: new})) # xreplace rebuilds without the constructors' checks, so a matrix # turned back into a scalar can leave a Transpose(Symbol) behind - a # tree nothing can print - and a scalar turned into a matrix a # ``1 + Matrix`` that prints but that SymPy would never have built # (``M + 1`` is a TypeError), on which every transformation is then # a silent no-op. Rebuild it through the constructors and refuse # what they refuse, and what they merely tolerate. try: new_expr = _rebuilt(new_expr) _well_formed(new_expr) plain_latex(new_expr, **self.printer_settings) except Exception as exc: raise ValueError(f"{name} cannot become a {kind} where it is used: {exc}") from None # Only a change that went through is recorded: a refused one must not # leave the panel (and typed input) believing the name has changed. self.declared[name] = new return self._commit(new_expr) # -- serialisation ------------------------------------------------------ def snapshot(self, error: Optional[str] = None, expr: Optional[Basic] = None) -> Dict[str, Any]: """JSON-able description of the current state for the front end (of ``expr`` instead of the current expression, for a preview).""" self._seq += 1 if expr is None: expr = self.expr tex, nodes = annotate(expr, **self.printer_settings) # The methods menu: each snapshot carries the method lists of the # types it introduces (once per document - the front end caches them # by type name), so no extra request ever races an edit. methods = {} for node in nodes.values(): cls = type(node) if cls.__name__ not in self._methods_sent: self._methods_sent.add(cls.__name__) methods[cls.__name__] = type_methods(cls) snap = { "seq": self._seq, "latex": tex, "latex_plain": plain_latex(expr, **self.printer_settings), "src": str(expr), "spans": {path: list(span) for path, span in annotate_str(expr)[1].items()}, "srepr": srepr(expr), "declared": [srepr(obj) for obj in self.declared.values()], # to rebuild the document elsewhere "nodes": {format_path(path): self._node_info(path, node, expr) for path, node in nodes.items()}, "symbols": self.symbol_info(), "can_undo": self.can_undo, "can_redo": self.can_redo, "ops": [{"name": op.name, "label": op.label, "kinds": list(op.kinds) if op.kinds else None, "params": [dict(prm) for prm in op.params], "doc": op.doc, "lazy": op.lazy is not None} for op in self.ops.values()], "kind_labels": dict(self.kind_labels), "methods": methods, "addons": list(self.addons), "addons_available": self.available_addons(), # the empty slots, in reading order: Tab walks them, and a new one # is selected as it appears so that typing fills it "placeholders": [format_path(p) for p, n in sorted(nodes.items(), key=lambda kv: tuple(str(i) for i in kv[0])) if is_placeholder(n)], "error": error, } for addon in self.addons.values(): addon.contribute(self, snap, expr) return snap def _node_info(self, path: Path, node: Basic, expr: Optional[Basic] = None) -> Dict[str, Any]: """A node's entry in the snapshot. ``node`` is the view-tree node printed at ``path``. ``parts`` lists the names of its virtual parts when it is shown as a fraction or after a minus sign; such a node is neither ``insertable`` nor ``rangeable`` (its arguments are not what is shown - the parts are, and they may be).""" parts = self._parts(node) info: Dict[str, Any] = {"src": str(node), "type": type(node).__name__, "kind": node_kind(node, self.kinds), "kinds": node_kinds(node, self.kinds), "nargs": len(node.args), "insertable": is_insertable(node) and not parts, "rangeable": is_rangeable(node) and not parts, "free": sorted(str(s) for s in getattr(node, "free_symbols", ()))[:12]} if parts: info["parts"] = [name for name, _value in parts] if is_placeholder(node): info["placeholder"] = True if isinstance(node, MatrixBase): # an explicit matrix: the front end offers its row/column tools and # the corner handle that resizes it (see edit_matrix) info["matrix"] = {"rows": int(node.rows), "cols": int(node.cols)} elif isinstance(node, NDimArray): # An explicit array: its entries are one flat list of arguments, # as a matrix's are, and the printer lays them out in two # dimensions (a rank-3 array is a row of matrices). The shape # says how; the front end moves through them by what is drawn. info["array"] = {"shape": [int(d) for d in node.shape]} # What unwrap could keep, when there is more than one candidate: the # front end asks which argument to leave instead of picking for the user. choices = self._keep_candidates(node) if len(choices) > 1: info["keep_choices"] = [{"key": key, "src": str(value)} for key, value in choices] return info def preview(self, src: str) -> Dict[str, Any]: """A snapshot of ``src`` parsed as the whole expression, without committing it (the source line shows it while it is typed; Enter commits with ``set``). Flagged ``preview``; a string that does not parse gives the current snapshot with ``error`` and the flag. Parsed exactly as ``set`` will parse it - in the context of the expression it replaces, so that over a matrix new names are matrices in the preview as they will be in the result. The two used to differ: ``a*b + c`` typed over a matrix previewed as a scalar sum and committed as a sum of matrix symbols.""" try: snap = self.snapshot(expr=self.parse(src, context=self.expr)) except Exception as exc: snap = self.snapshot(error=f"{type(exc).__name__}: {exc}") snap["preview"] = True if self.last_note and not snap["error"]: snap["note"] = self.last_note return snap def handle(self, message: Dict[str, Any]) -> Dict[str, Any]: """Process a front-end message and return a snapshot. Messages: ``{"action": "replace", "path": "/0", "src": "y**2"}`` (``replace``, ``delete`` and ``apply`` take ``"children": [i, j]`` to act on the range of those arguments of the node at ``path``), ``{"action": "apply", "path": "/", "op": "expand"[, "args": ["(1, 0)"]]}`` (``args`` for an op that declares ``params``, such as the array tools), ``{"action": "delete", "path": "/1"}``, ``{"action": "set", "src": ...}``, ``{"action": "matrix", "path", "op": "insert_row" | "insert_col" | "delete_row" | "delete_col" | "resize" | "reshape", "rows", "cols"}``, ``{"action": "insert", "path": "/", "index": 2, "src": "y", "left": 1}``, ``{"action": "extend", "path": "/2/0", "side": "after", "src": "+ 1"}``, ``{"action": "unwrap", "path": "/1", "keep": 0}`` (keep an argument, drop the node), ``{"action": "wrap", "path": "/1", "func": "cos"}`` (the node becomes the argument of a function; ``"args"`` supplies any further ones), ``{"action": "isolate", "path": "/1"}`` (the node becomes the whole expression), ``{"action": "call", "path": "/", "func": "diff(x)"}`` (any SymPy function/method), ``{"action": "functions"}`` (a snapshot with the list of SymPy function names), ``{"action": "retype", "name": "A", "type": "MatrixSymbol", "rows": 2, "cols": 2}`` (``"assumptions": ["positive"]`` for a Symbol), ``{"action": "declare", ...}`` with the same fields for a name not yet in the expression, ``{"action": "undeclare", "name": "A"}``, ``{"action": "preview", "src": ...}`` (a snapshot of the parsed source, not committed), ``{"action": "undo"}``, ``{"action": "redo"}``, ``{"action": "snapshot"}``, ``{"action": "addon", "addon": name, "method": ..., ...}`` (a method of one of the document's add-ons: a query answers under ``"query"``, a change like any edit), ``{"action": "addons", "enable": [names], "disable": [names]}`` (switch add-ons on or off; see :meth:`available_addons`). Errors are reported in the snapshot's ``"error"`` field. """ self.last_note = None try: action = message.get("action") path = message.get("path", "/") children = message.get("children") self._action_label = self._describe(message) if action == "preview": return self.preview(str(message.get("src", ""))) if action == "addon": return self._handle_addon(message) if action == "addons": # Switch add-ons on or off; not a step of the history. The # answer carries the front ends of the ones that are on, so # the editor can mount what it has not seen yet. for name in message.get("disable") or []: self.disable(str(name)) for name in message.get("enable") or []: self.enable(str(name)) snap = self.snapshot() snap["addon_clients"] = [addon.client() for addon in self.addons.values()] return snap if action == "export": snap = self.snapshot() snap["export"] = self.export() snap["history"] = self.history_labels() return snap if action == "methods": target = self._get_at(self.expr, self._path(path)) snap = self.snapshot() snap["methods"] = dict(snap.get("methods") or {}) snap["methods"][type(target).__name__] = type_methods(type(target)) return snap if action == "script": snap = self.snapshot() snap["script"] = self.python_script(message.get("title")) return snap if action == "goto": self.goto(message.get("index", 0)) elif action == "replace": self.replace(path, str(message.get("src", "")), children=children) elif action == "retype": self.retype(str(message.get("name", "")), str(message.get("type", "")), message.get("rows"), message.get("cols"), message.get("assumptions")) elif action == "declare": self.declare(str(message.get("name", "")), str(message.get("type", "Symbol")), message.get("rows"), message.get("cols"), message.get("assumptions")) elif action == "undeclare": self.undeclare(str(message.get("name", ""))) elif action == "insert": self.insert(path, int(message.get("index", 0)), str(message.get("src", "")), left=message.get("left"), right=message.get("right"), attach=message.get("attach")) elif action == "operator": self.operator(path, message.get("left"), message.get("right"), str(message.get("op", "") or ""), lazy=bool(message.get("lazy"))) elif action == "unwrap": self.unwrap(path, message.get("keep")) elif action == "wrap": self.wrap(path, str(message.get("func", "")), str(message.get("args", "") or ""), children=children) elif action == "isolate": self.isolate(path, children=children) elif action == "matrix": self.edit_matrix(path, str(message.get("op", "")), message.get("rows"), message.get("cols")) elif action == "call": self.call(path, str(message.get("func", "")), children=children, lazy=bool(message.get("lazy"))) elif action == "functions": snap = self.snapshot() snap["functions"] = sympy_functions() snap["signatures"] = {} for name in COMMON_FUNCTIONS: try: snap["signatures"][name] = function_signature(name) except ValueError: pass return snap elif action == "signature": target = self._extract_range(self.expr, self._path(path), children) if children is not None else self._get_at(self.expr, self._path(path)) snap = self.snapshot() snap["signature"] = function_signature(str(message.get("name", "")), target) return snap elif action == "extend": self.extend(path, str(message.get("side", "after")), str(message.get("src", ""))) elif action == "set": self.replace("/", str(message.get("src", ""))) elif action == "apply": self.apply(path, str(message.get("op", "")), children=children, args=message.get("args"), lazy=bool(message.get("lazy"))) elif action == "delete": self.delete(path, children=children) elif action == "undo": self.undo() elif action == "redo": self.redo() elif action == "snapshot": pass else: raise ValueError(f"Unknown action: {action!r}") snap = self.snapshot() if self.last_note: snap["note"] = self.last_note return snap except Exception as exc: return self.snapshot(error=f"{type(exc).__name__}: {exc}") finally: self._action_label = None def _handle_addon(self, message: Dict[str, Any]) -> Dict[str, Any]: """One of an add-on's methods (see :meth:`Addon.handle`): a dict answer is a query, put under ``snap["query"]`` with nothing changed; a SymPy object is committed as the whole expression; None leaves the document as the method left it.""" name = str(message.get("addon", "")) method = str(message.get("method", "")) addon = self.addons.get(name) if addon is None: raise ValueError(f"No add-on {name!r} in this document (it has {', '.join(self.addons) or 'none'})") payload = {k: v for k, v in message.items() if k not in ("action", "addon", "method", "_req")} self._action_label = addon.describe(method, payload) or f"{addon.label or name}: {method}" try: result = addon.handle(self, method, payload) except Exception as exc: # The failure goes back to the panel that asked (api.call rejects # with it) and nowhere else: the editor's own error line is for # the editor's own edits. The plot asking for samples of a piece # that has none is not an error of the formula. snap = self.snapshot() snap["query"] = {"addon": name, "method": method, "error": f"{type(exc).__name__}: {exc}"} return snap if isinstance(result, dict): snap = self.snapshot() snap["query"] = {"addon": name, "method": method, "result": result} return snap if result is not None: self._commit(self._coerce(result)) snap = self.snapshot() snap["addon"] = {"name": name, "method": method} if self.last_note: snap["note"] = self.last_note return snap def _describe(self, message: Dict[str, Any]) -> Optional[str]: """What a message does, for the history ("Transform: Simplify", "SymPy: diff(x)", "Edit: y → cos(y)"...).""" def short(text: Any, n: int = 48) -> str: text = str(text).replace("\n", " ") return text if len(text) <= n else text[: n - 1] + "…" def node() -> str: try: p = self._path(message.get("path", "/")) if message.get("children") is not None: return short(self._extract_range(self.expr, p, message["children"])) return short(self._get_at(self.expr, p)) except Exception: return "…" action = message.get("action") try: if action == "replace": return f"Edit: {node()} → {short(message.get('src', ''))}" if action == "set": return f"Type the whole expression: {short(message.get('src', ''))}" lazy = " (unevaluated)" if message.get("lazy") else "" if action == "apply": op = self.ops.get(str(message.get("op", ""))) return f"Transform: {op.label if op else message.get('op')}{lazy}" if action == "call": return f"SymPy: {short(message.get('func', ''))}{lazy}" if action == "insert": return f"Insert \"{short(message.get('src', ''))}\" in {node()}" if action == "operator": sym = str(message.get("op", "") or "").strip() or "nothing (a product)" return f"Operator {sym} in {node()}{lazy}" if action == "extend": return f"Type \"{short(message.get('src', ''))}\" {'after' if message.get('side', 'after') == 'after' else 'before'} {node()}" if action == "delete": return f"Delete {node()}" if action == "unwrap": return f"Unwrap {node()}" if action == "isolate": return f"Isolate {node()}" if action == "matrix": op = str(message.get("op", "")) if op == "resize": return f"Matrix: resize to {message.get('rows')}×{message.get('cols')}" if op == "reshape": return f"Matrix: reshape to {message.get('rows')}×{message.get('cols')}" return "Matrix: " + {"insert_row": "new row", "insert_col": "new column", "delete_row": "delete row", "delete_col": "delete column"}.get(op, op) if action in ("retype", "declare"): return f"{'Retype' if action == 'retype' else 'Declare'} {message.get('name')} as {message.get('type', 'Symbol')}" except Exception: pass return str(action).capitalize() if action else None # -- helpers ------------------------------------------------------------ @staticmethod def _path(path: PathLike) -> Path: return parse_path(path) if isinstance(path, str) else tuple(path) def _coerce(self, expr) -> Basic: # srepr output names Str (a MatrixSymbol's name) which SymPy < 1.14 # does not export: without it in scope, sympify reads Str('A') as an # undefined function of A, and the matrix symbol's name becomes "Str". # An add-on's node types are named in its namespace, so its srepr # strings read back too. if isinstance(expr, str): local: Dict[str, Any] = {"Str": Str, "Placeholder": Placeholder} for addon in getattr(self, "addons", {}).values(): for name, obj in addon.namespace().items(): local.setdefault(name, obj) result = sympify(expr, locals=local) else: result = sympify(expr) if not isinstance(result, Basic): raise TypeError(f"Cannot edit {type(expr).__name__} objects") return result def _showable(self, expr: Basic) -> None: """Refuse an expression the front end could not render. Every message answers with a snapshot of the current expression, so a head of the history that does not print would fail every request after the one that put it there - the document would be dead. The annotated render done here is kept for the history list.""" try: self._render_cache_get(expr) annotate_str(expr) plain_latex(expr, **self.printer_settings) except Exception as exc: raise ValueError(f"The result cannot be shown ({type(exc).__name__}: {exc}); " "the expression is unchanged") from None def _commit(self, expr: Basic) -> Basic: self._showable(expr) del self._history[self._index + 1:] del self._labels[self._index + 1:] self._history.append(expr) self._labels.append(self._action_label) if len(self._history) > self.max_history: del self._history[: len(self._history) - self.max_history] del self._labels[: len(self._labels) - self.max_history] self._index = len(self._history) - 1 self._notify() return expr def _notify(self) -> None: # The edit is committed by now: a callback that fails must not make # it look as if it had not been. Its traceback goes to the log. for cb in list(self._listeners): try: cb(self.expr) except Exception: logging.getLogger(__name__).exception("on_change callback %r failed", cb) def __repr__(self) -> str: return f"Document({self.expr!r})"