epilogue 📜

Strict execution boundaries for deferred side-effects.

Standard logic forces you to push 3rd-party API calls to the absolute bottom of your functions to prevent partial failures. epilogue lets you queue side-effects during execution, running them only if the core function finishes successfully.

By calling defer(), you register an intent. If the function crashes at any point, the queue is silently destroyed and the error is re-raised. Zero side effects occur.

Usage

import epilogue

@epilogue.atomic
def checkout(user, cart):
    # 1. Register the intent. (Does NOT hit the network yet!)
    epilogue.defer(stripe.charge, user.id, cart.total)

    # 2. Do heavy, crash-prone database logic
    db.save_order(user, cart)

    # 3. Register another intent.
    epilogue.defer(email.send_receipt, user.email)

    return True

    # CHECKPOINT:
    # If db.save_order() throws an Exception, the function crashes normally.
    # The Stripe charge and email are completely aborted.
    # If it returns True, the deferred actions are safely executed in order.
    # If Stripe fails during the epilogue, the email STILL sends, and an ExceptionGroup naturally bubbles up.

Features

• All-Or-Nothing Safety: Prevent partial failures without writing complex Saga patterns or Kafka queues.
• Pure Functions: Keeps your core domain logic clean. If you run the code without the decorator (e.g., in unit tests), it just builds a list in memory without triggering real side-effects.
• Context-Safe by Design: Powered entirely by native contextvars. Topologically safe across concurrent threads, asyncio boundaries, and deep recursion without explicit state tracking.
• Flawless Fault Propagation: Uses Python 3.11+ ExceptionGroup to guarantee all successful side-effects execute, even if one fails during the epilogue phase.

Installation

uv add epilogue
# or
pip install epilogue