expr_tracker 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

expr_tracker/alerts/backends/__init__.py

@@ -13,6 +13,7 @@ from .base import (
     create_backend,
     post_json,
     register_backend,
+    render_html,
     render_text,
 )
 
@@ -189,7 +190,10 @@ class EmailBackend(AlertBackend):
         mail["Subject"] = f"[{message.level.value}] {message.title}"
         mail["From"] = options.get("sender") or options.get("user") or "expr-tracker"
         mail["To"] = ", ".join(recipients)
-        mail.set_content(render_text(message))
+        # multipart/alternative: rich clients show the card, the rest see the text
+        mail.set_content(f"{message.title}\n\n{render_text(message)}")
+        if options.get("html", True):
+            mail.add_alternative(render_html(message), subtype="html")
         policy_timeout = self.config.policy.timeout if self.config.policy else 10.0
         try:
             factory = smtplib.SMTP_SSL if options.get("ssl") else smtplib.SMTP

expr_tracker/alerts/backends/base.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import html
 import json
 import urllib.error
 import urllib.parse
@@ -85,7 +86,7 @@ def post_json(
 
 def render_text(message: AlertMessage, include_fields: bool = True) -> str:
     """Render a message as plain text for channels without rich cards."""
-    parts = [message.text]
+    parts = [message.subtitle, message.text] if message.subtitle else [message.text]
     if include_fields and message.fields:
         parts.append("")
         parts.extend(f"{key}: {value}" for key, value in message.fields.items())
@@ -97,6 +98,74 @@ def render_text(message: AlertMessage, include_fields: bool = True) -> str:
     return "\n".join(parts)
 
 
+LEVEL_COLORS = {
+    "debug": "#616161",
+    "info": "#0288d1",
+    "warning": "#ed6c02",
+    "error": "#d32f2f",
+    "critical": "#b71c1c",
+}
+
+
+def render_html(message: AlertMessage) -> str:
+    """Render a message as self-contained HTML for email.
+
+    Everything is inline-styled and table-based: mail clients strip stylesheets,
+    and several of them ignore ``div`` layout entirely.
+    """
+    color = LEVEL_COLORS.get(message.level.value, "#616161")
+    esc = html.escape
+    rows = "".join(
+        f'<tr><td style="padding:4px 12px 4px 0;color:#666;'
+        f'white-space:nowrap;vertical-align:top">{esc(str(key))}</td>'
+        f'<td style="padding:4px 0;color:#111">{esc(str(value))}</td></tr>'
+        for key, value in message.fields.items()
+    )
+    blocks = [
+        f'<tr><td style="background:{color};padding:14px 20px;color:#fff">'
+        f'<div style="font-size:17px;font-weight:600">{esc(message.title)}</div>'
+        f'<div style="font-size:12px;opacity:.85;text-transform:uppercase;'
+        f'letter-spacing:.05em">{esc(message.level.value)}'
+        + (f" &middot; {esc(message.subtitle)}" if message.subtitle else "")
+        + "</div></td></tr>"
+    ]
+    if message.text:
+        blocks.append(
+            '<tr><td style="padding:18px 20px 0;font-size:14px;line-height:1.5;'
+            f'color:#111">{esc(message.text)}</td></tr>'
+        )
+    if rows:
+        blocks.append(
+            '<tr><td style="padding:16px 20px 0"><table cellpadding="0" '
+            f'cellspacing="0" style="font-size:13px">{rows}</table></td></tr>'
+        )
+    if message.traceback:
+        blocks.append(
+            '<tr><td style="padding:16px 20px 0"><pre style="margin:0;padding:12px;'
+            "background:#f6f6f6;border-radius:4px;font-size:12px;overflow:auto;"
+            f'white-space:pre-wrap">{esc(message.traceback)}</pre></td></tr>'
+        )
+    if message.link:
+        link = esc(message.link)
+        blocks.append(
+            f'<tr><td style="padding:18px 20px 0"><a href="{link}" '
+            f'style="display:inline-block;padding:8px 16px;background:{color};'
+            'color:#fff;text-decoration:none;border-radius:4px;font-size:13px">'
+            "Open run</a></td></tr>"
+        )
+    blocks.append('<tr><td style="padding:20px"></td></tr>')
+    return (
+        '<html><body style="margin:0;background:#f4f4f4;'
+        'font-family:-apple-system,Segoe UI,Roboto,Helvetica,Arial,sans-serif">'
+        '<table cellpadding="0" cellspacing="0" width="100%" '
+        'style="background:#f4f4f4;padding:24px 0"><tr><td align="center">'
+        '<table cellpadding="0" cellspacing="0" width="520" '
+        'style="background:#fff;border-radius:6px;overflow:hidden;max-width:520px">'
+        + "".join(blocks)
+        + "</table></td></tr></table></body></html>"
+    )
+
+
 def _parse_retry_after(value) -> float | None:
     try:
         return float(value)

expr_tracker/alerts/engine.py

@@ -209,7 +209,12 @@ class AlertEngine:
         except Exception as e:  # pragma: no cover - format_map already tolerates gaps
             logger.warning(f"Failed to render message for rule {rule.name!r}: {e}")
             rendered = rule.condition
-        title = _format(rule.title, values) if rule.title else rule.name
+        if rule.title:
+            title = _format(rule.title, values)
+        else:
+            # An auto-generated name is a hash; the condition says far more,
+            # especially as an email subject line
+            title = rule.condition if getattr(rule, "auto_named", False) else rule.name
         level = AlertLevel.INFO if recovered else rule.level
         message = AlertMessage(
             title=f"[recovered] {title}" if recovered else title,

expr_tracker/alerts/expr/lexer.py

@@ -11,6 +11,7 @@ OP = "OP"
 EOF = "EOF"
 
 KEYWORDS = {"and", "or", "not", "true", "false"}
+QUOTES = "\"'`"
 TWO_CHAR_OPS = {">=", "<=", "==", "!=", "&&", "||"}
 ONE_CHAR_OPS = set("><+-*/%()[],|&!~")
 DURATION_UNITS = (
@@ -51,10 +52,10 @@ def tokenize(source: str) -> list[Token]:
             i += 1
             continue
         start = i
-        if ch == "`":
-            end = source.find("`", i + 1)
+        if ch in QUOTES:
+            end = source.find(ch, i + 1)
             if end < 0:
-                raise ExprSyntaxError("Unterminated `identifier`", source, i)
+                raise ExprSyntaxError(f"Unterminated {ch}quoted name{ch}", source, i)
             tokens.append(Token(NAME, source[i + 1 : end], start))
             i = end + 1
             continue
@@ -69,8 +70,7 @@ def tokenize(source: str) -> list[Token]:
                 tokens.append(Token(NUMBER, float(text), start))
             continue
         if ch.isalpha() or ch == "_":
-            while i < n and (source[i].isalnum() or source[i] in "_."):
-                i += 1
+            i = scan_name(source, i)
             word = source[start:i]
             tokens.append(
                 Token(
@@ -110,6 +110,25 @@ def parse_duration(text: str) -> float:
         ) from e
 
 
+def is_name_char(ch: str) -> bool:
+    return ch.isalnum() or ch in "_.@"
+
+
+def scan_name(source: str, i: int) -> int:
+    """Consume a metric name, which may contain ``/`` as in ``val/m1/acc@16``.
+
+    A ``/`` only joins the name when a name character follows it immediately, so
+    division has to be spaced: ``a / b`` divides, ``a/b`` is one metric.
+    """
+    n = len(source)
+    while i < n and (
+        is_name_char(source[i])
+        or (source[i] == "/" and i + 1 < n and is_name_char(source[i + 1]))
+    ):
+        i += 1
+    return i
+
+
 def _scan_number(source: str, i: int) -> int:
     n = len(source)
     while i < n and (source[i].isdigit() or source[i] == "."):

expr_tracker/alerts/expr/nodes.py

@@ -113,7 +113,7 @@ class MetricRef(Node):
     name: str
 
     def to_source(self) -> str:
-        return self.name if _is_plain(self.name) else f"`{self.name}`"
+        return self.name if _is_plain(self.name) else _quote(self.name)
 
     def metrics(self) -> set[str]:
         return {self.name}
@@ -342,9 +342,27 @@ def _wrap(node: Node, parent_op: str | None = None) -> str:
 
 
 def _is_plain(name: str) -> bool:
+    """Whether the name can be written bare and lex back to exactly itself."""
+    from .lexer import is_name_char
+
     if not name or not (name[0].isalpha() or name[0] == "_"):
         return False
-    return all(ch.isalnum() or ch in "_." for ch in name)
+    for index, ch in enumerate(name):
+        if is_name_char(ch):
+            continue
+        # A `/` only joins the name when a name character follows it
+        if ch == "/" and index + 1 < len(name) and is_name_char(name[index + 1]):
+            continue
+        return False
+    return True
+
+
+def _quote(name: str) -> str:
+    """Wrap a name in whichever quote it does not already contain."""
+    for quote in ('"', "'", "`"):
+        if quote not in name:
+            return f"{quote}{name}{quote}"
+    return f'"{name}"'  # pragma: no cover - a name with all three quote styles
 
 
 def _format_duration(seconds: float | None) -> str:

expr_tracker/alerts/models.py

@@ -230,6 +230,9 @@ class AlertRule:
                 f"Unknown alert rule mode {self.mode!r}; use 'edge' or 'level'."
             )
         self.for_steps = max(1, int(self.for_steps))
+        # A generated name identifies the rule but reads badly as a headline, so
+        # remember whether the user chose it. Not a field: it stays out of to_dict().
+        self.auto_named = not self.name
         if not self.name:
             self.name = f"rule_{self._auto_digest()}"
         if not self.message:

{expr_tracker-0.2.0.dist-info → expr_tracker-0.2.2.dist-info}/METADATA

@@ -1,8 +1,28 @@
 Metadata-Version: 2.4
 Name: expr_tracker
-Version: 0.2.0
-Summary: Add your description here
+Version: 0.2.2
+Summary: Local-first experiment tracking with queryable history and expression-based alerts on your training metrics
+Project-URL: Homepage, https://hspk.github.io/expr_tracker/
+Project-URL: Documentation, https://hspk.github.io/expr_tracker/
+Project-URL: Repository, https://github.com/HSPK/expr_tracker
+Project-URL: Issues, https://github.com/HSPK/expr_tracker/issues
+Project-URL: Changelog, https://github.com/HSPK/expr_tracker/releases
 Author-email: HSPK <whxway@whu.edu.cn>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: alerting,deep-learning,experiment-tracking,machine-learning,mlops,monitoring,training,wandb
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: click>=8.1.0
 Requires-Dist: loguru>=0.7.3
@@ -27,6 +47,11 @@ Description-Content-Type: text/markdown
 
 # Experiment Tracker
 
+[![PyPI](https://img.shields.io/pypi/v/expr-tracker)](https://pypi.org/project/expr-tracker/)
+[![Python](https://img.shields.io/pypi/pyversions/expr-tracker)](https://pypi.org/project/expr-tracker/)
+[![License](https://img.shields.io/pypi/l/expr-tracker)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-github.io-blue)](https://hspk.github.io/expr_tracker/)
+
 A local-first experiment tracker. Metrics land in a JSONL file you own, stay
 queryable while the run is live, and can trigger alerts from an expression language.
 `wandb` and `trackio` are optional mirrors, not requirements.
@@ -141,3 +166,7 @@ Published to GitHub Pages by `.github/workflows/docs.yaml` on every push to `mai
 Internals: [`docs/design.md`](docs/design.md) (data model and key invariants) and
 [`docs/architecture.md`](docs/architecture.md) (module map, read/write paths,
 concurrency model).
+
+## License
+
+[MIT](LICENSE)

{expr_tracker-0.2.0.dist-info → expr_tracker-0.2.2.dist-info}/RECORD

@@ -3,21 +3,22 @@ expr_tracker/_compat.py,sha256=qf8oYIK_lkoLzcPp6wPCYLJtVatCl7ROYRNPwc5F1Pg,981
 expr_tracker/artifacts.py,sha256=yRVXmuqdZUxiZa0c_CwZi4rBxaItwhu9bZ1x21yP1S0,12560
 expr_tracker/cli.py,sha256=YM1tuPX19Y_oNWtCi1DmAY3wyKd-uGILzM1twvv5il4,6305
 expr_tracker/encoders.py,sha256=X5ySQasSrYPsdYCdk7nhpJFGFB9f_8HWQuGOQjTvh9E,11991
+expr_tracker/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 expr_tracker/run.py,sha256=7hHuLaa5Ox-cP891eMuxZ6_Uy9iTaaqMjjshl32kmVk,15744
 expr_tracker/summary.py,sha256=lpHSh3pci2Ym6wJhVZwNUJbUp2A64EN_rC7Ym2d7PPI,3150
 expr_tracker/tracker.py,sha256=NabstZ2Ysme64RkPooZj-r7AA8Wst49H9au5Q7yTn9o,5073
 expr_tracker/types.py,sha256=69gFtUaKGl4asLK7nJci9XyTyV0yTIPorB-bcfGrCBA,383
 expr_tracker/alerts/__init__.py,sha256=dl96OYZh75kV3NLBSA35zNvTFcL6XFMuPoYvRoz7hlQ,8192
 expr_tracker/alerts/dispatch.py,sha256=k2pDZVJy6ajlQ7kUdvaBBZ_AmdtZ8opaQWjADn_i8uI,11652
-expr_tracker/alerts/engine.py,sha256=t7MfyqHZefPa9qQajue7YZCFp2lFsM17HQaONgBOde8,13547
-expr_tracker/alerts/models.py,sha256=NurzlMusmpL2trl9STAwZr4LBQAVVg5BunDX3ilq-Fg,11739
-expr_tracker/alerts/backends/__init__.py,sha256=a4XGFOTkP1aaZWypu_1lUPYi8c1iw5VIBBOlktMWpFU,8387
-expr_tracker/alerts/backends/base.py,sha256=Vwdo3rYoAYykVHRW4Ga4fKH1BsrzDvtzlBWHu4UScV8,3592
+expr_tracker/alerts/engine.py,sha256=Lcfc3VchFegmbAwHwTE6mWuG4gUYAlbsAoq5gDd6cr8,13774
+expr_tracker/alerts/models.py,sha256=LjPGBKXroxGP1qYm456shNQAbkm1PEVga0vBy4nxRZI,11946
+expr_tracker/alerts/backends/__init__.py,sha256=6j2wyfG1mMuWkdI5i99gOUlxOTwfuMOeg78dYs_ciT0,8620
+expr_tracker/alerts/backends/base.py,sha256=tILaNVDQ4rt9WoxO-KXHfWkIza_lX-eFO70LsSf2aTo,6479
 expr_tracker/alerts/expr/__init__.py,sha256=qXBt6ih1pMAplUozsDzYY_ZWHlLABX4NoshbjJO_oJk,616
 expr_tracker/alerts/expr/eval.py,sha256=UccIwg1r-A_yzUf16TGyx3MO8e0kegCsrRHDyHirsNg,11609
 expr_tracker/alerts/expr/functions.py,sha256=wuuFKplta_5KkFHIsvEmpryFtPCdfHV4wjqnx3t2g9A,7043
-expr_tracker/alerts/expr/lexer.py,sha256=_EsZR17-8KDJaqwMWDzQ4F9dpQdufoY3deEfFZwppBQ,4047
-expr_tracker/alerts/expr/nodes.py,sha256=bsfdULXPl9PQvtFfJTYgy1V9GFRhGO_3-W3BxSxtavk,9251
+expr_tracker/alerts/expr/lexer.py,sha256=NrvDi-f_8F9V1_vQT-vAGENNA8nauD9IbJH4r21-7oQ,4563
+expr_tracker/alerts/expr/nodes.py,sha256=ZsXX4VJDolVQsVoEtIhkDj6QspMz7lTfRYaEZ8F6grg,9896
 expr_tracker/alerts/expr/parser.py,sha256=heGXAVjCZ1AM0u5-Usld4G_P38N0nUaXMlh8C7CHqjQ,6315
 expr_tracker/alerts/expr/rule.py,sha256=nO8vzhWyGDxSmSXqJrXOU_Yoy7Tzot3_c2W2bZ4s2Qw,3653
 expr_tracker/history/__init__.py,sha256=sppio0jJ2E8WBr3HcZ7UO5vo7GNqQA1rhEgN6wuhQ_o,522
@@ -27,7 +28,8 @@ expr_tracker/history/reader.py,sha256=YYrQluS5dopax84ltd5gr6xO4yrygRiOo3emIhjR6K
 expr_tracker/history/series.py,sha256=cFdUO1FRs5KW0jYsNPzda3tcu645NH1wwfXJitQfXFM,4042
 expr_tracker/history/store.py,sha256=Q7F0I_dF2zxHUTtSnzfVCviSeAvW49i3OqLMjoQh1sQ,33072
 expr_tracker/history/writer.py,sha256=q5kNANcZCq5nykvOK5jZ2xc6Z1B4oZxEn3uSXzDCtlY,16096
-expr_tracker-0.2.0.dist-info/METADATA,sha256=UWReC8eKpPLsgmA-HYizoa7LD7wBP1n6Y7ax_f-o7fo,6867
-expr_tracker-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-expr_tracker-0.2.0.dist-info/entry_points.txt,sha256=GfZCAG2JFsd5CxTjRsGJAhYInpBCuLjrU3csmUVBDSs,45
-expr_tracker-0.2.0.dist-info/RECORD,,
+expr_tracker-0.2.2.dist-info/METADATA,sha256=525p8soaoyMXiBApvXQjcJ5JVTJOb1b0v6lakS6ZB5Y,8388
+expr_tracker-0.2.2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+expr_tracker-0.2.2.dist-info/entry_points.txt,sha256=GfZCAG2JFsd5CxTjRsGJAhYInpBCuLjrU3csmUVBDSs,45
+expr_tracker-0.2.2.dist-info/licenses/LICENSE,sha256=ORsYTnF-2SLUaM8FgXlJ-uXuN4ceGACAAU3JZiS8pvs,1069
+expr_tracker-0.2.2.dist-info/RECORD,,

expr_tracker-0.2.2.dist-info/licenses/LICENSE

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