📑 Table of Contents

• The Problem
• The Solution
• Install
• Features
• Usage
• API
• FAQ
• Roadmap
• Contributing
• License & Support

😩 The Problem

Every Python developer has felt this:

• 🧠 Train a model for 12 hours → power outage at hour 11 → everything gone.
• 🕷️ Scrape a million pages → accidental Ctrl+C → start from zero.
• 📦 Process 2TB of data → MemoryError at hour 6 → begin again.
• 🔬 Run a 48-hour simulation → cluster kills the job → rerun from scratch.

The usual answer: save checkpoints manually. You write try/except + pickle.dump, manage state files, handle corrupt saves… then forget one edge case, and it all falls apart anyway.

There has to be a better way.

✨ The Solution

from neverlose import resurrect, checkpoint

@resurrect
def train():
    for epoch in range(1000):
        loss = do_epoch(epoch)
        checkpoint({"epoch": epoch, "loss": loss})

train()

That's it. Run it. Stop it. Crash it. Re-run the same file → it resumes automatically from the last epoch.

No try/except. No pickle.dump. No dependencies.

🚀 Install

pip install neverlose

Python 3.9 → 3.13. Zero dependencies (standard library only).

🎯 Features

Feature What it means for you 🔁 Automatic resume Re-run the same file → picks up where it left off 💾 Atomic writes Power loss mid-save = no corrupt checkpoints, ever 🛑 Signal handling Catches Ctrl+C and SIGTERM, saves before exiting 🧬 Fingerprinting Detects code changes → avoids stale resumes 📦 Zero dependencies Only Python stdlib — works in air-gapped environments 🐍 Pure Python No C extensions, no compiled wheels

📖 Usage

🧠 Machine Learning Training

from neverlose import resurrect, checkpoint

@resurrect(key="gpt-small-v3")
def train_model():
    model = build_model()
    for epoch in range(100):
        for batch in dataloader:
            loss = train_step(model, batch)
        checkpoint({"epoch": epoch, "loss": loss})

train_model()

Change key= when hyperparameters change → forces a fresh start.

from neverlose import resurrect, checkpoint

@resurrect(key="news-2026")
def scrape_all():
    state = scrape_all.resume_state() or {"done": []}
    done = set(state["done"])
    for url in url_list:
        if url in done:
            continue
        save(fetch(url), url)
        done.add(url)
        checkpoint({"done": list(done)})

scrape_all()

from pathlib import Path
from neverlose import resurrect, checkpoint

@resurrect
def process(path):
    files = list(Path(path).glob("*.parquet"))
    state = process.resume_state() or {"i": 0}
    for i, f in enumerate(files[state["i"] + 1:], start=state["i"] + 1):
        transform(f)
        checkpoint({"i": i, "total": len(files)})

process("/data/raw")

⚙️ API

@resurrect(key="", keep=True, verbose=True)
def my_function():
    ...

Param Type Default Description key str "" Extra fingerprint ingredient — change to force a fresh start keep bool True Keep checkpoint file after success, or delete it verbose bool True Print resume/save messages to stderr

from neverlose import checkpoint, resume_state, reset

checkpoint({"step": 42})       # manual save inside a decorated function
resume_state(my_function)      # → last saved value, or None
my_function.reset()            # → delete checkpoint file

Environment variable: NEVERLOSE_DIR (default: ~/.neverlose)

❓ FAQ

⚖️ Comparison

🗺️ Roadmap

• v1.0 — Sync functions, atomic writes, signal handling
• v1.1 — async def support ← ⭐ to ship it faster
• v1.2 — Multiprocessing-safe checkpoints
• v1.3 — Cloud backends: S3 · GCS · Azure Blob
• v2.0 — Distributed checkpoint registry

🤝 Contributing

Every PR is welcome — from typo fixes to full features.

git clone https://github.com/neverlose-io/neverlose.git
cd neverlose
pip install -e ".[dev]"
pytest -v

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

📜 License

MIT © 2026 NeverLose IO — see LICENSE.

💖 License & Support

NeverLose is free and open source, built with zero funding and no corporate backing.

⭐ Star History