processes 1.0.5__tar.gz → 2.0.1__tar.gz

{processes-1.0.5 → processes-2.0.1}/.github/workflows/docs.yml

@@ -3,6 +3,17 @@ on:
   push:
     branches:
       - main
+    paths:
+      - "**.py"
+      - "docs/**"
+      - "mkdocs.yml"
+  pull_request:
+    branches:
+      - main
+    paths:
+          - "**.py"
+          - "docs/**"
+          - "mkdocs.yml"
 permissions:
   contents: write
 jobs:

{processes-1.0.5 → processes-2.0.1}/.github/workflows/lint.yml

@@ -3,8 +3,12 @@ name: Lint
 on:
   push:
     branches: [main]
+    paths:
+      - "**.py"
   pull_request:
     branches: [main]
+    paths:
+      - "**.py"
 
 jobs:
   lint:

{processes-1.0.5 → processes-2.0.1}/.github/workflows/mypy.yml

@@ -3,8 +3,12 @@ name: mypy-check
 on:
   push:
     branches: [main]
+    paths:
+      - "**.py"
   pull_request:
     branches: [main]
+    paths:
+      - "**.py"
 
 jobs:
   lint:

{processes-1.0.5 → processes-2.0.1}/.github/workflows/publish.yml

@@ -18,9 +18,6 @@ jobs:
       - name: Ruff Check
         run: uv run ruff check .
 
-      - name: Ruff Format
-        run: uv run ruff format --check .
-
       - name: Mypy
         run: uv run mypy src
 

{processes-1.0.5 → processes-2.0.1}/.gitignore

@@ -54,6 +54,8 @@ cover/
 # Translations
 *.mo
 *.pot
+CLAUDE.md
+/.claude
 
 # Django stuff:
 *.log

{processes-1.0.5 → processes-2.0.1}/CHANGELOG.md

@@ -1,3 +1,27 @@
+## v2.0.1 (2026-06-12)
+
+### Fix
+
+- **publish.yml**: remove unneeded step ruff format check in quality-gate
+
+## v2.0.0 (2026-06-12)
+
+### BREAKING CHANGE
+
+- log records no longer carry
+``post_traceback_html_body``. Consumers introspecting that attribute
+must read ``record.task_context`` instead.
+
+### Feat
+
+- **email_alerting**: Traced Variables section with file:line reference in email body
+- **email_alerting**: language alternatives for HTML email body
+- **email_alerting**: template-driven HTML body from pure metadata
+
+### Fix
+
+- **process**: parallel runner no longer raises on unrunnable tail
+
 ## v1.0.5 (2026-01-19)
 
 ### Fix

{processes-1.0.5 → processes-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: processes
-Version: 1.0.5
+Version: 2.0.1
 Summary: A Python library for managing and executing dependent tasks in parallel or sequential order with automatic dependency resolution and topological sorting
 Project-URL: Homepage, https://github.com/oliverm91/processes
 Project-URL: Documentation, https://oliverm91.github.io/processes/
@@ -26,7 +26,7 @@ Description-Content-Type: text/markdown
   <img src="https://raw.githubusercontent.com/oliverm91/processes/refs/heads/main/assets/banner.svg" width="100%" alt="Processes - Smart Task Orchestration">
 </div>
 
-# 🚀 Processes: Smart Task Orchestration
+# 🚀 Processes: Robust Routines Management
 
 [![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
 ![Fast & Lightweight](https://img.shields.io/badge/Library-Pure%20Python-green.svg)
@@ -92,53 +92,120 @@ The library operates on two main primitives:
 ---
 
 ## 💻 Quick Start
-Define your tasks and their dependencies. **Processes** will handle the execution order and data injection between tasks.
+
+Four short examples — read top to bottom.
+
+### 1. One task
 
 ```python
-from datetime import date
+from processes import Process, Task
 
-from processes import Process, Task, TaskDependency, HTMLSMTPHandler
+def hello():
+    return 42
 
-# 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')
-)
+tasks = [Task("greet", "run.log", hello)]
+
+with Process(tasks) as process:
+    result = process.run()
+
+print(result.passed_tasks_results["greet"].result)   # 42
+```
+
+### 2. `args` and `kwargs`
+
+`args` and `kwargs` are forwarded to your function — like `func(*args, **kwargs)`.
+
+```python
+from processes import Process, Task
+
+def fetch(source, *, limit=100, dry_run=False):
+    return ["row1", "row2"]
 
-# 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")
-        ]
-    )
+    Task(
+        "fetch_orders", "run.log", fetch,
+        args=("orders_api",),
+        kwargs={"limit": 500, "dry_run": True},
+    ),
 ]
 
-# 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)
+with Process(tasks) as process:
+    process.run()
+```
+
+### 3. Dependencies + result injection
+
+`TaskDependency` orders tasks. To also pipe the upstream result into the downstream function, pick one:
+
+* `use_result_as_additional_args=True` — appended as the next **positional** argument.
+* `use_result_as_additional_kwargs=True` + `additional_kwarg_name="..."` — passed as a **keyword** argument.
+
+```python
+from processes import Process, Task, TaskDependency
+
+def load_users():
+    return [{"id": 1}, {"id": 2}, {"id": 3}]
+
+def enrich(api_key, users):                # `users` injected positionally
+    return [{**u, "name": f"user-{u['id']}"} for u in users]
+
+def summarize(*, enriched, label="report"):  # `enriched` injected as kwarg
+    return f"{label}: {len(enriched)} users"
+
+tasks = [
+    Task("load", "run.log", load_users),
+
+    Task(
+        "enrich", "run.log", enrich,
+        args=("MY_API_KEY",),
+        dependencies=[
+            TaskDependency("load", use_result_as_additional_args=True),
+        ],
+    ),
+
+    Task(
+        "summary", "run.log", summarize,
+        kwargs={"label": "daily"},
+        dependencies=[
+            TaskDependency(
+                "enrich",
+                use_result_as_additional_kwargs=True,
+                additional_kwarg_name="enriched",
+            ),
+        ],
+    ),
+]
+
+with Process(tasks) as process:
+    result = process.run(parallel=True)
+
+print(result.passed_tasks_results["summary"].result)
+# "daily: 3 users"
+```
+
+> Task order doesn't matter — `Process` sorts them. A failure only skips its own dependents; the rest keeps running.
+
+### 4. Email alerts on failure
+
+Attach an `HTMLSMTPHandler` to any task. If it raises, an HTML email is sent.
+
+```python
+from processes import HTMLSMTPHandler, Process, Task
+
+smtp = HTMLSMTPHandler(
+    mailhost=("smtp.example.com", 587),
+    fromaddr="alerts@example.com",
+    toaddrs=["oncall@example.com"],
+    credentials=("user", "pass"),
+    secure=(),                             # () = STARTTLS; omit for no encryption
+)
+
+tasks = [
+    Task("risky_step", "run.log", lambda: 1 / 0, html_mail_handler=smtp),
+]
 
+with Process(tasks) as process:
+    process.run()
 ```
 
 ---

processes-2.0.1/README.md

@@ -0,0 +1,210 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/oliverm91/processes/refs/heads/main/assets/banner.svg" width="100%" alt="Processes - Smart Task Orchestration">
+</div>
+
+# 🚀 Processes: Robust Routines Management
+
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+![Fast & Lightweight](https://img.shields.io/badge/Library-Pure%20Python-green.svg)
+
+
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://oliverm91.github.io/processes/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+
+[![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)
+[![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)
+
+[![PyPI version](https://img.shields.io/pypi/v/processes.svg)](https://pypi.org/project/processes/)
+
+
+
+
+**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
+
+Four short examples — read top to bottom.
+
+### 1. One task
+
+```python
+from processes import Process, Task
+
+def hello():
+    return 42
+
+tasks = [Task("greet", "run.log", hello)]
+
+with Process(tasks) as process:
+    result = process.run()
+
+print(result.passed_tasks_results["greet"].result)   # 42
+```
+
+### 2. `args` and `kwargs`
+
+`args` and `kwargs` are forwarded to your function — like `func(*args, **kwargs)`.
+
+```python
+from processes import Process, Task
+
+def fetch(source, *, limit=100, dry_run=False):
+    return ["row1", "row2"]
+
+tasks = [
+    Task(
+        "fetch_orders", "run.log", fetch,
+        args=("orders_api",),
+        kwargs={"limit": 500, "dry_run": True},
+    ),
+]
+
+with Process(tasks) as process:
+    process.run()
+```
+
+### 3. Dependencies + result injection
+
+`TaskDependency` orders tasks. To also pipe the upstream result into the downstream function, pick one:
+
+* `use_result_as_additional_args=True` — appended as the next **positional** argument.
+* `use_result_as_additional_kwargs=True` + `additional_kwarg_name="..."` — passed as a **keyword** argument.
+
+```python
+from processes import Process, Task, TaskDependency
+
+def load_users():
+    return [{"id": 1}, {"id": 2}, {"id": 3}]
+
+def enrich(api_key, users):                # `users` injected positionally
+    return [{**u, "name": f"user-{u['id']}"} for u in users]
+
+def summarize(*, enriched, label="report"):  # `enriched` injected as kwarg
+    return f"{label}: {len(enriched)} users"
+
+tasks = [
+    Task("load", "run.log", load_users),
+
+    Task(
+        "enrich", "run.log", enrich,
+        args=("MY_API_KEY",),
+        dependencies=[
+            TaskDependency("load", use_result_as_additional_args=True),
+        ],
+    ),
+
+    Task(
+        "summary", "run.log", summarize,
+        kwargs={"label": "daily"},
+        dependencies=[
+            TaskDependency(
+                "enrich",
+                use_result_as_additional_kwargs=True,
+                additional_kwarg_name="enriched",
+            ),
+        ],
+    ),
+]
+
+with Process(tasks) as process:
+    result = process.run(parallel=True)
+
+print(result.passed_tasks_results["summary"].result)
+# "daily: 3 users"
+```
+
+> Task order doesn't matter — `Process` sorts them. A failure only skips its own dependents; the rest keeps running.
+
+### 4. Email alerts on failure
+
+Attach an `HTMLSMTPHandler` to any task. If it raises, an HTML email is sent.
+
+```python
+from processes import HTMLSMTPHandler, Process, Task
+
+smtp = HTMLSMTPHandler(
+    mailhost=("smtp.example.com", 587),
+    fromaddr="alerts@example.com",
+    toaddrs=["oncall@example.com"],
+    credentials=("user", "pass"),
+    secure=(),                             # () = STARTTLS; omit for no encryption
+)
+
+tasks = [
+    Task("risky_step", "run.log", lambda: 1 / 0, html_mail_handler=smtp),
+]
+
+with Process(tasks) as process:
+    process.run()
+```
+
+---
+
+## 🛡️ 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
+
+Registered in PyPI: https://pypi.org/project/processes/
+```bash
+pip install processes
+```
+
+Also, since it's a pure Python library, you can install it directly from the repository:
+
+```bash
+pip install git+https://github.com/oliverm91/processes.git
+```

{processes-1.0.5 → processes-2.0.1}/assets/banner.svg

@@ -28,30 +28,61 @@
     <path d="M0,0 L1200,0 M0,100 L1200,100 M0,200 L1200,200 M0,300 L1200,300 M0,400 L1200,400" stroke="#4ecca3" stroke-width="1"/>
   </g>
   
-  <!-- Task flow visualization (left side) -->
-  <g opacity="0.8">
-    <!-- Top branch flowing down -->
-    <line x1="80" y1="120" x2="140" y2="120" stroke="#4ecca3" stroke-width="3" stroke-linecap="round"/>
-    <line x1="140" y1="120" x2="200" y2="180" stroke="#4ecca3" stroke-width="3" stroke-linecap="round"/>
+  <!-- Task flow visualization (left side) - New logo design -->
+  <g opacity="0.9" transform="translate(30, 80)">
+    <!-- Connections (edges) -->
+    <g stroke-width="3" stroke-linecap="round">
+      <!-- Blue branches -->
+      <g stroke="#4ecca3" fill="none">
+        <!-- Top to second level -->
+        <path d="M 125 20 L 80 60"/>
+        <path d="M 125 20 L 170 60"/>
+        
+        <!-- Second to third level -->
+        <path d="M 80 60 L 125 100"/>
+        <path d="M 170 60 L 125 100"/>
+        <path d="M 80 60 L 60 120"/>
+        
+        <!-- Vertical parallel branches -->
+        <path d="M 125 100 L 125 185"/>
+        <path d="M 60 120 L 60 185"/>
+      </g>
+      
+      <!-- Connection to failing task (blue) -->
+      <g stroke="#4ecca3" fill="none">
+        <path d="M 170 60 L 190 120"/>
+      </g>
+      
+      <!-- Failed branch (red) -->
+      <g stroke="#ef4444" fill="none">
+        <path d="M 190 120 L 190 185"/>
+      </g>
+    </g>
     
-    <!-- Middle branch straight -->
-    <line x1="80" y1="200" x2="200" y2="200" stroke="#4ecca3" stroke-width="3" stroke-linecap="round"/>
+    <!-- Nodes (tasks) -->
+    <g fill="#4ecca3" filter="url(#glow)">
+      <!-- Top node -->
+      <circle cx="125" cy="20" r="8"/>
+      
+      <!-- Second level -->
+      <circle cx="80" cy="60" r="8"/>
+      <circle cx="170" cy="60" r="8"/>
+      
+      <!-- Third level -->
+      <circle cx="125" cy="100" r="8"/>
+      <circle cx="60" cy="120" r="7"/>
+      
+      <!-- Final nodes -->
+      <circle cx="60" cy="190" r="10"/>
+      <circle cx="125" cy="190" r="10"/>
+    </g>
     
-    <!-- Bottom branch flowing up -->
-    <line x1="80" y1="280" x2="140" y2="280" stroke="#4ecca3" stroke-width="3" stroke-linecap="round"/>
-    <line x1="140" y1="280" x2="200" y2="220" stroke="#4ecca3" stroke-width="3" stroke-linecap="round"/>
+    <!-- Failed branch nodes (red) -->
+    <g fill="#ef4444" filter="url(#glow)">
+      <circle cx="190" cy="120" r="7"/>
+      <circle cx="190" cy="190" r="10"/>
+    </g>
     
-    <!-- Merge point -->
-    <circle cx="200" cy="200" r="8" fill="#4ecca3" filter="url(#glow)"/>
-    
-    <!-- Arrow to right -->
-    <line x1="200" y1="200" x2="314" y2="200" stroke="#4ecca3" stroke-width="3" stroke-linecap="round">
-      <animate attributeName="stroke-dasharray" values="0 400; 400 0" dur="2s" repeatCount="indefinite"/>
-      <animate attributeName="stroke-dashoffset" values="0; -400" dur="2s" repeatCount="indefinite"/>
-    </line>
-    <polygon points="320,200 305,193 305,207" fill="#4ecca3" filter="url(#glow)">
-      <animate attributeName="opacity" values="0.5;1;0.5" dur="2s" repeatCount="indefinite"/>
-    </polygon>
   </g>
   
   <!-- Main Title -->
@@ -61,7 +92,7 @@
   
   <!-- Subtitle -->
   <text x="600" y="210" font-family="'SF Mono', 'Monaco', 'Courier New', monospace" font-size="28" fill="#ffffff" text-anchor="middle" opacity="0.9">
-    Smart Task Orchestration
+    Robust Routines Management
   </text>
   
   <!-- Feature badges -->

processes-2.0.1/assets/logo.svg

@@ -0,0 +1,71 @@
+<svg viewBox="0 0 500 500" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="bgGradient" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#1a1a2e;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#16213e;stop-opacity:1" />
+    </linearGradient>
+    
+    <filter id="glow">
+      <feGaussianBlur stdDeviation="3" result="coloredBlur"/>
+      <feMerge>
+        <feMergeNode in="coloredBlur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+  </defs>
+  
+  <!-- Transparent background -->
+  
+  <!-- Task graph structure -->
+  <g stroke-width="3" stroke-linecap="round">
+    <!-- Blue branches -->
+    <g stroke="#4ecca3" fill="none">
+      <!-- Top to second level -->
+      <path d="M 250 120 L 160 200"/>
+      <path d="M 250 120 L 340 200"/>
+      
+      <!-- Second to third level -->
+      <path d="M 160 200 L 250 280"/>
+      <path d="M 340 200 L 250 280"/>
+      <path d="M 160 200 L 120 300"/>
+      
+      <!-- Vertical parallel branches -->
+      <path d="M 250 280 L 250 415"/>
+      <path d="M 120 300 L 120 415"/>
+    </g>
+    
+    <!-- Connection to failing task (blue) -->
+    <g stroke="#4ecca3" fill="none">
+      <path d="M 340 200 L 380 300"/>
+    </g>
+    
+    <!-- Failed branch (red) -->
+    <g stroke="#ef4444" fill="none">
+      <path d="M 380 300 L 380 415"/>
+    </g>
+    
+    <!-- Nodes (tasks) -->
+    <g fill="#4ecca3" filter="url(#glow)">
+      <!-- Top node -->
+      <circle cx="250" cy="120" r="12"/>
+      
+      <!-- Second level -->
+      <circle cx="160" cy="200" r="12"/>
+      <circle cx="340" cy="200" r="12"/>
+      
+      <!-- Third level -->
+      <circle cx="250" cy="280" r="12"/>
+      <circle cx="120" cy="300" r="10"/>
+      
+      <!-- Final nodes -->
+      <circle cx="120" cy="420" r="14"/>
+      <circle cx="250" cy="420" r="14"/>
+    </g>
+    
+    <!-- Failed branch nodes (red) -->
+    <g fill="#ef4444" filter="url(#glow)">
+      <circle cx="380" cy="300" r="10"/>
+      <circle cx="380" cy="420" r="14"/>
+    </g>
+  </g>
+</svg>