pyhunt: Instructions file for Codex

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

pyhunt is a lightweight Python logging tool that automatically traces function calls and provides visual, tree-structured colored logs for debugging. It uses a simple @trace decorator to log function execution times, call hierarchies, and exceptions.

Development Commands

Package Management

# Install dependencies
uv sync

# Build the package
uv build

Python Execution

# Run Python files with uv
uv run python filename.py

# Run Python modules with uv
uv run python -m module_name

# Run Python interactively with uv
uv run python

Testing

# Run all tests
uv run pytest

# Run specific test file
uv run pytest test/test_examples.py

# Run tests with verbose output
uv run pytest -v

Code Quality

# Lint all files in the current directory
uvx ruff check

# Format all files in the current directory
uvx ruff format

CLI Tool

# Set up environment file (creates .env with DEBUG level)
hunt

# Set specific log levels
hunt --debug
hunt --info
hunt --warning
hunt --error
hunt --critical

# Set root directory and repeat limit
hunt --root
hunt --repeat 5

Core Architecture

Main Components

• pyhunt/decorator.py: Core @trace decorator implementation for function call tracing
• pyhunt/cli.py: Command-line interface for managing log levels and environment variables
• pyhunt/logger.py: Direct logging interface for manual log messages
• pyhunt/console.py: Console output formatting and color handling
• pyhunt/config.py: Environment variable configuration and .env file management
• pyhunt/colors.py: Color definitions for different log levels
• pyhunt/context.py: Call context management for tracking execution depth
• pyhunt/utils.py: Utility functions for path handling and formatting
• pyhunt/helpers.py: Helper functions for decorator and logging operations