expr-tracker 0.2.0__tar.gz → 0.2.1__tar.gz

{expr_tracker-0.2.0 → expr_tracker-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: expr_tracker
-Version: 0.2.0
+Version: 0.2.1
 Summary: Add your description here
 Author-email: HSPK <whxway@whu.edu.cn>
 Requires-Python: >=3.10

{expr_tracker-0.2.0 → expr_tracker-0.2.1}/docs/design.md

@@ -199,15 +199,23 @@ unary   := ("-"|"+") unary | postfix
 postfix := primary ("[" window "]")?
 primary := NUMBER | DURATION | ident | ident "(" args ")" | "(" expr ")"
 window  := INT (points) | DURATION (30s / 5m / 2h)
-ident   := [A-Za-z_][A-Za-z0-9_.]* | `anything`
+ident   := [A-Za-z_][A-Za-z0-9_.@]* ("/" [A-Za-z0-9_.@]+)*   # train/loss, val/m1/acc@16
+         | "quoted" | 'quoted' | `quoted`                    # anything else
 ```
 
+A `/` joins an identifier only when a name character follows it immediately, so
+division has to be spaced: `a/b` is one metric, `a / b` divides. That makes the
+common case (`train/loss`) free of ceremony at the cost of `loss/2` naming a metric
+rather than halving `loss`. Quoted forms produce names, never string literals — the
+grammar has no strings, and the function table is a closed whitelist.
+
 A hand-written lexer and Pratt parser, **not Python's `ast`**: Python reads
 `diff(m1)>50 | m1>5` as `diff(m1) > (50|m1) > 5`. Precedence, low to high:
 `or < and < not < comparison < +- < */% < unary < call/window`.
 
 **Metric resolution**: exact name → `.` replaced by `/` → error with close-match
-suggestions. So `eval.acc` finds `eval/acc`; use backticks for exotic names.
+suggestions. So `eval.acc` finds `eval/acc`; quote anything the bare grammar cannot
+express.
 
 ### C.2 Three-valued logic (Kleene)
 

{expr_tracker-0.2.0 → expr_tracker-0.2.1}/docs/guide/alerts.md

@@ -29,8 +29,9 @@ Key points, covered fully in [Alert expressions](../reference/expressions.md):
   `loss[5m]` the last 5 minutes.
 - Precedence is `or < and < not < comparison < arithmetic` — **not** Python's. So
   `diff(m1) > 50 | m1 > 5` parses the way it reads, as `(diff(m1) > 50) or (m1 > 5)`.
-- `.` in a metric name resolves to `/`, so `eval.acc` finds `eval/acc`. Use backticks
-  for anything exotic: `` `a-b c` ``.
+- Metric names may contain `/` and `@` directly (`train/loss`, `val/m1/acc@16`), so
+  division has to be spaced: `a/b` is one metric, `a / b` divides. Quote anything
+  else with `"`, `'` or backticks: `"train loss"`.
 - Missing data, too few points, NaN and division by zero all evaluate to UNKNOWN,
   which never fires and never changes state. Warm-up cannot produce false alarms.
 

{expr_tracker-0.2.0 → expr_tracker-0.2.1}/docs/reference/expressions.md

@@ -30,9 +30,44 @@ Precedence is `or < and < not < comparison < +- < */%`.
 
 ## Metric names
 
-- Bare names: `loss`, `grad_norm`.
-- `.` resolves to `/`: `eval.acc` finds the metric `eval/acc`.
-- Backticks for anything else: `` `a-b c` ``, `` `中文指标` ``.
+Bare names may contain letters, digits, `_`, `.`, `@` and `/`, so the names ML code
+actually uses need no ceremony:
+
+```
+train/loss > 1
+val/m1/acc@16 < 0.5
+mean(train/loss[20]) > 1
+```
+
+`.` also resolves to `/`, so `eval.acc` finds `eval/acc` if no metric is literally
+called `eval.acc`.
+
+### `/` is part of a name unless it is spaced
+
+A `/` joins the name when a name character follows it immediately. Division must
+therefore be written with spaces:
+
+| Written | Means |
+| --- | --- |
+| `a/b` | the metric `a/b` |
+| `a / b` | `a` divided by `b` |
+| `a /b`, `a/ b` | `a` divided by `b` (any space makes it division) |
+| `loss/2` | the metric `loss/2` |
+| `loss / 2` | `loss` divided by 2 |
+| `1/2` | division — a name cannot start with a digit |
+
+### Quote anything else
+
+A name with spaces or other characters must be quoted, with `"`, `'` or `` ` ``:
+
+```
+"train loss" > 1
+'val acc@16' < 0.5
+`a-b` > 1
+```
+
+Quotes only ever produce a metric name; the language has no string literals.
+`to_source()` renders with `"` (or another quote if the name contains one).
 
 ## Windows
 

expr_tracker-0.2.1/outputs/hello/test/metrics.jsonl

@@ -0,0 +1,5 @@
+{"_step": 0, "_time": 1785984521.3747878, "val/loss": 10, "train/loss": 20}
+{"_step": 1, "_time": 1785984578.8073661, "val/loss": 10, "train/loss": 25}
+{"_step": 2, "_time": 1785984751.5897822, "val/loss": 10, "train/loss": 25}
+{"_step": 3, "_time": 1785984760.5739543, "val/loss": 10, "train/loss": 25}
+{"_step": 4, "_time": 1785984823.973783, "train": 30, "loss": 1}

expr_tracker-0.2.1/outputs/hello/test/metrics.meta.json

@@ -0,0 +1 @@
+{"schema": 2, "size": 369, "lines": 5, "last_step": 4, "max_step": 4, "sorted": true, "has_duplicate_steps": false, "index": [[0, 0, 0]], "run": {"project": "hello", "name": "test", "started_at": 1785984737.2126129}}

expr_tracker-0.2.1/outputs/hello/test/summary.json

@@ -0,0 +1,6 @@
+{
+  "val/loss": 10,
+  "train/loss": 25,
+  "train": 30,
+  "loss": 1
+}

{expr_tracker-0.2.0 → expr_tracker-0.2.1}/src/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-0.2.0 → expr_tracker-0.2.1}/src/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-0.2.0 → expr_tracker-0.2.1}/tests/test_expr_builder.py

@@ -31,7 +31,8 @@ def context(**series):
 
 def test_metric_reference_forms():
     assert M.loss.to_source() == "loss"
-    assert M["train/loss"].to_source() == "`train/loss`"
+    assert M["train/loss"].to_source() == "train/loss"
+    assert M["odd name"].to_source() == '"odd name"'
     assert M.train.loss.to_source() == "train.loss"  # dotted path becomes one name
 
 

{expr_tracker-0.2.0 → expr_tracker-0.2.1}/tests/test_expr_parser.py

@@ -49,10 +49,17 @@ def test_window_selector():
     assert parse("mean(loss[5m])").args[0].duration == 300.0
 
 
-def test_backtick_metric_names():
-    node = parse("`train/loss` > 1")
+@pytest.mark.parametrize("quote", ["`", '"', "'"])
+def test_quoted_metric_names(quote):
+    node = parse(f"{quote}train loss{quote} > 1")
+    assert isinstance(node.left, MetricRef) and node.left.name == "train loss"
+    assert node.to_source() == '"train loss" > 1'  # rendered with the plain quote
+
+
+def test_a_slashed_name_needs_no_quoting():
+    node = parse("train/loss > 1")
     assert isinstance(node.left, MetricRef) and node.left.name == "train/loss"
-    assert node.to_source() == "`train/loss` > 1"
+    assert node.to_source() == "train/loss > 1"
 
 
 def test_dotted_metric_names_are_plain():
@@ -100,9 +107,11 @@ def test_no_python_injection_surface():
     """The grammar is a closed whitelist: no string literals, attributes or free calls."""
     from expr_tracker.alerts.expr import ExprError, validate
 
-    for source in ["__import__('os')", "open('x')", 'eval("1")']:
-        with pytest.raises(ExprSyntaxError):
-            parse(source)
+    # Quoted tokens are metric names, never strings, and the function table is a
+    # closed whitelist, so nothing here survives validation.
+    for source in ["__import__('os')", "open('x')", 'eval("1")', "os.system('ls')"]:
+        with pytest.raises((ExprSyntaxError, ExprError)):
+            validate(parse(source))
     with pytest.raises(ExprError):
         validate(parse("open(1)"))
     # A dot is just part of a metric name, never attribute access
@@ -162,7 +171,7 @@ def test_parse_rule_from_builder():
 
 def test_builder_round_trip():
     node = M["train/loss"][50].zscore() > 4
-    assert node.to_source() == "zscore(`train/loss`[50]) > 4"
+    assert node.to_source() == "zscore(train/loss[50]) > 4"
     assert parse(node.to_source()).to_source() == node.to_source()
 
 

{expr_tracker-0.2.0 → expr_tracker-0.2.1}/tests/test_expr_properties.py

@@ -76,8 +76,11 @@ EXPRESSIONS = [
     "step() > 100",
     # names
     "train.loss > 1",
-    "`odd name` > 1",
-    "`a-b` + `c d` > 1",
+    '"odd name" > 1',
+    "'a-b' + 'c d' > 1",
+    "train/loss > 1",
+    "val/m1/acc@16 > 2",
+    "mean(train/loss[20]) > 1",
     # literals
     "a > 1e-8",
     "a > .5",
@@ -222,7 +225,8 @@ BUILT = {
     "mean(a[5]) > 1": lambda: M.a[5].mean() > 1,
     "mean(a[30s]) > 1": lambda: M.a["30s"].mean() > 1,
     "train.loss > 1": lambda: M.train.loss > 1,
-    "`odd name` > 1": lambda: M["odd name"] > 1,
+    '"odd name" > 1': lambda: M["odd name"] > 1,
+    "train/loss > 1": lambda: M["train/loss"] > 1,
     "diff(a[2]) > 1": lambda: M.a[2].diff() > 1,
     "zscore(a[20]) > 3": lambda: M.a[20].zscore() > 3,
 }

{expr_tracker-0.2.0 → expr_tracker-0.2.1}/tests/test_features.py

@@ -415,3 +415,122 @@ def test_a_missing_config_file_is_an_error(tmp_path):
 def test_an_unsupported_config_source_is_rejected():
     with pytest.raises(TypeError, match="Unsupported alert config"):
         load_config(12345)
+
+
+# ====================================================================== names
+
+
+@pytest.mark.parametrize(
+    "name",
+    [
+        "train/loss",
+        "val/m1/acc@16",
+        "a/b/c/d",
+        "acc@16",
+        "loss@ep1/step",
+        "train/loss.avg",
+        "_private/metric",
+        "a1/b2",
+    ],
+)
+def test_slashed_and_at_names_need_no_quoting(name):
+    node = parse(f"{name} > 1")
+    assert node.metrics() == {name}
+    assert node.to_source() == f"{name} > 1"
+
+
+@pytest.mark.parametrize("source", ["a / b", "a /b", "a/ b", "a  /  b"])
+def test_a_spaced_slash_is_division(source):
+    node = parse(f"{source} > 1")
+    assert node.metrics() == {"a", "b"}
+    assert node.to_source() == "(a / b) > 1"
+
+
+def test_an_unspaced_slash_is_one_metric():
+    node = parse("a/b > 1")
+    assert node.metrics() == {"a/b"}
+
+
+def test_dividing_by_a_number_needs_spaces():
+    """`loss/2` is a metric name; the division has to be written `loss / 2`."""
+    assert parse("loss/2 > 1").metrics() == {"loss/2"}
+    assert parse("loss / 2 > 1").metrics() == {"loss"}
+
+
+def test_numbers_still_divide_without_spaces():
+    """A name cannot start with a digit, so `1/2` is unambiguous."""
+    from expr_tracker.alerts.expr import EvalContext, evaluate
+    from expr_tracker.history import MetricSeries
+
+    assert evaluate(parse("1/2"), EvalContext(MetricSeries())) == 0.5
+
+
+@pytest.mark.parametrize("quote", ['"', "'", "`"])
+def test_every_quote_style_names_a_metric(quote):
+    node = parse(f"{quote}train loss{quote} > 1")
+    assert node.metrics() == {"train loss"}
+
+
+@pytest.mark.parametrize(
+    "name", ["train loss", "a-b", "a b/c", "100loss", "with  spaces", "中文 指标"]
+)
+def test_quoting_carries_names_the_bare_grammar_cannot(name):
+    node = parse(f'"{name}" > 1')
+    assert node.metrics() == {name}
+    assert parse(node.to_source()).metrics() == {name}
+
+
+def test_a_name_containing_a_quote_uses_another_one():
+    assert parse('"a\'b" > 1').to_source() == '"a\'b" > 1'
+    assert parse('`a"b` > 1').to_source() == "'a\"b' > 1"
+
+
+@pytest.mark.parametrize("source", ['"unterminated', "'unterminated", "`unterminated"])
+def test_an_unterminated_quote_is_reported(source):
+    with pytest.raises(ExprSyntaxError, match="Unterminated"):
+        tokenize(f"{source} > 1")
+
+
+@pytest.mark.parametrize("name", ["a/", "a//b", "/a"])
+def test_names_the_lexer_cannot_read_back_are_quoted(name):
+    """to_source must stay re-parseable, so these keep their quotes."""
+    from expr_tracker.alerts.expr.nodes import MetricRef
+
+    rendered = MetricRef(name).to_source()
+    assert rendered != name
+    assert parse(rendered).metrics() == {name}
+
+
+def test_a_slashed_name_works_in_a_window_and_a_call():
+    node = parse("mean(val/m1/acc@16[20]) > 0.5")
+    assert node.metrics() == {"val/m1/acc@16"}
+    assert node.to_source() == "mean(val/m1/acc@16[20]) > 0.5"
+
+
+def test_a_slashed_name_fires_a_real_rule(tmp_path):
+    import expr_tracker as et
+
+    received: list = []
+    run = et.init(
+        project="names",
+        name="r",
+        dir=str(tmp_path),
+        backends=[],
+        max_open_seconds=None,
+        alert={
+            "channels": [
+                {
+                    "type": "callable",
+                    "name": "c",
+                    "options": {"handler": received.append},
+                    "policy": {"async_send": False, "dedup_window": 0},
+                }
+            ]
+        },
+        alert_rules=["val/m1/acc@16 < 0.5 => warning: low accuracy"],
+    )
+    try:
+        run.log({"val/m1/acc@16": 0.1})
+        assert [m.text for m in received] == ["low accuracy"]
+    finally:
+        et.finish()