processes 3.1.0__tar.gz → 3.1.1__tar.gz

{processes-3.1.0 → processes-3.1.1}/CHANGELOG.md

@@ -1,3 +1,9 @@
+## v3.1.1 (2026-06-13)
+
+### Refactor
+
+- rename _log_formatting to _logfile_formatting and _TaskLogFormatter to _TaskLogfileFormatter
+
 ## v3.1.0 (2026-06-13)
 
 ### Feat

{processes-3.1.0 → processes-3.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: processes
-Version: 3.1.0
+Version: 3.1.1
 Summary: Orchestrate graphs of callables in Python with automatic dependency resolution, parallel execution, retries, timeouts, and HTML email alerts on failure — zero dependencies
 Project-URL: Homepage, https://github.com/oliverm91/processes
 Project-URL: Documentation, https://oliverm91.github.io/processes/
@@ -336,6 +336,20 @@ HTMLEmailStyle(
 
 All fields are optional — omit `HTMLEmailStyle` entirely to use the defaults.
 
+#### Traced Variables
+
+On failure, the email body includes the local variables of the **outermost
+user frame in the traceback** — i.e. the last frame that is not inside
+`site-packages` or your virtualenv. A `file:line` reference next to the
+section shows exactly where those values were captured.
+
+`traced_vars_frame_filter` lets you point this at a different frame: set it
+to a path substring (e.g. one of your own package or module names) to
+capture locals from the outermost frame whose filename contains that
+substring instead. This is useful for deep-debugging code that runs through
+several layers of internal libraries or wrappers, where the default
+outermost-user-frame would land too high up the call stack.
+
 </details>
 
 <details>

{processes-3.1.0 → processes-3.1.1}/README.md

@@ -311,6 +311,20 @@ HTMLEmailStyle(
 
 All fields are optional — omit `HTMLEmailStyle` entirely to use the defaults.
 
+#### Traced Variables
+
+On failure, the email body includes the local variables of the **outermost
+user frame in the traceback** — i.e. the last frame that is not inside
+`site-packages` or your virtualenv. A `file:line` reference next to the
+section shows exactly where those values were captured.
+
+`traced_vars_frame_filter` lets you point this at a different frame: set it
+to a path substring (e.g. one of your own package or module names) to
+capture locals from the outermost frame whose filename contains that
+substring instead. This is useful for deep-debugging code that runs through
+several layers of internal libraries or wrappers, where the default
+outermost-user-frame would land too high up the call stack.
+
 </details>
 
 <details>

{processes-3.1.0 → processes-3.1.1}/docs/index.md

@@ -184,6 +184,13 @@ in the source the listed values were captured, which is usually the
 fastest way to figure out *why* a complex task broke deep inside a
 wrapper.
 
+This default can be overridden with `HTMLEmailStyle.traced_vars_frame_filter`.
+Set it to a path substring (e.g. the name of one of your own packages or
+modules) to capture locals from the outermost frame whose filename contains
+that substring instead — useful for deep-debugging code that runs through
+several layers of internal libraries or wrappers, where the default
+outermost-user-frame would land too high up the call stack.
+
 ---
 
 ## 🛡️ Fault Tolerance & Logs

{processes-3.1.0 → processes-3.1.1}/src/processes/_email_internals.py

@@ -22,7 +22,18 @@ _PALETTE_MARKER = "{{__palette_css__}}"
 
 
 def _load_language_strings(language: str) -> dict[str, str]:
-    """Load translatable strings for the given ISO 639-1 language code."""
+    """Load translatable strings for the given ISO 639-1 language code.
+
+    Parameters
+    ----------
+    language : str
+        ISO 639-1 language code, e.g. ``"en"``.
+
+    Returns
+    -------
+    dict[str, str]
+        Mapping of translation keys to localized strings.
+    """
     path = os.path.join(_LANGUAGES_DIR, f"{language}.json")
     with open(path, encoding="utf-8") as fh:
         return cast(dict[str, str], json.load(fh))
@@ -57,9 +68,20 @@ class _HTMLEmailFormatter(_ErrorContextFormatter):
     def _split_traceback_at_target(self, tb_str: str, location: str) -> tuple[str, str, str]:
         """Split *tb_str* around the frame line matching *location*.
 
-        Returns ``(before, highlight, after)`` where ``highlight`` is the
-        ``File "<filename>", line <lineno>, in <func>`` line for that frame.
-        Returns ``("", "", tb_str)`` if no match is found.
+        Parameters
+        ----------
+        tb_str : str
+            Full formatted traceback to split.
+        location : str
+            ``"filename:lineno"`` of the frame to highlight, as produced by
+            ``_build_traced_vars_location``.
+
+        Returns
+        -------
+        tuple[str, str, str]
+            ``(before, highlight, after)`` where ``highlight`` is the
+            ``File "<filename>", line <lineno>, in <func>`` line for that
+            frame. Returns ``("", "", tb_str)`` if no match is found.
         """
         if not tb_str or not location:
             return ("", "", tb_str)
@@ -83,7 +105,18 @@ class _HTMLEmailFormatter(_ErrorContextFormatter):
         return rendered
 
     def format(self, record: logging.LogRecord) -> str:
-        """Render a log record as a complete HTML email body."""
+        """Render a log record as a complete HTML email body.
+
+        Parameters
+        ----------
+        record : logging.LogRecord
+            The record being formatted.
+
+        Returns
+        -------
+        str
+            The fully rendered HTML email body.
+        """
         error = self._error_data(record)
 
         tb_before, tb_highlight, tb_after = self._split_traceback_at_target(
@@ -159,7 +192,23 @@ def _build_task_email_handler(
     style: HTMLEmailStyle,
     task_name: str,
 ) -> _HTMLEmailHandler:
-    """Create a fully configured email handler bound to one task."""
+    """Create a fully configured email handler bound to one task.
+
+    Parameters
+    ----------
+    smtp_config : SMTPConfig
+        SMTP transport configuration for the handler.
+    style : HTMLEmailStyle
+        HTML presentation settings used by the handler's formatter.
+    task_name : str
+        Name of the task the handler is bound to, used in the email subject.
+
+    Returns
+    -------
+    _HTMLEmailHandler
+        A handler at ``logging.ERROR`` level, with its formatter and
+        localized subject configured.
+    """
     handler = _HTMLEmailHandler(smtp_config)
     handler.setFormatter(_HTMLEmailFormatter(style))
     handler.setLevel(logging.ERROR)

{processes-3.1.0 → processes-3.1.1}/src/processes/_error_data.py

@@ -7,7 +7,29 @@ from typing import Any
 
 @dataclass(frozen=True)
 class _ErrorData:
-    """Typed view of a task failure, extracted from ``record.task_context``."""
+    """Typed view of a task failure, extracted from ``record.task_context``.
+
+    Attributes
+    ----------
+    task_name : str
+        Name of the task that failed. Defaults to ``"?"``.
+    function : str
+        Name of the function that was executing. Defaults to ``"?"``.
+    args : tuple[Any, ...]
+        Positional arguments the function was called with. Defaults to ``()``.
+    kwargs : dict[str, Any]
+        Keyword arguments the function was called with. Defaults to ``{}``.
+    downstream_impact : list[str]
+        Names of tasks skipped as a result of this failure. Defaults to ``[]``.
+    exception : str
+        String representation of the raised exception. Defaults to ``""``.
+    traceback_str : str
+        Full formatted traceback. Defaults to ``""``.
+    traced_vars : str
+        Rendered local variables of the traced frame. Defaults to ``""``.
+    traced_vars_location : str
+        ``"filename:lineno"`` of the traced frame. Defaults to ``""``.
+    """
 
     task_name: str = "?"
     function: str = "?"
@@ -24,6 +46,20 @@ class _ErrorContextFormatter(logging.Formatter):
     """Base formatter providing typed access to a record's failure context."""
 
     def _error_data(self, record: logging.LogRecord) -> _ErrorData:
+        """Extract the failure context from a log record.
+
+        Parameters
+        ----------
+        record : logging.LogRecord
+            The record being formatted. May or may not carry a
+            ``task_context`` attribute.
+
+        Returns
+        -------
+        _ErrorData
+            Typed view of ``record.task_context``, with defaults filled in
+            for any missing fields.
+        """
         ctx = getattr(record, "task_context", None) or {}
         return _ErrorData(
             task_name=str(ctx.get("task_name", "?")),

processes-3.1.0/src/processes/_log_formatting.py → processes-3.1.1/src/processes/_logfile_formatting.py

@@ -7,7 +7,7 @@ from ._error_data import _ErrorContextFormatter
 _LOG_FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
 
 
-class _TaskLogFormatter(_ErrorContextFormatter):
+class _TaskLogfileFormatter(_ErrorContextFormatter):
     """Plain-text formatter for task logfiles.
 
     On failure, appends the same failure context shown in the HTML email
@@ -19,6 +19,19 @@ class _TaskLogFormatter(_ErrorContextFormatter):
         super().__init__(_LOG_FORMAT)
 
     def format(self, record: logging.LogRecord) -> str:
+        """Render a log record as plain text, appending failure context if present.
+
+        Parameters
+        ----------
+        record : logging.LogRecord
+            The record being formatted.
+
+        Returns
+        -------
+        str
+            The formatted log line, with the failure context appended if
+            ``record.task_context`` is set.
+        """
         if not getattr(record, "task_context", None):
             return super().format(record)
 

{processes-3.1.0 → processes-3.1.1}/src/processes/_tb_utils.py

@@ -8,7 +8,19 @@ from typing import Any
 
 
 def _is_library_path(filename: str) -> bool:
-    """Return True if ``filename`` lives inside a library or stdlib."""
+    """Check whether a source file belongs to a library or the stdlib.
+
+    Parameters
+    ----------
+    filename : str
+        Path of a traceback frame's source file.
+
+    Returns
+    -------
+    bool
+        True if ``filename`` lives inside ``site-packages``, a ``.venv``,
+        or the Python install prefix, False otherwise.
+    """
     if "site-packages" in filename:
         return True
     if ".venv" in filename:
@@ -26,6 +38,18 @@ def _is_library_path(filename: str) -> bool:
 
 
 def _iter_tb(exc_tb: Any) -> Any:
+    """Iterate over a traceback's frames from outermost to innermost.
+
+    Parameters
+    ----------
+    exc_tb : types.TracebackType | None
+        The traceback to walk, typically ``exc.__traceback__``.
+
+    Returns
+    -------
+    Iterator[types.TracebackType]
+        Each traceback node from ``exc_tb`` to the innermost frame.
+    """
     tb = exc_tb
     while tb is not None:
         yield tb
@@ -38,6 +62,19 @@ def _resolve_target_tb(exc_tb: Any, frame_filter: str | None) -> Any:
     With ``frame_filter=None``, picks the last non-library frame.
     With a filter string, picks the last frame whose filename contains it.
     Falls back to the innermost frame when nothing matches.
+
+    Parameters
+    ----------
+    exc_tb : types.TracebackType | None
+        The traceback to search, typically ``exc.__traceback__``.
+    frame_filter : str | None
+        Substring used to select a frame by filename, or ``None`` to pick
+        the outermost non-library frame.
+
+    Returns
+    -------
+    types.TracebackType | None
+        The selected traceback frame, or ``None`` if ``exc_tb`` is ``None``.
     """
     frames = list(_iter_tb(exc_tb))
     if not frames:
@@ -50,7 +87,22 @@ def _resolve_target_tb(exc_tb: Any, frame_filter: str | None) -> Any:
 
 
 def _build_traced_vars_html(exc_tb: Any, frame_filter: str | None) -> str:
-    """Return HTML-escaped ``name = repr(value)`` lines for the target frame's locals."""
+    """Return HTML-escaped ``name = repr(value)`` lines for the target frame's locals.
+
+    Parameters
+    ----------
+    exc_tb : types.TracebackType | None
+        The traceback to search, typically ``exc.__traceback__``.
+    frame_filter : str | None
+        Substring used to select a frame by filename, or ``None`` to pick
+        the outermost non-library frame.
+
+    Returns
+    -------
+    str
+        Newline-separated, HTML-escaped ``name = repr(value)`` lines for the
+        target frame's locals, or ``""`` if no frame is found.
+    """
     target = _resolve_target_tb(exc_tb, frame_filter)
     if target is None:
         return ""
@@ -66,7 +118,21 @@ def _build_traced_vars_html(exc_tb: Any, frame_filter: str | None) -> str:
 
 
 def _build_traced_vars_location(exc_tb: Any, frame_filter: str | None) -> str:
-    """Return ``"filename:lineno"`` for the target frame, or empty string."""
+    """Return ``"filename:lineno"`` for the target frame, or empty string.
+
+    Parameters
+    ----------
+    exc_tb : types.TracebackType | None
+        The traceback to search, typically ``exc.__traceback__``.
+    frame_filter : str | None
+        Substring used to select a frame by filename, or ``None`` to pick
+        the outermost non-library frame.
+
+    Returns
+    -------
+    str
+        ``"filename:lineno"`` of the target frame, or ``""`` if no frame is found.
+    """
     target = _resolve_target_tb(exc_tb, frame_filter)
     if target is None:
         return ""
@@ -75,5 +141,17 @@ def _build_traced_vars_location(exc_tb: Any, frame_filter: str | None) -> str:
 
 
 def _format_traceback(exc: BaseException) -> str:
-    """Return the full traceback of *exc* as a single string."""
+    """Return the full traceback of *exc* as a single string.
+
+    Parameters
+    ----------
+    exc : BaseException
+        The exception whose traceback should be formatted.
+
+    Returns
+    -------
+    str
+        The full traceback, as produced by ``traceback.format_exception``,
+        joined into a single string.
+    """
     return "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))

{processes-3.1.0 → processes-3.1.1}/src/processes/email_config.py

@@ -26,9 +26,11 @@ class SMTPConfig:
         Recipient email addresses.
     credentials : tuple[str, str] | None
         ``(username, password)`` for SMTP authentication. Defaults to ``None``.
-    secure : tuple | None
-        Security configuration. Use ``()`` for STARTTLS, ``(certfile, keyfile)``
-        for explicit TLS, or ``None`` for no encryption. Defaults to ``None``.
+    secure : tuple[()] | tuple[str] | tuple[str, str] | tuple[str, str, ssl.SSLContext] | None
+        Security configuration. Use ``()`` for STARTTLS, ``(keyfile,)`` or
+        ``(keyfile, certfile)`` for explicit TLS context creation, or
+        ``(keyfile, certfile, ssl_context)`` to supply a pre-built
+        ``ssl.SSLContext``. ``None`` means no encryption. Defaults to ``None``.
     timeout : int
         Connection timeout in seconds. Defaults to ``5``.
     """
@@ -64,6 +66,14 @@ class HTMLEmailStyle:
         appear in the *Traced Variables* section. When ``None`` (default),
         the outermost user frame is used; when set, the outermost frame whose
         filename contains this substring is used instead.
+
+    Raises
+    ------
+    ValueError
+        If ``style``, ``palette``, or ``language`` is not one of the
+        supported values.
+    TypeError
+        If ``traced_vars_frame_filter`` is neither ``str`` nor ``None``.
     """
 
     style: str = _DEFAULT_STYLE

{processes-3.1.0 → processes-3.1.1}/src/processes/process.py

@@ -298,6 +298,8 @@ class ProcessRunner:
         Results from successfully executed tasks.
     failed_tasks : set[str]
         Names of tasks that failed during execution.
+    skipped_tasks : set[str]
+        Names of tasks that were never run because an upstream dependency failed.
     submitted_tasks : set[str]
         Names of tasks that have been submitted for execution.
     """
@@ -310,7 +312,14 @@ class ProcessRunner:
         self.submitted_tasks: set[str] = set()
 
     def _is_done(self) -> bool:
-        """Whether every task has either passed or failed."""
+        """Check whether every task has either passed or failed.
+
+        Returns
+        -------
+        bool
+            True if every task has a recorded result (passed or failed),
+            False otherwise.
+        """
         return len(self.passed_results) + len(self.failed_tasks) >= len(self.process.tasks)
 
     def run(self, parallel: bool, max_workers: int) -> ProcessResult:

{processes-3.1.0 → processes-3.1.1}/src/processes/task.py

@@ -10,7 +10,7 @@ if TYPE_CHECKING:
 import logging
 
 from ._email_internals import _build_task_email_handler
-from ._log_formatting import _TaskLogFormatter
+from ._logfile_formatting import _TaskLogfileFormatter
 from ._tb_utils import _build_traced_vars_html, _build_traced_vars_location, _format_traceback
 from .email_config import HTMLEmailStyle, SMTPConfig
 from .exceptions import CircularDependencyError
@@ -251,7 +251,7 @@ class Task:
 
         file_handler = logging.FileHandler(self.log_path)
         file_handler.setLevel(logging.INFO)
-        file_handler.setFormatter(_TaskLogFormatter())
+        file_handler.setFormatter(_TaskLogfileFormatter())
         logger.addHandler(file_handler)
 
         if smtp_config is not None:
@@ -271,6 +271,13 @@ class Task:
         """
         Validates all input parameter types.
 
+        Parameters
+        ----------
+        smtp_config : SMTPConfig | None
+            SMTP transport configuration passed to the constructor, if any.
+        email_style : HTMLEmailStyle | None
+            HTML presentation settings passed to the constructor, if any.
+
         Raises
         ------
         TypeError

processes-3.1.0/RELEASE_NOTES.md

@@ -1,36 +0,0 @@
-# v3.0.1 — Email API Overhaul, Task Retries & Timeouts
-
-## ⚠️ Breaking Changes
-
-- **Removed `HTMLSMTPHandler` and `html_mail_handler`**. Email alerting is now configured with two plain dataclasses passed to `Task`:
-  - `SMTPConfig` — SMTP transport settings (host, credentials, sender/recipients, TLS).
-  - `HTMLEmailStyle` — presentation settings (style, color palette, language, traced-vars frame filter).
-
-  ```python
-  Task(..., smtp_config=SMTPConfig(...), email_style=HTMLEmailStyle(style="modern", palette="catppuccin"))
-  ```
-
-## ✨ New Features
-
-- **Per-task timeouts**: `Task(..., timeout=30)` raises `TimeoutError` if an attempt exceeds the limit.
-- **Automatic retries**: `Task(..., retries=3, retry_on=(ConnectionError, TimeoutError))` retries failed attempts on the specified exception types (defaults to `ConnectionError`/`TimeoutError`).
-- **Structured exceptions**: `DependencyNotFoundError`, `TaskNotFoundError`, and `CircularDependencyError` now carry structured attributes (`task_name`, `missing_dep`) instead of plain messages.
-- **Traced variables in error emails**: failure emails include a "Traced Variables" section showing local variables at the relevant stack frame, with a configurable `traced_vars_frame_filter` to target a specific module.
-
-## 🔧 Refactoring
-
-- Centralized failure-context extraction: `Task._resolve_args` and `Task._build_failure_context` cleanly separate dependency-result injection from failure reporting.
-- Split traceback/frame-walking utilities (`_tb_utils.py`) from email-rendering internals (`_email_internals.py`) — each module now has a single responsibility.
-- Each `Task` now gets a unique per-instance logger, preventing handler leakage between tasks with the same name.
-- Minor cleanups in `Process`: bare `raise` for re-raised exceptions, extracted `_is_done()` helper for the parallel runner loop.
-
-## 🐛 Bug Fixes
-
-- Fixed a logging bug where `logger.exception(...)` was called outside an `except` block, resulting in empty exception details (`None`) in failure emails. Errors now log with full `exc_info` and a structured `task_context` payload.
-- Fixed `Task.run()` not reporting the actual exception when retries were exhausted.
-
-## 🧪 Testing & CI
-
-- Migrated the test suite to a shared `BaseTest` base class with consistent per-test log directories and cleanup.
-- Added dedicated tests for timeout and retry behavior.
-- Bumped GitHub Actions (`actions/checkout` → v6, `astral-sh/setup-uv` → v6) to silence deprecation warnings.