debugonce

Effortlessly capture and reproduce bugs in your Python code.

🔍 Overview

debugonce is a Python utility that makes debugging easier by capturing function calls, inputs, and runtime context. With a simple decorator, you can store a snapshot of any function execution and replay it later for consistent bug reproduction.

✨ Features

• 🧠 Automatically captures function arguments, environment variables, working directory, Python version, stack trace, file access, and HTTP requests.
• 📁 Saves session data to .debugonce/ as readable JSON files.
• 🧪 CLI commands to inspect, replay, export, list, or clean captured sessions.
• 🧵 Reproduce bugs consistently with auto-generated _replay.py scripts that include the full function implementation and do not require the @debugonce decorator at replay time.
• ✅ Robust tracking even in the presence of test-time mocks (file and HTTP access are always captured).
• 🔒 Logging is isolated to .debugonce/debugonce.log and never corrupts session files.
• 🧩 Arguments are faithfully serialized (strings quoted, numbers as-is) for accurate replay.
• ✅ Minimal setup — just decorate and debug!

📦 Installation

pip install debugonce

🚀 Basic Usage

1. Decorate Your Function

To capture the state of a function, simply decorate it with @debugonce:

from debugonce_packages import debugonce

@debugonce
def divide(x, y):
    return x / y

divide(4, 2)
divide(10, 0)  # This will raise an error and trigger capture

2. Check the Captured Session

.debugonce/
├── session_<timestamp>.json
├── session_<timestamp>_replay.py
├── debugonce.log

🛠️ CLI Commands

🔎 List All Sessions

debugonce list

🧾 Inspect a Session

debugonce inspect .debugonce/session_<timestamp>.json

📤 Export a Session

Generates a _replay.py file to recreate the captured call, including the function implementation and correct argument quoting:

debugonce export .debugonce/session_<timestamp>.json

▶️ Replay the Session

Executes the _replay.py to reproduce the same error with the same scenario. Exception output is printed to stderr for CLI visibility.

debugonce replay .debugonce/session_<timestamp>.json

🧹 Clean All Sessions

debugonce clean

📁 What’s Captured?

• ✅ Function name and arguments (with correct types/quoting)
• ✅ HTTP Requests
• ✅ File access (read/write)
• ✅ Python version
• ✅ Current working directory
• ✅ Environment variables
• ✅ Stack trace (if an error occurred)
• ✅ Timestamp

🔧 Advanced Example

from debugonce_packages import debugonce

@debugonce
def fetch_and_save_post(post_id, filename):
    """Fetch a post from an API and save its title to a file."""
    url = f"https://jsonplaceholder.typicode.com/posts/{post_id}"
    response = requests.get(url)
    data = response.json()
    title = data["title"]
    with open(filename, "w") as f:
        f.write(title)
    return title

fetch_and_save_post(1, "post_title.txt")

Then run:

debugonce export .debugonce/session_<timestamp>.json
debugonce replay .debugonce/session_<timestamp>_replay.py

📂 Project Structure

project/
├── your_code.py        
└── .debugonce/
    ├── session_<timestamp>.json    # Generated by `debugonce export`
    ├── session_<timestamp>_replay.py
    ├── debugonce.log

🤝 Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue on the GitHub repository. If you'd like to contribute code:

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Make your changes, including tests if applicable.
4. Ensure all tests pass.
5. Submit a pull request.

or

• 📬 Email: nsjr2002@gmail.com

📄 License

This project is licensed under the MIT License. See the LICENSE file for more details.

🔗 Useful Links

• 📦 PyPI: https://pypi.org/project/debugonce/
• 💻 GitHub: https://github.com/sujithjoseph/debugonce

🏷️ Keywords

debugonce · python debugging · function replay · bug capture · debug decorator · debug CLI · reproducible debugging · python trace logger, debugging, production logging,