Install & Compatibility
Where this runs
tested against v4.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.032s · 18.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.032s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
UniqueList
✓ from python_utils import UniqueList
SlicableDeque
✓ from python_utils import SlicableDeque
to_int
✓ from python_utils.converters import to_int
✗ from python_utils import to_int
While some top-level imports exist, importing from specific submodules like `converters` is clearer and often recommended if the symbol is not directly exposed at the top level or to avoid name collisions. The documentation shows examples of both direct and submodule imports.
listify
✓ from python_utils.decorators import listify
✗ from python_utils import listify
Importing from specific submodules like `decorators` is clearer and often recommended, though some functions might be exposed at the top-level for convenience.
Logged
✓ from python_utils.logger import Logged
✗ from python_utils import Logged
Importing logging utilities from the `logger` submodule ensures clarity.
This quickstart demonstrates how to use the `to_int` converter to safely extract integers from strings and the `listify` decorator to convert generator output into a list.
from python_utils.converters import to_int
from python_utils.decorators import listify
# Convert a string to an integer, with a default if conversion fails
num = to_int('spam15eggs')
print(f"Converted 'spam15eggs' to {num}")
default_num = to_int('spam', default=1)
print(f"Converted 'spam' with default to {default_num}")
# Use a decorator to automatically convert a generator to a list
@listify()
def generate_numbers():
yield 1
yield 2
yield 3
my_list = generate_numbers()
print(f"Generator output as a list: {my_list}")
Debug
Known issues
gotchaWhen migrating from `python-utils` v2.x.x (Python 2 compatible) to v3.x.x (Python 3+), note that v3.x.x explicitly requires Python 3.9 or higher and has no other external dependencies. Compatibility with Python 2 requires the `six` package and older library versions.fixEnsure your project is running on Python 3.9+ for `python-utils` v3.x.x. If using older Python 3 versions, you might need older `python-utils` releases and potentially address `typing-extensions` compatibility if encountering type-hinting issues.
affects: <3.0.0 to >=3.0.0
gotchaAvoid incorrect top-level imports like `import utils`. The correct package name is `python_utils`, and you should import specific classes, functions, or submodules from `python_utils` (e.g., `from python_utils import UniqueList` or `from python_utils.converters import to_int`).fixAlways use `import python_utils` or `from python_utils import <symbol>` / `from python_utils.<submodule> import <symbol>`.
affects: All versions
gotchaIn `v3.8.2`, a fix was introduced for `fromtimestamp` overflow issues on Windows, where it previously raised a `ValueError` but can now also raise an `OSError`. This might affect code handling timestamp conversions.fixUpgrade to `v3.8.2` or higher and ensure your code handles both `ValueError` and `OSError` when working with `datetime.fromtimestamp` and potentially large or invalid timestamp values, especially on Windows.
affects: <3.8.2
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'utils'
The `python-utils` library is installed via `pip install python-utils`, but the user is attempting to import it using the incorrect top-level module name `utils` instead of `python_utils`.
ImportError: cannot import name 'UniqueList' from 'python_utils'
The `UniqueList` class is part of the `python_utils.lists` submodule, not directly available under the main `python_utils` package.
fixfrom python_utils.lists import UniqueList
ImportError: cannot import name 'memoize' from 'python_utils'
The `memoize` decorator is located within the `python_utils.decorators` submodule, not directly in the top-level `python_utils` package.
fixfrom python_utils.decorators import memoize
TypeError: 'collections.deque' object does not support item assignment
While `SlicableDeque` (which inherits from `collections.deque`) allows retrieving elements using slice notation, it does not implement slice assignment (e.g., `my_deque[1:3] = [new_items]`) because this functionality is not supported by its base class `collections.deque`.
fixTo modify elements in a range, use `SlicableDeque`'s `del_slice()` method to remove the old elements, and then use `insert()` or `extend()` to add new ones at the desired position.
Upgrade
Version history
4.0.0latest on PyPI · released Jul 2, 2026
Audit
Dependencies
No dependency data recorded yet.