expr_tracker 0.1.6__tar.gz → 0.1.7__tar.gz

expr_tracker-0.1.7/.github/workflows/release.yaml

@@ -0,0 +1,53 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      # required for PyPI trusted publishing (OIDC)
+      id-token: write
+      # required to create the GitHub release
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          # uv-dynamic-versioning derives the version from git tags
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Build sdist and wheel
+        run: |
+          uv build
+          ls -l dist/
+
+      - name: Check distribution metadata
+        run: uvx twine check dist/*
+
+      - name: Publish to PyPI
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub release
+        if: startsWith(github.ref, 'refs/tags/v')
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${GITHUB_REF_NAME}" dist/* \
+            --repo "${GITHUB_REPOSITORY}" \
+            --title "${GITHUB_REF_NAME}" \
+            --generate-notes

{expr_tracker-0.1.6 → expr_tracker-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: expr_tracker
-Version: 0.1.6
+Version: 0.1.7
 Summary: Add your description here
 Author-email: HSPK <whxway@whu.edu.cn>
 Requires-Python: >=3.10
@@ -36,4 +36,32 @@ et.init(project="my_project", name="my_experiment", backends=["wandb", "jsonl"])
 et.log({"accuracy": 0.95, "loss": 0.05})
 et.alert("Experiment completed!", text="Your experiment has finished successfully.", subtitle="Experiment Status")
 et.finish()
+```
+
+### JSONL buffering
+
+The `jsonl` backend adapts its buffering to how often you call `log()`, so that
+high-frequency logging doesn't hammer the disk (helpful on network mounts such as
+BlobFuse) while low-frequency logging still lands on disk immediately:
+
+- If the gap since the previous `log()` call is `>= buffer_interval` (default `1.0s`),
+  the call is considered low-frequency and is written straight through.
+- Otherwise records are batched in memory and flushed once `buffer_size` (default `50`)
+  records accumulate.
+- A background timer flushes records that have been buffered for more than
+  `max_buffer_seconds` (default `5.0s`), so a burst that suddenly stops is never stranded
+  in memory. `finish()` and the `atexit` hook flush any remainder.
+
+Set `buffer_interval=None` to disable the frequency check, or `max_buffer_seconds=None`
+to disable the background timer. Tune them via `backend_kwargs`:
+
+```python
+et.init(
+    project="my_project",
+    name="my_experiment",
+    backends=["jsonl"],
+    backend_kwargs={
+        "jsonl": {"buffer_size": 200, "buffer_interval": 0.5, "max_buffer_seconds": 10},
+    },
+)
 ```

expr_tracker-0.1.7/README.md

@@ -0,0 +1,55 @@
+# Experiment Tracker
+
+A simple experiment tracker that supports `wandb`, `trackio` and local `jsonl` storage. Features include:
+
+## Features
+1. **Multi-Backend Support**: Compatible with `wandb`, `trackio`, and local `jsonl` storage.
+2. **Alert System**: Send alerts via Lark, with email and other platforms to be added.
+3. **Resume Functionality**: Allows resuming experiments using project and name as unique identifiers.
+4. **Simple API**: Provides a straightforward API similar to `wandb`, making it easy to integrate into existing workflows.
+
+## Usage
+
+Add dependency to your project:
+
+```bash
+uv add expr_tracker
+```
+
+Simple usage example:
+```python
+import expr_tracker as et
+
+et.init(project="my_project", name="my_experiment", backends=["wandb", "jsonl"])
+et.log({"accuracy": 0.95, "loss": 0.05})
+et.alert("Experiment completed!", text="Your experiment has finished successfully.", subtitle="Experiment Status")
+et.finish()
+```
+
+### JSONL buffering
+
+The `jsonl` backend adapts its buffering to how often you call `log()`, so that
+high-frequency logging doesn't hammer the disk (helpful on network mounts such as
+BlobFuse) while low-frequency logging still lands on disk immediately:
+
+- If the gap since the previous `log()` call is `>= buffer_interval` (default `1.0s`),
+  the call is considered low-frequency and is written straight through.
+- Otherwise records are batched in memory and flushed once `buffer_size` (default `50`)
+  records accumulate.
+- A background timer flushes records that have been buffered for more than
+  `max_buffer_seconds` (default `5.0s`), so a burst that suddenly stops is never stranded
+  in memory. `finish()` and the `atexit` hook flush any remainder.
+
+Set `buffer_interval=None` to disable the frequency check, or `max_buffer_seconds=None`
+to disable the background timer. Tune them via `backend_kwargs`:
+
+```python
+et.init(
+    project="my_project",
+    name="my_experiment",
+    backends=["jsonl"],
+    backend_kwargs={
+        "jsonl": {"buffer_size": 200, "buffer_interval": 0.5, "max_buffer_seconds": 10},
+    },
+)
+```

expr_tracker-0.1.7/src/expr_tracker/jsonl.py

@@ -0,0 +1,209 @@
+import atexit
+import json
+import threading
+import time
+from pathlib import Path
+
+import jsonlines
+from loguru import logger
+
+from expr_tracker.encoders import jsonable_encoder
+
+DEFAULT_BUFFER_SIZE = 50
+DEFAULT_BUFFER_INTERVAL = 1.0
+DEFAULT_MAX_BUFFER_SECONDS = 5.0
+
+
+class JsonlTracker:
+    def __init__(self):
+        self.buffer = []
+        self.buffer_size = DEFAULT_BUFFER_SIZE
+        self.buffer_interval = DEFAULT_BUFFER_INTERVAL
+        self.max_buffer_seconds = DEFAULT_MAX_BUFFER_SECONDS
+        self.log_fp = None
+        self._lock = threading.RLock()
+        self._last_log_time = None
+        self._first_buffered_time = None
+        self._flush_timer = None
+
+    def init(
+        self,
+        project: str,
+        name: str | None = None,
+        config: dict | None = None,
+        dir: str | None = None,
+        print_to_screen: bool = False,
+        print_handle=print,
+        buffer_size: int = DEFAULT_BUFFER_SIZE,
+        buffer_interval: float | None = DEFAULT_BUFFER_INTERVAL,
+        max_buffer_seconds: float | None = DEFAULT_MAX_BUFFER_SECONDS,
+        **kwargs,
+    ):
+        """初始化 jsonl backend。
+
+        缓冲策略（按 log 频率自适应）：
+        - ``buffer_size``: buffer 中记录数达到该值立即写盘。
+        - ``buffer_interval``: 相邻两次 ``log()`` 的间隔 >= 该值时认为不是高频写入，
+          直接写盘（低延迟）；小于该值才认为是高频写入，先攒在内存里。
+          设为 ``None`` 表示关闭该判断（只按 buffer_size 攒批）。
+        - ``max_buffer_seconds``: 记录在 buffer 中的最长停留时间，超时后由后台定时器
+          强制写盘，避免高频写入突然停止时数据长期滞留内存。设为 ``None`` 关闭。
+        """
+        self.project = project
+        self.name = name
+        if dir is None:
+            dir = "./tracker/jsonl"
+        self.log_dir = Path(dir) / self.project / self.name
+        self.config_fp = self.log_dir / "config.json"
+        self.log_fp = self.log_dir / "metrics.jsonl"
+
+        # 初始化 Buffer 配置
+        self._cancel_timer()
+        with self._lock:
+            self.buffer = []
+            self.buffer_size = max(1, int(buffer_size))
+            self.buffer_interval = (
+                None if buffer_interval is None else float(buffer_interval)
+            )
+            self.max_buffer_seconds = (
+                None if max_buffer_seconds is None else float(max_buffer_seconds)
+            )
+            self._last_log_time = None
+            self._first_buffered_time = None
+
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+
+        if self.config_fp.exists():
+            logger.warning(
+                f"Config file {self.config_fp} already exists. It will be overwritten."
+            )
+
+        if config is not None:
+            # Config 通常只写一次，直接写入即可
+            with open(self.config_fp, "w") as f:
+                json.dump(jsonable_encoder(config), f, indent=4)
+
+        self.print_to_screen = print_to_screen
+        self.print_handle = print_handle
+
+        # 优化：流式计算行数，避免一次性加载大文件到内存 (对 BlobFuse 友好)
+        self.current_step = 0
+        if self.log_fp.exists():
+            try:
+                with open(self.log_fp, "rb") as f:
+                    self.current_step = sum(1 for _ in f)
+            except Exception as e:
+                logger.warning(f"Could not count existing lines in {self.log_fp}: {e}")
+
+        # 注册退出钩子：确保程序意外终止时也能写入剩余数据
+        atexit.register(self.flush)
+
+    def log(self, metrics: dict, step: int | None = None):
+        now = time.monotonic()
+
+        with self._lock:
+            if step is not None:
+                self.current_step = step
+
+            record = {"_step": self.current_step, **metrics}
+
+            # 1. 写入内存 Buffer
+            self.buffer.append(record)
+            if self._first_buffered_time is None:
+                self._first_buffered_time = now
+
+            # 2. 根据「距离上一次 log 的时间间隔」判断是否为高频写入
+            interval = None if self._last_log_time is None else now - self._last_log_time
+            self._last_log_time = now
+
+            should_flush = self._should_flush(now, interval)
+            self.current_step += 1
+
+        # 3. 屏幕打印（放在锁外，避免 print handle 阻塞其他线程）
+        if self.print_to_screen:
+            self.print_handle(f"{record}")
+
+        # 4. 立即写盘，或安排一次超时写盘
+        if should_flush:
+            self.flush()
+        else:
+            self._schedule_timer()
+
+    def _should_flush(self, now: float, interval: float | None) -> bool:
+        """判断当前是否应该立即写盘（需在持锁状态下调用）"""
+        # Buffer 已满
+        if len(self.buffer) >= self.buffer_size:
+            return True
+        # 首次 log：直接落盘，尽快产生文件内容
+        if interval is None:
+            return True
+        # 低频写入：距离上次 log 已经过去足够久，没必要继续攒批
+        if self.buffer_interval is not None and interval >= self.buffer_interval:
+            return True
+        # 高频写入，但最早的记录已在内存中停留过久
+        return (
+            self.max_buffer_seconds is not None
+            and self._first_buffered_time is not None
+            and now - self._first_buffered_time >= self.max_buffer_seconds
+        )
+
+    def _schedule_timer(self):
+        """为 buffer 中最早的记录安排一次超时写盘"""
+        if self.max_buffer_seconds is None:
+            return
+        with self._lock:
+            if self._flush_timer is not None or not self.buffer:
+                return
+            now = time.monotonic()
+            elapsed = now - (self._first_buffered_time or now)
+            delay = max(0.0, self.max_buffer_seconds - elapsed)
+            timer = threading.Timer(delay, self._on_timer)
+            timer.daemon = True
+            self._flush_timer = timer
+        timer.start()
+
+    def _on_timer(self):
+        with self._lock:
+            self._flush_timer = None
+        self.flush()
+
+    def _cancel_timer(self):
+        with self._lock:
+            timer = self._flush_timer
+            self._flush_timer = None
+        if timer is not None:
+            timer.cancel()
+
+    def flush(self):
+        """强制将内存中的 Buffer 写入磁盘"""
+        self._cancel_timer()
+
+        with self._lock:
+            self._first_buffered_time = None
+            if not self.buffer:
+                return
+            records, self.buffer = self.buffer, []
+            log_fp = self.log_fp
+
+        # 确保目录存在 (防止运行时目录被删)
+        if log_fp and not log_fp.parent.exists():
+            log_fp.parent.mkdir(parents=True, exist_ok=True)
+
+        try:
+            # 批量追加写入
+            with jsonlines.open(log_fp, mode="a") as writer:
+                writer.write_all(records)
+        except Exception as e:
+            logger.error(f"Failed to flush metrics to {log_fp}: {e}")
+            # 写入失败：放回 buffer 头部，等待下次 flush 重试
+            with self._lock:
+                self.buffer[:0] = records
+                self._first_buffered_time = time.monotonic()
+            self._schedule_timer()
+
+    def finish(self):
+        """结束时显式调用"""
+        self._cancel_timer()
+        self.flush()
+        # 如果手动调用了 finish，取消 atexit 注册，防止重复调用
+        atexit.unregister(self.flush)

expr_tracker-0.1.7/tests/test_jsonl_buffer.py

@@ -0,0 +1,113 @@
+import tempfile
+import threading
+import time
+from pathlib import Path
+
+import jsonlines
+
+from expr_tracker.jsonl import JsonlTracker
+
+
+def _count_lines(fp: Path) -> int:
+    if not fp.exists():
+        return 0
+    with open(fp, "rb") as f:
+        return sum(1 for _ in f)
+
+
+def _new_tracker(name: str, **kwargs):
+    tracker = JsonlTracker()
+    tracker.init(project="p", name=name, dir=tempfile.mkdtemp(), **kwargs)
+    return tracker
+
+
+def test_low_frequency_writes_through():
+    """间隔大于 buffer_interval 的低频 log 应该直接写盘"""
+    tracker = _new_tracker("low_freq", buffer_size=50, buffer_interval=0.2)
+    for i in range(4):
+        tracker.log({"v": i})
+        time.sleep(0.25)
+    assert _count_lines(tracker.log_fp) == 4
+    assert tracker.buffer == []
+    tracker.finish()
+
+
+def test_high_frequency_is_buffered():
+    """高频 log 攒批，直到 buffer_size 满才写盘"""
+    tracker = _new_tracker(
+        "high_freq", buffer_size=10, buffer_interval=0.2, max_buffer_seconds=None
+    )
+    for i in range(9):
+        tracker.log({"v": i})
+
+    # 第一条直接落盘，其余 8 条留在 buffer 中
+    assert _count_lines(tracker.log_fp) == 1
+    assert len(tracker.buffer) == 8
+
+    for i in range(2):
+        tracker.log({"v": 100 + i})
+    assert _count_lines(tracker.log_fp) == 11
+    assert tracker.buffer == []
+    tracker.finish()
+
+
+def test_max_buffer_seconds_flushes_stale_records():
+    """高频写入突然停止时，后台定时器应在超时后写盘"""
+    tracker = _new_tracker(
+        "timer", buffer_size=1000, buffer_interval=1.0, max_buffer_seconds=0.5
+    )
+    for i in range(5):
+        tracker.log({"v": i})
+    assert _count_lines(tracker.log_fp) == 1
+
+    time.sleep(0.9)
+    assert _count_lines(tracker.log_fp) == 5
+    assert tracker.buffer == []
+    tracker.finish()
+
+
+def test_steps_are_continuous_across_resume():
+    tracker = _new_tracker(
+        "resume", buffer_size=3, buffer_interval=None, max_buffer_seconds=None
+    )
+    log_dir = tracker.log_dir.parent.parent
+    for i in range(6):
+        tracker.log({"v": i})
+    tracker.finish()
+    assert _count_lines(tracker.log_fp) == 6
+
+    resumed = JsonlTracker()
+    resumed.init(project="p", name="resume", dir=str(log_dir))
+    assert resumed.current_step == 6
+    resumed.log({"v": 6})
+    resumed.finish()
+
+    with jsonlines.open(resumed.log_fp) as reader:
+        assert [record["_step"] for record in reader] == list(range(7))
+
+
+def test_concurrent_logging_does_not_lose_records():
+    tracker = _new_tracker(
+        "threads", buffer_size=25, buffer_interval=0.05, max_buffer_seconds=0.2
+    )
+
+    def worker():
+        for i in range(200):
+            tracker.log({"v": i})
+
+    threads = [threading.Thread(target=worker) for _ in range(4)]
+    for thread in threads:
+        thread.start()
+    for thread in threads:
+        thread.join()
+    tracker.finish()
+
+    assert _count_lines(tracker.log_fp) == 800
+
+
+if __name__ == "__main__":
+    for _name, _fn in sorted(globals().items()):
+        if _name.startswith("test_") and callable(_fn):
+            _fn()
+            print(f"{_name} OK")
+    print("ALL OK")

expr_tracker-0.1.6/README.md

@@ -1,27 +0,0 @@
-# Experiment Tracker
-
-A simple experiment tracker that supports `wandb`, `trackio` and local `jsonl` storage. Features include:
-
-## Features
-1. **Multi-Backend Support**: Compatible with `wandb`, `trackio`, and local `jsonl` storage.
-2. **Alert System**: Send alerts via Lark, with email and other platforms to be added.
-3. **Resume Functionality**: Allows resuming experiments using project and name as unique identifiers.
-4. **Simple API**: Provides a straightforward API similar to `wandb`, making it easy to integrate into existing workflows.
-
-## Usage
-
-Add dependency to your project:
-
-```bash
-uv add expr_tracker
-```
-
-Simple usage example:
-```python
-import expr_tracker as et
-
-et.init(project="my_project", name="my_experiment", backends=["wandb", "jsonl"])
-et.log({"accuracy": 0.95, "loss": 0.05})
-et.alert("Experiment completed!", text="Your experiment has finished successfully.", subtitle="Experiment Status")
-et.finish()
-```

expr_tracker-0.1.6/src/expr_tracker/jsonl.py

@@ -1,107 +0,0 @@
-import atexit
-import json
-from pathlib import Path
-
-import jsonlines
-from loguru import logger
-
-from expr_tracker.encoders import jsonable_encoder
-
-
-class JsonlTracker:
-    def __init__(self):
-        self.buffer = []
-        self.buffer_size = 50
-        self.log_fp = None
-
-    def init(
-        self,
-        project: str,
-        name: str | None = None,
-        config: dict | None = None,
-        dir: str | None = None,
-        print_to_screen: bool = False,
-        print_handle=print,
-        buffer_size: int = 50,  # 新增 buffer_size 参数
-        **kwargs,
-    ):
-        self.project = project
-        self.name = name
-        if dir is None:
-            dir = "./tracker/jsonl"
-        self.log_dir = Path(dir) / self.project / self.name
-        self.config_fp = self.log_dir / "config.json"
-        self.log_fp = self.log_dir / "metrics.jsonl"
-
-        # 初始化 Buffer 配置
-        self.buffer = []
-        self.buffer_size = buffer_size
-
-        self.log_dir.mkdir(parents=True, exist_ok=True)
-
-        if self.config_fp.exists():
-            logger.warning(
-                f"Config file {self.config_fp} already exists. It will be overwritten."
-            )
-
-        if config is not None:
-            # Config 通常只写一次，直接写入即可
-            with open(self.config_fp, "w") as f:
-                json.dump(jsonable_encoder(config), f, indent=4)
-
-        self.print_to_screen = print_to_screen
-        self.print_handle = print_handle
-
-        # 优化：流式计算行数，避免一次性加载大文件到内存 (对 BlobFuse 友好)
-        self.current_step = 0
-        if self.log_fp.exists():
-            try:
-                with open(self.log_fp, "rb") as f:
-                    self.current_step = sum(1 for _ in f)
-            except Exception as e:
-                logger.warning(f"Could not count existing lines in {self.log_fp}: {e}")
-
-        # 注册退出钩子：确保程序意外终止时也能写入剩余数据
-        atexit.register(self.flush)
-
-    def log(self, metrics: dict, step: int | None = None):
-        if step is not None:
-            self.current_step = step
-
-        record = {"_step": self.current_step, **metrics}
-
-        # 1. 写入内存 Buffer
-        self.buffer.append(record)
-
-        # 2. 屏幕打印
-        if self.print_to_screen:
-            self.print_handle(f"{record}")
-
-        # 3. 检查 Buffer 是否已满
-        if len(self.buffer) >= self.buffer_size:
-            self.flush()
-
-        self.current_step += 1
-
-    def flush(self):
-        """强制将内存中的 Buffer 写入磁盘"""
-        if not self.buffer:
-            return
-
-        # 确保目录存在 (防止运行时目录被删)
-        if self.log_fp and not self.log_fp.parent.exists():
-            self.log_fp.parent.mkdir(parents=True, exist_ok=True)
-
-        try:
-            # 批量追加写入
-            with jsonlines.open(self.log_fp, mode="a") as writer:
-                writer.write_all(self.buffer)
-            self.buffer = []  # 写入成功后清空 Buffer
-        except Exception as e:
-            logger.error(f"Failed to flush metrics to {self.log_fp}: {e}")
-
-    def finish(self):
-        """结束时显式调用"""
-        self.flush()
-        # 如果手动调用了 finish，取消 atexit 注册，防止重复调用
-        atexit.unregister(self.flush)