mindtrace 0.1.0__py3-none-any.whl

mindtrace/core/mindtrace/core/__init__.py

@@ -0,0 +1,34 @@
+from mindtrace.core.base import Mindtrace, MindtraceABC, MindtraceMeta
+from mindtrace.core.config import Config
+from mindtrace.core.logging.logger import setup_logger
+from mindtrace.core.observables.context_listener import ContextListener
+from mindtrace.core.observables.event_bus import EventBus
+from mindtrace.core.observables.observable_context import ObservableContext
+from mindtrace.core.types.task_schema import TaskSchema
+from mindtrace.core.utils.checks import check_libs, first_not_none, ifnone, ifnone_url
+from mindtrace.core.utils.dynamic import get_class, instantiate_target
+from mindtrace.core.utils.lambdas import named_lambda
+from mindtrace.core.utils.timers import Timeout, Timer, TimerCollection
+
+setup_logger()  # Initialize the default logger
+
+__all__ = [
+    "check_libs",
+    "ContextListener",
+    "Config",
+    "EventBus",
+    "first_not_none",
+    "get_class",
+    "ifnone",
+    "ifnone_url",
+    "instantiate_target",
+    "Mindtrace",
+    "MindtraceABC",
+    "MindtraceMeta",
+    "named_lambda",
+    "ObservableContext",
+    "TaskSchema",
+    "Timer",
+    "TimerCollection",
+    "Timeout",
+]

mindtrace/core/mindtrace/core/base/__init__.py

@@ -0,0 +1,7 @@
+from mindtrace.core.base.mindtrace_base import Mindtrace, MindtraceABC, MindtraceMeta
+
+__all__ = [
+    "Mindtrace",
+    "MindtraceABC",
+    "MindtraceMeta",
+]

mindtrace/core/mindtrace/core/base/mindtrace_base.py

@@ -0,0 +1,374 @@
+"""Mindtrace class. Provides unified configuration, logging and context management."""
+
+import inspect
+import logging
+import traceback
+from abc import ABC, ABCMeta
+from functools import wraps
+from typing import Callable, Optional
+
+from mindtrace.core.config import Config
+from mindtrace.core.logging.logger import get_logger
+from mindtrace.core.utils import ifnone
+
+
+class MindtraceMeta(type):
+    """Metaclass for Mindtrace class.
+
+    The MindtraceMeta metaclass enables classes deriving from Mindtrace to automatically use the same default logger within
+    class methods as it does within instance methods. I.e. consider the following class:
+
+    Example, logging in both class methods and instance methods::
+
+        from mindtrace.core import Mindtrace
+
+        class MyClass(Mindtrace):
+            def __init__(self):
+                super().__init__()
+
+            def instance_method(self):
+                self.logger.info(f"Using logger: {self.logger.name}")  # Using logger: mindtrace.my_module.MyClass
+
+            @classmethod
+            def class_method(cls):
+                cls.logger.info(f"Using logger: {cls.logger.name}")  # Using logger: mindtrace.my_module.MyClass
+    """
+
+    def __init__(cls, name, bases, attr_dict):
+        super().__init__(name, bases, attr_dict)
+        cls._logger = None
+
+    @property
+    def logger(cls):
+        if cls._logger is None:
+            cls._logger = get_logger(cls.unique_name)
+        return cls._logger
+
+    @logger.setter
+    def logger(cls, new_logger):
+        cls._logger = new_logger
+
+    @property
+    def unique_name(self) -> str:
+        return self.__module__ + "." + self.__name__
+
+
+class Mindtrace(metaclass=MindtraceMeta):
+    """Base class for all Mindtrace package core classes.
+
+    The Mindtrace class adds default context manager and logging methods. All classes that derive from Mindtrace can be
+    used as context managers and will use a unified logging format.
+
+    The class automatically provides logging capabilities for both class methods and instance methods.
+    For example:
+
+    .. code-block:: python
+
+        from mindtrace.core import Mindtrace
+
+        class MyClass(Mindtrace):
+            def __init__(self):
+                super().__init__()
+
+            def instance_method(self):
+                self.logger.info(f"Using logger: {self.logger.name}")  # Using logger: mindtrace.my_module.MyClass
+
+            @classmethod
+            def class_method(cls):
+                cls.logger.info(f"Using logger: {cls.logger.name}")  # Using logger: mindtrace.my_module.MyClass
+
+    The logging functionality is automatically provided through the MindtraceMeta metaclass,
+    which ensures consistent logging behavior across all method types.
+    """
+
+    config = Config()
+
+    def __init__(self, suppress: bool = False, **kwargs):
+        """
+        Initialize the Mindtrace object.
+
+        Args:
+            suppress (bool): Whether to suppress exceptions in context manager use.
+            **kwargs: Additional keyword arguments. Logger-related kwargs are passed to `get_logger`.
+                Valid logger kwargs: log_dir, logger_level, stream_level, file_level,
+                file_mode, propagate, max_bytes, backup_count
+        """
+        # Initialize parent classes first (cooperative inheritance)
+        try:
+            super().__init__(**kwargs)
+        except TypeError:
+            # If parent classes don't accept some kwargs, try without logger-specific ones
+            logger_param_names = {
+                "log_dir",
+                "logger_level",
+                "stream_level",
+                "file_level",
+                "file_mode",
+                "propagate",
+                "max_bytes",
+                "backup_count",
+            }
+            remaining_kwargs = {k: v for k, v in kwargs.items() if k not in logger_param_names}
+            try:
+                super().__init__(**remaining_kwargs)
+            except TypeError:
+                # If that still fails, try with no kwargs
+                super().__init__()
+
+        # Set Mindtrace-specific attributes
+        self.suppress = suppress
+
+        # Filter logger-specific kwargs for logger setup
+        logger_param_names = {
+            "log_dir",
+            "logger_level",
+            "stream_level",
+            "file_level",
+            "file_mode",
+            "propagate",
+            "max_bytes",
+            "backup_count",
+        }
+        logger_kwargs = {k: v for k, v in kwargs.items() if k in logger_param_names}
+
+        # Set up the logger
+        self.logger = get_logger(self.unique_name, **logger_kwargs)
+
+    @property
+    def unique_name(self) -> str:
+        return self.__module__ + "." + type(self).__name__
+
+    @property
+    def name(self) -> str:
+        return type(self).__name__
+
+    def __enter__(self):
+        self.logger.debug(f"Initializing {self.name} as a context manager.")
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.logger.debug(f"Exiting context manager for {self.name}.")
+        if exc_type is not None:
+            info = (exc_type, exc_val, exc_tb)
+            self.logger.exception("Exception occurred", exc_info=info)
+            return self.suppress
+        return False
+
+    @classmethod
+    def autolog(
+        cls,
+        log_level=logging.DEBUG,
+        prefix_formatter: Optional[Callable] = None,
+        suffix_formatter: Optional[Callable] = None,
+        exception_formatter: Optional[Callable] = None,
+        self: Optional["Mindtrace"] = None,
+    ):
+        """Decorator that adds logger.log calls to the decorated method before and after the method is called.
+
+        By default, the autolog decorator will log the method name, arguments and keyword arguments before the method
+        is called, and the method name and result after the method completes. This behavior can be modified by passing
+        in prefix and suffix formatters.
+
+        The autolog decorator will also catch and log all Exceptions, re-raising any exception after logging it. The
+        behavior for autologging exceptions can be modified by passing in an exception_formatter.
+
+        The autolog decorator expects a logger to exist at self.logger, and hence can only be used by Mindtrace
+        subclasses or classes that have a logger attribute.
+
+        Args:
+            log_level: The log_level passed to logger.log().
+            prefix_formatter: The formatter used to log the command before the wrapped method runs. The prefix_formatter
+                will be given (and must accept) three arguments, in the following order:
+                - function: The function being wrapped.
+                - args: The args passed into the function.
+                - kwargs: The kwargs passed into the function.
+            suffix_formatter: The formatter used to log the command after the wrapped method runs. The suffix_formatter
+                will be given (and must accept) two arguments, in the following order:
+                - function: The function being wrapped.
+                - result: The result returned from the wrapped method.
+            exception_formatter: The formatter used to log any errors. The exception_formatter will be given (and must
+                accept) three arguments, in the following order:
+                - function: The function being wrapped.
+                - error: The caught Exception.
+                - stack trace: The stack trace, as provided by traceback.format_exc().
+            self: The instance of the class that the method is being called on. Self only needs to be passed in if the
+                wrapped method does not have self as the first argument. Refer to the example below for more details.
+
+        Example::
+
+            from mindtrace.core import Mindtrace
+
+            class MyClass(Mindtrace):
+                def __init__(self):
+                    super().__init__()
+
+                @Mindtrace.autolog()
+                def divide(self, arg1, arg2):
+                    self.logger.info("We are about to divide")
+                    result = arg1 / arg2
+                    self.logger.info("We have divided")
+                    return result
+
+            my_instance = MyClass()
+            my_instance.divide(1, 2)
+            my_instance.divide(1, 0)
+
+        The resulting log file should contain something similar to the following:
+
+        .. code-block:: text
+
+            MyClass - DEBUG - Calling divide with args: (1, 2) and kwargs: {}
+            MyClass - INFO - We are about to divide
+            MyClass - INFO - We have divided
+            MyClass - DEBUG - Finished divide with result: 0.5
+            MyClass - DEBUG - Calling divide with args: (1, 0) and kwargs: {}
+            MyClass - INFO - We are about to divide
+            MyClass - ERROR - division by zero
+            Traceback (most recent call last):
+            ...
+
+        If the wrapped method does not have self as the first argument, self must be passed in as an argument to the
+        autolog decorator.
+
+        .. code-block:: python
+
+            from fastapi import FastAPI
+            from mindtrace.core import Mindtrace
+
+            class MyClass(Mindtrace):
+                def __init__():
+                    super().__init__()
+
+                def create_app(self):
+                    app_ = FastAPI()
+
+                    @Mindtrace.autolog(self=self)  # self must be passed in as an argument as it is not captured in status()
+                    @app_.post("/status")
+                    def status():
+                        return {"status": "Available"}
+
+                    return app_
+
+        """
+        prefix_formatter = ifnone(
+            prefix_formatter,
+            default=lambda function,
+            args,
+            kwargs: f"Calling {function.__name__} with args: {args} and kwargs: {kwargs}",
+        )
+        suffix_formatter = ifnone(
+            suffix_formatter, default=lambda function, result: f"Finished {function.__name__} with result: {result}"
+        )
+        exception_formatter = ifnone(
+            exception_formatter,
+            default=lambda function,
+            e,
+            stack_trace: f"{function.__name__} failed to complete with the following error: {e}\n{stack_trace}",
+        )
+
+        def decorator(function):
+            is_async = inspect.iscoroutinefunction(function)
+
+            if self is None:
+                if is_async:
+
+                    @wraps(function)
+                    async def wrapper(self, *args, **kwargs):
+                        self.logger.log(log_level, prefix_formatter(function, args, kwargs))
+                        try:
+                            result = await function(self, *args, **kwargs)
+                        except Exception as e:
+                            self.logger.error(exception_formatter(function, e, traceback.format_exc()))
+                            raise
+                        else:
+                            self.logger.log(log_level, suffix_formatter(function, result))
+                            return result
+                else:
+
+                    @wraps(function)
+                    def wrapper(self, *args, **kwargs):
+                        self.logger.log(log_level, prefix_formatter(function, args, kwargs))
+                        try:
+                            result = function(self, *args, **kwargs)
+                        except Exception as e:
+                            self.logger.error(exception_formatter(function, e, traceback.format_exc()))
+                            raise
+                        else:
+                            self.logger.log(log_level, suffix_formatter(function, result))
+                            return result
+
+            else:
+                if is_async:
+
+                    @wraps(function)
+                    async def wrapper(*args, **kwargs):
+                        self.logger.log(log_level, prefix_formatter(function, args, kwargs))
+                        try:
+                            result = await function(*args, **kwargs)
+                        except Exception as e:
+                            self.logger.error(exception_formatter(function, e, traceback.format_exc()))
+                            raise
+                        else:
+                            self.logger.log(log_level, suffix_formatter(function, result))
+                            return result
+                else:
+
+                    @wraps(function)
+                    def wrapper(*args, **kwargs):
+                        self.logger.log(log_level, prefix_formatter(function, args, kwargs))
+                        try:
+                            result = function(*args, **kwargs)
+                        except Exception as e:
+                            self.logger.error(exception_formatter(function, e, traceback.format_exc()))
+                            raise
+                        else:
+                            self.logger.log(log_level, suffix_formatter(function, result))
+                            return result
+
+            return wrapper
+
+        return decorator
+
+
+class MindtraceABCMeta(MindtraceMeta, ABCMeta):
+    """Metaclass that combines MindtraceMeta and ABC metaclasses.
+
+    This metaclass resolves metaclass conflicts when creating classes that need to be both
+    abstract (using ABC) and have MindtraceMeta functionality. Python only allows a class to
+    have one metaclass, so this combined metaclass allows classes to inherit from both
+    Mindtrace class and ABC simultaneously.
+
+    Without this combined metaclass, trying to create a class that inherits from both Mindtrace class
+    and ABC would raise a metaclass conflict error since they each have different metaclasses.
+    """
+
+    pass
+
+
+class MindtraceABC(Mindtrace, ABC, metaclass=MindtraceABCMeta):
+    """Abstract base class combining Mindtrace class functionality with ABC support.
+
+    This class enables creating abstract classes that also have access to all Mindtrace features
+    such as logging, configuration, and context management. Use this class instead of
+    Mindtrace when you need to define abstract methods or properties in your class.
+
+    Example:
+        from mindtrace.core import MindtraceABC
+        from abc import abstractmethod
+
+        class MyAbstractService(MindtraceABC):
+            def __init__(self):
+                super().__init__()
+
+            @abstractmethod
+            def process_data(self, data):
+                '''Must be implemented by concrete subclasses.'''
+                pass
+
+    Note:
+        Without this class, attempting to create a class that inherits from both Mindtrace class and ABC
+        would fail due to metaclass conflicts. MindtraceABC resolves this by using the CombinedABCMeta.
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)

mindtrace/core/mindtrace/core/config/__init__.py

@@ -0,0 +1,3 @@
+from mindtrace.core.config.config import Config
+
+__all__ = ["Config"]

mindtrace/core/mindtrace/core/config/config.py

@@ -0,0 +1,27 @@
+import os
+
+
+class Config(dict):
+    """Template Config class."""
+
+    def __init__(self, **kwargs):
+        default_config = {
+            "MINDTRACE_TEMP_DIR": "~/.cache/mindtrace/temp",
+            "MINDTRACE_DEFAULT_REGISTRY_DIR": "~/.cache/mindtrace/registry",
+            "MINDTRACE_DEFAULT_HOST_URLS": {
+                "Service": "http://localhost:8000",
+            },
+            "MINDTRACE_MINIO_REGISTRY_URI": "~/.cache/mindtrace/minio-registry",
+            "MINDTRACE_MINIO_ENDPOINT": "localhost:9000",
+            "MINDTRACE_MINIO_ACCESS_KEY": "minioadmin",
+            "MINDTRACE_MINIO_SECRET_KEY": "minioadmin",
+            "MINDTRACE_SERVER_PIDS_DIR_PATH": "~/.cache/mindtrace/pids",
+            "MINDTRACE_LOGGER_DIR": "~/.cache/mindtrace/logs",
+        }
+        # Update defaults with any provided kwargs
+        default_config.update(kwargs)
+        # Expand ~ only if it is at the start of the string
+        for k, v in default_config.items():
+            if isinstance(v, str) and v.startswith("~/"):
+                default_config[k] = os.path.expanduser(v)
+        super().__init__(default_config)

mindtrace/core/mindtrace/core/logging/__init__.py

@@ -0,0 +1,3 @@
+from mindtrace.core.logging.logger import Logger
+
+__all__ = ["Logger"]

mindtrace/core/mindtrace/core/logging/logger.py

@@ -0,0 +1,112 @@
+import logging
+import os
+from logging import Logger
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+from typing import Optional
+
+from mindtrace.core.config import Config
+
+
+def default_formatter(fmt: Optional[str] = None) -> logging.Formatter:
+    """
+    Returns a logging formatter with a default format if none is specified.
+    """
+    default_fmt = "[%(asctime)s] %(levelname)s: %(name)s: %(message)s"
+    return logging.Formatter(fmt or default_fmt)
+
+
+def setup_logger(
+    name: str = "mindtrace",
+    log_dir: Optional[Path] = None,
+    logger_level: int = logging.DEBUG,
+    stream_level: int = logging.ERROR,
+    file_level: int = logging.DEBUG,
+    file_mode: str = "a",
+    propagate: bool = False,
+    max_bytes: int = 10 * 1024 * 1024,  # 10 MB
+    backup_count: int = 5,
+) -> Logger:
+    """Configure and initialize logging for Mindtrace components programmatically.
+
+    Sets up a rotating file handler and a console handler on the given logger.
+    Log file defaults to ~/.cache/mindtrace/{name}.log.
+
+    Args:
+        name (str): Logger name, defaults to "mindtrace".
+        log_dir (Optional[Path]): Custom directory for log file.
+        logger_level (int): Overall logger level.
+        stream_level (int): StreamHandler level (e.g., ERROR).
+        file_level (int): FileHandler level (e.g., DEBUG).
+        file_mode (str): Mode for file handler, default is 'a' (append).
+        propagate (bool): Whether the logger should propagate messages to ancestor loggers.
+        max_bytes (int): Maximum size in bytes before rotating log file.
+        backup_count (int): Number of backup files to retain.
+
+    Returns:
+        Logger: Configured logger instance.
+    """
+    logger = logging.getLogger(name)
+    logger.handlers.clear()
+    logger.setLevel(logger_level)
+    logger.propagate = propagate
+
+    # Set up stream handler
+    stream_handler = logging.StreamHandler()
+    stream_handler.setLevel(stream_level)
+    stream_handler.setFormatter(default_formatter())
+    logger.addHandler(stream_handler)
+
+    # Set up file handler
+    default_config = Config()
+    if name == "mindtrace":
+        child_log_path = f"{name}.log"
+    else:
+        child_log_path = os.path.join("modules", f"{name}.log")
+
+    if log_dir:
+        log_file_path = os.path.join(log_dir, child_log_path)
+    else:
+        log_file_path = os.path.join(default_config["MINDTRACE_LOGGER_DIR"], child_log_path)
+
+    os.makedirs(Path(log_file_path).parent, exist_ok=True)
+    file_handler = RotatingFileHandler(
+        filename=str(log_file_path), maxBytes=max_bytes, backupCount=backup_count, mode=file_mode
+    )
+    file_handler.setLevel(file_level)
+    file_handler.setFormatter(default_formatter())
+    logger.addHandler(file_handler)
+
+    return logger
+
+
+def get_logger(name: str = "mindtrace", **kwargs) -> logging.Logger:
+    """
+    Create or retrieve a named logger instance.
+
+    This function wraps Python's built-in ``logging.getLogger()`` to provide a
+    standardized logger for Mindtrace components. If the logger with the given
+    name already exists, it returns the existing instance; otherwise, it creates
+    a new one with optional configuration overrides.
+
+    Args:
+        name (str): The name of the logger. Defaults to "mindtrace".
+        **kwargs: Additional keyword arguments to be passed to `setup_logger`.
+
+    Returns:
+        logging.Logger: A configured logger instance.
+
+    Example:
+        .. code-block:: python
+
+            from mindtrace.core.logging.logger import get_logger
+
+            logger = get_logger("core.module", stream_level=logging.INFO, propagate=True)
+            logger.info("Logger configured with custom settings.")
+    """
+    if not name:
+        name = "mindtrace"
+
+    full_name = name if name.startswith("mindtrace") else f"mindtrace.{name}"
+    kwargs.setdefault("propagate", True)
+    return setup_logger(full_name, **kwargs)

mindtrace/core/mindtrace/core/observables/context_listener.py

@@ -0,0 +1,73 @@
+import logging
+from typing import Any
+
+from mindtrace.core import Mindtrace
+
+
+class ContextListener(Mindtrace):
+    """A context listener that can subscribe to a ObservableContext.
+
+    The ContextListener class provides two main benefits:
+
+    1. Deriving from Mindtrace, it provides for uniform logging of events.
+
+    Example::
+
+        from mindtrace.core import ContextListener, Logger
+
+        class MyListener(ContextListener):
+            def x_changed(self, source, old, new):
+                self.logger.info(f"x changed: {old} → {new}")  # Uses Mindtrace logging by default
+
+        my_listener = MyListener(logger=Logger("MyListener"))  # May pass in a custom logger
+
+
+    2. The default ContextListener can be used to automatically log changes to variables.
+
+    Example::
+
+        from mindtrace.core import ContextListener, ObservableContext
+
+        @ObservableContext(vars={"x": int, "y": int})
+        class MyContext:
+            def __init__(self):
+                self.x = 0
+                self.y = 0
+
+        my_context = MyContext()
+        my_context.subscribe(ContextListener(autolog=["x", "y"]))
+
+        my_context.x = 1
+        my_context.y = 2
+
+        # Logs:
+        # [MyContext] x changed: 0 → 1
+        # [MyContext] y changed: 0 → 2
+    """
+
+    def __init__(self, autolog: list[str] = None, log_level: int = logging.ERROR, logger: Any = None, **kwargs):
+        """Initialize the context listener.
+
+        Args:
+            autolog: A list of variables to log automatically.
+            log_level: The log level to use for the logger.
+        """
+        super().__init__(**kwargs)
+
+        if logger is not None:
+            self.logger = logger
+
+        if autolog is not None:
+            for var in autolog:
+                method_name = f"{var}_changed"
+
+                # Only attach if the child class hasn't already defined it
+                if not hasattr(self, method_name):
+                    # Use a factory to capture var correctly in loop
+                    setattr(self, method_name, self._make_auto_logger(var, log_level))
+
+    def _make_auto_logger(self, varname: str, log_level: int):
+        def _logger(source: str, old: Any, new: Any):
+            self.logger.log(log_level, f"[{source}] {varname} changed: {old} → {new}")
+
+        return _logger