<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)
</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 Environment Variable File
```bash
hunt
```
This command sets `HUNT_LEVEL=DEBUG` in your `.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 Methods
```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` blocks and re-raise exceptions with `raise` to maintain traceback.

</logging-rules>
```

### Modifying Existing Codebase
Command: **"Modify the codebase according to the logging rules."**

## Logger Usage

The `logger` interface is recommended for use only in critical 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

```bash
hunt [options]
```

### Supported Options

- `--debug` : DEBUG level (most detailed)
- `--info` : INFO level
- `--warning` : WARNING level
- `--error` : ERROR level
- `--critical` : CRITICAL level

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