Metadata-Version: 2.1
Name: debugonce
Version: 0.6.3
Summary: Effortlessly capture and reproduce bugs in your python code
Home-page: https://github.com/Sujith-sunny/debugonce
Author: Sujith Joseph
Author-email: nsjr2002@gmail.com
License: MIT
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,
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click
Requires-Dist: psutil
Requires-Dist: requests

# 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`,
