ddeutil-workflow 0.0.48__py3-none-any.whl → 0.0.50__py3-none-any.whl

ddeutil/workflow/logs.py

@@ -3,8 +3,9 @@
 # Licensed under the MIT License. See LICENSE in the project root for
 # license information.
 # ------------------------------------------------------------------------------
-# [x] Use fix config
-"""A Logs module contain TraceLog dataclass and AuditLog model.
+# [x] Use dynamic config
+# [x] Use fix config for `get_logger`, and Model initialize step.
+"""A Logs module contain Trace dataclass and Audit Pydantic model.
 """
 from __future__ import annotations
 
@@ -19,14 +20,14 @@ from functools import lru_cache
 from inspect import Traceback, currentframe, getframeinfo
 from pathlib import Path
 from threading import get_ident
-from typing import ClassVar, Literal, Optional, Union
+from typing import ClassVar, Literal, Optional, TypeVar, Union
 
-from pydantic import BaseModel, Field, ValidationInfo
+from pydantic import BaseModel, Field
 from pydantic.dataclasses import dataclass
 from pydantic.functional_validators import model_validator
 from typing_extensions import Self
 
-from .__types import DictData, DictStr, TupleStr
+from .__types import DictData, DictStr
 from .conf import config, dynamic
 from .utils import cut_id, get_dt_now
 
@@ -60,22 +61,6 @@ def get_logger(name: str):
 
 logger = get_logger("ddeutil.workflow")
 
-__all__: TupleStr = (
-    "FileTraceLog",
-    "SQLiteTraceLog",
-    "TraceData",
-    "TraceMeta",
-    "TraceLog",
-    "get_dt_tznow",
-    "get_logger",
-    "get_trace",
-    "get_trace_obj",
-    "get_audit",
-    "FileAudit",
-    "SQLiteAudit",
-    "Audit",
-)
-
 
 def get_dt_tznow() -> datetime:  # pragma: no cov
     """Return the current datetime object that passing the config timezone.
@@ -170,13 +155,39 @@ class TraceData(BaseModel):  # pragma: no cov
 
 
 @dataclass(frozen=True)
-class BaseTraceLog(ABC):  # pragma: no cov
-    """Base Trace Log dataclass object."""
+class BaseTrace(ABC):  # pragma: no cov
+    """Base Trace dataclass with abstraction class property."""
 
     run_id: str
     parent_run_id: Optional[str] = field(default=None)
     extras: DictData = field(default_factory=dict, compare=False, repr=False)
 
+    @classmethod
+    @abstractmethod
+    def find_traces(
+        cls,
+        path: Path | None = None,
+        extras: Optional[DictData] = None,
+    ) -> Iterator[TraceData]:  # pragma: no cov
+        raise NotImplementedError(
+            "Trace dataclass should implement `find_traces` class-method."
+        )
+
+    @classmethod
+    @abstractmethod
+    def find_trace_with_id(
+        cls,
+        run_id: str,
+        force_raise: bool = True,
+        *,
+        path: Path | None = None,
+        extras: Optional[DictData] = None,
+    ) -> TraceData:
+        raise NotImplementedError(
+            "Trace dataclass should implement `find_trace_with_id` "
+            "class-method."
+        )
+
     @abstractmethod
     def writer(self, message: str, is_err: bool = False) -> None:
         """Write a trace message after making to target pointer object. The
@@ -318,11 +329,11 @@ class BaseTraceLog(ABC):  # pragma: no cov
         logger.exception(msg, stacklevel=2)
 
 
-class FileTraceLog(BaseTraceLog):  # pragma: no cov
-    """Trace Log object that write file to the local storage."""
+class FileTrace(BaseTrace):  # pragma: no cov
+    """File Trace dataclass that write file to the local storage."""
 
     @classmethod
-    def find_logs(
+    def find_traces(
         cls,
         path: Path | None = None,
         extras: Optional[DictData] = None,
@@ -333,13 +344,13 @@ class FileTraceLog(BaseTraceLog):  # pragma: no cov
         :param extras: An extra parameter that want to override core config.
         """
         for file in sorted(
-            (path or dynamic("log_path", extras=extras)).glob("./run_id=*"),
+            (path or dynamic("trace_path", extras=extras)).glob("./run_id=*"),
             key=lambda f: f.lstat().st_mtime,
         ):
             yield TraceData.from_path(file)
 
     @classmethod
-    def find_log_with_id(
+    def find_trace_with_id(
         cls,
         run_id: str,
         force_raise: bool = True,
@@ -354,7 +365,7 @@ class FileTraceLog(BaseTraceLog):  # pragma: no cov
         :param path:
         :param extras: An extra parameter that want to override core config.
         """
-        base_path: Path = path or dynamic("log_path", extras=extras)
+        base_path: Path = path or dynamic("trace_path", extras=extras)
         file: Path = base_path / f"run_id={run_id}"
         if file.exists():
             return TraceData.from_path(file)
@@ -368,7 +379,7 @@ class FileTraceLog(BaseTraceLog):  # pragma: no cov
     @property
     def pointer(self) -> Path:
         log_file: Path = (
-            dynamic("log_path", extras=self.extras)
+            dynamic("trace_path", extras=self.extras)
             / f"run_id={self.parent_run_id or self.run_id}"
         )
         if not log_file.exists():
@@ -383,7 +394,7 @@ class FileTraceLog(BaseTraceLog):  # pragma: no cov
         """
         cut_run_id: str = cut_id(self.run_id)
         if not self.parent_run_id:
-            return f"{cut_run_id} -> {' ' * 6}"
+            return f"{cut_run_id}"
 
         cut_parent_run_id: str = cut_id(self.parent_run_id)
         return f"{cut_parent_run_id} -> {cut_run_id}"
@@ -453,8 +464,8 @@ class FileTraceLog(BaseTraceLog):  # pragma: no cov
             await f.write(trace_meta.model_dump_json() + "\n")
 
 
-class SQLiteTraceLog(BaseTraceLog):  # pragma: no cov
-    """Trace Log object that write trace log to the SQLite database file."""
+class SQLiteTrace(BaseTrace):  # pragma: no cov
+    """SQLite Trace dataclass that write trace log to the SQLite database file."""
 
     table_name: ClassVar[str] = "audits"
     schemas: ClassVar[
@@ -468,10 +479,21 @@ class SQLiteTraceLog(BaseTraceLog):  # pragma: no cov
         """
 
     @classmethod
-    def find_logs(cls) -> Iterator[DictStr]: ...
+    def find_traces(
+        cls,
+        path: Path | None = None,
+        extras: Optional[DictData] = None,
+    ) -> Iterator[TraceData]: ...
 
     @classmethod
-    def find_log_with_id(cls, run_id: str) -> DictStr: ...
+    def find_trace_with_id(
+        cls,
+        run_id: str,
+        force_raise: bool = True,
+        *,
+        path: Path | None = None,
+        extras: Optional[DictData] = None,
+    ) -> TraceData: ...
 
     def make_message(self, message: str) -> str: ...
 
@@ -480,47 +502,34 @@ class SQLiteTraceLog(BaseTraceLog):  # pragma: no cov
     def awriter(self, message: str, is_err: bool = False) -> None: ...
 
 
-TraceLog = Union[
-    FileTraceLog,
-    SQLiteTraceLog,
+Trace = TypeVar("Trace", bound=BaseTrace)
+TraceModel = Union[
+    FileTrace,
+    SQLiteTrace,
 ]
 
 
 def get_trace(
     run_id: str,
-    parent_run_id: str | None = None,
     *,
+    parent_run_id: str | None = None,
     extras: Optional[DictData] = None,
-) -> TraceLog:  # pragma: no cov
-    """Get dynamic TraceLog object from the setting config.
+) -> TraceModel:  # pragma: no cov
+    """Get dynamic Trace instance from the core config (it can override by an
+    extras argument) that passing running ID and parent running ID.
 
-    :param run_id: A running ID.
-    :param parent_run_id: A parent running ID.
-    :param extras: An extra parameter that want to override the core config.
+    :param run_id: (str) A running ID.
+    :param parent_run_id: (str) A parent running ID.
+    :param extras: (DictData) An extra parameter that want to override the core
+        config values.
 
     :rtype: TraceLog
     """
-    if dynamic("log_path", extras=extras).is_file():
-        return SQLiteTraceLog(
+    if dynamic("trace_path", extras=extras).is_file():
+        return SQLiteTrace(
             run_id, parent_run_id=parent_run_id, extras=(extras or {})
         )
-    return FileTraceLog(
-        run_id, parent_run_id=parent_run_id, extras=(extras or {})
-    )
-
-
-def get_trace_obj(
-    extras: Optional[DictData] = None,
-) -> type[TraceLog]:  # pragma: no cov
-    """Get trace object.
-
-    :param extras: An extra parameter that want to override the core config.
-
-    :rtype: type[TraceLog]
-    """
-    if dynamic("log_path", extras=extras).is_file():
-        return SQLiteTraceLog
-    return FileTraceLog
+    return FileTrace(run_id, parent_run_id=parent_run_id, extras=(extras or {}))
 
 
 class BaseAudit(BaseModel, ABC):
@@ -548,15 +557,50 @@ class BaseAudit(BaseModel, ABC):
     execution_time: float = Field(default=0, description="An execution time.")
 
     @model_validator(mode="after")
-    def __model_action(self, info: ValidationInfo) -> Self:
+    def __model_action(self) -> Self:
         """Do before the Audit action with WORKFLOW_AUDIT_ENABLE_WRITE env variable.
 
         :rtype: Self
         """
-        if dynamic("enable_write_audit", extras=info.data.get("extras")):
+        if dynamic("enable_write_audit", extras=self.extras):
             self.do_before()
         return self
 
+    @classmethod
+    @abstractmethod
+    def is_pointed(
+        cls,
+        name: str,
+        release: datetime,
+        *,
+        extras: Optional[DictData] = None,
+    ) -> bool:
+        raise NotImplementedError(
+            "Audit should implement `is_pointed` class-method"
+        )
+
+    @classmethod
+    @abstractmethod
+    def find_audits(
+        cls, name: str, *, extras: Optional[DictData] = None
+    ) -> Iterator[Self]:
+        raise NotImplementedError(
+            "Audit should implement `find_audits` class-method"
+        )
+
+    @classmethod
+    @abstractmethod
+    def find_audit_with_release(
+        cls,
+        name: str,
+        release: datetime | None = None,
+        *,
+        extras: Optional[DictData] = None,
+    ) -> Self:
+        raise NotImplementedError(
+            "Audit should implement `find_audit_with_release` class-method"
+        )
+
     def do_before(self) -> None:  # pragma: no cov
         """To something before end up of initial log model."""
 
@@ -688,7 +732,11 @@ class FileAudit(BaseAudit):
 
         :rtype: Self
         """
-        trace: TraceLog = get_trace(self.run_id, self.parent_run_id)
+        trace: Trace = get_trace(
+            self.run_id,
+            parent_run_id=self.parent_run_id,
+            extras=self.extras,
+        )
 
         # NOTE: Check environ variable was set for real writing.
         if not dynamic("enable_write_audit", extras=self.extras):
@@ -726,11 +774,38 @@ class SQLiteAudit(BaseAudit):  # pragma: no cov
         primary key ( run_id )
         """
 
+    @classmethod
+    def is_pointed(
+        cls,
+        name: str,
+        release: datetime,
+        *,
+        extras: Optional[DictData] = None,
+    ) -> bool: ...
+
+    @classmethod
+    def find_audits(
+        cls, name: str, *, extras: Optional[DictData] = None
+    ) -> Iterator[Self]: ...
+
+    @classmethod
+    def find_audit_with_release(
+        cls,
+        name: str,
+        release: datetime | None = None,
+        *,
+        extras: Optional[DictData] = None,
+    ) -> Self: ...
+
     def save(self, excluded: list[str] | None) -> SQLiteAudit:
         """Save logging data that receive a context data from a workflow
         execution result.
         """
-        trace: TraceLog = get_trace(self.run_id, self.parent_run_id)
+        trace: Trace = get_trace(
+            self.run_id,
+            parent_run_id=self.parent_run_id,
+            extras=self.extras,
+        )
 
         # NOTE: Check environ variable was set for real writing.
         if not dynamic("enable_write_audit", extras=self.extras):
@@ -740,19 +815,8 @@ class SQLiteAudit(BaseAudit):  # pragma: no cov
         raise NotImplementedError("SQLiteAudit does not implement yet.")
 
 
-class RemoteFileAudit(FileAudit):  # pragma: no cov
-    """Remote File Audit Pydantic Model."""
-
-    def save(self, excluded: list[str] | None) -> RemoteFileAudit: ...
-
-
-class RedisAudit(BaseAudit):  # pragma: no cov
-    """Redis Audit Pydantic Model."""
-
-    def save(self, excluded: list[str] | None) -> RedisAudit: ...
-
-
-Audit = Union[
+Audit = TypeVar("Audit", bound=BaseAudit)
+AuditModel = Union[
     FileAudit,
     SQLiteAudit,
 ]
@@ -760,7 +824,7 @@ Audit = Union[
 
 def get_audit(
     extras: Optional[DictData] = None,
-) -> type[Audit]:  # pragma: no cov
+) -> type[AuditModel]:  # pragma: no cov
     """Get an audit class that dynamic base on the config audit path value.
 
     :param extras: An extra parameter that want to override the core config.

ddeutil/workflow/result.py

@@ -21,7 +21,8 @@ from typing_extensions import Self
 
 from .__types import DictData
 from .conf import dynamic
-from .logs import TraceLog, get_dt_tznow, get_trace
+from .exceptions import ResultException
+from .logs import Trace, get_dt_tznow, get_trace
 from .utils import default_gen_id, gen_id, get_dt_now
 
 
@@ -34,12 +35,14 @@ class Status(IntEnum):
     FAILED: int = 1
     WAIT: int = 2
     SKIP: int = 3
+    CANCEL: int = 4
 
 
 SUCCESS = Status.SUCCESS
 FAILED = Status.FAILED
 WAIT = Status.WAIT
 SKIP = Status.SKIP
+CANCEL = Status.CANCEL
 
 
 @dataclass(
@@ -63,12 +66,11 @@ class Result:
 
     status: Status = field(default=WAIT)
     context: DictData = field(default_factory=dict)
-    errors: DictData = field(default_factory=dict)
     run_id: Optional[str] = field(default_factory=default_gen_id)
     parent_run_id: Optional[str] = field(default=None, compare=False)
     ts: datetime = field(default_factory=get_dt_tznow, compare=False)
 
-    trace: Optional[TraceLog] = field(default=None, compare=False, repr=False)
+    trace: Optional[Trace] = field(default=None, compare=False, repr=False)
     extras: DictData = field(default_factory=dict, compare=False, repr=False)
 
     @classmethod
@@ -113,8 +115,10 @@ class Result:
         :rtype: Self
         """
         if self.trace is None:  # pragma: no cov
-            self.trace: TraceLog = get_trace(
-                self.run_id, self.parent_run_id, extras=self.extras
+            self.trace: Trace = get_trace(
+                self.run_id,
+                parent_run_id=self.parent_run_id,
+                extras=self.extras,
             )
         return self
 
@@ -126,8 +130,8 @@ class Result:
         :rtype: Self
         """
         self.parent_run_id: str = running_id
-        self.trace: TraceLog = get_trace(
-            self.run_id, running_id, extras=self.extras
+        self.trace: Trace = get_trace(
+            self.run_id, parent_run_id=running_id, extras=self.extras
         )
         return self
 
@@ -135,7 +139,7 @@ class Result:
         self,
         status: int | Status,
         context: DictData | None = None,
-        error: DictData | None = None,
+        **kwargs,
     ) -> Self:
         """Catch the status and context to this Result object. This method will
         use between a child execution return a result, and it wants to pass
@@ -143,7 +147,6 @@ class Result:
 
         :param status: A status enum object.
         :param context: A context data that will update to the current context.
-        :param error: An error data that will update to the current errors.
 
         :rtype: Self
         """
@@ -151,7 +154,14 @@ class Result:
             Status(status) if isinstance(status, int) else status
         )
         self.__dict__["context"].update(context or {})
-        self.__dict__["errors"].update(error or {})
+        if kwargs:
+            for k in kwargs:
+                if k in self.__dict__["context"]:
+                    self.__dict__["context"][k].update(kwargs[k])
+                else:
+                    raise ResultException(
+                        f"The key {k!r} does not exists on context data."
+                    )
         return self
 
     def alive_time(self) -> float:  # pragma: no cov

ddeutil/workflow/reusables.py

@@ -91,7 +91,7 @@ def make_filter_registry(
     :rtype: dict[str, FilterRegistry]
     """
     rs: dict[str, FilterRegistry] = {}
-    for module in dynamic("regis_filter", f=registers):
+    for module in dynamic("registry_filter", f=registers):
         # NOTE: try to sequential import task functions
         try:
             importer = import_module(module)
@@ -343,7 +343,7 @@ def param2template(
     :returns: An any getter value from the params input.
     """
     registers: Optional[list[str]] = (
-        extras.get("regis_filter") if extras else None
+        extras.get("registry_filter") if extras else None
     )
     filters: dict[str, FilterRegistry] = filters or make_filter_registry(
         registers=registers
@@ -449,7 +449,7 @@ def make_registry(
     """
     rs: dict[str, Registry] = {}
     regis_calls: list[str] = dynamic(
-        "regis_call", f=registries
+        "registry_caller", f=registries
     )  # pragma: no cov
     regis_calls.extend(["ddeutil.vendors"])