liblaf-cherries 0.1.6__py3-none-any.whl → 0.2.0__py3-none-any.whl

liblaf/cherries/__init__.pyi

@@ -1,47 +1,8 @@
-from . import config, core, integration, meta, pathutils, presets, utils
-from ._run import end, run, start
-from .config import (
-    AssetKind,
-    BaseConfig,
-    MetaAsset,
-    PathProvider,
-    get_assets,
-    get_inputs,
-    get_outputs,
-    input,  # noqa: A004
-    output,
-)
-from .core import ConcreteImpl, ImplDef, SpecDef, impl, spec
-from .integration import (
-    AddTag,
-    AddTags,
-    End,
-    Experiment,
-    LogAsset,
-    LogCode,
-    LogMetric,
-    LogMetrics,
-    LogOther,
-    LogOthers,
-    LogParam,
-    LogParams,
-    Plugin,
-    Start,
-    add_tag,
-    add_tags,
-    current_exp,
-    log_asset,
-    log_code,
-    log_input,
-    log_metric,
-    log_metrics,
-    log_other,
-    log_others,
-    log_output,
-    log_param,
-    log_params,
-)
-from .pathutils import (
+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,
@@ -58,72 +19,32 @@ from .pathutils import (
 )
 
 __all__ = [
-    "AddTag",
-    "AddTags",
-    "AssetKind",
     "BaseConfig",
-    "ConcreteImpl",
-    "End",
-    "Experiment",
-    "ImplDef",
-    "LogAsset",
-    "LogCode",
-    "LogMetric",
-    "LogMetrics",
-    "LogOther",
-    "LogOthers",
-    "LogParam",
-    "LogParams",
-    "MetaAsset",
-    "PathProvider",
     "Plugin",
-    "SpecDef",
-    "Start",
-    "add_tag",
-    "add_tags",
+    "Run",
+    "active_run",
     "as_os_path",
     "as_path",
     "as_posix",
     "config",
     "core",
-    "current_exp",
     "data",
     "end",
-    "end",
-    "end",
     "entrypoint",
     "exp_dir",
-    "get_assets",
-    "get_inputs",
-    "get_outputs",
     "git_root",
     "git_root_safe",
-    "impl",
     "input",
     "inputs",
-    "integration",
     "log_asset",
-    "log_code",
-    "log_input",
-    "log_metric",
     "log_metrics",
-    "log_other",
-    "log_others",
-    "log_output",
-    "log_param",
-    "log_params",
     "meta",
     "output",
     "outputs",
     "params",
     "path",
-    "pathutils",
-    "presets",
-    "run",
+    "paths",
     "run",
-    "spec",
     "src",
     "start",
-    "start",
-    "utils",
 ]

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/_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/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/core/__init__.pyi

@@ -1,12 +1,20 @@
-from ._exp import Experiment
-from ._spec import ConcreteImpl, ImplDef, Plugin, SpecDef, impl, spec
+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__ = [
-    "ConcreteImpl",
-    "Experiment",
-    "ImplDef",
+    "ImplInfo",
+    "MethodName",
     "Plugin",
-    "SpecDef",
+    "PluginId",
+    "Run",
+    "SpecInfo",
+    "active_run",
+    "get_impl_info",
     "impl",
+    "log_asset",
+    "log_metrics",
     "spec",
 ]

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/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/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/core/_spec.py

@@ -1,177 +1,71 @@
 import functools
 import inspect
-from collections.abc import Callable, Generator, Iterable, Sequence
-from typing import Any, Self, overload, override
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any, Protocol, overload
 
 import attrs
-import networkx as nx
 
-from liblaf.grapes.typed import Decorator
+from liblaf import grapes
 
+from .typed import MethodName
 
-def as_seq(value: str | Iterable[str] | None = None) -> Sequence[str]:
-    if value is None:
-        return ()
-    if isinstance(value, (str, bytes)):
-        return (value,)
-    return tuple(value)
 
+class Plugin(Protocol):
+    def delegate(
+        self,
+        method: MethodName,
+        args: Sequence[Any],
+        kwargs: Mapping[str, Any],
+        *,
+        first_result: bool = False,
+    ) -> Any: ...
 
-@attrs.frozen
-class SpecDef:
-    name: str
-    firstresult: bool
 
-
-@attrs.frozen
-class ImplDef:
-    name: str
-    after: str | Sequence[str] = attrs.field(default=(), converter=as_seq)
-    before: str | Sequence[str] = attrs.field(default=(), converter=as_seq)
-    priority: int = 0
-
-
-@attrs.frozen
-class ConcreteImpl[C: Callable](ImplDef):
-    fn: C = attrs.field(kw_only=True)
-    plugin_name: str = attrs.field(kw_only=True)
-
-
-@attrs.define(slots=False)
-class Plugin:
-    plugins: list[Self] = attrs.field(factory=list)
-
-    @classmethod
-    def get_spec(cls, name: str | SpecDef) -> SpecDef:
-        if isinstance(name, SpecDef):
-            return name
-        fn: Callable | None = getattr(cls, name, None)
-        if fn is None:
-            raise KeyError(name)
-        spec: SpecDef | None = getattr(fn, "spec", None)
-        if spec is None:
-            raise KeyError(name)
-        return spec
-
-    @classmethod
-    def iter_specs(cls) -> Generator[SpecDef]:
-        for _name, fn in inspect.getmembers(cls):
-            spec: SpecDef | None = getattr(fn, "spec", None)
-            if spec is None:
-                continue
-            yield spec
-
-    @property
-    def name(self) -> str:
-        return type(self).__name__
-
-    @functools.cached_property
-    def impls(self) -> dict[str, Sequence[ConcreteImpl]]:
-        return {spec.name: tuple(self.iter_impls(spec)) for spec in self.iter_specs()}
-
-    def call(self, spec: str | SpecDef, /, *args, **kwargs) -> Any:
-        spec: SpecDef = self.get_spec(spec)
-        impls: Sequence[ConcreteImpl] = self.impls.get(spec.name, ())
-        if spec.firstresult:
-            if len(impls) == 0:
-                return None
-            return impls[0].fn(*args, **kwargs)
-        return [impl.fn(*args, **kwargs) for impl in impls]
-
-    def get_impl(self, spec: str | SpecDef, /) -> ConcreteImpl | None:
-        spec: SpecDef = self.get_spec(spec)
-        fn: Callable | None = getattr(self, spec.name, None)
-        if fn is None:
-            return None
-        impl: ImplDef | None = getattr(fn, "impl", None)
-        if impl is None:
-            return None
-        return ConcreteImpl(
-            name=impl.name,
-            after=impl.after,
-            before=impl.before,
-            priority=impl.priority,
-            fn=fn,
-            plugin_name=self.name,
-        )
-
-    def iter_impls(self, spec: str | SpecDef, /) -> Generator[ConcreteImpl]:
-        graph = nx.DiGraph()
-        impls: dict[str, ConcreteImpl] = {}
-        for impl in self.iter_impls_unordered(spec):
-            impls[impl.plugin_name] = impl
-            graph.add_node(impl.plugin_name)
-            for after in impl.after:
-                graph.add_edge(after, impl.plugin_name)
-            for before in impl.before:
-                graph.add_edge(impl.plugin_name, before)
-        for impl in nx.lexicographical_topological_sort(
-            graph, key=lambda n: impls[n].priority if n in impls else 0
-        ):
-            if impl not in impls:
-                continue
-            yield impls[impl]
-
-    def iter_impls_unordered(self, spec: str | SpecDef, /) -> Generator[ConcreteImpl]:
-        spec: SpecDef = self.get_spec(spec)
-        for plugin in self.plugins:
-            impl: ConcreteImpl | None = plugin.get_impl(spec)
-            if impl is None:
-                continue
-            yield impl
-
-    def register(self, plugin: Self) -> None:
-        self.plugins.append(plugin)
+@attrs.define
+class SpecInfo:
+    delegate: bool = attrs.field(default=True)
+    first_result: bool = attrs.field(default=False)
 
 
 @overload
-def spec(*, firstresult: bool = False) -> Decorator: ...
+def spec[C: Callable](
+    func: C, /, *, delegate: bool = True, first_result: bool = False
+) -> C: ...
 @overload
-def spec[C: Callable](fn: C, /, *, firstresult: bool = False) -> C: ...
+def spec[C: Callable](
+    *, delegate: bool = True, first_result: bool = False
+) -> Callable[[C], C]: ...
 def spec(
-    fn: Callable | None = None, /, *, firstresult: bool = False
-) -> Decorator | Callable:
-    if fn is None:
-        return functools.partial(spec, firstresult=firstresult)
-
-    @functools.wraps(fn)
-    def wrapper(self: Plugin, *args, **kwargs) -> Any:
-        return self.call(wrapper.spec, *args, **kwargs)  # pyright: ignore[reportAttributeAccessIssue]
-
-    wrapper.spec = SpecDef(name=fn.__name__, firstresult=firstresult)  # pyright: ignore[reportAttributeAccessIssue]
-    return wrapper
-
-
-@overload
-def impl(
-    *,
-    name: str,
-    after: str | Sequence[str] = (),
-    before: str | Sequence[str] = (),
-    priority: int = 0,
-) -> Decorator: ...
-@overload
-def impl[C: Callable](
-    fn: C,
-    /,
-    *,
-    name: str,
-    after: str | Sequence[str] = (),
-    before: str | Sequence[str] = (),
-    priority: int = 0,
-) -> C: ...
-def impl(
-    fn: Callable | None = None,
+    func: Callable | None = None,
     /,
     *,
-    name: str,
-    after: str | Sequence[str] = (),
-    before: str | Sequence[str] = (),
-    priority: int = 0,
-) -> Decorator | Callable:
-    if fn is None:
-        return functools.partial(
-            impl, name=name, after=after, before=before, priority=priority
+    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
         )
-    fn.impl = ImplDef(name=name, after=after, before=before, priority=priority)  # pyright: ignore[reportFunctionMemberAccess]
-    return override(fn)
+    }

liblaf/cherries/core/typed.py

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

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)