debugonce 0.6.3
Effortlessly capture and reproduce bugs in your python code
License: MIT
Requires Python: >=3.8
Keywords: debugonce, debugging, bug reproduction, python, error tracking, error reporting, , error handling, bug capture, bug reproduction, python debugging, error reproduction, , error logging, bug tracking, bug reporting, error analysis, debugging tools, , error handling tools, bug capture tools, bug reproduction tools, python error tracking, python error reporting, python error handling, , python bug capture, python bug reproduction, python debugging tools, , python error handling tools, python bug capture tools, python bug reproduction tools, python error logging, python bug tracking, python bug reporting, 

# debugonce

**Effortlessly capture and reproduce bugs in your Python code.**

[![PyPI Downloads](https://static.pepy.tech/badge/debugonce)](https://pepy.tech/projects/debugonce)
[![PyPI](https://img.shields.io/pypi/v/debugonce.svg)](https://pypi.org/project/debugonce/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Python Versions](https://img.shields.io/pypi/pyversions/debugonce.svg)](https://pypi.org/project/debugonce/)

---

## 🔍 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

```bash
pip install debugonce
```

---
## 🚀 Basic Usage

### 1. Decorate Your Function
To capture the state of a function, simply decorate it with `@debugonce`:


```python
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

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

---

## 🛠️ CLI Commands

### 🔎 List All Sessions

```bash
debugonce list
```

### 🧾 Inspect a Session

```bash
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:
```bash
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.
```bash
debugonce replay .debugonce/session_<timestamp>.json
```

### 🧹 Clean All Sessions

```bash
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

```python
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:

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

---

## 📂 Project Structure

```text
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](mailto:nsjr2002@gmail.com)

---

## 📄 License

This project is licensed under the [MIT License](https://opensource.org/licenses/MIT). See the `LICENSE` file for more details.

---

## 🔗 Useful Links

- 📦 PyPI: [https://pypi.org/project/debugonce/](https://pypi.org/project/debugonce/)
- 💻 GitHub: [https://github.com/sujithjoseph/debugonce](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`,