<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.

English | 한국어

---

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

pip install pyhunt

Install with uv

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.

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 folder.

Basic Example

from pyhunt import trace

@trace
def test(value):
    return value

Asynchronous Function

@trace
async def test(value):
    return value

Class

@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:

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

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.

hunt [options]

Supported Options

• --debug, --info, --warning, --error, --critical : Set log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)

  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.

  hunt --root
  

• --repeat <count> : Sets the HUNT_MAX_REPEAT environment variable to the specified count. (Log repetition limit)

  hunt --repeat 5
  

• --color <true|false> : Enable or disable color output in logs.

  hunt --color false
  

• --log-file <file> : Set log file output. If no file is specified, defaults to .pyhunt.log.

  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.