expr-tracker 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.7/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.python-version
+wandb/
+.env
+# Virtual environments
+.venv
+test.ipynb

expr_tracker-0.1.7/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: expr_tracker
+Version: 0.1.7
+Summary: Add your description here
+Author-email: HSPK <whxway@whu.edu.cn>
+Requires-Python: >=3.10
+Requires-Dist: jsonlines>=4.0.0
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: slark>=0.1.28
+Requires-Dist: wandb>=0.21.0
+Description-Content-Type: text/markdown
+
+# 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/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/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "expr_tracker"
+description = "Add your description here"
+readme = "README.md"
+authors = [{ name = "HSPK", email = "whxway@whu.edu.cn" }]
+requires-python = ">=3.10"
+dependencies = [
+    "jsonlines>=4.0.0",
+    "loguru>=0.7.3",
+    "slark>=0.1.28",
+    "wandb>=0.21.0",
+]
+dynamic = ["version"]
+
+[project.scripts]
+et = "expr_tracker.cli:main"
+
+[dependency-groups]
+dev = ["ipykernel>=6.30.1"]
+
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "uv-dynamic-versioning"

expr_tracker-0.1.7/src/expr_tracker/__init__.py

@@ -0,0 +1,9 @@
+from . import tracker
+from .alert import alert
+
+init = tracker.init
+finish = tracker.finish
+log = tracker.log
+info = tracker.info
+
+__all__ = ["init", "finish", "log", "info", "alert"]

expr_tracker-0.1.7/src/expr_tracker/_compat.py

@@ -0,0 +1,31 @@
+from typing import Any, Type
+
+from pydantic import BaseModel
+from pydantic.version import VERSION as PYDANTIC_VERSION
+from typing_extensions import Literal
+
+PYDANTIC_VERSION_MINOR_TUPLE = tuple(int(x) for x in PYDANTIC_VERSION.split(".")[:2])
+PYDANTIC_V2 = PYDANTIC_VERSION_MINOR_TUPLE[0] == 2
+
+Url: Type[Any]
+
+if PYDANTIC_V2:
+    from pydantic_core import PydanticUndefinedType
+    from pydantic_core import Url as Url
+
+    UndefinedType = PydanticUndefinedType
+
+    def _model_dump(
+        model: BaseModel, mode: Literal["json", "python"] = "json", **kwargs: Any
+    ) -> Any:
+        return model.model_dump(mode=mode, **kwargs)
+else:
+    from pydantic import AnyUrl as Url  # noqa: F401
+    from pydantic.fields import (  # type: ignore[no-redef, attr-defined]
+        UndefinedType as UndefinedType,  # noqa: F401
+    )
+
+    def _model_dump(
+        model: BaseModel, mode: Literal["json", "python"] = "json", **kwargs: Any
+    ) -> Any:
+        return model.dict(**kwargs)

expr_tracker-0.1.7/src/expr_tracker/alert.py

@@ -0,0 +1,73 @@
+from typing import Literal
+from loguru import logger
+
+
+def ignore_exception(func):
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except Exception as e:
+            logger.warning(f"Error occurred in {func.__name__}: {e}")
+            return None
+
+    return wrapper
+
+
+class LarkBackend:
+    def __init__(self, **kwargs):
+        from slark import Lark
+
+        self.lark = Lark(**kwargs)
+
+    def publish_alert(
+        self,
+        title: str,
+        text: str,
+        subtitle: str | None = None,
+        level: Literal["info", "warning", "error"] = "info",
+        traceback: str | None = None,
+    ):
+        if level == "info" or level == "warning":
+            self.lark.webhook.post_success_card(
+                msg=text, title=title, subtitle=subtitle
+            )
+        elif level == "error":
+            self.lark.webhook.post_error_card(
+                msg=text, traceback=traceback or "", title=title, subtitle=subtitle
+            )
+        else:
+            raise ValueError(
+                f"Unsupported level: {level}. Supported levels are 'info', 'warning', and 'error'."
+            )
+
+
+@ignore_exception
+def alert(
+    title: str,
+    text: str,
+    subtitle: str | None = None,
+    traceback: str | None = None,
+    level: Literal["info", "warning", "error"] = "info",
+    backends: list[Literal["lark", "slack", "email"]] = ["lark"],
+):
+    """
+    Send an alert message to specified backends.
+
+    Args:
+        title (str): The title of the alert.
+        text (str): The main content of the alert.
+        subtitle (str | None): Optional subtitle for the alert.
+        level (Literal["info", "warning", "error"]): The severity level of the alert.
+        backends (list[Literal["lark", "slack", "email"]]): List of backends to send the alert to.
+    """
+    for backend in backends:
+        if backend == "lark":
+            lark_backend = LarkBackend()
+            if lark_backend.lark._webhook_url is None:
+                logger.warning(
+                    "Lark webhook URL is not set. Please set the WEBHOOK_URL environment variable."
+                )
+                return
+            lark_backend.publish_alert(title, text, subtitle, level, traceback)
+        else:
+            raise NotImplementedError(f"Backend '{backend}' is not implemented.")

expr_tracker-0.1.7/src/expr_tracker/cli.py

@@ -0,0 +1,15 @@
+import click
+import expr_tracker as et
+
+
+@click.group()
+def main():
+    pass
+
+
+@main.command()
+@click.argument("msg")
+@click.option("--title", default="Alert", help="Title of the alert")
+@click.option("--level", default="info", help="Level of the alert")
+def alert(msg: str, title: str = "Alert", level: str = "info"):
+    et.alert(title=title, text=msg, level=level)

expr_tracker-0.1.7/src/expr_tracker/encoders.py

@@ -0,0 +1,344 @@
+import dataclasses
+import datetime
+from collections import defaultdict, deque
+from decimal import Decimal
+from enum import Enum
+from ipaddress import (
+    IPv4Address,
+    IPv4Interface,
+    IPv4Network,
+    IPv6Address,
+    IPv6Interface,
+    IPv6Network,
+)
+from pathlib import Path, PurePath
+from re import Pattern
+from types import GeneratorType
+from typing import Any, Callable, Dict, List, Optional, Tuple, Type, Union
+from uuid import UUID
+
+from expr_tracker.types import IncEx
+from pydantic import BaseModel
+from pydantic.color import Color
+from pydantic.networks import AnyUrl, NameEmail
+from pydantic.types import SecretBytes, SecretStr
+from typing_extensions import Annotated, Doc
+
+from ._compat import PYDANTIC_V2, UndefinedType, Url, _model_dump
+
+
+# Taken from Pydantic v1 as is
+def isoformat(o: Union[datetime.date, datetime.time]) -> str:
+    return o.isoformat()
+
+
+# Taken from Pydantic v1 as is
+# TODO: pv2 should this return strings instead?
+def decimal_encoder(dec_value: Decimal) -> Union[int, float]:
+    """
+    Encodes a Decimal as int of there's no exponent, otherwise float
+
+    This is useful when we use ConstrainedDecimal to represent Numeric(x,0)
+    where a integer (but not int typed) is used. Encoding this as a float
+    results in failed round-tripping between encode and parse.
+    Our Id type is a prime example of this.
+
+    >>> decimal_encoder(Decimal("1.0"))
+    1.0
+
+    >>> decimal_encoder(Decimal("1"))
+    1
+    """
+    if dec_value.as_tuple().exponent >= 0:  # type: ignore[operator]
+        return int(dec_value)
+    else:
+        return float(dec_value)
+
+
+ENCODERS_BY_TYPE: Dict[Type[Any], Callable[[Any], Any]] = {
+    bytes: lambda o: o.decode(),
+    Color: str,
+    datetime.date: isoformat,
+    datetime.datetime: isoformat,
+    datetime.time: isoformat,
+    datetime.timedelta: lambda td: td.total_seconds(),
+    Decimal: decimal_encoder,
+    Enum: lambda o: o.value,
+    frozenset: list,
+    deque: list,
+    GeneratorType: list,
+    IPv4Address: str,
+    IPv4Interface: str,
+    IPv4Network: str,
+    IPv6Address: str,
+    IPv6Interface: str,
+    IPv6Network: str,
+    NameEmail: str,
+    Path: str,
+    Pattern: lambda o: o.pattern,
+    SecretBytes: str,
+    SecretStr: str,
+    set: list,
+    UUID: str,
+    Url: str,
+    AnyUrl: str,
+}
+
+
+def generate_encoders_by_class_tuples(
+    type_encoder_map: Dict[Any, Callable[[Any], Any]],
+) -> Dict[Callable[[Any], Any], Tuple[Any, ...]]:
+    encoders_by_class_tuples: Dict[Callable[[Any], Any], Tuple[Any, ...]] = defaultdict(
+        tuple
+    )
+    for type_, encoder in type_encoder_map.items():
+        encoders_by_class_tuples[encoder] += (type_,)
+    return encoders_by_class_tuples
+
+
+encoders_by_class_tuples = generate_encoders_by_class_tuples(ENCODERS_BY_TYPE)
+
+
+def jsonable_encoder(
+    obj: Annotated[
+        Any,
+        Doc(
+            """
+            The input object to convert to JSON.
+            """
+        ),
+    ],
+    include: Annotated[
+        Optional[IncEx],
+        Doc(
+            """
+            Pydantic's `include` parameter, passed to Pydantic models to set the
+            fields to include.
+            """
+        ),
+    ] = None,
+    exclude: Annotated[
+        Optional[IncEx],
+        Doc(
+            """
+            Pydantic's `exclude` parameter, passed to Pydantic models to set the
+            fields to exclude.
+            """
+        ),
+    ] = None,
+    by_alias: Annotated[
+        bool,
+        Doc(
+            """
+            Pydantic's `by_alias` parameter, passed to Pydantic models to define if
+            the output should use the alias names (when provided) or the Python
+            attribute names. In an API, if you set an alias, it's probably because you
+            want to use it in the result, so you probably want to leave this set to
+            `True`.
+            """
+        ),
+    ] = True,
+    exclude_unset: Annotated[
+        bool,
+        Doc(
+            """
+            Pydantic's `exclude_unset` parameter, passed to Pydantic models to define
+            if it should exclude from the output the fields that were not explicitly
+            set (and that only had their default values).
+            """
+        ),
+    ] = False,
+    exclude_defaults: Annotated[
+        bool,
+        Doc(
+            """
+            Pydantic's `exclude_defaults` parameter, passed to Pydantic models to define
+            if it should exclude from the output the fields that had the same default
+            value, even when they were explicitly set.
+            """
+        ),
+    ] = False,
+    exclude_none: Annotated[
+        bool,
+        Doc(
+            """
+            Pydantic's `exclude_none` parameter, passed to Pydantic models to define
+            if it should exclude from the output any fields that have a `None` value.
+            """
+        ),
+    ] = False,
+    custom_encoder: Annotated[
+        Optional[Dict[Any, Callable[[Any], Any]]],
+        Doc(
+            """
+            Pydantic's `custom_encoder` parameter, passed to Pydantic models to define
+            a custom encoder.
+            """
+        ),
+    ] = None,
+    sqlalchemy_safe: Annotated[
+        bool,
+        Doc(
+            """
+            Exclude from the output any fields that start with the name `_sa`.
+
+            This is mainly a hack for compatibility with SQLAlchemy objects, they
+            store internal SQLAlchemy-specific state in attributes named with `_sa`,
+            and those objects can't (and shouldn't be) serialized to JSON.
+            """
+        ),
+    ] = True,
+) -> Any:
+    """
+    Convert any object to something that can be encoded in JSON.
+
+    This is used internally by FastAPI to make sure anything you return can be
+    encoded as JSON before it is sent to the client.
+
+    You can also use it yourself, for example to convert objects before saving them
+    in a database that supports only JSON.
+
+    Read more about it in the
+    [FastAPI docs for JSON Compatible Encoder](https://fastapi.tiangolo.com/tutorial/encoder/).
+    """
+    custom_encoder = custom_encoder or {}
+    if custom_encoder:
+        if type(obj) in custom_encoder:
+            return custom_encoder[type(obj)](obj)
+        else:
+            for encoder_type, encoder_instance in custom_encoder.items():
+                if isinstance(obj, encoder_type):
+                    return encoder_instance(obj)
+    if include is not None and not isinstance(include, (set, dict)):
+        include = set(include)
+    if exclude is not None and not isinstance(exclude, (set, dict)):
+        exclude = set(exclude)
+    if isinstance(obj, BaseModel):
+        # TODO: remove when deprecating Pydantic v1
+        encoders: Dict[Any, Any] = {}
+        if not PYDANTIC_V2:
+            encoders = getattr(obj.__config__, "json_encoders", {})  # type: ignore[attr-defined]
+            if custom_encoder:
+                encoders = {**encoders, **custom_encoder}
+        obj_dict = _model_dump(
+            obj,
+            mode="json",
+            include=include,
+            exclude=exclude,
+            by_alias=by_alias,
+            exclude_unset=exclude_unset,
+            exclude_none=exclude_none,
+            exclude_defaults=exclude_defaults,
+        )
+        if "__root__" in obj_dict:
+            obj_dict = obj_dict["__root__"]
+        return jsonable_encoder(
+            obj_dict,
+            exclude_none=exclude_none,
+            exclude_defaults=exclude_defaults,
+            # TODO: remove when deprecating Pydantic v1
+            custom_encoder=encoders,
+            sqlalchemy_safe=sqlalchemy_safe,
+        )
+    if dataclasses.is_dataclass(obj):
+        assert not isinstance(obj, type)
+        obj_dict = dataclasses.asdict(obj)
+        return jsonable_encoder(
+            obj_dict,
+            include=include,
+            exclude=exclude,
+            by_alias=by_alias,
+            exclude_unset=exclude_unset,
+            exclude_defaults=exclude_defaults,
+            exclude_none=exclude_none,
+            custom_encoder=custom_encoder,
+            sqlalchemy_safe=sqlalchemy_safe,
+        )
+    if isinstance(obj, Enum):
+        return obj.value
+    if isinstance(obj, PurePath):
+        return str(obj)
+    if isinstance(obj, (str, int, float, type(None))):
+        return obj
+    if isinstance(obj, UndefinedType):
+        return None
+    if isinstance(obj, dict):
+        encoded_dict = {}
+        allowed_keys = set(obj.keys())
+        if include is not None:
+            allowed_keys &= set(include)
+        if exclude is not None:
+            allowed_keys -= set(exclude)
+        for key, value in obj.items():
+            if (
+                (
+                    not sqlalchemy_safe
+                    or (not isinstance(key, str))
+                    or (not key.startswith("_sa"))
+                )
+                and (value is not None or not exclude_none)
+                and key in allowed_keys
+            ):
+                encoded_key = jsonable_encoder(
+                    key,
+                    by_alias=by_alias,
+                    exclude_unset=exclude_unset,
+                    exclude_none=exclude_none,
+                    custom_encoder=custom_encoder,
+                    sqlalchemy_safe=sqlalchemy_safe,
+                )
+                encoded_value = jsonable_encoder(
+                    value,
+                    by_alias=by_alias,
+                    exclude_unset=exclude_unset,
+                    exclude_none=exclude_none,
+                    custom_encoder=custom_encoder,
+                    sqlalchemy_safe=sqlalchemy_safe,
+                )
+                encoded_dict[encoded_key] = encoded_value
+        return encoded_dict
+    if isinstance(obj, (list, set, frozenset, GeneratorType, tuple, deque)):
+        encoded_list = []
+        for item in obj:
+            encoded_list.append(
+                jsonable_encoder(
+                    item,
+                    include=include,
+                    exclude=exclude,
+                    by_alias=by_alias,
+                    exclude_unset=exclude_unset,
+                    exclude_defaults=exclude_defaults,
+                    exclude_none=exclude_none,
+                    custom_encoder=custom_encoder,
+                    sqlalchemy_safe=sqlalchemy_safe,
+                )
+            )
+        return encoded_list
+
+    if type(obj) in ENCODERS_BY_TYPE:
+        return ENCODERS_BY_TYPE[type(obj)](obj)
+    for encoder, classes_tuple in encoders_by_class_tuples.items():
+        if isinstance(obj, classes_tuple):
+            return encoder(obj)
+
+    try:
+        data = dict(obj)
+    except Exception as e:
+        errors: List[Exception] = []
+        errors.append(e)
+        try:
+            data = vars(obj)
+        except Exception as e:
+            errors.append(e)
+            raise ValueError(errors) from e
+    return jsonable_encoder(
+        data,
+        include=include,
+        exclude=exclude,
+        by_alias=by_alias,
+        exclude_unset=exclude_unset,
+        exclude_defaults=exclude_defaults,
+        exclude_none=exclude_none,
+        custom_encoder=custom_encoder,
+        sqlalchemy_safe=sqlalchemy_safe,
+    )