pyutilkit: python's missing batteries

Python has long maintained the philosophy of "batteries included", providing users with a rich standard library that avoids the need for third-party tools for most tasks. Some packages are so common they have achieved similar status to the standard library. Yet, certain utilities are reimplemented across countless projects. This lightweight library, with minimal dependencies, aims to eliminate that repetition.

Quick Start

Install pyutilkit:

pip install pyutilkit

Or with uv (recommended for speed):

uv pip install pyutilkit

Basic usage example:

from pyutilkit.date_utils import now
from pyutilkit.timing import Stopwatch
from pyutilkit.term import SGRString, SGRCodes

# Get current time in any timezone
from zoneinfo import ZoneInfo

tokyo_time = now(ZoneInfo("Asia/Tokyo"))
print(f"Current time in Tokyo: {tokyo_time}")

# Measure execution time
stopwatch = Stopwatch()
with stopwatch:
    # Your code here
    result = sum(range(1000000))
print(f"Computation took: {stopwatch.elapsed}")

# Colorful terminal output
success = SGRString("✓ Task completed", params=[SGRCodes.GREEN, SGRCodes.BOLD])
success.print()

Key Features

• 🕐 Timezone Utilities: Robust datetime handling with cross-platform timezone support, ISO parsing (including Zulu timezone), and seamless timezone conversion
• ⏱️ High-Precision Timing: Nanosecond-precision timing with human-readable formatting, lap tracking, and stopwatch functionality
• 🎨 Terminal Formatting: ANSI color codes with smart TTY detection, automatic style stripping for piped output, and convenient header formatting
• 🛡️ Error Handling: Elegant exception handling decorator that logs errors and returns defaults instead of raising exceptions
• 📁 File Utilities: Efficient SHA-256 file hashing with buffered reading for large files
• 🚀 Subprocess Enhancement: Run external commands with real-time output streaming, automatic timing, and structured results
• 🔧 Design Patterns: Thread-safe Singleton metaclass implementation
• ✨ Zero Dependencies: Pure Python using only standard library (except optional tzdata on Windows)
• 🧪 Fully Tested: 100% test coverage with comprehensive type annotations

Documentation

• Installation Guide - Setup instructions and requirements
• Usage Guide - Comprehensive examples and tutorials for all modules
  • Classes - Singleton pattern implementation
  • Date Utilities - Timezone-aware datetime operations
  • File Utilities - Exception handling and file hashing
  • Subprocess - Enhanced command execution
  • Terminal - Terminal formatting and colors
  • Timing - Performance measurement and benchmarking
• Changelog - Version history and changes
• Code of Conduct - Community guidelines

Requirements

• Python 3.10 or higher
• No external dependencies (tzdata is automatically installed on Windows)

Links

• Full Documentation
• PyPI Package
• GitHub Repository
• Changelog
• Report Issues