🐍 python-utils-toolkit

A collection of practical, production-ready Python utilities built while working on crypto trading bots and AI agent systems. Pure Python — zero external dependencies.

Modules

Module	Description
utils/retry.py	@retry with exponential backoff + jitter
utils/rate_limiter.py	Token-bucket rate limiter (sync + async)
utils/timer.py	@timer decorator + Timer context manager
utils/file_helpers.py	Safe read/write, atomic saves, JSON helpers
utils/logger.py	Structured logging with colour + file rotation
utils/env.py	Typed .env / environment variable loader
utils/string_utils.py	slugify, truncate, camel_to_snake
utils/datetime_utils.py	UTC helpers, humanize_delta, market hours
utils/number_utils.py	Currency format, tick rounding, pct_change
utils/list_utils.py	chunk, flatten, deduplicate, batch_by
utils/dict_utils.py	deep_merge, safe_get, flatten_dict
utils/cache_utils.py	TTLCache + @memoize for API caching
utils/async_utils.py	async retry, timeout, gather_safe
utils/crypto_utils.py	HMAC-SHA256 signing, nonce generation
utils/validation_utils.py	Guard clauses, symbol/email validation

Quick Start

git clone https://github.com/Ghraven/python-utils-toolkit
cd python-utils-toolkit
python examples/retry_demo.py

Examples

Retry with backoff

from utils.retry import retry

@retry(max_attempts=3, base_delay=1.0, exceptions=(ConnectionError,))
def fetch_price(symbol: str) -> float:
    return api.get_price(symbol)

Rate limiter (Binance API)

from utils.rate_limiter import RateLimiter

limiter = RateLimiter(calls_per_second=5)
for symbol in watchlist:
    limiter.acquire()
    price = fetch_price(symbol)

Sign exchange API request

from utils.crypto_utils import hmac_sha256, timestamp_nonce

params = f"symbol=BTCUSDT&side=BUY&timestamp={timestamp_nonce()}"
signature = hmac_sha256(api_secret, params)

Cache API responses (avoid rate limits)

from utils.cache_utils import memoize

@memoize(ttl=30)
def get_ticker(symbol: str) -> dict:
    return exchange.fetch_ticker(symbol)

Async retry for websocket streams

from utils.async_utils import async_retry

@async_retry(max_attempts=3, base_delay=0.5)
async def fetch_orderbook(symbol: str) -> dict:
    return await ws.get_orderbook(symbol)

Why

Built for a live crypto futures trading bot (BTC/ETH/BNB/SOL on Binance) and multi-agent AI systems. When you're calling exchange APIs, running LLM chains, and processing live streams, you need reliable retry logic, rate limiting, and clean logging — without heavy frameworks.

License

MIT