ddeutil-workflow 0.0.85__py3-none-any.whl → 0.0.86__py3-none-any.whl

ddeutil/workflow/traces.py

@@ -17,6 +17,7 @@ Functions:
     set_logging: Configure logger with custom formatting.
     get_trace: Factory function for trace instances.
 """
+import contextlib
 import json
 import logging
 import os
@@ -38,6 +39,7 @@ from typing import (
     Optional,
     TypeVar,
     Union,
+    cast,
 )
 from zoneinfo import ZoneInfo
 
@@ -110,21 +112,23 @@ PrefixType = Literal[
     "audit",
 ]
 PREFIX_LOGS: Final[dict[str, dict]] = {
-    "CALLER": {
+    "caller": {
         "emoji": "⚙️",
         "desc": "logs from any usage from custom caller function.",
     },
-    "NESTED": {"emoji": "⛓️", "desc": "logs from stages module."},
-    "STAGE": {"emoji": "🔗", "desc": "logs from stages module."},
-    "JOB": {"emoji": "🏗", "desc": "logs from job module."},
-    "WORKFLOW": {"emoji": "👟", "desc": "logs from workflow module."},
-    "RELEASE": {"emoji": "📅", "desc": "logs from release workflow method."},
-    "SCHEDULE": {"emoji": "⏰", "desc": "logs from poke workflow method."},
-    "AUDIT": {"emoji": "📌", "desc": "logs from audit model."},
+    "nested": {"emoji": "⛓️", "desc": "logs from stages module."},
+    "stage": {"emoji": "🔗", "desc": "logs from stages module."},
+    "job": {"emoji": "🏗", "desc": "logs from job module."},
+    "workflow": {"emoji": "👟", "desc": "logs from workflow module."},
+    "release": {"emoji": "📅", "desc": "logs from release workflow method."},
+    "schedule": {"emoji": "⏰", "desc": "logs from poke workflow method."},
+    "audit": {"emoji": "📌", "desc": "logs from audit model."},
 }  # pragma: no cov
-PREFIX_DEFAULT: Final[str] = "CALLER"
+PREFIX_LOGS_UPPER: Final[Iterator[str]] = (p.upper() for p in PREFIX_LOGS)
+PREFIX_DEFAULT: Final[Literal["caller"]] = "caller"
+PREFIX_EMOJI_DEFAULT: Final[str] = "⚙️"
 PREFIX_LOGS_REGEX: Final[re.Pattern[str]] = re.compile(
-    rf"(^\[(?P<name>{'|'.join(PREFIX_LOGS)})]:\s?)?(?P<message>.*)",
+    rf"(^\[(?P<module>{'|'.join(PREFIX_LOGS_UPPER)})]:\s?)?(?P<message>.*)",
     re.MULTILINE | re.DOTALL | re.ASCII | re.VERBOSE,
 )  # pragma: no cov
 
@@ -136,42 +140,52 @@ class Message(BaseModel):
     with emoji support and categorization.
     """
 
-    name: Optional[str] = Field(
-        default=None, description="A prefix name of message."
+    module: Optional[PrefixType] = Field(
+        default=None,
+        description="A prefix module of message it allow to be None.",
     )
     message: Optional[str] = Field(default=None, description="A message.")
 
+    @field_validator("module", mode="before", json_schema_input_type=str)
+    def __prepare_module(cls, data: Optional[str]) -> Optional[str]:
+        return data.lower() if data is not None else data
+
     @classmethod
-    def from_str(cls, msg: str) -> Self:
+    def from_str(cls, msg: str, module: Optional[PrefixType] = None) -> Self:
         """Extract message prefix from an input message.
 
         Args:
-            msg: A message that want to extract.
+            msg (str): A message that want to extract.
+            module (PrefixType, default None): A prefix module type.
 
         Returns:
             Message: The validated model from a string message.
         """
-        return Message.model_validate(
-            obj=PREFIX_LOGS_REGEX.search(msg).groupdict()
-        )
+        msg = cls.model_validate(PREFIX_LOGS_REGEX.search(msg).groupdict())
+        if msg.module is None and module:
+            msg.module = module
+        return msg
 
     def prepare(self, extras: Optional[DictData] = None) -> str:
         """Prepare message with force add prefix before writing trace log.
 
         Args:
-            extras: An extra parameter that want to get the
-                `log_add_emoji` flag.
+            extras (DictData, default None): An extra parameter that want to
+                get the `log_add_emoji` flag.
 
         Returns:
             str: The prepared message with prefix and optional emoji.
         """
-        name: str = self.name or PREFIX_DEFAULT
+        module = cast(PrefixType, self.module or PREFIX_DEFAULT)
+        module_data: dict[str, str] = PREFIX_LOGS.get(
+            module, {"emoji": PREFIX_EMOJI_DEFAULT}
+        )
         emoji: str = (
-            f"{PREFIX_LOGS[name]['emoji']} "
+            f"{module_data['emoji']} "
             if (extras or {}).get("log_add_emoji", True)
             else ""
         )
-        return f"{emoji}[{name}]: {self.message}"
+        return f"{emoji}[{module.upper()}]: {self.message}"
 
 
 class Metric(BaseModel):  # pragma: no cov
@@ -195,6 +209,9 @@ class Metadata(BaseModel):  # pragma: no cov
     )
     process: int = Field(description="A process ID.")
     thread: int = Field(description="A thread ID.")
+    module: Optional[PrefixType] = Field(
+        default=None, description="A prefix module type."
+    )
     message: str = Field(description="A message log.")
     cut_id: Optional[str] = Field(
         default=None, description="A cutting of running ID."
@@ -274,6 +291,7 @@ class Metadata(BaseModel):  # pragma: no cov
         parent_run_id: Optional[str],
         *,
         metric: Optional[DictData] = None,
+        module: Optional[PrefixType] = None,
         extras: Optional[DictData] = None,
     ) -> Self:
         """Make the current metric for contract this Metadata model instance.
@@ -289,6 +307,7 @@ class Metadata(BaseModel):  # pragma: no cov
             run_id:
             parent_run_id:
             metric:
+            module:
             extras: An extra parameter that want to override core
                 config values.
 
@@ -333,6 +352,7 @@ class Metadata(BaseModel):  # pragma: no cov
             ),
             process=os.getpid(),
             thread=get_ident(),
+            module=module,
             message=message,
             cut_id=cutting_id,
             run_id=run_id,
@@ -1679,8 +1699,8 @@ class BaseEmit(ABC):
         msg: str,
         level: Level,
         *,
-        module: Optional[str] = None,
         metric: Optional[DictData] = None,
+        module: Optional[PrefixType] = None,
     ) -> None:
         """Write trace log with append mode and logging this message with any
         logging level.
@@ -1690,62 +1710,73 @@ class BaseEmit(ABC):
             level: A logging level.
             metric (DictData, default None): A metric data that want to export
                 to each target handler.
-            module (str, default None): A module name that use for adding prefix
-                at the message value.
+            module (PrefixType, default None): A module name that use for adding
+                prefix at the message value.
         """
         raise NotImplementedError(
             "Emit action should be implement for making trace log."
         )
 
-    def debug(self, msg: str, module: Optional[str] = None):
+    def debug(self, msg: str, module: Optional[PrefixType] = None):
         """Write trace log with append mode and logging this message with the
         DEBUG level.
 
         Args:
             msg: A message that want to log.
-            module (str, default None): A module name that use for adding prefix
-                at the message value.
+            module (PrefixType, default None): A module name that use for adding
+                prefix at the message value.
         """
         self.emit(msg, level="debug", module=module)
 
-    def info(self, msg: str) -> None:
+    def info(self, msg: str, module: Optional[PrefixType] = None) -> None:
         """Write trace log with append mode and logging this message with the
         INFO level.
 
         Args:
             msg: A message that want to log.
+            module (PrefixType, default None): A module name that use for adding
+                prefix at the message value.
         """
-        self.emit(msg, level="info")
+        self.emit(msg, level="info", module=module)
 
-    def warning(self, msg: str) -> None:
+    def warning(self, msg: str, module: Optional[PrefixType] = None) -> None:
         """Write trace log with append mode and logging this message with the
         WARNING level.
 
         Args:
             msg: A message that want to log.
+            module (PrefixType, default None): A module name that use for adding
+                prefix at the message value.
         """
-        self.emit(msg, level="warning")
+        self.emit(msg, level="warning", module=module)
 
-    def error(self, msg: str) -> None:
+    def error(self, msg: str, module: Optional[PrefixType] = None) -> None:
         """Write trace log with append mode and logging this message with the
         ERROR level.
 
         Args:
             msg: A message that want to log.
+            module (PrefixType, default None): A module name that use for adding
+                prefix at the message value.
         """
-        self.emit(msg, level="error")
+        self.emit(msg, level="error", module=module)
 
-    def exception(self, msg: str) -> None:
+    def exception(self, msg: str, module: Optional[PrefixType] = None) -> None:
         """Write trace log with append mode and logging this message with the
         EXCEPTION level.
 
         Args:
             msg: A message that want to log.
+            module (PrefixType, default None): A module name that use for adding
+                prefix at the message value.
         """
-        self.emit(msg, level="exception")
+        self.emit(msg, level="exception", module=module)
 
 
 class BaseAsyncEmit(ABC):
+    """Base Async Emit Abstract class for mixin `amit` method and async
+    logging that will use prefix with `a` charactor.
+    """
 
     @abstractmethod
     async def amit(
@@ -1754,6 +1785,7 @@ class BaseAsyncEmit(ABC):
         level: Level,
         *,
         metric: Optional[DictData] = None,
+        module: Optional[PrefixType] = None,
     ) -> None:
         """Async write trace log with append mode and logging this message with
         any logging level.
@@ -1763,55 +1795,77 @@ class BaseAsyncEmit(ABC):
             level (Mode): A logging level.
             metric (DictData, default None): A metric data that want to export
                 to each target handler.
+            module (PrefixType, default None): A module name that use for adding
+                prefix at the message value.
         """
         raise NotImplementedError(
             "Async Logging action should be implement for making trace log."
         )
 
-    async def adebug(self, msg: str) -> None:  # pragma: no cov
+    async def adebug(
+        self, msg: str, module: Optional[PrefixType] = None
+    ) -> None:  # pragma: no cov
         """Async write trace log with append mode and logging this message with
         the DEBUG level.
 
         Args:
             msg: A message that want to log.
+            module (PrefixType, default None): A module name that use for adding
+                prefix at the message value.
         """
-        await self.amit(msg, level="debug")
+        await self.amit(msg, level="debug", module=module)
 
-    async def ainfo(self, msg: str) -> None:  # pragma: no cov
+    async def ainfo(
+        self, msg: str, module: Optional[PrefixType] = None
+    ) -> None:  # pragma: no cov
         """Async write trace log with append mode and logging this message with
         the INFO level.
 
         Args:
             msg: A message that want to log.
+            module (PrefixType, default None): A module name that use for adding
+                prefix at the message value.
         """
-        await self.amit(msg, level="info")
+        await self.amit(msg, level="info", module=module)
 
-    async def awarning(self, msg: str) -> None:  # pragma: no cov
+    async def awarning(
+        self, msg: str, module: Optional[PrefixType] = None
+    ) -> None:  # pragma: no cov
         """Async write trace log with append mode and logging this message with
         the WARNING level.
 
         Args:
             msg: A message that want to log.
+            module (PrefixType, default None): A module name that use for adding
+                prefix at the message value.
         """
-        await self.amit(msg, level="warning")
+        await self.amit(msg, level="warning", module=module)
 
-    async def aerror(self, msg: str) -> None:  # pragma: no cov
+    async def aerror(
+        self, msg: str, module: Optional[PrefixType] = None
+    ) -> None:  # pragma: no cov
         """Async write trace log with append mode and logging this message with
         the ERROR level.
 
         Args:
             msg: A message that want to log.
+            module (PrefixType, default None): A module name that use for adding
+                prefix at the message value.
         """
-        await self.amit(msg, level="error")
+        await self.amit(msg, level="error", module=module)
 
-    async def aexception(self, msg: str) -> None:  # pragma: no cov
+    async def aexception(
+        self, msg: str, module: Optional[PrefixType] = None
+    ) -> None:  # pragma: no cov
         """Async write trace log with append mode and logging this message with
         the EXCEPTION level.
 
         Args:
             msg: A message that want to log.
+            module (PrefixType, default None): A module name that use for adding
+                prefix at the message value.
         """
-        await self.amit(msg, level="exception")
+        await self.amit(msg, level="exception", module=module)
 
 
 class Trace(BaseModel, BaseEmit, BaseAsyncEmit):
@@ -1857,24 +1911,13 @@ class Trace(BaseModel, BaseEmit, BaseAsyncEmit):
         cut_parent_run_id: str = cut_id(self.parent_run_id)
         return f"{cut_parent_run_id} -> {cut_run_id}"
 
-    def make_message(self, msg: str) -> str:
-        """Prepare and Make a message before write and log steps.
-
-        Args:
-            msg: A message that want to prepare and make before.
-
-        Returns:
-            str: The prepared message.
-        """
-        return prepare_newline(Message.from_str(msg).prepare(self.extras))
-
     def emit(
         self,
         msg: str,
         level: Level,
         *,
-        module: Optional[str] = None,
         metric: Optional[DictData] = None,
+        module: Optional[PrefixType] = None,
     ) -> None:
         """Emit a trace log to all handler. This will use synchronise process.
 
@@ -1883,14 +1926,15 @@ class Trace(BaseModel, BaseEmit, BaseAsyncEmit):
             level (Level): A tracing level.
             metric (DictData, default None): A metric data that want to export
                 to each target handler.
-            module (str, default None): A module name that use for adding prefix
-                at the message value.
+            module (PrefixType, default None): A module name that use for adding
+                prefix at the message value.
         """
-        _msg: str = self.make_message(msg)
+        _msg: Message = Message.from_str(msg, module=module)
         metadata: Metadata = Metadata.make(
             error_flag=(level in ("error", "exception")),
             level=level,
-            message=_msg,
+            module=_msg.module,
+            message=prepare_newline(_msg.prepare(self.extras)),
             cutting_id=self.cut_id,
             run_id=self.run_id,
             parent_run_id=self.parent_run_id,
@@ -1915,7 +1959,12 @@ class Trace(BaseModel, BaseEmit, BaseAsyncEmit):
             self._buffer.clear()
 
     async def amit(
-        self, msg: str, level: Level, *, metric: Optional[DictData] = None
+        self,
+        msg: str,
+        level: Level,
+        *,
+        metric: Optional[DictData] = None,
+        module: Optional[PrefixType] = None,
     ) -> None:
         """Async write trace log with append mode and logging this message with
         any logging level.
@@ -1925,12 +1974,15 @@ class Trace(BaseModel, BaseEmit, BaseAsyncEmit):
             level (Level): A logging mode.
             metric (DictData, default None): A metric data that want to export
                 to each target handler.
+            module (PrefixType, default None): A module name that use for adding
+                prefix at the message value.
         """
-        _msg: str = self.make_message(msg)
+        _msg: Message = Message.from_str(msg, module=module)
         metadata: Metadata = Metadata.make(
             error_flag=(level in ("error", "exception")),
             level=level,
-            message=_msg,
+            module=_msg.module,
+            message=prepare_newline(_msg.prepare(self.extras)),
             cutting_id=self.cut_id,
             run_id=self.run_id,
             parent_run_id=self.parent_run_id,
@@ -1942,35 +1994,40 @@ class Trace(BaseModel, BaseEmit, BaseAsyncEmit):
         for handler in self.handlers:
             await handler.amit(metadata, extra=self.extras)
 
-    def __enter__(self):
+    @contextlib.contextmanager
+    def buffer(self, module: Optional[PrefixType] = None) -> Iterator[Self]:
         """Enter the trace for catching the logs that run so fast. It will use
         buffer strategy to flush the logs instead emit.
+
+        Args:
+            module (PrefixType, default None): A module name that use for adding
+                prefix at the message value.
+
+        Yields:
+            Self: Itself instance.
         """
         self._enable_buffer = True
-        return self
-
-    def __exit__(self, exc_type, exc_val, exc_tb):
-        """Exit the trace that will clear all log in the buffer."""
-        if exc_type:
-            _msg: str = self.make_message(str(exc_val))
+        try:
+            yield self
+        except Exception as err:
+            _msg: Message = Message.from_str(str(err), module=module)
             metadata: Metadata = Metadata.make(
                 error_flag=True,
                 level="error",
-                message=_msg,
+                module=_msg.module,
+                message=prepare_newline(_msg.prepare(self.extras)),
                 cutting_id=self.cut_id,
                 run_id=self.run_id,
                 parent_run_id=self.parent_run_id,
                 extras=self.extras,
             )
             self._buffer.append(metadata)
-
-        if self._buffer:
-            for handler in self.handlers:
-                handler.flush(self._buffer, extra=self.extras)
-            self._buffer.clear()
-
-        # NOTE: Re-raise the exception if one occurred
-        return False
+            raise
+        finally:
+            if self._buffer:
+                for handler in self.handlers:
+                    handler.flush(self._buffer, extra=self.extras)
+                self._buffer.clear()
 
 
 def get_trace(
@@ -1979,23 +2036,24 @@ def get_trace(
     handlers: list[Union[DictData, Handler]] = None,
     parent_run_id: Optional[str] = None,
     extras: Optional[DictData] = None,
-    auto_pre_process: bool = True,
+    pre_process: bool = False,
 ) -> Trace:
-    """Get dynamic Trace instance from the core config.
+    """Get dynamic Trace instance from the core config. This function will use
+    for start some process, and it wants to generated trace object.
 
-    This factory function returns the appropriate trace implementation based on
-    configuration. It can be overridden by extras argument and accepts running ID
-    and parent running ID.
+        This factory function returns the appropriate trace implementation based
+    on configuration. It can be overridden by extras argument and accepts
+    running ID and parent running ID.
 
     Args:
         run_id (str): A running ID.
-        parent_run_id (str | None, default None): A parent running ID.
+        parent_run_id (str, default None): A parent running ID.
         handlers (list[DictData | Handler], default None): A list of handler or
             mapping of handler data that want to direct pass instead use
             environment variable config.
         extras (DictData, default None): An extra parameter that want to
             override the core config values.
-        auto_pre_process (bool, default False) A flag that will auto call pre
+        pre_process (bool, default False) A flag that will auto call pre
             method after validate a trace model.
 
     Returns:
@@ -2010,7 +2068,7 @@ def get_trace(
         }
     )
     # NOTE: Start pre-process when start create trace.
-    if auto_pre_process:
+    if pre_process:
         for handler in trace.handlers:
             handler.pre()
     return trace