boltons

library25.0.0pypypi✓ verified 49d ago

boltons is a collection of over 250 pure-Python utilities designed to fill gaps in Python's standard library. It provides high-performance data structures and convenient functions for common tasks across various domains like file systems, iteration, caching, and time management. The library maintains an active development status, with major releases occurring roughly annually, interspersed with minor updates bringing enhancements and bug fixes. [1, 4, 5, 6, 8, 11]

data serialization devops observability

pip install boltons

github ↗package ↗

Install & Compatibility

Where this runs

tested against v25.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.930 runs

installs and imports cleanly · install 0.0s · import 0.000s · 19MB

glibc

py 3.10–3.930 runs

installs and imports cleanly · install 1.6s · import 0.000s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

OrderedMultiDict

✓ from boltons.dictutils import OrderedMultiDict

A dictionary subclass that remembers insertion order and allows multiple values per key.

remap

✓ from boltons.iterutils import remap

For recursively traversing and transforming nested data structures.

LRU

✓ from boltons.cacheutils import LRU

A dictionary-like Least Recently Used (LRU) cache.

mkdir_p

✓ from boltons.fileutils import mkdir_p

Creates a directory and any necessary parent directories, similar to 'mkdir -p'.

This example demonstrates the `OrderedMultiDict` from `boltons.dictutils`, which allows storing multiple values for a single key while preserving insertion order. It's useful for scenarios where a standard dictionary's behavior is insufficient. [5, 6]

from boltons.dictutils import OrderedMultiDict # Initialize the OrderedMultiDict omd = OrderedMultiDict() # Add items - supports multiple values for a single key omd['fruit'] = 'apple' omd['fruit'] = 'banana' omd['vegetable'] = 'carrot' # Access all values for a key print(f"All fruits: {omd['fruit']}") # Expected output: All fruits: ['apple', 'banana'] # Get the first value for a key print(f"First fruit: {omd.get_first('fruit')}") # Expected output: First fruit: apple # Iterate through all key-value pairs (maintaining insertion order) print("\nAll items:") for key, value in omd.items(): print(f"{key}: {value}") # Expected output: # All items: # fruit: apple # fruit: banana # vegetable: carrot

Debug

Known issues

breakingVersion 24.0.0 dropped support for Python 2. boltons is now Python 3 only (3.7+). If you are on Python 2, you must pin your dependency to `boltons<24.0.0`.

fix

Upgrade to Python 3.7+ or pin boltons to a version less than 24.0.0 (e.g., `pip install 'boltons<24.0.0'`).

affects: >=24.0.0

deprecatedIn version 25.0.0, the use of `datetime.utcnow()` was replaced internally due to its deprecation in Python 3.12. While this was an internal change, direct usage of `utcnow()` in user code, especially when interacting with boltons' `timeutils`, should be updated to `datetime.now(timezone.utc)` for future compatibility and best practice.

fix

Replace `datetime.utcnow()` with `datetime.now(timezone.utc)`.

affects: >=25.0.0

gotchaDue to its nature as a collection of self-contained utilities with no external dependencies, boltons supports 'vendorization' of individual modules. If the full library is too large for your project, or for tighter integration, you can copy specific modules (e.g., `fileutils.py`) directly into your project.

fix

Consider copying individual modules into your project if you only need a small subset of functionality or prefer zero dependencies for those specific utilities. Refer to the 'Integration' section of the boltons documentation for more details. [7, 11]

affects: All

breakingThe `get_first` method was removed from `boltons.dictutils.OrderedMultiDict`. This method was associated with `NamedMapping`, which was removed in boltons version 23.1.0. Direct usage of `get_first` on `OrderedMultiDict` will now result in an `AttributeError`.

fix

Replace `omd.get_first(key)` with `omd.getlist(key)[0]` if you expect at least one value to exist. For safer access that handles empty lists, consider `(omd.getlist(key) or [None])[0]` or `next(iter(omd.getlist(key)), None)`.

affects: >=23.1.0

breakingIn version 23.0.0, the `OrderedMultiDict.get_first()` method was removed. Code relying on this method will raise an AttributeError. Use `OrderedMultiDict.get(key)` to retrieve the first value, or `OrderedMultiDict.getlist(key)` to get all values as a list.

fix

Replace `omd.get_first(key)` with `omd.get(key)` for the first value, or `omd.getlist(key)` for all values. Alternatively, pin `boltons` to a version less than 23.0.0 (e.g., `pip install 'boltons<23.0.0'`).

affects: >=23.0.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'boltons'

The `boltons` library or a specific submodule was not found in the Python environment, typically because it was not installed or the wrong environment is active.

fix

Ensure `boltons` is installed in your current environment using `pip install boltons`.

ModuleNotFoundError: No module named 'boltons.cacheutils'

While `boltons` might be installed, a specific submodule like `cacheutils` is being imported incorrectly or is missing, or the Python environment is not correctly configured to find the installed package.

fix

Verify `boltons` is installed and then ensure the import statement correctly reflects the module structure, e.g., `from boltons.cacheutils import cachedproperty`.

ERROR: Could not find a version that satisfies the requirement boltons

This error usually occurs during installation when pip cannot find a compatible version of `boltons` for your Python version or due to network issues preventing access to PyPI.

fix

Check your Python version (`python --version`) against `boltons`'s supported versions (>=3.7). Ensure pip is up-to-date (`pip install --upgrade pip`) and try installing in a fresh virtual environment: `python -m venv myenv && source myenv/bin/activate && pip install boltons`.

TypeError: bytes expected, got <type 'str'>

This error occurs when a `boltons` utility, such as `SpooledBytesIO` from `boltons.ioutils`, expects bytes-like objects but receives a string (str) instead.

fix

Convert the string to bytes before passing it to the `boltons` utility. For example, instead of `f.write('Happy IO')`, use `f.write(b'Happy IO')`.

Upgrade

Version history

25.0.0latest on PyPI

Audit

Dependencies

No dependency data recorded yet.

Agent activity

37 hits · last 30 days

seranking-bot

mj12bot

ahrefsbot

Amazon

amazonbot

bytedance

googlebot

Resources

githubhttps://github.com/mahmoud/boltons ↗

packagehttps://pypi.org/project/boltons/ ↗