pyhunt 1.2.0
Lightweight Python logging tool for visual call tracing, tree-structured colored logs, and easy debugging with a simple decorator. Optimized for both standard and AI-generated codebases. 
Requires Python: >=3.12

<div align="center">

<img src="docs/logo.png" alt="pyhunt_logo" width="200"/>

# pyhunt

`pyhunt` is a lightweight logging tool that visually represents logs for quick structural understanding and debugging.  
Simply add a decorator to your functions, and all logs are automatically traced and displayed in your terminal.

[![PyPI version](https://img.shields.io/pypi/v/pyhunt.svg)](https://pypi.org/project/pyhunt/)
[![Python Versions](https://img.shields.io/pypi/pyversions/pyhunt.svg)](https://pypi.org/project/pyhunt/)

#### English | [한국어](/README_KR.md)

---

https://github.com/user-attachments/assets/3d4389fe-4708-423a-812e-25f2e7200053

<img src="docs/description.png" alt="pyhunt_description" width="600"/>

</div>

## Features

- **Automatic Function/Method Call Tracing**: Automatically records the flow of synchronous/asynchronous functions and classes with a single `@trace` decorator.
- **Rich Colors and Tree-Structured Logs**: Enhances readability with color and indentation based on call depth.
- **Multiple Log Levels Supported**: DEBUG, INFO, WARNING, ERROR, CRITICAL.
- **Set Log Level via CLI**: Manage and store `HUNT_LEVEL` in a `.env` file.
- **Optimized for AI Workflows**: Easily trace code generated by AI.
- **Detailed Exception Information**: Includes call arguments, location, and stack trace on exceptions.

## Installation

### Install with pip
```bash
pip install pyhunt
```

### Install with uv
```bash
uv add pyhunt
```

## Quick Start

### 1. Set Up and Manage Environment Variable File
You can set up and manage the `.env` file by running the `hunt` command.

```bash
hunt
```

Executing the above command sets `HUNT_LEVEL=DEBUG` and `ROOT_DIR` to the current directory in the `.env` file.

### 2. Apply `@trace` to Functions or Classes
See more examples in the [examples](https://github.com/pyhunt/pyhunt/tree/main/examples) folder.

#### Basic Example
```py
from pyhunt import trace

@trace
def test(value):
    return value
```

#### Asynchronous Function
```py
@trace
async def test(value):
    return value
```

#### Class
```py
@trace
class MyClass:
    def first_method(self, value):
        return value

    def second_method(self, value):
        return value
```

## Using with AI

### Rule Setup
Add the following rules to `.cursorrules`, `.clinerules`, or `.roorules`:

```md
<logging-rules>

**Import:** Import the decorator with `from pyhunt import trace`.
**Tracing:** Use the `@trace` decorator to automatically log function calls and execution times.
**Avoid `print()`:** Do not use the `print()` function.
**Exception Handling:** Use `try`/`except Exception as e: raise e` blocks to maintain traceback.

</logging-rules>
```

### Modifying Existing Codebase
Prompt: **"Modify the code according to the logging rules."**

## Logger Usage

The `logger` interface is recommended for use only in important sections.  
Most actions are traced via `@trace`, and excessive use may reduce readability.

```py
from pyhunt import logger

logger.debug("This is a debug log.")
logger.info("This is an info log.")
logger.warning("This is a warning log.")
logger.error("This is an error log.")
logger.critical("This is a critical log.")
```

## CLI Usage

You can manage log levels and other settings using the `hunt` command.

```bash
hunt [options]
```

### Supported Options

- `--debug` : DEBUG level (most detailed)
- `--info` : INFO level
- `--warning` : WARNING level
- `--error` : ERROR level
- `--critical` : CRITICAL level
- `--root` : Sets the `ROOT_DIR` environment variable to the current directory.
- `--repeat <count>` : Sets the `HUNT_MAX_REPEAT` environment variable to the specified count. (Log repetition limit)
- `--color <true|false>` : Enable or disable color output in logs.
- `--log-file [file]` : Set log file output. If no file is specified, defaults to `.pyhunt.log`.

If no option is specified, the default is `DEBUG`.

### Environment Variables

`pyhunt` supports the following environment variables through the `.env` file:

- `HUNT_LEVEL`: Sets the log level (DEBUG, INFO, WARNING, ERROR, CRITICAL). Default is `DEBUG`.
- `HUNT_MAX_REPEAT`: The number of times the same log is displayed when repeated. Default is 3.
- `ELAPSED`: Sets whether to display function execution time in logs (`True` or `False`). Default is `True`.
- `HUNT_COLOR`: Sets whether to enable color output (`True` or `False`). Default is `True`.
- `HUNT_LOG_FILE`: Sets the file path for log output. If not specified, logs are only displayed in the terminal.
- `ROOT_DIR`: Sets the base directory for log output. Displays paths more accurately.