thread-order 1.3.0__tar.gz → 1.3.2__tar.gz

{thread_order-1.3.0/thread_order.egg-info → thread_order-1.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thread-order
-Version: 1.3.0
+Version: 1.3.2
 Summary: A lightweight framework for running functions concurrently across multiple threads while maintaining a defined execution order.
 Author-email: Emilio Reyes <soda480@gmail.com>
 License-Expression: Apache-2.0
@@ -218,29 +218,26 @@ These appear in `initial_state` and can be processed in your module’s `setup_s
 
 This allows your module to compute initial state based on CLI parameters.
 
-## Custom Logging
+## Optional Highlights
 
-If a module defines a `setup_logging()` function, `tdrun` will automatically detect and invoke it during module initialization. This allows the module to configure its own logging behavior in a consistent and structured way while remaining compatible with the execution model.
+`tdrun` CLI supports customizable log highlighting. In addition to the built-in highlight rules (e.g. PASSED, FAILED, SKIPPED), you may provide additional highlight patterns to emphasize important output.
+
+If a module defines an `add_logging_highlights()` function, it should return a list of (compiled_regex, color) pairs:
 
 ```Python
-def setup_logging(
-    workers,                    # Effective worker count resolved by CLI
-    verbose=False,              # Enable verbose (debug-level) logging
-    add_stream_handler=False,   # Attach console handler (disabled when progress/viewer active)
-    add_file_handler=False      # Attach file handler when --log is enabled
-):
+import re
+from colorama import Fore
+
+def add_logging_highlights():
+  return [
+      (re.compile(r'\bCRITICAL\b'), Fore.RED),
+      (re.compile(r'Environment:\s+\w+'), Fore.CYAN),
+  ]
 ```
 
-At runtime, `tdrun` will invoke it as:
+When logging is enabled, these rules are appended to the default highlights and applied to log output during execution.
 
-```Python
-setup_logging(
-    args.workers,  # effective workers
-    verbose=args.verbose,
-    add_stream_handler=not args.progress and not args.viewer,
-    add_file_handler=args.log,
-)
-```
+This allows modules or callers to visually emphasize important state, metadata, or runtime signals without modifying the core logging configuration.
 
 ### DAG Inspection
 
@@ -311,6 +308,7 @@ class Scheduler(
     setup_logging=False,          # enable built-in logging config
     add_stream_handler=True,      # attach stream handler to logger
     add_file_handler=True,        # attach file handlers for each thread to logger
+    highlights=None,              # Optional list of highlight rules applied to log output
     verbose=False,                # enable extra debug logging on stream handler
     skip_dependents=False         # skip dependents when prerequisites fail
 )

{thread_order-1.3.0 → thread_order-1.3.2}/README.md

@@ -176,29 +176,26 @@ These appear in `initial_state` and can be processed in your module’s `setup_s
 
 This allows your module to compute initial state based on CLI parameters.
 
-## Custom Logging
+## Optional Highlights
 
-If a module defines a `setup_logging()` function, `tdrun` will automatically detect and invoke it during module initialization. This allows the module to configure its own logging behavior in a consistent and structured way while remaining compatible with the execution model.
+`tdrun` CLI supports customizable log highlighting. In addition to the built-in highlight rules (e.g. PASSED, FAILED, SKIPPED), you may provide additional highlight patterns to emphasize important output.
+
+If a module defines an `add_logging_highlights()` function, it should return a list of (compiled_regex, color) pairs:
 
 ```Python
-def setup_logging(
-    workers,                    # Effective worker count resolved by CLI
-    verbose=False,              # Enable verbose (debug-level) logging
-    add_stream_handler=False,   # Attach console handler (disabled when progress/viewer active)
-    add_file_handler=False      # Attach file handler when --log is enabled
-):
+import re
+from colorama import Fore
+
+def add_logging_highlights():
+  return [
+      (re.compile(r'\bCRITICAL\b'), Fore.RED),
+      (re.compile(r'Environment:\s+\w+'), Fore.CYAN),
+  ]
 ```
 
-At runtime, `tdrun` will invoke it as:
+When logging is enabled, these rules are appended to the default highlights and applied to log output during execution.
 
-```Python
-setup_logging(
-    args.workers,  # effective workers
-    verbose=args.verbose,
-    add_stream_handler=not args.progress and not args.viewer,
-    add_file_handler=args.log,
-)
-```
+This allows modules or callers to visually emphasize important state, metadata, or runtime signals without modifying the core logging configuration.
 
 ### DAG Inspection
 
@@ -269,6 +266,7 @@ class Scheduler(
     setup_logging=False,          # enable built-in logging config
     add_stream_handler=True,      # attach stream handler to logger
     add_file_handler=True,        # attach file handlers for each thread to logger
+    highlights=None,              # Optional list of highlight rules applied to log output
     verbose=False,                # enable extra debug logging on stream handler
     skip_dependents=False         # skip dependents when prerequisites fail
 )

{thread_order-1.3.0 → thread_order-1.3.2}/thread_order/__init__.py

@@ -12,6 +12,7 @@ __all__ = [
     'default_workers',
     'load_and_collect_functions',
     'register_functions',
+    'validate_highlights',
     '__version__']
 
 def __getattr__(name):
@@ -42,6 +43,9 @@ def __getattr__(name):
     if name == 'register_functions':
         from .scheduler import register_functions
         return register_functions
+    if name == 'validate_highlights':
+        from .logger import validate_highlights
+        return validate_highlights
     # If the requested attribute isn't one of the known top-level symbols,
     # try to lazily import a submodule (e.g. `thread_order.scheduler`) so
     # attribute lookups such as those used by mocking/patching succeed.
@@ -53,7 +57,7 @@ def __getattr__(name):
 try:
     __version__ = _metadata.version(__name__)
 except _metadata.PackageNotFoundError:
-    __version__ = '1.3.0'
+    __version__ = '1.3.2'
 
 if getenv('DEV'):
     __version__ = f'{__version__}+dev'

{thread_order-1.3.0 → thread_order-1.3.2}/thread_order/cli/app.py

@@ -4,7 +4,12 @@ import json
 from contextlib import nullcontext
 from pathlib import Path
 from thread_order import (
-    Scheduler, ThreadProxyLogger, default_workers, load_and_collect_functions, register_functions)
+    Scheduler,
+    ThreadProxyLogger,
+    default_workers,
+    load_and_collect_functions,
+    register_functions,
+    validate_highlights)
 from thread_order.graph_summary import format_graph_summary
 try:
     from progress1bar import ProgressBar
@@ -177,19 +182,16 @@ def _build_scheduler_kwargs(args, initial_state, clear_results_on_start, module)
         'skip_dependents': args.skip_deps
     }
     # prefer module-provided logging hook if available
-    setup_logging_function = getattr(module, 'setup_logging', None)
-    if callable(setup_logging_function):
-        setup_logging_function(
-            args.effective_workers,
-            verbose=args.verbose,
-            add_stream_handler=not args.progress and not args.viewer,
-            add_file_handler=args.log)
-    else:
-        scheduler_kwargs['setup_logging'] = True
-        scheduler_kwargs['verbose'] = args.verbose
-        scheduler_kwargs['add_stream_handler'] = not args.progress and not args.viewer
-        scheduler_kwargs['add_file_handler'] = args.log
+    add_logging_highlights_function = getattr(module, 'add_logging_highlights', None)
+    if callable(add_logging_highlights_function):
+        highlights = add_logging_highlights_function()
+        validated_highlights = validate_highlights(highlights)
+        scheduler_kwargs['highlights'] = validated_highlights
 
+    scheduler_kwargs['setup_logging'] = True
+    scheduler_kwargs['verbose'] = args.verbose
+    scheduler_kwargs['add_stream_handler'] = not args.progress and not args.viewer
+    scheduler_kwargs['add_file_handler'] = args.log
     return scheduler_kwargs
 
 def validate_args(args):

thread_order-1.3.2/thread_order/logger.py

@@ -0,0 +1,162 @@
+import os
+import re
+import sys
+import threading
+import logging
+from colorama import init
+from colorama import Fore, Style
+
+def validate_highlights(highlights):
+    if not isinstance(highlights, (list, tuple)):
+        raise TypeError('highlights must be a list/tuple of (regex, color) pairs')
+    for item in highlights:
+        if not isinstance(item, (list, tuple)) or len(item) != 2:
+            raise TypeError('each highlight must be a (regex, color) pair')
+        pattern, _ = item
+        if not isinstance(pattern, re.Pattern):
+            raise TypeError('highlight pattern must be a compiled regex (re.Pattern)')
+    return list(highlights)
+
+class ColoredFormatter(logging.Formatter):
+    LEVEL_COLORS = {
+        logging.DEBUG: Style.BRIGHT + Fore.CYAN,
+        logging.INFO: Style.BRIGHT + Fore.BLUE,
+        logging.WARNING: Style.BRIGHT + Fore.YELLOW,
+        logging.ERROR: Style.BRIGHT + Fore.RED,
+        logging.CRITICAL: Style.BRIGHT + Fore.RED,
+    }
+    DEFAULT_HIGHLIGHTS = [
+        (re.compile(r'\bPASSED\b', re.IGNORECASE), Fore.GREEN),
+        (re.compile(r'\bFAILED\b', re.IGNORECASE), Fore.RED),
+        (re.compile(r'\bSKIPPED\b', re.IGNORECASE), Fore.YELLOW),
+        (re.compile(r'Scheduler::State:\s*(\{.*?^})', re.DOTALL | re.MULTILINE), Fore.MAGENTA)
+    ]
+
+    def __init__(self, workers, *args, **kwargs):
+        highlights = kwargs.pop('highlights', [])
+        if highlights is not None:
+            validated = validate_highlights(highlights)
+            self.highlights = [*self.DEFAULT_HIGHLIGHTS, *validated]
+        else:
+            self.highlights = list(self.DEFAULT_HIGHLIGHTS)
+        self.verbose = kwargs.pop('verbose', False)
+        super().__init__(*args, **kwargs)
+
+    def _apply_highlights(self, message):
+        out = message
+        for pattern, color in self.highlights:
+            def replace(m):
+                text = m.group(0)
+                return f'{color}{text}{Style.RESET_ALL}{Fore.WHITE}'
+            out = pattern.sub(replace, out)
+        return out
+
+    def format(self, record):
+        timestamp = self.formatTime(record, self.datefmt)
+        level_color = self.LEVEL_COLORS.get(record.levelno, Fore.WHITE)
+
+        raw_msg = record.getMessage()
+        colored_msg = self._apply_highlights(raw_msg)
+
+        # only log thread name if it's not MainThread
+        # to avoid cluttering the logs with 'MainThread' entries
+        if record.threadName == 'MainThread':
+            thread_name = ''
+        else:
+            thread_name = f'[{record.threadName}] '
+
+        if self.verbose:
+            msg = (
+                f"{Style.DIM}{timestamp}{Style.RESET_ALL} "
+                f"{level_color}{record.levelname:<5}{Style.RESET_ALL} "
+                f"{thread_name}"
+                f"{Fore.WHITE}{record.funcName}: {colored_msg}{Style.RESET_ALL}"
+            )
+        else:
+            msg = (
+                f"{Style.DIM}{timestamp}{Style.RESET_ALL} "
+                f"{thread_name}"
+                f"{colored_msg}{Style.RESET_ALL}"
+            )
+        if record.exc_info:
+            msg += '\n' + self.formatException(record.exc_info)
+
+        return msg
+
+    def _validate_highlights(self, highlights):
+        if not isinstance(highlights, (list, tuple)):
+            raise TypeError('highlights must be a list/tuple of (regex, color) pairs')
+        for item in highlights:
+            if not isinstance(item, (list, tuple)) or len(item) != 2:
+                raise TypeError('each highlight must be a (regex, color) pair')
+            pattern, _ = item
+            if not isinstance(pattern, re.Pattern):
+                raise TypeError('highlight pattern must be a compiled regex (re.Pattern)')
+        return list(highlights)
+
+class MainThreadAwareFormatter(logging.Formatter):
+
+    def __init__(self, main_fmt, thread_fmt, workers, thread_prefix='thread_', *args, **kwargs):
+        super().__init__(fmt=main_fmt, *args, **kwargs)
+        self.main_fmt = main_fmt
+        self.thread_fmt = thread_fmt
+        self.thread_prefix = thread_prefix
+
+    def format(self, record):
+        if record.threadName == 'MainThread':
+            self._style._fmt = self.main_fmt
+        else:
+            self._style._fmt = self.thread_fmt
+        return super().format(record)
+
+class ThreadProxyLogger:
+    def __getattr__(self, name):
+        return getattr(logging.getLogger(threading.current_thread().name), name)
+
+def configure_logging(workers, prefix='thread', add_stream_handler=False, highlights=None,
+                      verbose=False, add_file_handler=True):
+
+    root_logger = logging.getLogger()
+    if getattr(root_logger, '_logging_initialized', False):
+        return
+
+    root_logger.setLevel(logging.DEBUG)
+    root_logger.handlers.clear()
+
+    # Prevent lastResort output by ensuring *a* handler exists:
+    root_logger.addHandler(logging.NullHandler())
+
+    file_formatter = logging.Formatter(
+        '%(asctime)s %(levelname)-5s [%(threadName)s] %(funcName)s: %(message)s')
+
+    if add_stream_handler:
+        init(autoreset=False)
+        stream_formatter = ColoredFormatter(workers, highlights=highlights, verbose=verbose)
+        stream_handler = logging.StreamHandler(sys.stderr)
+        stream_handler.setFormatter(stream_formatter)
+        stream_handler.setLevel(logging.DEBUG if verbose else logging.INFO)
+        root_logger.addHandler(stream_handler)
+
+        root_logger._logging_initialized = True
+
+    base = os.path.splitext(os.path.basename(sys.argv[0]))[0]
+
+    def add_handler(name):
+        filename = f'{base}_{name}.log'
+        logger = logging.getLogger(name)
+        if not any(
+            isinstance(handler, logging.FileHandler)
+            and getattr(handler, 'baseFilename', '').endswith(filename)
+            for handler in logger.handlers
+        ):
+            fhandler = logging.FileHandler(filename, mode='a', encoding='utf-8')
+            fhandler.setLevel(logging.DEBUG)
+            fhandler.setFormatter(file_formatter)
+            logger.addHandler(fhandler)
+        logger.setLevel(logging.DEBUG)
+        return logger
+
+    if add_file_handler:
+        add_handler(threading.current_thread().name)
+        for index in range(workers):
+            add_handler(f'{prefix}_{index}')

{thread_order-1.3.0 → thread_order-1.3.2}/thread_order/scheduler.py

@@ -32,7 +32,7 @@ class Scheduler:
     """
     def __init__(self, workers=None, setup_logging=False, add_stream_handler=True,
                  state=None, store_results=True, clear_results_on_start=True, verbose=False,
-                 skip_dependents=False, add_file_handler=True):
+                 skip_dependents=False, add_file_handler=True, highlights=None):
         """ initialize scheduler with thread pool size, logging, and callback placeholders
         """
         # number of concurrent worker threads in the pool
@@ -83,7 +83,8 @@ class Scheduler:
         if setup_logging:
             configure_logging(self._workers, prefix=self._prefix, verbose=verbose,
                               add_stream_handler=add_stream_handler,
-                              add_file_handler=add_file_handler)
+                              add_file_handler=add_file_handler,
+                              highlights=highlights)
         self._skip_dependents = skip_dependents
 
     def register(self, obj, name, after=None, with_state=False):