triplot 1.1.0__py3-none-any.whl

dscpanel/core/ops.py

@@ -0,0 +1,161 @@
+"""Operator registry - the backbone of the F3 search (Blender-style).
+
+Every user-facing action registers here once, with an `enabled` predicate
+evaluated against the live app context, so the search can sieve by what is
+SELECTED - "Distribute offsets evenly" lights up with two or more scans
+selected, "Set molar mass" with one sample, "Flip heat-flow arrow" only when
+the arrow is in the selection. docs/OPERATORS.md is the human-readable log of
+this list; keep the two in sync when adding operators.
+
+UI-free: `ctx` is duck-typed (the main window), predicates and callbacks are
+plain callables, so the registry is testable with a stub context.
+"""
+
+from typing import Callable, List, Optional, Tuple
+
+
+class Operator:
+    def __init__(self, op_id, label, run, enabled=None, category="General",
+                 shortcut="", aliases=(), key="", extra_keys=()):
+        # type: (str, str, Callable, Optional[Callable], str, str, tuple, str) -> None
+        self.id = op_id
+        self.label = label
+        self.run = run
+        self._enabled = enabled
+        self.category = category
+        # `shortcut` is PROSE for the palette ("G, then X/Y/Z, number");
+        # `key` is the machine-readable QKeySequence string the UI actually
+        # binds ("G"). Two fields because the useful thing to tell a user and
+        # the thing Qt can parse are rarely the same text - and because the
+        # binding must not depend on an operator happening to sit in a menu.
+        self.shortcut = shortcut
+        self.key = key
+        # Extra words the search should match - the same action goes by
+        # different names in different programs ("re-perceive" vs
+        # "recalculate" bonds), and a palette that only knows one of them
+        # looks empty to everyone who learned the other.
+        self.aliases = tuple(aliases)
+        # Additional bindings for the SAME operator - a second key people
+        # already have in their fingers from another program (Blender deletes
+        # with X, this program has always used Del). They are bound alongside `key`
+        # and counted by `duplicate_keys` like any other claim.
+        self.extra_keys = tuple(k for k in extra_keys if k)
+
+    def enabled(self, ctx):
+        # type: (object) -> bool
+        if self._enabled is None:
+            return True
+        try:
+            return bool(self._enabled(ctx))
+        except Exception:
+            return False
+
+    def __repr__(self):
+        return "Operator({!r})".format(self.id)
+
+
+class OperatorRegistry:
+    def __init__(self):
+        self._ops = []          # type: List[Operator]
+        self._by_id = {}
+
+    def register(self, op_id, label, run, enabled=None, category="General",
+                 shortcut="", aliases=(), key="", extra_keys=()):
+        # type: (str, str, Callable, Optional[Callable], str, str, tuple, str, tuple) -> Operator
+        if op_id in self._by_id:
+            raise ValueError("duplicate operator id: {}".format(op_id))
+        op = Operator(op_id, label, run, enabled, category, shortcut, aliases,
+                      key, extra_keys)
+        self._ops.append(op)
+        self._by_id[op_id] = op
+        return op
+
+    def unregister(self, op_id):
+        # type: (str) -> bool
+        """Remove an operator. True if there was one.
+
+        For ADD-ONS: `register` raises on a duplicate id, so an add-on that
+        registers an operator and cannot take it away again fails to enable the
+        second time it is switched on - which is an ordinary thing for a user
+        to do while trying one out.
+
+        Safe for an operator registered AFTER startup, which is every add-on's:
+        `MainWindow._install_shortcuts` builds its QActions once, so a late
+        operator has no action or menu entry to leave dangling, and F3 reads
+        the registry live. Removing a built-in one would strand its QAction,
+        so do not.
+        """
+        op = self._by_id.pop(op_id, None)
+        if op is None:
+            return False
+        self._ops = [o for o in self._ops if o.id != op_id]
+        return True
+
+    def get(self, op_id):
+        # type: (str) -> Optional[Operator]
+        return self._by_id.get(op_id)
+
+    def all(self):
+        # type: () -> List[Operator]
+        return list(self._ops)
+
+    def keyed(self):
+        # type: () -> List[Operator]
+        """Operators that own a key binding, in registration order."""
+        return [op for op in self._ops if op.key]
+
+    def duplicate_keys(self):
+        # type: () -> dict
+        """{key: [op ids]} for keys claimed more than once.
+
+        Qt does NOT pick a winner when two QActions share a shortcut: it
+        reports an ambiguous overload and fires NEITHER. F3 was bound twice
+        (Edit menu and App menu) and the operator search silently stopped
+        opening - so a clash is a hard error, not a warning.
+        """
+        seen = {}
+        for op in self._ops:
+            for key in ((op.key,) if op.key else ()) + op.extra_keys:
+                seen.setdefault(key, []).append(op.id)
+        return {k: v for k, v in seen.items() if len(v) > 1}
+
+    def search(self, text, ctx):
+        # type: (str, object) -> List[Tuple[Operator, bool]]
+        """Filter + rank for the F3 dialog. Returns (op, enabled) pairs:
+        substring match on label/category/id (case-insensitive, all words
+        must match), enabled ops first, then label-prefix matches, then
+        registration order."""
+        words = [w for w in (text or "").lower().split() if w]
+        out = []
+        for k, op in enumerate(self._ops):
+            hay = " ".join((op.label, op.category, op.id)
+                           + op.aliases).lower()
+            if all(w in hay for w in words):
+                en = op.enabled(ctx)
+                prefix = op.label.lower().startswith(words[0]) if words else False
+                out.append((not en, not prefix, k, op, en))
+        out.sort(key=lambda t: t[:3])
+        return [(op, en) for _e, _p, _k, op, en in out]
+
+
+def chord_variants(key):
+    # type: (str) -> list
+    """Every spelling of a key that a user pressing it might actually produce.
+
+    A two-part chord like `Shift+Space, L` only matches if Shift is RELEASED
+    before the second key - hold it through, as anyone naturally does, and Qt
+    sees `Shift+Space, Shift+L` and fires nothing. That is why the lasso
+    "hotkey does not work" while the box-select one appeared to: it is not a
+    case problem in the string, it is whether the modifier is still down.
+
+    So a chord whose first part carries Shift is registered BOTH ways. UI-free
+    and returning plain strings, so `_install_shortcuts` stays a loop.
+    """
+    key = str(key or "").strip()
+    if not key or "," not in key:
+        return [key] if key else []
+    head, tail = key.split(",", 1)
+    head, tail = head.strip(), tail.strip()
+    if not tail or "Shift" not in head or "Shift" in tail:
+        return [key]
+    return [key, "{}, Shift+{}".format(head, tail)]

dscpanel/core/presets.py

@@ -0,0 +1,312 @@
+"""Style presets: a figure's look in a file, chosen from a menu.
+
+The house style (`core/style.py`) already has a figure's own column: sizes,
+formats, fonts and alignment saved with ONE session. A preset is that column
+taken out of the session and given a name, so the same look - "thesis",
+"poster", "ACS single column" - is put on any figure in one step, and passed
+to a colleague as a file.
+
+What a preset holds:
+
+* **the style**: every figure setting, RESOLVED (the value the figure is
+  drawn with, not "follow my defaults"), so a preset looks the same on a
+  machine whose defaults differ. A hand-written preset may name only some
+  settings; the others are then left as they are.
+* **the size and margins**, optionally (`core/figure.py`): with them, two
+  figures made with one preset have the same axes box to the hundredth of a
+  millimetre - two stacks side by side in Word.
+* **the frame and the furniture** every figure has (the arrow's place and
+  the axis captions once did not come across): both axes - caption,
+  sizes, distances, ticks, numbers, sides - and the weight axis of an SDT
+  run (all but its side, which follows the heat flow's), the heat-flow
+  arrow's place,
+  shape and text size, and the legend's place and look. Not what the arrow
+  SAYS (exo up or down is a fact about the data) and nothing that belongs
+  to one figure's data: scans, labels, analyses, pictures.
+
+What it does not touch: the other objects' own choices (a label sized by
+hand stays so), the handling settings (the pick distance is about a hand,
+not a figure) and the screen theme.
+
+Applying one is ONE undo step on the figure's column. The files are JSON
+with the extension in `branding.PRESET_EXT`, in a `presets` folder beside
+the preferences; dropping one onto the window installs it there.
+
+UI-free, like the rest of `core`.
+"""
+
+import io
+import json
+import os
+import re
+import shutil
+
+from .. import branding
+from . import figure as figure_module
+from . import labels
+from . import model
+from . import style
+
+FORMAT = "style-preset"
+VERSION = 1
+
+_AXIS_FIELDS = ("visible", "label", "label_size", "label_along", "label_gap",
+                "show_numbers", "tick_size", "number_format", "side",
+                "ticks_inward", "minor_ticks", "minor_count", "major_step",
+                "tick_length", "minor_length", "mirror", "mirror_ticks",
+                "show_grid")
+
+#: Which fields of which of the figure's own objects a preset carries.
+OBJECT_FIELDS = {
+    "axis_x": _AXIS_FIELDS,
+    "axis_y": _AXIS_FIELDS,
+    # The weight axis of an SDT run: its side is always the one opposite
+    # the heat flow's, and it has no line of its own on the far side.
+    "axis_y2": tuple(f for f in _AXIS_FIELDS
+                     if f not in ("side", "mirror", "mirror_ticks")),
+    "arrow": ("visible", "x", "y", "space", "anchor", "colour", "size",
+              "head_length", "head_width", "tail_width", "tail_length",
+              "lock"),
+    "legend": ("visible", "x", "y", "space", "anchor", "colour", "rotation",
+               "size", "show_frame", "sample", "spacing", "line_width"),
+}
+
+#: What each carried field may hold, for checking a file: "bool", "number",
+#: "number?" (or None), "int", "text?", "format?", or a tuple of choices.
+_KINDS = {
+    "visible": "bool", "show_numbers": "bool", "ticks_inward": "bool",
+    "minor_ticks": "bool", "mirror": "bool", "mirror_ticks": "bool",
+    "show_grid": "bool", "show_frame": "bool",
+    "label": "text?", "number_format": "format?", "colour": "text",
+    "label_size": "number?", "label_gap": "number?", "tick_size": "number?",
+    "major_step": "number?", "size": "number?", "line_width": "number?",
+    "minor_count": "int", "label_along": "number", "tick_length": "number",
+    "minor_length": "number", "x": "number", "y": "number",
+    "rotation": "number", "head_length": "number", "head_width": "number",
+    "tail_width": "number", "tail_length": "number", "sample": "number",
+    "spacing": "number",
+    "space": (model.SPACE_RELATIVE, model.SPACE_DATA),
+    "anchor": tuple(model.ANCHORS),
+    "lock": (None,) + tuple(model.ARROW_LOCKS),
+}
+
+#: An axis's side, by which axis it is.
+_SIDES = {"axis_x": ("bottom", "top"), "axis_y": ("left", "right")}
+
+
+def figure_objects(doc):
+    """`{name: object}` for the objects a preset styles."""
+    return {"axis_x": doc.axes["x"], "axis_y": doc.axes["y"],
+            "axis_y2": doc.axes["y2"],
+            "arrow": doc.arrow, "legend": doc.legend}
+
+
+def _checked(name, field, raw):
+    """`(True, value)` when `raw` is a legal value of `field`, else
+    `(False, None)`."""
+    kind = _SIDES[name] if field == "side" and name in _SIDES \
+        else _KINDS.get(field)
+    if isinstance(kind, tuple):
+        return (raw in kind, raw if raw in kind else None)
+    if kind is None:
+        return False, None
+    if kind.endswith("?") and raw is None:
+        return True, None
+    kind = kind.rstrip("?")
+    if kind == "bool":
+        return (isinstance(raw, bool), raw)
+    if kind in ("text", "format"):
+        if not isinstance(raw, str):
+            return False, None
+        if kind == "format":
+            cleaned = labels.normalise_format(raw)
+            return (cleaned is not None, cleaned)
+        return True, raw
+    if isinstance(raw, bool) or not isinstance(raw, (int, float)):
+        return False, None
+    if raw != raw or abs(raw) == float("inf"):
+        return False, None
+    if kind == "int":
+        return (raw == int(raw) and raw >= 1, int(raw))
+    return True, float(raw)
+
+
+class Preset(object):
+    """A named look: `values` {setting key: value}; `layout` - a
+    `FigureLayout` state - or None to leave the size alone; and `objects`
+    {"axis_x" / "axis_y" / "axis_y2" / "arrow" / "legend": {field:
+    value}}."""
+
+    def __init__(self, name, values=None, layout=None, path="",
+                 objects=None):
+        self.name = str(name)
+        self.values = dict(values or {})
+        self.layout = dict(layout) if layout else None
+        self.objects = dict((k, dict(v)) for k, v in (objects or {}).items())
+        self.path = str(path or "")
+
+    def __repr__(self):
+        return "Preset({!r})".format(self.name)
+
+
+def folder():
+    """Where presets live: beside the preferences (so a test's temporary
+    preferences have their own presets too)."""
+    return os.path.join(os.path.dirname(style.preferences_path()), "presets")
+
+
+def from_figure(doc, name, with_layout=True):
+    """This figure's look as a preset: every figure setting as it is DRAWN,
+    and the size and margins when `with_layout`."""
+    values = dict((setting.key, style.figure_value(doc, setting.key))
+                  for setting in style.FIGURE_SETTINGS)
+    layout = doc.figure.to_state() if with_layout else None
+    objects = dict((name, dict((field, getattr(obj, field))
+                               for field in OBJECT_FIELDS[name]))
+                   for name, obj in figure_objects(doc).items())
+    return Preset(name, values, layout, objects=objects)
+
+
+def to_state(preset):
+    state = {"format": FORMAT, "version": VERSION, "name": preset.name,
+             "style": dict(preset.values)}
+    if preset.layout:
+        state["figure"] = dict(preset.layout)
+    if preset.objects:
+        state["objects"] = dict((k, dict(v))
+                                for k, v in preset.objects.items())
+    return state
+
+
+def from_state(state, path=""):
+    """A preset from its JSON state. Every value is checked the way the
+    preferences are (`Setting.clean`): an unknown key or an illegal value is
+    left out rather than raised about. ValueError when it is no preset."""
+    if not isinstance(state, dict) or state.get("format") != FORMAT:
+        raise ValueError("not a style preset")
+    values = {}
+    for key, raw in (state.get("style") or {}).items():
+        setting = style.BY_KEY.get(key)
+        if setting is None or not setting.figure:
+            continue
+        cleaned = setting.clean(raw)
+        if cleaned is not None:
+            values[key] = cleaned
+    layout = state.get("figure")
+    if isinstance(layout, dict):
+        checked = figure_module.FigureLayout().load_state(layout)
+        layout = (dict((name, getattr(checked, name))
+                       for name in figure_module.FigureLayout.FIELDS
+                       if name in layout)
+                  if checked.is_valid() else None)
+    else:
+        layout = None
+    objects = {}
+    for name, fields in (state.get("objects") or {}).items():
+        if name not in OBJECT_FIELDS or not isinstance(fields, dict):
+            continue
+        kept = {}
+        for field, raw in fields.items():
+            if field not in OBJECT_FIELDS[name]:
+                continue
+            ok, value = _checked(name, field, raw)
+            if ok:
+                kept[field] = value
+        if kept:
+            objects[name] = kept
+    name = str(state.get("name") or "").strip() or os.path.splitext(
+        os.path.basename(path))[0] or "Preset"
+    return Preset(name, values, layout, path, objects)
+
+
+def read(path):
+    """The preset in the file at `path`. ValueError when it is none."""
+    try:
+        with io.open(path, "r", encoding="utf-8") as fh:
+            state = json.load(fh)
+    except (OSError, ValueError) as exc:
+        raise ValueError("cannot read {}: {}".format(
+            os.path.basename(path), exc))
+    return from_state(state, path)
+
+
+def file_name(name):
+    """A file name for a preset called `name`: its letters, digits, spaces
+    and dashes, and the preset extension."""
+    stem = re.sub(r"[^\w\- ]+", "", str(name)).strip() or "preset"
+    return stem + branding.PRESET_EXT
+
+
+def save(preset, where=None):
+    """Write `preset` into the presets folder (or `where`), replacing one of
+    the same name. Returns the path."""
+    where = where or folder()
+    if not os.path.isdir(where):
+        os.makedirs(where)
+    path = os.path.join(where, file_name(preset.name))
+    temporary = path + ".tmp"
+    with io.open(temporary, "w", encoding="utf-8") as fh:
+        json.dump(to_state(preset), fh, indent=1)
+    os.replace(temporary, path)
+    preset.path = path
+    return path
+
+
+def available(where=None):
+    """`(presets, problems)`: every preset in the folder, by name, and a
+    line for each file that could not be read."""
+    where = where or folder()
+    found, problems = [], []
+    try:
+        names = sorted(os.listdir(where))
+    except OSError:
+        return [], []
+    for entry in names:
+        if not entry.lower().endswith(branding.PRESET_EXT):
+            continue
+        try:
+            found.append(read(os.path.join(where, entry)))
+        except ValueError as exc:
+            problems.append(str(exc))
+    found.sort(key=lambda p: p.name.lower())
+    return found, problems
+
+
+def install(path, where=None):
+    """A preset file from elsewhere (a drop, a colleague's), copied into the
+    presets folder and returned. ValueError when it is no preset."""
+    preset = read(path)
+    where = where or folder()
+    if not os.path.isdir(where):
+        os.makedirs(where)
+    target = os.path.join(where, file_name(preset.name))
+    if os.path.normcase(os.path.abspath(path)) != os.path.normcase(
+            os.path.abspath(target)):
+        shutil.copyfile(path, target)
+    preset.path = target
+    return preset
+
+
+def changes(doc, preset):
+    """`[(obj, attr, value), ...]` that put `preset` on `doc`: the figure's
+    style column and, when the preset has one, its size and margins. Only
+    what differs, so an undo step holds exactly what changed."""
+    out = []
+    for key, value in preset.values.items():
+        if getattr(doc.style, key, None) != value:
+            out.append((doc.style, key, value))
+    if preset.layout:
+        layout = doc.figure
+        wanted = layout.copy().load_state(preset.layout)
+        for name in figure_module.FigureLayout.FIELDS:
+            if getattr(wanted, name) != getattr(layout, name):
+                out.append((layout, name, getattr(wanted, name)))
+    targets = figure_objects(doc)
+    for name, fields in preset.objects.items():
+        obj = targets.get(name)
+        if obj is None:
+            continue
+        for field, value in fields.items():
+            if getattr(obj, field, None) != value:
+                out.append((obj, field, value))
+    return out

dscpanel/core/profile.py

@@ -0,0 +1,15 @@
+"""What is particular to THIS plotter's data: DSC and SDT/TGA.
+
+This program is the first of a family of stacked-trace plotters on one
+handling. The handling is shared; what a kind of data wants differently -
+how F frames it, which analyses exist, which decorators a figure starts
+with - is gathered here, so a sibling changes this module rather than the
+handling code.
+
+UI-free: plain values.
+"""
+
+#: F frames everything at once: a two-step F - x first, then y - is of
+#: no use for DSC. A spectra plotter, where the x range is the question,
+#: sets True.
+FIT_STAGED = False