python-utils

⚡ Python Utils

The fast, fully-typed stdlib helpers you keep rewriting — in one tiny, dependency-light package.

PyPI version Python versions CI Coverage Status Typed Ruff License Downloads

Documentation · PyPI · Source · Issues

Python Utils is a collection of small, battle-tested functions and classes that make everyday Python patterns shorter, safer and faster. No sprawling framework, no heavy dependencies — just the helpers you find yourself re-writing in project after project, packaged once and typed to the hilt.

It has powered production code for years (and is used by libraries such as Django Utils and progressbar2).

✨ Highlights

  • 🪶 Zero-cost imports — thanks to PEP 562 lazy loading, import python_utils pulls in nothing until you actually touch a helper. No asyncio, no typing_extensions, until you ask for them.
  • ⚡ Async-native — acount, abatcher, and timeout/stall detectors bring itertools-style ergonomics to async for.
  • 📦 Smart containers — self-casting dicts, duplicate-proof lists and a sliceable deque.
  • 🔢 Forgiving converters — pull an int/float out of any messy string, scale bytes to KiB/MiB, remap values between ranges (with Decimal precision).
  • ⏱️ Time & retries — human-readable durations plus timeout generators for sampling slow APIs without hanging.
  • 🎯 Fully typed & 100% covered — ships py.typed, passes mypy, basedpyright and pyrefly in strict mode, with 100% test coverage.
  • 🐍 Modern & tiny — Python 3.10+, a single runtime dependency (typing_extensions), BSD-3 licensed.

🗺️ What's inside

Module What you get
converters to_int · to_float · to_str · to_unicode · scale_1024 · remap
formatters camel_to_underscore · apply_recursive · timesince
time format_time · timeout_generator · aio_timeout_generator · aio_generator_timeout_detector
generators batcher · abatcher (batch by size or time interval)
aio acount · acontainer — async itertools
containers CastedDict · LazyCastedDict · UniqueList · SliceableDeque
decorators listify · set_attributes · sample · wraps_classmethod
logger Logged · LoggerBase (+ Logurud via the loguru extra)
import_ import_global — programmatic from x import *
exceptions raise_exception · reraise
terminal get_terminal_size — works in shells, IPython & Jupyter
types handy type aliases (Number, Scope, StringTypes, …)

📦 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 it's imported lazily).

🚀 Quickstart

import python_utils

# Pull a number out of any messy string
python_utils.to_int('listening on port=8080', regexp=True)   # 8080

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

# Remap a value between ranges (46% volume -> dB on an AVR)
python_utils.remap(46.0, 0.0, 100.0, -80.0, 10.0)           # -38.6

# "time ago" formatting, Django-style
import datetime
python_utils.timesince(datetime.datetime.now() - datetime.timedelta(seconds=61))
# '1 minute and 1 second ago'

Everything is reachable straight off the top-level package (python_utils.<name>) or from its submodule (python_utils.converters.to_int) — pick whichever reads better. Either way, only the modules you touch get imported.

🧰 Examples

🔢 Converters — numbers out of anything 
from python_utils import converters

# Extract digits with a built-in or custom regexp
converters.to_int('spam15eggs', regexp=True)          # 15
converters.to_int('nope', default=-1)                 # -1
converters.to_float('pi is 3.14', regexp=True)        # 3.14

# Scale bytes to a sensible unit (value, power) -> 2.0 KiB
converters.scale_1024(2048, 3)                         # (2.0, 1)

# Linear remap; pass a Decimal anywhere to keep full precision
converters.remap(500, 0, 1000, 0, 100)                # 50
import decimal
converters.remap(decimal.Decimal('250.0'), 0.0, 1000.0, 0.0, 100.0)
# Decimal('25.0')
📦 Containers — dicts & lists with super-powers 
from python_utils import containers

# Keys and values are cast on the way in
d = containers.CastedDict(int, int)
d['3'] = '4'
d.update({'5': '6'})
d                                   # {3: 4, 5: 6}

# A list that silently drops duplicates (or raises, if you prefer)
u = containers.UniqueList(1, 2, 3)
u.append(2)                         # ignored
u                                   # [1, 2, 3]

# A deque you can actually slice
s = containers.SliceableDeque([1, 2, 3, 4, 5])
s[1:4]                              # SliceableDeque([2, 3, 4])
⚡ Async helpers — itertools for async for 
from python_utils import aio, generators

# Async counter (optionally with a delay and a stop value)
async def demo():
    async for i in aio.acount(stop=3):
        print(i)                    # 0, 1, 2

# Batch an async stream by size OR time interval — whichever comes first.
# Great for chunking bursty producers without ever stalling a slow loop.
async def batched():
    async for batch in generators.abatcher(aio.acount(stop=10), batch_size=3):
        print(batch)                # [0, 1, 2], [3, 4, 5], [6, 7, 8], [9]

# Sync batching too:
list(generators.batcher(range(9), 3))   # [[0, 1, 2], [3, 4, 5], [6, 7, 8]]
⏱️ Time & retries — sample slow APIs, format durations 
import datetime
from python_utils import time

# Loop over a slow operation, but give up after `timeout` seconds
for i in time.timeout_generator(0.1, interval=0.06):
    ...                             # yields 0, 1, 2 then stops

# Format timedeltas, datetimes and raw seconds uniformly
time.format_time(1)                                         # '0:00:01'
time.format_time(datetime.timedelta(seconds=3661))         # '1:01:01'
time.format_time(datetime.datetime(2000, 1, 2, 3, 4, 5))   # '2000-01-02 03:04:05'
time.format_time(None)                                     # '--:--:--'

There's also aio_timeout_generator (the async for twin) and aio_generator_timeout_detector, which fails fast when an async generator stalls instead of hanging forever.

🔤 Formatters — case conversion & friendly timestamps 
from python_utils import formatters

formatters.camel_to_underscore('SpamEggsAndBacon')   # 'spam_eggs_and_bacon'

# Recursively rewrite every key in a nested dict
formatters.apply_recursive(
    formatters.camel_to_underscore,
    {'SpamEggs': {'FooBar': 1}},
)                                                    # {'spam_eggs': {'foo_bar': 1}}
🎀 Decorators — collect generators, tag functions, sample calls 
from python_utils import decorators

# Turn a generator into a concrete collection automatically
@decorators.listify()
def numbers():
    yield 1
    yield 2
    yield 3

numbers()                           # [1, 2, 3]

@decorators.listify(collection=dict)
def pairs():
    yield 'a', 1
    yield 'b', 2

pairs()                             # {'a': 1, 'b': 2}

# Attach metadata to a function (handy for the Django admin)
@decorators.set_attributes(short_description='Name')
def upper_case_name(self, obj):
    return f'{obj.first_name} {obj.last_name}'.upper()

# Only actually run ~10% of the calls
@decorators.sample(0.1)
def maybe_log(msg): ...
📝 Logging — a correctly-named logger on every class 
from python_utils.logger import Logged

class MyClass(Logged):
    def do_work(self):
        self.info('starting %s', 'work')     # stdlib %-style logging args
        self.error('something went wrong')

MyClass().do_work()

Prefer loguru? Install the extra (pip install 'python-utils[loguru]') and subclass Logurud instead — the same self.info(...) / self.error(...) API, backed by loguru so you keep all its configuration and per-instance context.

🖥️ Terminal & 🧩 misc 
from python_utils import terminal, import_
from python_utils.exceptions import raise_exception, reraise

# Robust terminal size (tries IPython/Jupyter, shutil, blessings, ioctl, tput…)
terminal.get_terminal_size()                    # e.g. (80, 24)

# Programmatic `from some_module import *`
import_.import_global('os')

# Build a callable that raises — useful as a default/callback
on_error = raise_exception(ValueError, 'boom')

⚡ Performance: lazy by default

import python_utils is intentionally cheap. Every submodule and every export is wired through a PEP 562 __getattr__, so nothing is imported until first access — and then it's cached. In particular:

  • Need only the synchronous helpers? asyncio is never imported.
  • Even typing_extensions is deferred, so the import graph stays minimal.
import sys
import python_utils                 # imports basically nothing extra

'asyncio' in sys.modules            # False
python_utils.acount                 # now `aio` (and asyncio) load, on demand

See the performance guide for the full story.

📚 Documentation

Full API reference and guides live at https://python-utils.readthedocs.io/en/latest/.

🔗 Links

🔒 Security

To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.

🤝 Contributing

Contributions are very welcome! We keep a strict 100% coverage bar and run ruff, three type checkers and the full test matrix in CI. See CONTRIBUTING.md to get set up.

📄 License

BSD-3-Clause — see LICENSE.

Project links

Data verified by PyPI on Aug 30, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for jhammudoglu from gravatar.com jhammudoglu Avatar for wolph from gravatar.com wolph

Credits

Author: Rick van Hattem

GitHub Statistics

Data verified by PyPI on Aug 30, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

BSD-3-Clause
View SPDX License List

Requires

Python >=3.10

Provides Extra

docs loguru tests

Tags

utils utilities helpers typing typed async lazy-imports

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

python_utils-4.0.1.tar.gz (43.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

python_utils-4.0.1-py3-none-any.whl (39.9 kB view details)

Uploaded Python 3

File details

Details for the file python_utils-4.0.1.tar.gz.

File metadata

  • Download URL: python_utils-4.0.1.tar.gz
  • Upload date:
  • Size: 43.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for python_utils-4.0.1.tar.gz
Algorithm Hash digest
SHA256 4e8e8ecaba3862f843a60c1982c99cda23b522f417006a807996a876c18beb8d
MD5 1e9da9fbaf96200705393e02cea5b4ed
BLAKE2b-256 5d71ec6665d4ce42ee5a59fffd31a4d5164f92da15ccb8c758dba13d2419ea53

See more details on using hashes here.

Provenance

The following attestation bundles were made for python_utils-4.0.1.tar.gz:

Publisher: publish.yml on wolph/python-utils

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file python_utils-4.0.1-py3-none-any.whl.

File metadata

  • Download URL: python_utils-4.0.1-py3-none-any.whl
  • Upload date:
  • Size: 39.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for python_utils-4.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 6017bb56498a58656ecf48e66fb1f1632c7b33f9f2968548a021563e85be1aed
MD5 2fa5da295d1e33319c3feb01c3b294cc
BLAKE2b-256 654ddf2b7b53f759af128123afc73ce7094a29286ef4293dfeb2341f8469018e

See more details on using hashes here.

Provenance

The following attestation bundles were made for python_utils-4.0.1-py3-none-any.whl:

Publisher: publish.yml on wolph/python-utils

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

4.0.1 This release

2 files

4.0.0

2 files

3.9.1

2 files

3.9.0

2 files

3.8.2

2 files

3.8.1

2 files

3.8.0

2 files

3.7.0

2 files

3.6.1

2 files

3.6.0

2 files

3.5.2

2 files

3.5.1

2 files

3.5.0

2 files

3.4.5

2 files

3.4.4

2 files

3.4.3

2 files

3.4.2

2 files

3.4.1

2 files

3.4.0

2 files

3.3.3

2 files

3.3.2

2 files

3.3.1

2 files

3.3.0

2 files

3.2.3

2 files

3.2.2

2 files

3.2.1

2 files

3.2.0

2 files

3.1.0

2 files

3.0.0

2 files

2.7.1

2 files

2.7.0

2 files

2.6.3

2 files

2.6.2

2 files

2.6.1

2 files

2.6.0

2 files

2.5.6

2 files

2.5.5

2 files

2.5.3

2 files

2.5.2

2 files

2.5.1

2 files

2.5.0

2 files

2.4.0

2 files

2.3.0

2 files

2.2.0

2 files

2.1.0

2 files

2.0.1

2 files

2.0.0

2 files

1.6.2

1 file

1.6.1

1 file

1.6.0

1 file

1.5.2

1 file

1.5.1

1 file

1.5.0

1 file

1.1.2

1 file

1.1.1

1 file

1.1.0

1 file

1.0.1

2 files

1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page