processes 1.0.2__py3-none-any.whl

processes/__init__.py

@@ -0,0 +1,24 @@
+from importlib.metadata import PackageNotFoundError as _pnfe
+from importlib.metadata import version as _v
+
+from .html_logging import HTMLSMTPHandler as HTMLSMTPHandler
+from .process import (
+    CircularDependencyError as CircularDependencyError,
+)
+from .process import (
+    DependencyNotFoundError as DependencyNotFoundError,
+)
+from .process import (
+    Process as Process,
+)
+from .process import (
+    TaskNotFoundError as TaskNotFoundError,
+)
+from .task import Task as Task
+from .task import TaskDependency as TaskDependency
+from .task import TaskResult as TaskResult
+
+try:
+    __version__ = _v("processes")
+except _pnfe:
+    __version__ = "0.0.0-unknown"

processes/html_logging.py

@@ -0,0 +1,201 @@
+import logging
+import logging.handlers
+import smtplib
+import ssl
+import traceback
+from email.mime.text import MIMEText
+from email.utils import formatdate
+
+
+class HTMLSMTPHandler(logging.handlers.SMTPHandler):
+    """
+    A logging handler that sends log records via SMTP as HTML formatted emails.
+
+    Extends the standard SMTPHandler to support HTML-formatted email messages,
+    enabling richer formatting and styling in error notifications.
+
+    Attributes
+    ----------
+    mailhost : tuple[str, int]
+        A tuple of (host, port) for the SMTP server.
+    fromaddr : str
+        The email address to send messages from.
+    toaddrs : list[str]
+        List of email addresses to send messages to.
+    credentials : tuple[str, str] | None
+        A tuple of (username, password) for SMTP authentication. Defaults to None.
+    secure : tuple | tuple[str, str] | tuple[str, str, ssl.SSLContext] | None
+        Security configuration for SMTP connection. Can be an empty tuple for no security,
+        a tuple of (certfile, keyfile), or (certfile, keyfile, SSLContext).
+        Defaults to None.
+    timeout : int
+        Connection timeout in seconds. Defaults to 5.
+    """
+
+    def __init__(
+        self,
+        mailhost: tuple[str, int],
+        fromaddr: str,
+        toaddrs: list[str],
+        credentials: tuple[str, str] | None = None,
+        secure: tuple[()]
+        | tuple[str]
+        | tuple[str, str]
+        | tuple[str, str, ssl.SSLContext]
+        | None = None,
+        timeout: int = 5,
+    ):
+        self._crd = credentials
+        self._sec = secure
+        self._to = timeout
+
+        super().__init__(
+            mailhost,
+            fromaddr,
+            toaddrs,
+            "",
+            credentials=credentials,
+            secure=secure,  # type: ignore[arg-type]
+            timeout=timeout,
+        )
+
+    def copy(self) -> "HTMLSMTPHandler":
+        """Create a shallow copy of this handler.
+
+        Returns
+        -------
+        HTMLSMTPHandler
+            A new HTMLSMTPHandler instance with the same configuration.
+        """
+        return HTMLSMTPHandler(
+            self.mailhost,  # type: ignore[arg-type]
+            self.fromaddr,
+            self.toaddrs,
+            credentials=self._crd,
+            secure=self._sec,
+            timeout=self._to,
+        )
+
+    def __copy__(self) -> "HTMLSMTPHandler":
+        """Support for copy.copy() method.
+
+        Returns
+        -------
+        HTMLSMTPHandler
+            A shallow copy of this handler.
+        """
+        return self.copy()
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Send a log record via email as HTML formatted message.
+
+        Formats the log record using the handler's formatter and sends it
+        as an HTML-formatted email. Errors during sending are handled gracefully.
+
+        Parameters
+        ----------
+        record : logging.LogRecord
+            The log record to send.
+        """
+        try:
+            port = self.mailport
+            if not port:
+                port = smtplib.SMTP_PORT
+            smtp = smtplib.SMTP(self.mailhost, port)
+            msg = self.format(record)
+
+            # Create MIMEText object with HTML content
+            mime_msg = MIMEText(msg, "html")
+            mime_msg["From"] = self.fromaddr
+            mime_msg["To"] = ",".join(self.toaddrs)
+            mime_msg["Subject"] = self.getSubject(record)
+            mime_msg["Date"] = formatdate()
+
+            if self.username:
+                if self.secure is not None:
+                    smtp.starttls(*self.secure)
+                smtp.login(self.username, self.password)
+            smtp.sendmail(self.fromaddr, self.toaddrs, mime_msg.as_string())
+            smtp.quit()
+        except Exception:
+            self.handleError(record)
+
+
+class ExceptionHTMLFormatter(logging.Formatter):
+    """
+    A logging formatter that converts exception records to HTML format.
+
+    Formats exception tracebacks with syntax-highlighted HTML styling and
+    supports custom post-traceback content. Provides visually appealing
+    exception reports suitable for email delivery.
+    """
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Format a log record as HTML, with special handling for exceptions.
+
+        Extracts exception information and traceback, formats them with HTML
+        styling, and includes any additional post-traceback content from the
+        log record's `post_traceback_html_body` attribute.
+
+        Parameters
+        ----------
+        record : logging.LogRecord
+            The log record to format.
+
+        Returns
+        -------
+        str
+            HTML-formatted string containing exception details, traceback,
+            and styling.
+        """
+        # Format the exception details and traceback
+        if record.exc_info:
+            exception_object = record.exc_info[1]
+            exception = str(exception_object)
+            tb_str = traceback.format_exc()
+        else:
+            exception = record.getMessage()
+            tb_str = "No traceback available"
+
+        post_traceback_html_body = getattr(record, "post_traceback_html_body", "")
+
+        # HTML content
+        tb_str = tb_str.replace("\n", "<br>")
+        body = f"""
+        <html>
+        <head>
+            <style>
+                body {{
+                    font-family: Arial, sans-serif;
+                    margin: 20px;
+                    color: #333;
+                }}
+                h2 {{
+                    color: #d9534f;
+                }}
+                .exception {{
+                    font-weight: bold;
+                    color: #d9534f;
+                }}
+                .traceback {{
+                    background-color: #f9f2f4;
+                    border: 1px solid #d9534f;
+                    padding: 10px;
+                    font-family: 'Courier New', Courier, monospace;
+                    white-space: pre-wrap;
+                    color: #333;
+                    border-radius: 4px;
+                }}
+            </style>
+        </head>
+        <body>
+            <h2>Exception Details</h2>
+            <p class="exception">Exception: {exception}</p>
+            <p><strong>Traceback:</strong></p>
+            <div class="traceback">{tb_str}</div>
+            <br>
+            {post_traceback_html_body}
+        </body>
+        </html>
+        """
+        return body

processes/process.py

@@ -0,0 +1,417 @@
+import concurrent.futures
+from types import TracebackType
+from typing import Literal, Self
+
+from .task import Task, TaskResult
+
+
+class DependencyNotFoundError(Exception):
+    """Raised when a task depends on a non-existent task."""
+
+    pass
+
+
+class TaskNotFoundError(Exception):
+    """Raised when attempting to retrieve a task that does not exist in the process."""
+
+    pass
+
+
+class CircularDependencyError(Exception):
+    """Raised when circular dependencies are detected among tasks."""
+
+    pass
+
+
+class ProcessResult:
+    """
+    Container for the results of a process execution.
+
+    Holds the outcomes of all tasks executed in a process, separating successful
+    and failed tasks with their respective results.
+
+    Attributes
+    ----------
+    passed_tasks_results : dict[str, TaskResult]
+        Mapping of task names to TaskResult objects for all tasks that executed successfully.
+    failed_tasks : set[str]
+        Set of task names for all tasks that failed during execution.
+    """
+
+    def __init__(self, passed_tasks_results: dict[str, TaskResult], failed_tasks: set[str]):
+        self.passed_tasks_results = passed_tasks_results
+        self.failed_tasks = failed_tasks
+
+
+class Process:
+    """
+    Manages and executes a collection of interdependent tasks.
+
+    A Process orchestrates the execution of multiple tasks, handling dependency
+    resolution, task ordering. Task execution can be performed in parallel or sequentially. It
+    provides logging management and error propagation for dependent tasks. If a task fails,
+    all tasks depending on it are marked as failed without execution, but non-dependent tasks
+    continue to run.
+
+    Attributes
+    ----------
+    tasks : list[Task]
+        List of tasks to be executed, automatically sorted by dependencies.
+    runner : ProcessRunner
+        The runner responsible for executing the tasks.
+
+    Raises
+    ------
+    TypeError
+        If tasks is not a list or contains non-Task elements.
+    ValueError
+        If duplicate task names are found.
+    DependencyNotFoundError
+        If a task depends on a non-existent task.
+    CircularDependencyError
+        If circular dependencies are detected among tasks.
+    """
+
+    def __init__(self, tasks: list[Task]):
+        self.tasks = tasks
+
+        try:
+            self._check_input_types()
+            self._check_duplicate_names()
+            self._check_dependencies_exist()
+            self._topological_sort()
+        except Exception as e:
+            self.close_loggers()
+            raise e
+        self.runner = ProcessRunner(self)
+
+    def __enter__(self) -> Self:
+        """Called when entering the 'with' block."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> Literal[False]:
+        """Called when exiting the 'with' block, even if an error occurred."""
+        self.close_loggers()
+        return False
+
+    def _check_input_types(self) -> None:
+        """Validate that tasks is a list containing only Task objects.
+
+        Raises
+        ------
+        TypeError
+            If tasks is not a list or contains non-Task elements.
+        """
+        if not isinstance(self.tasks, list):
+            raise TypeError(f"tasks must be list. Got {type(self.tasks)}")
+        for task in self.tasks:
+            if not isinstance(task, Task):
+                raise TypeError(f"task must be Task. Got {type(task)}")
+
+    def _check_duplicate_names(self) -> None:
+        """Verify that all task names are unique.
+
+        Raises
+        ------
+        ValueError
+            If duplicate task names are found.
+        """
+        names = set()
+        for task in self.tasks:
+            if task.name in names:
+                raise ValueError(f"Duplicate task name: {task.name}")
+            names.add(task.name)
+
+    def _check_dependencies_exist(self) -> None:
+        """Verify that all task dependencies refer to existing tasks.
+
+        Raises
+        ------
+        DependencyNotFoundError
+            If a task depends on a non-existent task.
+        """
+        names = {t.name for t in self.tasks}
+        for task in self.tasks:
+            for dep in task.get_dependencies_names():
+                if dep not in names:
+                    raise DependencyNotFoundError(
+                        f"Task {task.name} depends on missing task: {dep}"
+                    )
+
+    def _topological_sort(self) -> None:
+        """Sort tasks based on dependencies using Kahn's Algorithm in O(V+E) time.
+
+        Reorders the task list so that dependencies are always executed before
+        tasks that depend on them.
+
+        Raises
+        ------
+        CircularDependencyError
+            If circular dependencies are detected among tasks.
+        """
+        in_degree = {t.name: 0 for t in self.tasks}
+        graph: dict[str, list[str]] = {t.name: [] for t in self.tasks}
+        task_map = {t.name: t for t in self.tasks}
+
+        for task in self.tasks:
+            for dep in task.dependencies:
+                graph[dep.task_name].append(task.name)
+                in_degree[task.name] += 1
+
+        queue = [name for name, deg in in_degree.items() if deg == 0]
+        sorted_tasks = []
+
+        while queue:
+            u = queue.pop(0)
+            sorted_tasks.append(task_map[u])
+            for v in graph[u]:
+                in_degree[v] -= 1
+                if in_degree[v] == 0:
+                    queue.append(v)
+
+        if len(sorted_tasks) != len(self.tasks):
+            raise CircularDependencyError("Circular dependency detected.")
+        self.tasks = sorted_tasks
+
+    def get_task(self, task_name: str) -> Task:
+        """Retrieve a task by name.
+
+        Parameters
+        ----------
+        task_name : str
+            The name of the task to retrieve.
+
+        Returns
+        -------
+        Task
+            The task with the specified name.
+
+        Raises
+        ------
+        TaskNotFoundError
+            If no task with the given name exists.
+        """
+        for task in self.tasks:
+            if task.name == task_name:
+                return task
+        raise TaskNotFoundError(f"Task not found: {task_name}")
+
+    def run(self, parallel: bool | None = None, max_workers: int = 4) -> ProcessResult:
+        """Execute all tasks in the process.
+
+        Runs tasks sequentially or in parallel while respecting dependencies.
+        Dependencies are always resolved before dependent tasks are executed.
+
+        Parameters
+        ----------
+        parallel : bool, optional
+            Whether to run tasks in parallel while respecting dependencies.
+            If None, automatically set to True for processes with 10 or more tasks,
+            False otherwise. Defaults to None.
+        max_workers : int, optional
+            Maximum number of worker threads for parallel execution. Defaults to 4.
+            Only used when parallel=True. If set to 1, falls back to sequential execution.
+
+        Returns
+        -------
+        ProcessResult
+            Contains passed_tasks_results (dict mapping task names to TaskResult)
+            and failed_tasks (set of task names that failed).
+        """
+        if parallel is None:
+            parallel = len(self.tasks) >= 10
+
+        max_workers = max(1, max_workers)
+        if parallel:
+            if max_workers == 1:
+                parallel = False  # Fallback to sequential if only one worker
+        process_result = self.runner.run(parallel, max_workers)
+        return process_result
+
+    def get_dependant_tasks(self, task_name: str) -> list[Task]:
+        """Retrieve all tasks that directly or indirectly depend on a given task.
+
+        Parameters
+        ----------
+        task_name : str
+            The name of the task to find dependants for.
+
+        Returns
+        -------
+        list[Task]
+            List of all tasks that depend on the specified task, including
+            transitive dependencies (tasks that depend on tasks that depend
+            on the specified task).
+        """
+        found = []
+
+        def find(name: str) -> None:
+            for t in self.tasks:
+                if name in t.get_dependencies_names() and t not in found:
+                    found.append(t)
+                    find(t.name)
+
+        find(task_name)
+        return found
+
+    def close_loggers(self) -> None:
+        """Close and clean up all logger handlers for all tasks.
+
+        Should be called when the process is done to ensure proper resource cleanup.
+        """
+        for task in self.tasks:
+            for handler in task.logger.handlers:
+                handler.close()
+                task.logger.removeHandler(handler)
+
+
+class ProcessRunner:
+    """
+    Executes tasks in a Process, handling both sequential and parallel execution.
+
+    Manages task execution state, tracks passed and failed tasks, and coordinates
+    dependencies during execution.
+
+    Attributes
+    ----------
+    process : Process
+        Reference to the parent Process being executed.
+    passed_results : dict[str, TaskResult]
+        Results from successfully executed tasks.
+    failed_tasks : set[str]
+        Names of tasks that failed during execution.
+    submitted_tasks : set[str]
+        Names of tasks that have been submitted for execution.
+    """
+
+    def __init__(self, process_ref: Process):
+        self.process = process_ref
+        self.passed_results: dict[str, TaskResult] = {}
+        self.failed_tasks: set[str] = set()
+        self.submitted_tasks: set[str] = set()
+
+    def run(self, parallel: bool, max_workers: int) -> ProcessResult:
+        """Execute all tasks in the process using the specified execution mode.
+
+        Parameters
+        ----------
+        parallel : bool
+            If True, execute tasks in parallel; otherwise execute sequentially.
+        max_workers : int
+            Maximum number of worker threads for parallel execution.
+
+        Returns
+        -------
+        ProcessResult
+            The combined results of all task executions.
+        """
+        if parallel:
+            self._run_parallel(max_workers)
+        else:
+            self._run_sequential()
+        return ProcessResult(self.passed_results, self.failed_tasks)
+
+    def _is_unrunnable(self, task: Task) -> bool:
+        """Check if a task cannot be run due to failed dependencies.
+
+        Parameters
+        ----------
+        task : Task
+            The task to check.
+
+        Returns
+        -------
+        bool
+            True if any of the task's dependencies have failed, False otherwise.
+            If True, the task is also marked as failed.
+        """
+        if any(d.task_name in self.failed_tasks for d in task.dependencies):
+            self.failed_tasks.add(task.name)  # Propagate failure
+            return True
+        return False
+
+    def _all_deps_met(self, task: Task) -> bool:
+        """Check if all dependencies of a task have been successfully executed.
+
+        Parameters
+        ----------
+        task : Task
+            The task to check.
+
+        Returns
+        -------
+        bool
+            True if all dependencies have passed, False otherwise.
+        """
+        return all(d.task_name in self.passed_results for d in task.dependencies)
+
+    def _run_sequential(self) -> None:
+        """Execute all tasks sequentially in dependency order."""
+        for task in self.process.tasks:
+            if self._is_unrunnable(task):
+                continue
+            if self._all_deps_met(task):
+                res = task.run(self.process)
+                if res.worked:
+                    self.passed_results[task.name] = res
+                else:
+                    self.failed_tasks.add(task.name)
+
+    def _run_parallel(self, max_workers: int) -> None:
+        """Execute tasks in parallel using a thread pool while respecting dependencies.
+
+        Parameters
+        ----------
+        max_workers : int
+            Maximum number of worker threads to use.
+
+        Raises
+        ------
+        RuntimeError
+            If execution stalls with no candidates ready and no tasks running.
+        """
+        with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
+            fut_to_name = {}
+            while len(self.passed_results) + len(self.failed_tasks) < len(self.process.tasks):
+                # Look for candidates to execute now
+                candidates = [
+                    t
+                    for t in self.process.tasks
+                    if t.name not in self.submitted_tasks
+                    and t.name not in self.failed_tasks
+                    and not self._is_unrunnable(t)
+                    and self._all_deps_met(t)
+                ]
+
+                # Send tasks for execution and register as Task as submitted
+                for task in candidates:
+                    fut = executor.submit(task.run, self.process)
+                    fut_to_name[fut] = task.name
+                    self.submitted_tasks.add(task.name)
+
+                # If there are tasks pending, wait. As soon one is completed,
+                # save as passed or failed and remove from futures.
+                if fut_to_name:
+                    done, _ = concurrent.futures.wait(
+                        fut_to_name.keys(), return_when="FIRST_COMPLETED"
+                    )
+                    for fut in done:
+                        name = fut_to_name.pop(fut)
+                        try:
+                            res = fut.result()
+                            if res.worked:
+                                self.passed_results[name] = res
+                            else:
+                                self.failed_tasks.add(name)
+                        except Exception:
+                            self.failed_tasks.add(name)
+                else:
+                    # No candidates and no running tasks - likely a deadlock or logic error
+                    raise RuntimeError(
+                        "Parallel execution stalled: no candidates found and no tasks running"
+                    )

processes/task.py

@@ -0,0 +1,302 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .process import Process
+
+import logging
+
+from .html_logging import ExceptionHTMLFormatter, HTMLSMTPHandler
+
+
+class TaskResult:
+    """
+    Container for the result of a task execution.
+
+    Holds the outcome of running a task, including whether it succeeded,
+    its return value, and any exception that occurred.
+
+    Attributes
+    ----------
+    worked : bool
+        True if the task executed successfully, False if an exception occurred.
+    result : Any
+        The return value of the task's function if execution succeeded, None if failed.
+    exception : Exception | None
+        The exception object if execution failed, None if successful.
+    """
+
+    def __init__(self, worked: bool, result: Any, exception: Exception | None):
+        self.worked = worked
+        self.result = result
+        self.exception = exception
+
+
+class TaskDependency:
+    """
+    Represents a dependency relationship between tasks.
+
+    Defines how a task depends on another task, including how the result
+    of the dependency should be passed to the dependent task (as additional
+    positional arguments, keyword arguments, or both).
+
+    Attributes
+    ----------
+    task_name : str
+        The name of the task this dependency refers to.
+    use_result_as_additional_args : bool
+        If True, the result of the dependency task will be passed as an
+        additional positional argument as the last argument. Defaults to False.
+    use_result_as_additional_kwargs : bool
+        If True, the result of the dependency task will be passed as a
+        keyword argument. Defaults to False.
+    additional_kwarg_name : str | None
+        The name of the keyword argument to use if use_result_as_additional_kwargs
+        is True. Required when use_result_as_additional_kwargs is True.
+        Defaults to None.
+
+    Raises
+    ------
+    TypeError
+        If any parameter type is invalid or if use_result_as_additional_kwargs
+        is True but additional_kwarg_name is not a string.
+    """
+
+    def __init__(
+        self,
+        task_name: str,
+        use_result_as_additional_args: bool = False,
+        use_result_as_additional_kwargs: bool = False,
+        additional_kwarg_name: str = "",
+    ):
+        self.task_name = task_name
+        self.use_result_as_additional_args = use_result_as_additional_args
+        self.use_result_as_additional_kwargs = use_result_as_additional_kwargs
+        self.additional_kwarg_name = additional_kwarg_name
+
+        if not isinstance(self.task_name, str):
+            raise TypeError(f"task_name must be of type str. Got {type(self.task_name)}")
+        if not isinstance(self.use_result_as_additional_args, bool):
+            raise TypeError(
+                f"use_result_as_additional_args must be of type bool. "
+                f"Got {type(self.use_result_as_additional_args)}"
+            )
+        if not isinstance(self.use_result_as_additional_kwargs, bool):
+            raise TypeError(
+                f"use_result_as_additional_kwargs must be of type bool. "
+                f"Got {type(self.use_result_as_additional_kwargs)}"
+            )
+
+        if self.use_result_as_additional_kwargs and self.additional_kwarg_name == "":
+            raise TypeError(
+                "If use_result_as_additional_kwargs is True, additional_kwarg_name"
+                " must be a non-empty string."
+            )
+
+    def __hash__(self) -> int:
+        """
+        Return hash of the dependency based on task name.
+
+        Returns
+        -------
+        int
+            Hash value based on the task_name attribute.
+        """
+        return hash(self.task_name)
+
+
+class Task:
+    """
+    A Task represents a unit of work to be executed within a Process.
+
+    A Task encapsulates a callable function with its arguments, dependencies on other tasks,
+    and logging configuration. Tasks can be executed, by the Process class, sequentially
+    or in parallel, with automatic dependency resolution and result passing between dependent tasks.
+
+    Attributes
+    ----------
+    name : str
+        Unique name for the task (cannot contain spaces).
+    log_path : str
+        File path where task logs will be written.
+    func : Callable
+        The function to execute when the task runs.
+    args : tuple
+        Positional arguments to pass to the function. Defaults to empty tuple.
+    kwargs : dict
+        Keyword arguments to pass to the function. Defaults to empty dict.
+    dependencies : list[TaskDependency]
+        List of tasks this task depends on. Defaults to empty list.
+    html_mail_handler : HTMLSMTPHandler, optional
+        Handler for sending error logs via email in HTML format. Defaults to None.
+    logger : logging.Logger
+        Logger instance for this task, automatically configured.
+    """
+
+    kwargs: dict[str, Any]
+    dependencies: list[TaskDependency]
+
+    def __init__(
+        self,
+        name: str,
+        log_path: str,
+        func: Callable[..., Any],
+        args: tuple[Any, ...] = (),
+        kwargs: dict[str, Any] | None = None,
+        dependencies: list[TaskDependency] | None = None,
+        html_mail_handler: HTMLSMTPHandler | None = None,
+    ):
+        self.name = name
+        self.log_path = log_path
+        self.func = func
+        self.args = args
+        self.html_mail_handler = html_mail_handler
+
+        if kwargs is None:
+            self.kwargs = {}
+        else:
+            self.kwargs = kwargs
+        if dependencies is None:
+            self.dependencies = []
+        else:
+            self.dependencies = dependencies
+
+        self._check_input_types()
+        if " " in self.name:
+            raise ValueError(f"Task name cannot contain spaces. Got {self.name}")
+
+        depedencies_names = []
+        for dependency in self.dependencies:
+            if dependency.task_name in depedencies_names:
+                raise ValueError(f"Duplicate dependency name: {dependency.task_name}")
+            depedencies_names.append(dependency.task_name)
+            if dependency.task_name == self.name:
+                raise ValueError(
+                    f"Got dependency with same name as Task. "
+                    f"Task: {self.name}. Dependency: {dependency.task_name}"
+                )
+
+        logger = logging.getLogger(self.name)
+        logger.setLevel(logging.DEBUG)
+        if logger.hasHandlers():
+            logger.handlers.clear()
+
+        file_handler = logging.FileHandler(self.log_path)
+        file_handler.setLevel(logging.INFO)
+        formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+        file_handler.setFormatter(formatter)
+        logger.addHandler(file_handler)
+
+        if self.html_mail_handler is not None:
+            _html_mail_handler = self.html_mail_handler.copy()
+            _html_mail_handler.setFormatter(ExceptionHTMLFormatter())
+            _html_mail_handler.setLevel(logging.ERROR)
+            _html_mail_handler.subject = f"Error in task {self.name}"
+            logger.addHandler(_html_mail_handler)
+
+        self.logger = logger
+
+    def _check_input_types(self) -> None:
+        """
+        Validates all input parameter types.
+
+        Raises
+        ------
+        TypeError
+            If any parameter is not of the expected type.
+        """
+        if not callable(self.func):
+            raise TypeError(f"func must be callable. Got {type(self.func)}")
+
+        if not isinstance(self.args, tuple):
+            raise TypeError(f"args must be tuple. Got {type(self.args)}")
+
+        if not isinstance(self.kwargs, dict):
+            raise TypeError(f"kwargs must be dict. Got {type(self.kwargs)}")
+
+        if self.html_mail_handler is not None and not isinstance(
+            self.html_mail_handler, HTMLSMTPHandler
+        ):
+            raise TypeError(
+                f"mail_cfg must be of type HTMLSMTPHandler. Got {type(self.html_mail_handler)}"
+            )
+
+        if not isinstance(self.dependencies, list):
+            raise TypeError(f"dependencies must be list. Got {type(self.dependencies)}")
+
+        for dependency in self.dependencies:
+            if not isinstance(dependency, TaskDependency):
+                raise TypeError(
+                    f"dependency must be of type TaskDependency. Got {type(dependency)}"
+                )
+
+    def get_dependencies_names(self) -> set[str]:
+        """
+        Get the names of all tasks this task depends on.
+
+        Returns
+        -------
+        set[str]
+            Set of dependency task names.
+        """
+        return {dependency.task_name for dependency in self.dependencies}
+
+    def run(self, executing_process: Process | None = None) -> TaskResult:
+        """
+        Execute the task's function with its arguments and dependencies.
+
+        This method runs the task's function, automatically injecting results from
+        dependent tasks as specified in the dependency configuration. Logs the task
+        execution and captures any exceptions.
+
+        Parameters
+        ----------
+        executing_process : Process, optional
+            The parent Process executing this task. Used to retrieve results from
+            dependent tasks. Defaults to None.
+
+        Returns
+        -------
+        TaskResult
+            Object containing:
+            - worked (bool): True if execution succeeded, False otherwise.
+            - result: The return value of the function if successful, None if failed.
+            - exception (Exception | None): The exception raised if execution failed,
+            None if successful.
+        """
+        final_args = list(self.args)  # Start with original positional args
+        final_kwargs = self.kwargs.copy()  # Start with original keyword args
+
+        if executing_process is not None:
+            for dep in self.dependencies:
+                dep_result = executing_process.runner.passed_results[dep.task_name].result
+                if dep.use_result_as_additional_args:
+                    final_args.append(dep_result)
+                if dep.use_result_as_additional_kwargs:
+                    final_kwargs[dep.additional_kwarg_name] = dep_result
+
+        try:
+            self.logger.info(f"Starting {self.name}.")
+            result = self.func(*final_args, **final_kwargs)
+            self.logger.info(f"Finished {self.name}.")
+            return TaskResult(True, result, None)
+        except Exception as e:
+            report = ""
+            if executing_process is not None:
+                dependencies_names = [
+                    d.name for d in executing_process.get_dependant_tasks(self.name)
+                ]
+                if dependencies_names:
+                    report = (
+                        "<h3>Downstream Impact</h3><p>The following tasks will be skipped:</p><ul>"
+                    )
+                    report += "".join(
+                        f"<li>{dependency_name}</li>" for dependency_name in dependencies_names
+                    )
+                    report += "</ul>"
+            report += f"<p><b>Context:</b><br>Function: {self.func.__name__}"
+            report += f"<br>Args: {self.args}<br>Kwargs: {self.kwargs}</p>"
+            self.logger.exception(e, extra={"post_traceback_html_body": report})
+            return TaskResult(False, None, e)

processes-1.0.2.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: processes
+Version: 1.0.2
+Summary: A Python library for managing and executing dependent tasks in parallel or sequential order with automatic dependency resolution and topological sorting
+Author-email: Oliver Mohr Bonometti <oliver.mohr.b@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dag,dependencies,etl,parallel,process,tasks,topological-sort,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="assets/banner.svg" width="100%" alt="Processes - Smart Task Orchestration">
+</div>
+
+# 🚀 Processes: Smart Task Orchestration
+
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![Python Tests Status](https://github.com/oliverm91/processes/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/oliverm91/processes/actions/workflows/tests.yml)
+![Fast & Lightweight](https://img.shields.io/badge/Library-Pure%20Python-green.svg)
+
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://oliverm91.github.io/processes/)
+
+[![Ruff Lint Status](https://github.com/oliverm91/processes/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/oliverm91/processes/actions/workflows/lint.yml)
+[![mypy-check](https://github.com/oliverm91/processes/actions/workflows/mypy.yml/badge.svg)](https://github.com/oliverm91/processes/actions/workflows/mypy.yml)
+
+
+
+
+
+**Processes** is a lightweight, high-performance Python library designed to execute complex task graphs. It manages **dependencies**, handles **parallel execution**, and ensures system resilience without any external libraries.
+
+File logging and **email notification** is supported.
+
+---
+
+## 📑 Table of Contents
+* [✨ Features](#-features)
+* [⚙️ Core Concepts](#️-core-concepts)
+* [🛠️ Use Cases](#️-use-cases)
+* [💻 Quick Start](#-quick-start)
+* [🛡️ Fault Tolerance & Logs](#️-fault-tolerance--logs)
+* [📦 Installation](#-installation)
+
+---
+
+## ✨ Features
+
+* **🐍 Pure Python:** Zero external dependencies. Built entirely on the **Python Standard Library**.
+* **⚡ Parallel Execution:** Built-in support for parallelization to maximize throughput.
+* **🔗 Dependency Resolution:** Automatically sorts and executes tasks based on their requirements, regardless of input order.
+* **📝 Shared Logging:** Multiple tasks can write to the same logfile or maintain separate ones seamlessly.
+* **📧 Email Notifications:** Integrated SMTP support (including HTML) to alert you the moment an exception occurs.
+
+---
+
+## ⚙️ Core Concepts
+
+The library operates on two main primitives:
+
+1.  **Task**: The atomic unit of work. It encapsulates a function, its parameters, its specific logfile, and its relationship with other tasks.
+2.  **Process**: The orchestrator. It builds the execution graph, validates dependencies, and manages the lifecycle of the entire workflow.
+
+
+---
+
+## 🛠️ Use Cases
+- **ETL Pipelines:** Fetch data from an API, transform it, and load it into a database as separate, dependent tasks.
+
+- **System Maintenance:** Run parallel cleanup scripts, check server health, and receive email alerts if a specific check fails.
+
+- **Automated Reporting:** Generate multiple data parts in parallel, aggregate them into a final report, and distribute via SMTP.
+
+
+---
+
+## 💻 Quick Start
+Define your tasks and their dependencies. **Processes** will handle the execution order and data injection between tasks.
+
+```python
+from datetime import date
+
+from processes import Process, Task, TaskDependency, HTMLSMTPHandler
+
+# 1. Setup Email Alerts (Optional)
+smtp_handler = HTMLSMTPHandler(
+    ('smtp_server', 587), 'sender@example.com', ['admin@example.com', 'user@example.com'], 
+    use_tls=True, credentials=('user', 'pass')
+)
+
+# 2. If necessary, create wrappers for your Tasks.
+def get_previous_working_day():
+    return date(2025, 12, 30)
+def indep_task():
+    return "foo"
+def search_and_sum_csv(t: date):
+    return 10
+def sum_data_from_csv_and_x(x, a=1, b=2):
+    return x + a + b
+
+# 3. Create the Task Graph (order is irrelevant, that is handled by Process)
+tasks = [
+    Task("t-1", "etl.log", get_previous_working_day),
+    Task("intependent", "indep.log", indep_task, html_mail_handler=smtp_handler),  # This task will send email on failure
+    Task("sum_csv", "etl.log", search_and_sum_csv,
+            dependencies= [
+                TaskDependency("t-1",
+                use_result_as_additional_args=True)  # Adds result of t-1 task to search_and_sum_csv function as aditional args
+            ]
+        ),
+    Task("sum_x_and_csv", "etl.log", sum_data_from_csv_and_x,
+            args = (10,), kwargs = {"b": 100},
+            dependencies=[
+                TaskDependency("sum_csv",
+            use_result_as_additional_kwargs=True,
+            additional_kwarg_name="a")
+        ]
+    )
+]
+
+# 4. Run the Process
+with Process(tasks) as process: # Context Manager ensures correct disposal of loggers
+    process_result = process.run() # To enable parallelization use .run(parallel=True)
+
+```
+
+---
+
+## 🛡️ Fault Tolerance & Logs
+### Resilience by Design
+If a `Task` raises an exception, the `Process` **does not stop**. It intelligently skips any tasks that depend on the failed one but continues to execute all other independent branches of your workflow.
+
+### Advanced Logging
+All tasks record their execution flow to their assigned logfiles. You can share a single logfile across the whole process or isolate specific tasks for easier debugging.
+
+
+---
+
+## 📦 Installation
+
+Since it's a pure Python library, you can install it directly from the repository using `pip`:
+
+```bash
+pip install git+https://github.com/oliverm91/processes.git
+```

processes-1.0.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+processes/__init__.py,sha256=ZSr2xIsReGtYp4-s5ajRz-_VJcuN6XTbcBEUAgBROtY,661
+processes/html_logging.py,sha256=qYtVrIZtdJ2f1eYa9PGvW1nZAMYiVyfdNMjuryuwpRc,6394
+processes/process.py,sha256=kLoPKa5uywPZcO-lzuMN5zNgNooTalIwbDGY55yHJhA,14134
+processes/task.py,sha256=gHKyN_vG4qTmxXV9KUDcSO8aVyb0aYeMdvCagfvffOQ,11364
+processes-1.0.2.dist-info/METADATA,sha256=lqrH-dK8oE4dFb02wJ-nc9dS_-paBjKbOpomY0eTTVg,6260
+processes-1.0.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+processes-1.0.2.dist-info/licenses/LICENSE,sha256=dVzfhK9bNx3A2yfwXvyvl6mw1N_vmp6elZROHNVfoLQ,1068
+processes-1.0.2.dist-info/RECORD,,

processes-1.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

processes-1.0.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oliver Mohr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.