liblaf-cherries 0.1.6__tar.gz → 0.2.0__tar.gz

{liblaf_cherries-0.1.6 → liblaf_cherries-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: liblaf-cherries
-Version: 0.1.6
+Version: 0.2.0
 Summary: Add your description here
 Project-URL: Changelog, https://github.com/liblaf/cherries/blob/main/CHANGELOG.md
 Project-URL: Documentation, https://liblaf.github.io/cherries/
@@ -31,17 +31,19 @@ Classifier: Topic :: System :: Logging
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
+Requires-Dist: attrs<26,>=25.0.0
 Requires-Dist: comet-ml<4,>=3.0.0
 Requires-Dist: dvc[webdav]<4,>=3.0.0
 Requires-Dist: environs<15,>=14.0.0
 Requires-Dist: gitpython<4,>=3.0.0
-Requires-Dist: lazy-loader<0.5,>=0.4.0
-Requires-Dist: liblaf-grapes<0.4,>=0.3.0
+Requires-Dist: lazy-loader<0.5,>=0.4
+Requires-Dist: liblaf-grapes<0.7,>=0.6.0
 Requires-Dist: loguru<0.8,>=0.7.0
 Requires-Dist: networkx<4,>=3.0.0
 Requires-Dist: pydantic-settings<3,>=2.0.0
 Requires-Dist: pydantic<3,>=2.0.0
 Requires-Dist: rich<15,>=14.0.0
+Requires-Dist: wrapt<2,>=1.0.0
 Description-Content-Type: text/markdown
 
 <div align="center" markdown><a name="readme-top"></a>

{liblaf_cherries-0.1.6 → liblaf_cherries-0.2.0}/pyproject.toml

@@ -30,13 +30,7 @@ docs = [
   "pymdown-extensions",
   "ruff",
 ]
-test = [
-  "pytest",
-  "pytest-benchmark",
-  "pytest-codspeed",
-  "pytest-cov",
-  "pytest-xdist",
-]
+test = ["pytest", "pytest-codspeed", "pytest-cov", "pytest-xdist"]
 
 [project]
 authors = [
@@ -64,17 +58,19 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
+  "attrs>=25.0.0,<26",
   "comet-ml>=3.0.0,<4",
   "dvc[webdav]>=3.0.0,<4",
   "environs>=14.0.0,<15",
   "gitpython>=3.0.0,<4",
-  "lazy-loader>=0.4.0,<0.5",
-  "liblaf-grapes>=0.3.0,<0.4",
+  "lazy-loader>=0.4,<0.5",
+  "liblaf-grapes>=0.6.0,<0.7",
   "loguru>=0.7.0,<0.8",
   "networkx>=3.0.0,<4",
   "pydantic-settings>=2.0.0,<3",
   "pydantic>=2.0.0,<3",
   "rich>=14.0.0,<15",
+  "wrapt>=1.0.0,<2",
 ]
 description = "Add your description here"
 dynamic = ["version"]

liblaf_cherries-0.2.0/src/liblaf/cherries/__init__.pyi

@@ -0,0 +1,50 @@
+from . import config, core, meta, paths
+from ._entrypoint import end, run, start
+from .config import BaseConfig, input, output  # noqa: A004
+from .core import Plugin, Run, active_run, log_asset, log_metrics
+from .paths import (
+    as_os_path,
+    as_path,
+    as_posix,
+    data,
+    entrypoint,
+    exp_dir,
+    git_root,
+    git_root_safe,
+    inputs,
+    outputs,
+    params,
+    path,
+    src,
+)
+
+__all__ = [
+    "BaseConfig",
+    "Plugin",
+    "Run",
+    "active_run",
+    "as_os_path",
+    "as_path",
+    "as_posix",
+    "config",
+    "core",
+    "data",
+    "end",
+    "entrypoint",
+    "exp_dir",
+    "git_root",
+    "git_root_safe",
+    "input",
+    "inputs",
+    "log_asset",
+    "log_metrics",
+    "meta",
+    "output",
+    "outputs",
+    "params",
+    "path",
+    "paths",
+    "run",
+    "src",
+    "start",
+]

liblaf_cherries-0.2.0/src/liblaf/cherries/_entrypoint.py

@@ -0,0 +1,56 @@
+import inspect
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any
+
+from liblaf.cherries import core, profiles
+
+
+def end() -> None:
+    core.active_run.end()
+
+
+def run[T](main: Callable[..., T], *, profile: profiles.ProfileLike | None = None) -> T:
+    run: core.Run = start(profile=profile)
+    args: Sequence[Any]
+    kwargs: Mapping[str, Any]
+    args, kwargs = _make_args(main)
+    # TODO: log config & inputs
+    result: T = main(*args, **kwargs)
+    # TODO: log outputs
+    run.end()
+    return result
+
+
+def start(
+    profile: profiles.ProfileLike | None = None,
+) -> core.Run:
+    run: core.Run = profiles.factory(profile).init()
+    run.start()
+    # TODO: log metadata
+    return run
+
+
+def _make_args(func: Callable) -> tuple[Sequence[Any], Mapping[str, Any]]:
+    signature: inspect.Signature = inspect.signature(func)
+    args: list[Any] = []
+    kwargs: dict[str, Any] = {}
+    for name, param in signature.parameters.items():
+        match param.kind:
+            case (
+                inspect.Parameter.POSITIONAL_ONLY
+                | inspect.Parameter.POSITIONAL_OR_KEYWORD
+            ):
+                args.append(_make_arg(param))
+            case inspect.Parameter.KEYWORD_ONLY:
+                kwargs[name] = _make_arg(param)
+            case _:
+                pass
+    return args, kwargs
+
+
+def _make_arg(param: inspect.Parameter) -> Any:
+    if param.default is not inspect.Parameter.empty:
+        return param.default
+    if param.annotation is not inspect.Parameter.empty:
+        return param.annotation()
+    return None

{liblaf_cherries-0.1.6 → liblaf_cherries-0.2.0}/src/liblaf/cherries/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.1.6'
-__version_tuple__ = version_tuple = (0, 1, 6)
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)

{liblaf_cherries-0.1.6 → liblaf_cherries-0.2.0}/src/liblaf/cherries/config/_asset.py

@@ -6,7 +6,7 @@ from typing import Any
 import pydantic
 
 from liblaf import grapes
-from liblaf.cherries import pathutils as _path
+from liblaf.cherries import paths
 from liblaf.cherries.typed import PathLike
 
 
@@ -61,12 +61,12 @@ def get_outputs(cfg: pydantic.BaseModel) -> list[Path]:
 
 
 def input(path: PathLike, extra: PathProvider | None = None, **kwargs) -> Path:  # noqa: A001
-    field_info: pydantic.fields.FieldInfo = pydantic.Field(_path.data(path), **kwargs)  # pyright: ignore[reportAssignmentType]
+    field_info: pydantic.fields.FieldInfo = pydantic.Field(paths.data(path), **kwargs)  # pyright: ignore[reportAssignmentType]
     field_info.metadata.append(MetaAsset(kind=AssetKind.INPUT, extra=extra))
     return field_info  # pyright: ignore[reportReturnType]
 
 
 def output(path: PathLike, extra: PathProvider | None = None, **kwargs) -> Path:
-    field_info: pydantic.fields.FieldInfo = pydantic.Field(_path.data(path), **kwargs)  # pyright: ignore[reportAssignmentType]
+    field_info: pydantic.fields.FieldInfo = pydantic.Field(paths.data(path), **kwargs)  # pyright: ignore[reportAssignmentType]
     field_info.metadata.append(MetaAsset(kind=AssetKind.OUTPUT, extra=extra))
     return field_info  # pyright: ignore[reportReturnType]

liblaf_cherries-0.2.0/src/liblaf/cherries/core/__init__.pyi

@@ -0,0 +1,20 @@
+from ._impl import ImplInfo, get_impl_info, impl
+from ._plugin import Plugin
+from ._run import Run, active_run, log_asset, log_metrics
+from ._spec import SpecInfo, spec
+from .typed import MethodName, PluginId
+
+__all__ = [
+    "ImplInfo",
+    "MethodName",
+    "Plugin",
+    "PluginId",
+    "Run",
+    "SpecInfo",
+    "active_run",
+    "get_impl_info",
+    "impl",
+    "log_asset",
+    "log_metrics",
+    "spec",
+]

liblaf_cherries-0.2.0/src/liblaf/cherries/core/_impl.py

@@ -0,0 +1,58 @@
+import functools
+from collections.abc import Callable, Iterable
+from typing import Any, overload
+
+import attrs
+
+from liblaf import grapes
+
+from .typed import PluginId
+
+
+@attrs.define
+class ImplInfo:
+    after: Iterable[PluginId] = attrs.field(default=())
+    before: Iterable[PluginId] = attrs.field(default=())
+    priority: int = 0
+
+
+@overload
+def impl[C: Callable](
+    func: C,
+    /,
+    *,
+    priority: int = 0,
+    after: Iterable[PluginId] = (),
+    before: Iterable[PluginId] = (),
+) -> C: ...
+@overload
+def impl[C: Callable](
+    *,
+    priority: int = 0,
+    after: Iterable[PluginId] = (),
+    before: Iterable[PluginId] = (),
+) -> Callable[[C], C]: ...
+def impl(
+    func: Callable | None = None,
+    /,
+    priority: int = 0,
+    after: Iterable[PluginId] = (),
+    before: Iterable[PluginId] = (),
+) -> Any:
+    if func is None:
+        return functools.partial(impl, priority=priority, after=after, before=before)
+    info = ImplInfo(after=after, before=before, priority=priority)
+
+    @grapes.decorator(attrs={"_self_impl": info})
+    def wrapper(
+        wrapped: Callable, _instance: Any, args: tuple, kwargs: dict[str, Any]
+    ) -> Any:
+        return wrapped(*args, **kwargs)
+
+    return wrapper(func)
+
+
+def get_impl_info(func: Callable | None) -> ImplInfo | None:
+    if func is None:
+        return None
+    return getattr(func, "_self_impl", None)

liblaf_cherries-0.2.0/src/liblaf/cherries/core/_plugin.py

@@ -0,0 +1,96 @@
+import inspect
+from collections.abc import Mapping, MutableMapping, Sequence
+from typing import Any, Self
+
+import attrs
+import networkx as nx
+
+from ._impl import ImplInfo, get_impl_info
+from ._spec import SpecInfo
+from .typed import MethodName
+
+
+@attrs.define
+class Plugin:
+    plugins: dict[str, "Plugin"] = attrs.field(factory=dict)
+
+    _plugin_parent: Self | None = attrs.field(default=None)
+    _sort_plugins_cache: MutableMapping[MethodName, Sequence["Plugin"]] = attrs.field(
+        factory=dict, init=False
+    )
+
+    @classmethod
+    def plugin_id_cls(cls) -> str:
+        return cls.__name__
+
+    @property
+    def plugin_id(self) -> str:
+        return self.plugin_id_cls()
+
+    @property
+    def plugin_root(self) -> Self:
+        if self._plugin_parent is None:
+            return self
+        return self._plugin_parent.plugin_root
+
+    @property
+    def specs(self) -> dict[str, SpecInfo]:
+        return {
+            name: method._self_spec  # noqa: SLF001
+            for name, method in inspect.getmembers(
+                type(self), lambda m: getattr(m, "_self_spec", None) is not None
+            )
+        }
+
+    def delegate(
+        self,
+        method: MethodName,
+        args: Sequence[Any] = (),
+        kwargs: Mapping[str, Any] = {},
+        *,
+        first_result: bool = False,
+    ) -> Any:
+        results: list[Any] = []
+        for plugin in self._sort_plugins_cache.get(method, []):
+            result: Any = getattr(plugin, method)(*args, **kwargs)
+            if result is None:
+                continue
+            if first_result:
+                return result
+            results.append(result)
+        return results
+
+    def register(self, plugin: "Plugin") -> None:
+        plugin._plugin_parent = self  # noqa: SLF001
+        self.plugins[plugin.plugin_id] = plugin
+
+    def _prepare(self) -> None:
+        for method in self.specs:
+            self._sort_plugins_cache[method] = self._sort_plugins(
+                method, refresh_cache=True
+            )
+
+    def _sort_plugins(
+        self, method: str, *, refresh_cache: bool = False
+    ) -> Sequence["Plugin"]:
+        if refresh_cache or method not in self._sort_plugins_cache:
+            plugin_infos: dict[str, ImplInfo] = {
+                plugin_id: info
+                for plugin_id, plugin in self.plugins.items()
+                if (info := get_impl_info(getattr(plugin, method, None))) is not None
+            }
+            graph = nx.DiGraph()
+            for plugin_id, impl_info in plugin_infos.items():
+                graph.add_node(plugin_id)
+                for after in impl_info.after:
+                    graph.add_edge(after, plugin_id)
+                for before in impl_info.before:
+                    graph.add_edge(plugin_id, before)
+            self._sort_plugins_cache[method] = tuple(
+                plugin
+                for plugin_id in nx.lexicographical_topological_sort(
+                    graph, key=lambda node: plugin_infos[node].priority
+                )
+                if (plugin := self.plugins.get(plugin_id)) is not None
+            )
+        return self._sort_plugins_cache[method]

liblaf_cherries-0.2.0/src/liblaf/cherries/core/_run.py

@@ -0,0 +1,42 @@
+from pathlib import Path
+
+import attrs
+
+from liblaf.cherries import paths
+
+from ._plugin import Plugin
+from ._spec import spec
+
+
+@attrs.define
+class Run(Plugin):
+    """.
+
+    References:
+        1. [Experiment - Comet Docs](https://www.comet.com/docs/v2/api-and-sdk/python-sdk/reference/Experiment/)
+        2. [Logger | ClearML](https://clear.ml/docs/latest/docs/references/sdk/logger)
+        3. [MLflow Tracking APIs | MLflow](https://www.mlflow.org/docs/latest/ml/tracking/tracking-api/)
+    """
+
+    @property
+    def exp_dir(self) -> Path:
+        return paths.exp_dir(absolute=True)
+
+    @spec
+    def end(self, *args, **kwargs) -> None: ...
+
+    @spec
+    def log_asset(self, *args, **kwargs) -> None: ...
+
+    @spec
+    def log_metrics(self, *args, **kwargs) -> None: ...
+
+    @spec(delegate=False)
+    def start(self, *args, **kwargs) -> None:
+        self._prepare()
+        self.delegate("start", args, kwargs)
+
+
+active_run: Run = Run()
+log_asset = active_run.log_asset
+log_metrics = active_run.log_metrics

liblaf_cherries-0.2.0/src/liblaf/cherries/core/_spec.py

@@ -0,0 +1,71 @@
+import functools
+import inspect
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any, Protocol, overload
+
+import attrs
+
+from liblaf import grapes
+
+from .typed import MethodName
+
+
+class Plugin(Protocol):
+    def delegate(
+        self,
+        method: MethodName,
+        args: Sequence[Any],
+        kwargs: Mapping[str, Any],
+        *,
+        first_result: bool = False,
+    ) -> Any: ...
+
+
+@attrs.define
+class SpecInfo:
+    delegate: bool = attrs.field(default=True)
+    first_result: bool = attrs.field(default=False)
+
+
+@overload
+def spec[C: Callable](
+    func: C, /, *, delegate: bool = True, first_result: bool = False
+) -> C: ...
+@overload
+def spec[C: Callable](
+    *, delegate: bool = True, first_result: bool = False
+) -> Callable[[C], C]: ...
+def spec(
+    func: Callable | None = None,
+    /,
+    *,
+    delegate: bool = True,
+    first_result: bool = False,
+) -> Any:
+    if func is None:
+        return functools.partial(spec, delegate=delegate, first_result=first_result)
+
+    info = SpecInfo(delegate=delegate, first_result=first_result)
+
+    @grapes.decorator(attrs={"_self_spec": info})
+    def wrapper(
+        wrapped: Callable, instance: Plugin, args: tuple, kwargs: dict[str, Any]
+    ) -> Any:
+        if info.delegate:
+            return instance.delegate(
+                wrapped.__name__, args, kwargs, first_result=info.first_result
+            )
+        return wrapped(*args, **kwargs)
+
+    return wrapper(func)
+
+
+def collect_specs(cls: type[Plugin] | Plugin) -> dict[str, SpecInfo]:
+    if isinstance(cls, type):
+        cls = type(cls)
+    return {
+        name: method._self_spec  # noqa: SLF001
+        for name, method in inspect.getmembers(
+            cls, lambda m: getattr(m, "_self_spec", None) is not None
+        )
+    }

liblaf_cherries-0.2.0/src/liblaf/cherries/core/typed.py

@@ -0,0 +1,2 @@
+type MethodName = str
+type PluginId = str

{liblaf_cherries-0.1.6 → liblaf_cherries-0.2.0}/src/liblaf/cherries/meta/_git.py

@@ -3,7 +3,7 @@ import subprocess as sp
 import git
 
 from liblaf import grapes
-from liblaf.cherries import pathutils as _path
+from liblaf.cherries import paths
 
 
 def git_auto_commit(
@@ -40,10 +40,10 @@ def git_commit_url(sha: str | None = None) -> str:
 
 def git_info() -> grapes.git.GitInfo:
     info: grapes.git.GitInfo = grapes.git.info(
-        _path.entrypoint(absolute=True), search_parent_directories=True
+        paths.entrypoint(absolute=True), search_parent_directories=True
     )
     return info
 
 
 def _repo() -> git.Repo:
-    return git.Repo(_path.entrypoint(absolute=True), search_parent_directories=True)
+    return git.Repo(paths.entrypoint(absolute=True), search_parent_directories=True)

{liblaf_cherries-0.1.6 → liblaf_cherries-0.2.0}/src/liblaf/cherries/meta/_name.py

@@ -3,7 +3,7 @@ from pathlib import Path
 import git.exc
 
 from liblaf import grapes
-from liblaf.cherries import pathutils as _path
+from liblaf.cherries import paths
 
 from ._git import git_info
 
@@ -18,8 +18,8 @@ def project_name() -> str:
 
 
 def exp_name() -> str:
-    exp_dir: Path = _path.entrypoint(absolute=False)
-    exp_name: str = _path.as_posix(exp_dir)
+    exp_dir: Path = paths.entrypoint(absolute=False)
+    exp_name: str = paths.as_posix(exp_dir)
     exp_name = exp_name.removeprefix("exp")
     exp_name = exp_name.removeprefix("/")
     return exp_name

{liblaf_cherries-0.1.6/src/liblaf/cherries/pathutils → liblaf_cherries-0.2.0/src/liblaf/cherries/paths}/_path.py

@@ -1,4 +1,5 @@
 import sys
+from collections.abc import Container
 from pathlib import Path
 
 import git
@@ -27,7 +28,7 @@ def git_root_safe() -> Path:
     try:
         return git_root()
     except git.exc.InvalidGitRepositoryError:
-        logger.warning("Not in a git repository, using current directory")
+        logger.warning("Not in a git repository, using current directory", once=True)
         return _entrypoint_absolute().parent
 
 
@@ -50,15 +51,16 @@ def _entrypoint_relative() -> Path:
     return path.relative_to(git_root_safe())
 
 
+EXP_DIR_NAMES: Container[str] = {"exp", "experiment", "experiments", "exps", "src"}
+
+
 @utils.cache
 def _exp_dir_absolute() -> Path:
     entrypoint: Path = _entrypoint_absolute()
-    for path in entrypoint.parents:
-        if (path / "exp.cherries.toml").is_file():
-            return path
-        if (path / "src").is_dir():
-            return path
-    return git_root_safe()
+    parent: Path = entrypoint.parent
+    if parent.name in EXP_DIR_NAMES:
+        return parent.parent
+    return parent
 
 
 @utils.cache

liblaf_cherries-0.2.0/src/liblaf/cherries/plugins/__init__.pyi

@@ -0,0 +1,3 @@
+from .logging import Logging
+
+__all__ = ["Logging"]

liblaf_cherries-0.2.0/src/liblaf/cherries/plugins/logging.py

@@ -0,0 +1,25 @@
+from typing import override
+
+from liblaf import grapes
+from liblaf.cherries import core
+
+
+class Logging(core.Run):
+    @override
+    @core.impl
+    def start(self, *args, **kwargs) -> None:
+        profile = grapes.logging.profiles.ProfileCherries(
+            handlers=[
+                grapes.logging.rich_handler(),
+                grapes.logging.file_handler(sink=self.plugin_root.exp_dir / "run.log"),
+            ]
+        )
+        grapes.logging.init(profile=profile)
+
+    @override
+    @core.impl
+    def end(self, *args, **kwargs) -> None:
+        if (self.plugin_root.exp_dir / "run.log").exists():
+            self.plugin_root.log_asset(self.plugin_root.exp_dir / "run.log")
+        if (self.plugin_root.exp_dir / "run.log.jsonl").exists():
+            self.plugin_root.log_asset(self.plugin_root.exp_dir / "run.log.jsonl")

liblaf_cherries-0.2.0/src/liblaf/cherries/profiles/__init__.pyi

@@ -0,0 +1,13 @@
+from ._abc import Profile
+from ._default import ProfileDefault
+from ._factory import ProfileLike, ProfileName, factory
+from ._playground import ProfilePlayground
+
+__all__ = [
+    "Profile",
+    "ProfileDefault",
+    "ProfileLike",
+    "ProfileName",
+    "ProfilePlayground",
+    "factory",
+]

liblaf_cherries-0.2.0/src/liblaf/cherries/profiles/_abc.py

@@ -0,0 +1,10 @@
+import abc
+
+import autoregistry
+
+from liblaf.cherries import core
+
+
+class Profile(abc.ABC, autoregistry.Registry, prefix="Profile"):
+    @abc.abstractmethod
+    def init(self) -> core.Run: ...

liblaf_cherries-0.2.0/src/liblaf/cherries/profiles/_default.py

@@ -0,0 +1,12 @@
+from typing import override
+
+from liblaf.cherries import core
+
+from ._playground import ProfilePlayground
+
+
+class ProfileDefault(ProfilePlayground):
+    @override  # impl Profile
+    def init(self) -> core.Run:
+        run: core.Run = super().init()
+        return run

liblaf_cherries-0.2.0/src/liblaf/cherries/profiles/_factory.py

@@ -0,0 +1,21 @@
+from typing import Literal
+
+from ._abc import Profile
+
+# ensure profiles are registered
+from ._default import ProfileDefault
+from ._playground import ProfilePlayground  # noqa: F401
+
+# for code-completion
+type ProfileName = Literal["default", "playground"] | str  # noqa: PYI051
+type ProfileLike = ProfileName | Profile | type[Profile]
+
+
+def factory(profile: ProfileLike | None = None) -> Profile:
+    if profile is None:
+        return ProfileDefault()
+    if isinstance(profile, str):
+        return Profile[profile]()
+    if isinstance(profile, Profile):
+        return profile
+    return profile()