🚀 Getting started

Python Utils is a small collection of typed, dependency-light helpers for the patterns you keep rewriting: pulling numbers out of strings, batching iterables, formatting durations, casting dictionaries, and more.

Installation

pip install python-utils

Optional extras:

pip install 'python-utils[loguru]'   # loguru-backed logging mixin

Python 3.10+ is required. The only runtime dependency is typing_extensions, and even that is imported lazily.

Lazy by design

Everything is reachable straight off the top-level package, but nothing is imported until you actually use it (see the performance guide):

import python_utils

python_utils.to_int('port=8080', regexp=True)   # 8080

You can also import from a submodule when you prefer an explicit namespace — the result is identical, and only the modules you touch get loaded:

from python_utils import converters

converters.to_int('port=8080', regexp=True)      # 8080

A five-minute tour

import datetime
import python_utils

# Numbers out of anything
python_utils.to_int('spam15eggs', regexp=True)              # 15

# Human-readable sizes: (value, power-of-1024)
python_utils.scale_1024(2048, 3)                            # (2.0, 1)  -> 2 KiB

# Remap a value between ranges (Decimal-safe)
python_utils.remap(46.0, 0.0, 100.0, -80.0, 10.0)          # -38.6

# Friendly durations
python_utils.format_time(datetime.timedelta(seconds=3661))  # '1:01:01'
python_utils.timesince(
    datetime.datetime.now() - datetime.timedelta(seconds=61)
)                                                           # '1 minute and 1 second ago'

# Batch an iterable
list(python_utils.batcher(range(9), 3))                     # [[0, 1, 2], [3, 4, 5], [6, 7, 8]]

Where to next