triplot 1.1.0__py3-none-any.whl

dscpanel/core/loader.py

@@ -0,0 +1,202 @@
+"""Turning a path into a `Sample`: the reader, plus what it does not tell us.
+
+UI-free. The threading that keeps a five-file drop from freezing the window
+lives in `ui/loading.py`; everything here is a plain function, so it can be
+tested against a real file without a window.
+
+**The exotherm direction is read from the file, not assumed.** A DSC trace
+means the opposite thing upside down, and TRIOS stores its own convention:
+
+* a `.txt` export writes `Exotherm Direction   Down` in its header;
+* a `.tri` carries TRIOS's audit trail, where changing the setting leaves the
+  sentence `Sample - Exotherm changed to 'Exo Down' from '0'` (seen in a
+  TRIOS 6.0 run). The last such sentence is the setting that was in force.
+
+Neither is guaranteed to be there - a TRIOS 5.1.1 run may have no audit
+sentence at all - so the fallback is "down", which is the TA default and what
+every file seen so far was recorded under. The fallback is REPORTED rather than
+silent (`Sample.exo_source`), because a file recorded the other way round would
+otherwise produce a figure that is upside down and says nothing about it.
+
+Open item, and the cheapest way to settle it: an indium calibration run. Its
+melting peak is unambiguously endothermic, so which way it points in the
+stored arrays proves what the convention in them is, once and for all.
+"""
+
+import io
+import contextlib
+import os
+import re
+
+from . import model
+from . import trios_io
+from . import units
+
+#: What the open dialog and a drop will accept.
+READABLE = (".tri", ".txt")
+
+#: TRIOS's audit sentence, and the export header line.
+_AUDIT = re.compile(rb"Exotherm changed to '(Exo|Endo) (Up|Down)'",
+                    re.IGNORECASE)
+_HEADER = re.compile(r"^Exotherm\s+Direction\s*[\t:]\s*(Up|Down)\s*$",
+                     re.IGNORECASE | re.MULTILINE)
+
+#: How much of a `.tri` is searched for the audit trail. It sits in the
+#: document region at the END of the file, so the tail is where to look, and
+#: a bounded read keeps this cheap on a 40 MB file.
+_TAIL_BYTES = 4_000_000
+
+
+class ReadError(Exception):
+    """A file that cannot be read as a TRIOS measurement."""
+
+
+def reader_origin():
+    """Which TRIOS reader is in use, for the About box: the program's own
+    (`core/trios_io.py`)."""
+    return "this program's own"
+
+
+def looks_readable(path):
+    """Could this path be a TRIOS file? Extension only, deliberately loose.
+
+    The reader is the only thing that can really tell, so this exists to keep
+    an obvious mis-drop out. Anything that gets past it and turns out not to
+    be a measurement is refused by `read_sample` with a reason, which is a
+    better answer than a drop that silently does nothing.
+    """
+    return (os.path.isfile(str(path))
+            and os.path.splitext(str(path))[1].lower() in READABLE)
+
+
+def detect_exotherm(path):
+    """`(direction, source)` for the file: what the arrays are in.
+
+    `source` is "export header", "audit trail" or "assumed", and the window
+    shows it, because the difference between knowing and assuming is the
+    difference between a figure and an upside-down figure.
+    """
+    path = str(path)
+    ext = os.path.splitext(path)[1].lower()
+    try:
+        if ext == ".txt":
+            with open(path, "r", encoding="latin-1", errors="replace") as fh:
+                head = fh.read(200_000)
+            match = _HEADER.search(head)
+            if match:
+                return match.group(1).lower(), "export header"
+        else:
+            size = os.path.getsize(path)
+            with open(path, "rb") as fh:
+                if size > _TAIL_BYTES:
+                    fh.seek(size - _TAIL_BYTES)
+                raw = fh.read()
+            found = list(_AUDIT.finditer(raw))
+            if found:
+                word, direction = (found[-1].group(1).decode().lower(),
+                                   found[-1].group(2).decode().lower())
+                # The audit sentence names a LABEL ("Exo Down", "Endo Up"),
+                # which is the same pair of words the arrow carries, so the
+                # same function turns it into a direction.
+                return units.orientation(word, direction), "audit trail"
+    except OSError:
+        pass
+    return units.EXO_DOWN, "assumed"
+
+
+def read_sample(path):
+    """Read one file into a `Sample`, keeping what the reader said.
+
+    The reader prints its warnings (a partial segment identified by shape, an
+    analysis that could not be attributed). Under a windowed entry point
+    there is no console for those to reach, and they are exactly the lines
+    somebody needs to see, so they are captured onto the sample and shown in
+    the note line instead of being thrown away.
+    """
+    path = str(path)
+    if not os.path.isfile(path):
+        raise ReadError("no such file: {}".format(os.path.basename(path)))
+    chatter = io.StringIO()
+    try:
+        with contextlib.redirect_stdout(chatter):
+            data = trios_io.read_tri(path)
+    except ReadError:
+        raise
+    except Exception as exc:                 # the reader raises many kinds
+        raise ReadError("{}: {}".format(type(exc).__name__, exc))
+    if not (data or {}).get("numdata"):
+        raise ReadError("no measured segments in {}".format(
+            os.path.basename(path)))
+    exo, source = detect_exotherm(path)
+    sample = model.Sample(path, data, exo=exo, exo_source=source)
+    sample.note = "\n".join(
+        line for line in chatter.getvalue().splitlines() if line.strip())
+    return sample
+
+
+def sibling_export(path):
+    """A TRIOS `.txt` export of the same run, beside the `.tri`, or None.
+
+    Worth finding when a `.tri` segment records no heat flow: the export of
+    the same run is the other place a heat flow can come from, and
+    reconstructing one from the raw sensors is not an option (on the indium
+    calibration run it was 7 % out in heat flow and 0.29 K out in
+    temperature, worse than the calibration is judged by). That indium ramp
+    was the case this was written for, and it turned out to be RECORDED, in
+    arrays with a flags list (TRI-FORMAT.md section 3) that the reader once
+    did not read; no segment of the files tested lacks a heat flow now, but
+    the mechanism stays for one that does.
+    """
+    folder = os.path.dirname(os.path.abspath(str(path)))
+    stem = os.path.splitext(os.path.basename(str(path)))[0].lower()
+    try:
+        names = os.listdir(folder)
+    except OSError:
+        return None
+    for name in names:
+        base, ext = os.path.splitext(name)
+        if ext.lower() == ".txt" and base.lower() == stem:
+            return os.path.join(folder, name)
+    return None
+
+
+def segments_without_heat_flow(sample):
+    """Segment numbers (as TRIOS counts them) that record no heat flow."""
+    out = []
+    for index, step in enumerate((sample.data or {}).get("numdata", [])):
+        dims = step.get("dims") or []
+        if "Heat Flow" not in dims and "Heat Flow (Normalized)" not in dims:
+            out.append(index + 1)
+    return out
+
+
+def summary(sample):
+    """One line about a file that was just opened, for the note line."""
+    bits = ["{}: {} segments".format(sample.name, sample.segment_count())]
+    if sample.mass_g:
+        # An SDT run has no sample-size field: the reader derives the mass
+        # from Weight / Weight Change, and an inference says so.
+        head = (sample.data or {}).get("head", {}) or {}
+        derived = head.get("mass_source") == "derived from the weight"
+        bits.append("{:g} mg{}".format(
+            sample.mass_g * 1000.0,
+            " (derived from the weight)" if derived else ""))
+    else:
+        bits.append("NO SAMPLE MASS")
+    count = sum(len(sample.analyses_for(seg))
+                for seg in range(sample.segment_count()))
+    if count:
+        bits.append("{} stored analyses".format(count))
+    if sample.exo_source == "assumed":
+        bits.append("exo direction assumed to be down")
+    else:
+        bits.append("exo {} ({})".format(sample.exo, sample.exo_source))
+    gaps = segments_without_heat_flow(sample)
+    if gaps:
+        bits.append("segment {} records no heat flow".format(
+            ", ".join(str(g) for g in gaps)))
+        export = sibling_export(sample.path)
+        if export:
+            bits.append("open {} instead, TRIOS derives it there".format(
+                os.path.basename(export)))
+    return ", ".join(bits)

dscpanel/core/log.py

@@ -0,0 +1,147 @@
+"""The log: what the program did, and every error, in a file.
+
+Started from its shortcut the program has no console, so an error had
+nowhere to go - and PySide6 turns an exception inside a Qt slot into the
+end of the process unless an excepthook takes it. `install` fixes both: the
+hook writes the traceback here and the program carries on (the work is
+still open), and `faulthandler` writes the stack of a hard crash - one in
+Qt itself - into a file of its own beside it.
+
+The files live with the preferences (`branding.app_dir()`); Help > Open the
+log folder shows them. Rotating: a megabyte, two old ones kept.
+
+The hook reaches an error in a SLOT only. One inside a method Qt calls by
+itself - `mouseMoveEvent`, `paintEvent`, `event` - ends the process in
+PySide6 6.11 without asking `sys.excepthook`: an access violation, and not
+a line in the log (dragging a label whose curve was hidden did that).
+Every UI module therefore ends with `guard_classes`, which wraps those
+methods so that such an error goes the same way as a slot's.
+
+UI-free. `on_error` is how the window hears about an error it should show.
+"""
+
+import faulthandler
+import functools
+import inspect
+import logging
+import logging.handlers
+import os
+import platform
+import sys
+import time
+import traceback
+
+from .. import branding
+
+#: The program's logger. Modules log through `logging.getLogger(NAME)`;
+#: without `install` (tests, tools) nothing is written anywhere.
+NAME = "dscpanel"
+LOGGER = logging.getLogger(NAME)
+
+#: Called with a one-line summary after an error was logged, or None.
+on_error = None
+
+_crash_file = None
+
+
+def path():
+    """The log file."""
+    return os.path.join(branding.app_dir(), branding.EXE_NAME + ".log")
+
+
+def install(target=None):
+    """Log to `target` (the default file), catch every unhandled error and
+    every hard crash. Returns the file's path; never raises - a program
+    that cannot write its log should still start."""
+    global _crash_file
+    target = target or path()
+    try:
+        folder = os.path.dirname(target)
+        if folder and not os.path.isdir(folder):
+            os.makedirs(folder)
+        handler = logging.handlers.RotatingFileHandler(
+            target, maxBytes=1000000, backupCount=2, encoding="utf-8")
+        handler.setFormatter(logging.Formatter(
+            "%(asctime)s %(levelname)s %(message)s"))
+        LOGGER.addHandler(handler)
+        LOGGER.setLevel(logging.INFO)
+        _crash_file = open(target + ".crash", "a", encoding="utf-8")
+        faulthandler.enable(_crash_file)
+    except OSError:
+        pass
+    sys.excepthook = _hook
+    from .. import __version__
+    LOGGER.info("%s %s started: Python %s on %s", branding.APP_NAME,
+                __version__, platform.python_version(), platform.platform())
+    return target
+
+
+def _hook(kind, value, tb):
+    """Every unhandled error: its traceback into the log, a line to the
+    window. The program carries on."""
+    text = "".join(traceback.format_exception(kind, value, tb))
+    LOGGER.error("Unhandled %s: %s\n%s", kind.__name__, value, text)
+    if sys.__stderr__ is not None:
+        try:
+            sys.__stderr__.write(text)
+        except Exception:
+            pass
+    if on_error is not None:
+        try:
+            on_error("{}: {}".format(kind.__name__, value))
+        except Exception:
+            pass
+
+
+#: The methods Qt calls by itself that `guard_classes` wraps besides every
+#: `...Event`, and what each hands back to Qt when it failed.
+HANDLERS = {"event": True, "eventFilter": False, "nativeEvent": (False, 0),
+            "paint": None, "accept": None, "reject": None, "done": None}
+
+#: The last error a guard reported and when: the same one again within
+#: `QUIET_S` is not reported again, so a paint that fails on every frame
+#: (and the flash that reports it, which paints) does not fill the log.
+_last_guarded = [None, 0.0]
+QUIET_S = 5.0
+
+
+def guarded(function, fallback=None):
+    """`function`, with an error inside it logged and survived WHILE the
+    hook is installed (the program); otherwise (tests, tools) raised as
+    ever, so a test still fails on it."""
+    @functools.wraps(function)
+    def handler(*args, **kwargs):
+        try:
+            return function(*args, **kwargs)
+        except Exception:
+            if sys.excepthook is not _hook:
+                raise
+            kind, value, tb = sys.exc_info()
+            key = (function.__qualname__, kind, str(value))
+            now = time.monotonic()
+            if key != _last_guarded[0] or now - _last_guarded[1] > QUIET_S:
+                _hook(kind, value, tb)
+            _last_guarded[0], _last_guarded[1] = key, now
+            return fallback
+    handler.guarded = True
+    return handler
+
+
+def guard_classes(namespace, module):
+    """Wrap the Qt handlers of every class `module` defines (`guarded`):
+    each `...Event` method and the ones in `HANDLERS`. A UI module ends
+    with `log.guard_classes(globals(), __name__)`; a test checks that none
+    is missed. Returns how many were wrapped."""
+    count = 0
+    for value in list(namespace.values()):
+        if not inspect.isclass(value) or value.__module__ != module:
+            continue
+        for name, attr in list(vars(value).items()):
+            if not (name.endswith("Event") or name in HANDLERS):
+                continue
+            if not inspect.isfunction(attr) or getattr(attr, "guarded",
+                                                       False):
+                continue
+            setattr(value, name, guarded(attr, HANDLERS.get(name)))
+            count += 1
+    return count