https://github.com/easydevv/pyhunt
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.
https://github.com/easydevv/pyhunt
ai colored-log debug decorator developer-tool logging stacktrace terminal trace tree-structure
Last synced: about 11 hours ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/easydevv/pyhunt
- Owner: EasyDevv
- License: mit
- Created: 2025-04-12T02:50:26.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-09-11T16:14:00.000Z (5 months ago)
- Last Synced: 2025-09-13T19:22:55.314Z (5 months ago)
- Topics: ai, colored-log, debug, decorator, developer-tool, logging, stacktrace, terminal, trace, tree-structure
- Language: Python
- Homepage:
- Size: 163 KB
- Stars: 44
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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.
[](https://pypi.org/project/pyhunt/)
[](https://pypi.org/project/pyhunt/)
#### English | [한국어](/README_KR.md)
---
https://github.com/user-attachments/assets/3d4389fe-4708-423a-812e-25f2e7200053
## 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 `AGENTS.md` or `CLAUDE.md`:
```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.
```
### 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`, `--info`, `--warning`, `--error`, `--critical` : Set log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
```bash
hunt --debug # Most detailed logs
hunt --info # Information logs
hunt --warning # Warning logs
hunt --error # Error logs
hunt --critical # Critical logs only
```
- `--root` : Sets the `ROOT_DIR` environment variable to the current directory.
```bash
hunt --root
```
- `--repeat ` : Sets the `HUNT_MAX_REPEAT` environment variable to the specified count. (Log repetition limit)
```bash
hunt --repeat 5
```
- `--color ` : Enable or disable color output in logs.
```bash
hunt --color false
```
- `--log-file ` : Set log file output. If no file is specified, defaults to `.pyhunt.log`.
```bash
hunt --log-file
```
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.