expr-tracker 0.3.1__tar.gz → 0.3.5__tar.gz

expr_tracker-0.3.5/.github/workflows/ci.yaml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python }}
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-extras
+
+      - name: Lint
+        run: uv run --frozen ruff check src tests
+
+      - name: Test
+        run: uv run --frozen pytest -m "not slow and not benchmark"

{expr_tracker-0.3.1 → expr_tracker-0.3.5}/.github/workflows/release.yaml

@@ -10,8 +10,12 @@ permissions:
   contents: read
 
 jobs:
+  checks:
+    uses: ./.github/workflows/ci.yaml
+
   release:
     name: Build and publish to PyPI
+    needs: checks
     runs-on: ubuntu-latest
     permissions:
       # required for PyPI trusted publishing (OIDC)

{expr_tracker-0.3.1 → expr_tracker-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: expr_tracker
-Version: 0.3.1
+Version: 0.3.5
 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/
@@ -25,8 +25,11 @@ Classifier: Topic :: System :: Monitoring
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: click>=8.1.0
+Requires-Dist: filelock>=3.12
 Requires-Dist: loguru>=0.7.3
 Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
 Provides-Extra: all
 Requires-Dist: nvidia-ml-py>=12.0; extra == 'all'
 Requires-Dist: pandas>=1.5; extra == 'all'
@@ -86,7 +89,7 @@ et.history(-1, output_type="pd")  # everything, as a DataFrame
 ## Install
 
 ```bash
-uv add expr_tracker                 # local-first: click, loguru, pydantic only
+uv add expr_tracker                 # local-first; no remote backend required
 uv add "expr_tracker[wandb]"        # mirror to Weights & Biases
 uv add "expr_tracker[trackio]"      # mirror to trackio
 uv add "expr_tracker[pandas]"       # history(output_type="pandas")

{expr_tracker-0.3.1 → expr_tracker-0.3.5}/README.md

@@ -39,7 +39,7 @@ et.history(-1, output_type="pd")  # everything, as a DataFrame
 ## Install
 
 ```bash
-uv add expr_tracker                 # local-first: click, loguru, pydantic only
+uv add expr_tracker                 # local-first; no remote backend required
 uv add "expr_tracker[wandb]"        # mirror to Weights & Biases
 uv add "expr_tracker[trackio]"      # mirror to trackio
 uv add "expr_tracker[pandas]"       # history(output_type="pandas")

{expr_tracker-0.3.1 → expr_tracker-0.3.5}/docs/guide/artifacts.md

@@ -26,6 +26,9 @@ Artifacts are **deduplicated by content**: logging the same files again reuses t
 existing version rather than creating a new one, while any new aliases are still
 recorded against it.
 
+Publishers sharing a store serialize version allocation, file copying, and index
+updates with a filesystem lock, including when they run in separate processes.
+
 ```python
 a = et.log_artifact("ckpt.pt", name="model")   # v0
 b = et.log_artifact("ckpt.pt", name="model", aliases=["best"])

{expr_tracker-0.3.1 → expr_tracker-0.3.5}/docs/guide/cli.md

@@ -89,3 +89,17 @@ et alert "node 3 is on fire" --level critical --channel oncall
 
 Channels come from the same configuration the library uses: `ET_ALERT_CONFIG` or the
 `ET_LARK_WEBHOOK_URL` environment variable. See [Alerts](alerts.md).
+
+`et alert` automatically loads `.env` from the directory where you invoke it,
+before resolving alert configuration. Existing environment variables take
+precedence, including empty values. It does not search parent directories; a
+missing `.env` is fine. Use `--no-dotenv` to disable loading.
+
+```dotenv
+# .env
+ET_LARK_WEBHOOK_URL=https://example.com/your-webhook
+```
+
+Quoted values, comments, and `${VAR}` expansion are supported; shell commands are
+not executed. Keep secrets out of version control. This loading applies only to
+`et alert`, not other CLI commands or the Python API.

{expr_tracker-0.3.1 → expr_tracker-0.3.5}/pyproject.toml

@@ -32,8 +32,11 @@ classifiers = [
 ]
 dependencies = [
     "click>=8.1.0",
+    "filelock>=3.12",
     "loguru>=0.7.3",
     "pydantic>=2.0",
+    "python-dotenv>=1.0",
+    "tomli>=2.0; python_version < '3.11'",
 ]
 
 dynamic = ["version"]

{expr_tracker-0.3.1 → expr_tracker-0.3.5}/src/expr_tracker/alerts/__init__.py

@@ -99,7 +99,10 @@ def _read_config_file(path: str | Path) -> dict:
     file = Path(path)
     text = file.read_text(encoding="utf-8")
     if file.suffix == ".toml":
-        import tomllib
+        try:
+            import tomllib
+        except ModuleNotFoundError:
+            import tomli as tomllib
 
         data = tomllib.loads(text)
     elif file.suffix in (".yaml", ".yml"):

{expr_tracker-0.3.1 → expr_tracker-0.3.5}/src/expr_tracker/alerts/backends/__init__.py

@@ -6,7 +6,7 @@ import json
 import smtplib
 from email.message import EmailMessage
 
-from ..models import AlertLevel, AlertMessage
+from ..models import AlertLevel, AlertMessage, WebhookPolicy
 from .base import (
     AlertBackend,
     SendError,
@@ -53,8 +53,15 @@ class UrlBackend(AlertBackend):
         return policy.timeout if policy else 10.0
 
     def post(self, payload: dict) -> str:
+        policy = self.config.policy
         return post_json(
-            self.url, payload, self.timeout, self.config.options.get("headers")
+            self.url,
+            payload,
+            self.timeout,
+            self.config.options.get("headers"),
+            retry_on_status=(
+                policy.retry_on_status if policy else WebhookPolicy.retry_on_status
+            ),
         )
 
     def post_reply(self, payload: dict) -> dict:

{expr_tracker-0.3.1 → expr_tracker-0.3.5}/src/expr_tracker/alerts/backends/base.py

@@ -8,7 +8,7 @@ import urllib.error
 import urllib.parse
 import urllib.request
 
-from ..models import AlertMessage, ChannelConfig
+from ..models import AlertMessage, ChannelConfig, WebhookPolicy
 
 
 class SendError(Exception):
@@ -56,7 +56,12 @@ def create_backend(config: ChannelConfig) -> AlertBackend:
 
 
 def post_json(
-    url: str, payload: dict, timeout: float, headers: dict | None = None
+    url: str,
+    payload: dict,
+    timeout: float,
+    headers: dict | None = None,
+    *,
+    retry_on_status: tuple[int, ...] = WebhookPolicy.retry_on_status,
 ) -> str:
     """POST a JSON body, raising :class:`SendError` on failure."""
     data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
@@ -75,7 +80,7 @@ def post_json(
         )
         raise SendError(
             f"HTTP {e.code} from {_redact(url)}: {e.reason}",
-            retryable=e.code in (408, 429, 500, 502, 503, 504),
+            retryable=e.code in retry_on_status,
             retry_after=retry_after,
         ) from e
     except urllib.error.URLError as e:

{expr_tracker-0.3.1 → expr_tracker-0.3.5}/src/expr_tracker/alerts/dispatch.py

@@ -278,10 +278,17 @@ class Dispatcher:
 
     def flush(self, timeout: float = 5.0):
         deadline = time.monotonic() + timeout
-        while time.monotonic() < deadline:
-            if all(rt.pending == 0 for rt in self.channels.values()):
-                return
-            time.sleep(0.02)
+        for runtime in self.channels.values():
+            work = runtime.queue
+            if work is None:
+                continue
+            # A dequeued message remains unfinished until delivery (and retries) ends.
+            with work.all_tasks_done:
+                while work.unfinished_tasks:
+                    remaining = deadline - time.monotonic()
+                    if remaining <= 0:
+                        return
+                    work.all_tasks_done.wait(remaining)
 
     def close(self, timeout: float = 5.0):
         self.flush(timeout)

{expr_tracker-0.3.1 → expr_tracker-0.3.5}/src/expr_tracker/alerts/expr/functions.py

@@ -191,13 +191,19 @@ def _stalled(w: Window, eps: float = 0.0):
 def _increasing(w: Window):
     if not _need(w, 2):
         return UNKNOWN
-    return all(b > a for a, b in itertools.pairwise(w.values))
+    values = w.values
+    if any(not math.isfinite(v) for v in values):
+        return UNKNOWN
+    return all(b > a for a, b in itertools.pairwise(values))
 
 
 def _decreasing(w: Window):
     if not _need(w, 2):
         return UNKNOWN
-    return all(b < a for a, b in itertools.pairwise(w.values))
+    values = w.values
+    if any(not math.isfinite(v) for v in values):
+        return UNKNOWN
+    return all(b < a for a, b in itertools.pairwise(values))
 
 
 # ---------------------------------------------------------------------- scalar

{expr_tracker-0.3.1 → expr_tracker-0.3.5}/src/expr_tracker/artifacts.py

@@ -20,6 +20,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
+from filelock import FileLock
 from loguru import logger
 
 DEFAULT_TYPE = "dataset"
@@ -220,7 +221,8 @@ class ArtifactStore:
             )
         artifact.aliases = sorted({*artifact.aliases, *(aliases or [])} - {LATEST})
         artifact.digest = self._digest(artifact)
-        with self._lock:
+        self.root.mkdir(parents=True, exist_ok=True)
+        with self._lock, FileLock(self.root / ".lock"):
             # One pass over the index answers both questions: has this exact content
             # been stored before, and what is the next free version?
             versions = [a for a in self.entries() if a.name == artifact.name]

{expr_tracker-0.3.1 → expr_tracker-0.3.5}/src/expr_tracker/cli.py

@@ -4,8 +4,10 @@ from __future__ import annotations
 
 import json
 import time
+from pathlib import Path
 
 import click
+from dotenv import load_dotenv
 
 from .alerts import alert as send_alert
 from .alerts.dispatch import Dispatcher
@@ -26,8 +28,21 @@ def main():
 @click.option("--title", default="Alert", help="Title of the alert")
 @click.option("--level", default="info", help="info | warning | error | critical")
 @click.option("--channel", "channels", multiple=True, help="Restrict to these channels")
-def alert(msg: str, title: str, level: str, channels: tuple[str, ...]):
-    """Send a manual alert."""
+@click.option(
+    "--no-dotenv", is_flag=True, help="Skip loading .env from the current directory"
+)
+def alert(
+    msg: str, title: str, level: str, channels: tuple[str, ...], no_dotenv: bool
+):
+    """Send a manual alert, loading the current directory's .env by default."""
+    if not no_dotenv:
+        try:
+            with Path(".env").open(encoding="utf-8") as stream:
+                load_dotenv(stream=stream, override=False)
+        except FileNotFoundError:
+            pass
+        except (OSError, UnicodeError) as exc:
+            raise click.ClickException(f"Could not read .env: {exc}") from exc
     send_alert(title=title, text=msg, level=level, channels=list(channels) or None)
 
 

{expr_tracker-0.3.1 → expr_tracker-0.3.5}/src/expr_tracker/history/writer.py

@@ -146,7 +146,11 @@ class JsonlWriter:
 
     def _rebuild_from_disk(self, size: int):
         """Rescan from the last anchor that still lies inside the file."""
-        usable = [entry for entry in self.index if entry[2] < size]
+        # Unsorted prefixes can contain a maximum between anchors. Rescan them
+        # fully; after truncation even the old metadata's maximum may be gone.
+        usable = (
+            [entry for entry in self.index if entry[2] < size] if self.sorted else []
+        )
         anchor_step, start_line, start_offset = usable[-1] if usable else (None, 0, 0)
         self.index = usable[:-1]  # the last anchor is re-added while rescanning
         # No predecessor for the first rescanned line: the anchor line is read again,

{expr_tracker-0.3.1 → expr_tracker-0.3.5}/tests/test_alert_backends.py

@@ -1,22 +1,31 @@
 """Channel payload construction and HTTP error mapping."""
 
+import io
 import json
 import urllib.error
 import urllib.request
+from unittest.mock import Mock
 
 import pytest
 
 from expr_tracker.alerts import backends as backend_module
 from expr_tracker.alerts.backends import create_backend
 from expr_tracker.alerts.backends.base import SendError, post_json
-from expr_tracker.alerts.models import AlertLevel, AlertMessage, ChannelConfig
+from expr_tracker.alerts.dispatch import Dispatcher
+from expr_tracker.alerts.models import (
+    AlertConfig,
+    AlertLevel,
+    AlertMessage,
+    ChannelConfig,
+    WebhookPolicy,
+)
 
 
 @pytest.fixture
 def captured(monkeypatch):
     sink: list = []
 
-    def fake_post(url, payload, timeout, headers=None):
+    def fake_post(url, payload, timeout, headers=None, *, retry_on_status=None):
         sink.append(
             {"url": url, "payload": payload, "timeout": timeout, "headers": headers}
         )
@@ -122,6 +131,52 @@ def test_post_json_maps_http_errors(monkeypatch, status, retryable):
     assert info.value.retry_after == 2.0
 
 
+@pytest.mark.parametrize("kind", ["webhook", "slack", "lark", "dingtalk", "wecom"])
+@pytest.mark.parametrize("channel_policy", [False, True])
+@pytest.mark.parametrize(
+    ("status", "statuses", "attempts", "sent"),
+    [
+        (418, (418,), 2, 1),
+        (500, (), 1, 0),
+        (500, None, 2, 1),
+        (418, None, 1, 0),
+    ],
+)
+def test_webhook_http_retries_follow_policy(
+    monkeypatch, kind, channel_policy, status, statuses, attempts, sent
+):
+    urlopen = Mock(
+        side_effect=[
+            urllib.error.HTTPError("http://hook", status, "boom", {}, None),
+            io.BytesIO(b"{}"),
+        ]
+    )
+    monkeypatch.setattr(urllib.request, "urlopen", urlopen)
+    policy = WebhookPolicy(
+        async_send=False,
+        dedup_window=0,
+        rate_limit_per_minute=None,
+        max_retries=1,
+        backoff_initial=0,
+        **({"retry_on_status": statuses} if statuses is not None else {}),
+    )
+    channel = ChannelConfig(
+        type=kind,
+        url="http://hook",
+        policy=policy if channel_policy else None,
+    )
+    dispatcher = Dispatcher(
+        AlertConfig(
+            channels=[channel],
+            default_policy=WebhookPolicy() if channel_policy else policy,
+        )
+    )
+    dispatcher.send(message())
+    assert urlopen.call_count == attempts
+    assert dispatcher.stats()[kind]["sent"] == sent
+    assert dispatcher.stats()[kind]["failed"] == 1 - sent
+
+
 def test_post_json_maps_network_errors(monkeypatch):
     def raise_url(*args, **kwargs):
         raise urllib.error.URLError("no route")

{expr_tracker-0.3.1 → expr_tracker-0.3.5}/tests/test_alert_dispatch.py

@@ -246,6 +246,79 @@ def test_async_delivery_and_flush():
     assert len(received) == 10
 
 
+@pytest.fixture
+def blocked_delivery():
+    started = threading.Event()
+    release = threading.Event()
+    completed = threading.Event()
+
+    def handler(msg):
+        started.set()
+        release.wait()
+        completed.set()
+
+    policy = WebhookPolicy(
+        async_send=True, dedup_window=0, rate_limit_per_minute=None, max_retries=0
+    )
+    dispatcher, _ = make(policy=policy)
+    dispatcher.channels["test"].config.options["handler"] = handler
+    try:
+        dispatcher.send(message())
+        assert started.wait(2.0)
+        assert dispatcher.channels["test"].pending == 0
+        yield dispatcher, release, completed
+    finally:
+        release.set()
+        dispatcher.close(timeout=2.0)
+
+
+def test_flush_waits_for_inflight_delivery(blocked_delivery, monkeypatch):
+    dispatcher, release, completed = blocked_delivery
+    work = dispatcher.channels["test"].queue
+    waiting = threading.Event()
+    flushed = threading.Event()
+    original_wait = work.all_tasks_done.wait
+
+    def wait(timeout=None):
+        waiting.set()
+        return original_wait(timeout)
+
+    monkeypatch.setattr(work.all_tasks_done, "wait", wait)
+
+    def flush():
+        dispatcher.flush(timeout=2.0)
+        flushed.set()
+
+    thread = threading.Thread(target=flush)
+    thread.start()
+    try:
+        assert waiting.wait(1.0)
+        assert not flushed.is_set()
+        assert not completed.is_set()
+        release.set()
+        assert flushed.wait(1.0)
+        assert completed.is_set()
+        assert dispatcher.stats()["test"]["sent"] == 1
+        assert work.unfinished_tasks == 0
+    finally:
+        release.set()
+        thread.join(timeout=3.0)
+    assert not thread.is_alive()
+
+
+def test_flush_timeout_leaves_inflight_delivery_running(blocked_delivery):
+    dispatcher, release, completed = blocked_delivery
+    started = time.monotonic()
+    dispatcher.flush(timeout=0.05)
+    assert time.monotonic() - started >= 0.05
+    assert not completed.is_set()
+    assert dispatcher.channels["test"].queue.unfinished_tasks == 1
+    release.set()
+    dispatcher.flush(timeout=2.0)
+    assert completed.is_set()
+    assert dispatcher.stats()["test"]["sent"] == 1
+
+
 def test_queue_full_drops_oldest():
     policy = WebhookPolicy(
         async_send=True, dedup_window=0, rate_limit_per_minute=None, queue_size=2

{expr_tracker-0.3.1 → expr_tracker-0.3.5}/tests/test_alert_engine.py

@@ -106,6 +106,35 @@ def test_recovery_notification():
     assert h.messages[1].level.value == "info"
 
 
+@pytest.mark.parametrize(
+    ("function", "direction"), [("increasing", 1), ("decreasing", -1)]
+)
+def test_nan_in_trend_window_does_not_recover(function, direction):
+    h = Harness(
+        {
+            "condition": f"{function}(loss[2])",
+            "notify_recovery": True,
+            "cooldown": None,
+        }
+    )
+    h.feed(loss=direction)
+    h.feed(loss=2 * direction)
+    assert len(h.messages) == 1
+    state = next(iter(h.engine.rules.values())).state
+    assert state.firing
+
+    for metric in (float("nan"), 3 * direction, 4 * direction):
+        h.feed(loss=metric)
+        assert state.firing
+        assert state.fires == 1
+        assert len(h.messages) == 1
+
+    h.feed(loss=4 * direction)
+    assert not state.firing
+    assert len(h.messages) == 2
+    assert h.messages[-1].title.startswith("[recovered]")
+
+
 def test_max_fires():
     h = Harness({"condition": "loss > 5", "max_fires": 1})
     for value in (10, 1, 10, 1, 10):

{expr_tracker-0.3.1 → expr_tracker-0.3.5}/tests/test_artifacts.py

@@ -2,12 +2,13 @@
 
 import inspect
 import json
+import multiprocessing
 from pathlib import Path
 
 import pytest
 
 import expr_tracker as et
-from expr_tracker.artifacts import Artifact, ArtifactStore, coerce_artifact
+from expr_tracker.artifacts import Artifact, ArtifactStore, coerce_artifact, file_digest
 from expr_tracker.summary import Summary
 
 
@@ -60,6 +61,62 @@ def test_identical_contents_reuse_a_version(run, payload):
     assert third.version == 1
 
 
+def _log_shared_artifact(root, source, ready, entered, release):
+    store = ArtifactStore(root)
+    original_entries = store.entries
+
+    def entries():
+        entered.set()
+        if release is not None and not release.wait(10):
+            raise TimeoutError("Artifact publisher was not released")
+        return original_entries()
+
+    store.entries = entries
+    artifact = Artifact("model").add_file(source, name="weights")
+    ready.set()
+    store.log(artifact)
+
+
+@pytest.mark.parametrize("identical", [False, True])
+def test_concurrent_artifact_publishers_share_a_lock(tmp_path, identical):
+    context = multiprocessing.get_context("spawn")
+    root = tmp_path / "artifacts"
+    sources = [tmp_path / "first", tmp_path / "second"]
+    sources[0].write_bytes(b"weights-A")
+    sources[1].write_bytes(b"weights-A" if identical else b"weights-B")
+    ready = [context.Event(), context.Event()]
+    entered = [context.Event(), context.Event()]
+    release = context.Event()
+    processes = [
+        context.Process(
+            target=_log_shared_artifact,
+            args=(root, source, ready[i], entered[i], release if i == 0 else None),
+        )
+        for i, source in enumerate(sources)
+    ]
+    started = []
+    try:
+        processes[0].start()
+        started.append(processes[0])
+        assert entered[0].wait(10)
+        processes[1].start()
+        started.append(processes[1])
+        assert ready[1].wait(10)
+        assert not entered[1].wait(0.2)
+    finally:
+        release.set()
+        for process in started:
+            process.join(10)
+            if process.is_alive():
+                process.terminate()
+                process.join(5)
+    assert all(process.exitcode == 0 for process in processes)
+    artifacts = ArtifactStore(root).entries()
+    assert [artifact.version for artifact in artifacts] == ([0] if identical else [0, 1])
+    for artifact in artifacts:
+        assert artifact.entries[0].digest == file_digest(artifact.get_path("weights"))
+
+
 def test_use_artifact_resolution(run, payload, tmp_path):
     run(backends=[])
     et.log_artifact(