|GithubActions| |ReadTheDocs| |Pypi| |Downloads| |Codecov| |CircleCI| |Appveyor|

.. .. |CodeQuality| |TwitterFollow|

.. The large version wont work because github strips rst image rescaling. https://i.imgur.com/AcWVroL.png .. image:: https://i.imgur.com/PoYIsWE.png :height: 100px :align: left

.. .. raw:: html .. <img src="https://i.imgur.com/AcWVroL.png" height="100px">

Ubelt is a standard-library companion: a collection of ~120 focused utilities that make everyday Python tasks shorter, cleaner, and more consistent.

Here are some of the things it does best:

• Progress reporting → ub.ProgIter <https://ubelt.readthedocs.io/en/latest/auto/ubelt.progiter.html>__ (faster, simpler alternative to tqdm)
• Hashing → ub.hash_data <https://ubelt.readthedocs.io/en/latest/auto/ubelt.util_hash.html#ubelt.util_hash.hash_data>, ub.hash_file <https://ubelt.readthedocs.io/en/latest/auto/ubelt.util_hash.html#ubelt.util_hash.hash_file>
• Caching → ub.Cacher <https://ubelt.readthedocs.io/en/latest/auto/ubelt.util_cache.html#ubelt.util_cache.Cacher>, ub.CacheStamp <https://ubelt.readthedocs.io/en/latest/auto/ubelt.util_cache.html#ubelt.util_cache.CacheStamp>
• Shell commands → ub.cmd <https://ubelt.readthedocs.io/en/latest/auto/ubelt.util_cmd.html#ubelt.util_cmd.cmd>__
• Set-enriched dictionaries → ub.udict <https://ubelt.readthedocs.io/en/latest/auto/ubelt.util_dict.html#ubelt.util_dict.UDict>__

Beyond that, you'll find helpers for downloading data, parallel job execution, path management, repr formatting, and more.

Ubelt is:

• Lightweight – pure Python, minimal dependencies, fast import.
• Reliable – mature, actively maintained since 2017, with high test coverage.
• Cross-platform – consistent behavior on Linux, Mac, and Windows.

Check out the function usefulness chart <https://ubelt.readthedocs.io/en/latest/index.html#the-api-by-usefulness>__ to see what gets the most mileage in real projects.

Introduction:

Ubelt is a lightweight library of robust, tested, documented, and simple functions that extend the Python standard library. It has a flat API that all behaves similarly on Windows, Mac, and Linux (up to some small unavoidable differences). Almost every function in ubelt was written with a doctest. This provides helpful documentation and example usage as well as helping achieve 100% test coverage (with minor exceptions on Windows).

• Goal: provide simple functions that accomplish common tasks not yet addressed by the python standard library.

• Constraints: Must be low-impact pure python; it should be easy to install and use.

• Method: All functions are written with docstrings and doctests to ensure that a baseline level of documentation and testing always exists (even if functions are copy/pasted into other libraries)

• Motto: Good utilities lift all codes.

Read the docs here: https://ubelt.readthedocs.io/en/latest

These are some of the tasks that ubelt's API enables:

• extended pathlib with expand, ensuredir, endswith, augment, delete (ub.Path)

• get paths to cross platform data/cache/config directories (ub.Path.appdir, ...)

• perform set operations on dictionaries (SetDict)

• a dictionary with extended helper methods like subdict, take, peek_value, invert, sorted_keys, sorted_vals (UDict)

• hash common data structures like list, dict, int, str, etc. (hash_data)

• hash files (hash_file)

• cache a block of code (Cacher, CacheStamp)

• time a block of code (Timer)

• show loop progress with less overhead than tqdm (ProgIter)

• download a file with optional caching and hash verification (download, grabdata)

• run shell commands (cmd)

• find a file or directory in candidate locations (find_path, find_exe)

• string-repr for nested data structures (urepr)

• color text with ANSI tags (color_text)

• horizontally concatenate multiline strings (hzcat)

• create cross platform symlinks (symlink)

• import a module using the path to that module (import_module_from_path)

• check if a particular flag or value is on the command line (argflag, argval)

• memoize functions (memoize, memoize_method, memoize_property)

• build ordered sets (oset)

• argmax/min/sort on lists and dictionaries (argmin, argsort,)

• get a histogram of items or find duplicates in a list (dict_hist, find_duplicates)

• group a sequence of items by some criterion (group_items)

Ubelt is small. Its top-level API is defined using roughly 40 lines:

.. code:: python

from ubelt.util_arg import (argflag, argval,)
from ubelt.util_cache import (CacheStamp, Cacher,)
from ubelt.util_colors import (NO_COLOR, color_text, highlight_code,)
from ubelt.util_const import (NoParam,)
from ubelt.util_cmd import (cmd,)
from ubelt.util_dict import (AutoDict, AutoOrderedDict, SetDict, UDict, ddict,
                             dict_diff, dict_hist, dict_isect, dict_subset,
                             dict_union, dzip, find_duplicates, group_items,
                             invert_dict, map_keys, map_vals, map_values,
                             named_product, odict, sdict, sorted_keys,
                             sorted_vals, sorted_values, udict, varied_values,)
from ubelt.util_deprecate import (schedule_deprecation,)
from ubelt.util_download import (download, grabdata,)
from ubelt.util_func import (compatible, identity, inject_method,)
from ubelt.util_repr import (ReprExtensions, urepr,)
from ubelt.util_futures import (Executor, JobPool,)
from ubelt.util_io import (delete, touch,)
from ubelt.util_links import (symlink,)
from ubelt.util_list import (allsame, argmax, argmin, argsort, argunique,
                             boolmask, chunks, compress, flatten, iter_window,
                             iterable, peek, take, unique, unique_flags,)
from ubelt.util_hash import (hash_data, hash_file,)
from ubelt.util_import import (import_module_from_name,
                               import_module_from_path, modname_to_modpath,
                               modpath_to_modname, split_modpath,)
from ubelt.util_indexable import (IndexableWalker, indexable_allclose,)
from ubelt.util_memoize import (memoize, memoize_method, memoize_property,)
from ubelt.util_mixins import (NiceRepr,)
from ubelt.util_path import (ChDir, Path, TempDir, augpath, ensuredir,
                             expandpath, shrinkuser, userhome,)
from ubelt.util_platform import (DARWIN, LINUX, POSIX, WIN32, find_exe,
                                 find_path, platform_cache_dir,
                                 platform_config_dir, platform_data_dir,)
from ubelt.util_str import (codeblock, hzcat, indent, paragraph,)
from ubelt.util_stream import (CaptureStdout, CaptureStream, TeeStringIO,)
from ubelt.util_time import (Timer, timeparse, timestamp,)
from ubelt.util_zip import (split_archive, zopen,)
from ubelt.orderedset import (OrderedSet, oset,)
from ubelt.progiter import (ProgIter,)

Installation:

Ubelt is distributed on pypi as a universal wheel and can be pip installed on Python 3.6+. Installations are tested on CPython and PyPy implementations.

::

pip install ubelt

Note that our distributions on pypi are signed with GPG. The signing public key is D297D757; this should agree with the value in dev/public_gpg_key.

For older versions of Python, this table provides the last officially supported version of ubelt.

+------------------+---------------------------------------------+ | Python Version | Most Recent Supported Ubelt Version | +==================+=============================================+ | 3.8 - 3.14 | latest | +------------------+---------------------------------------------+ | 3.6 - 3.7 | 1.3.8 | +------------------+---------------------------------------------+ | 2.7, 3.5 | 0.11.1 | +------------------+---------------------------------------------+ | 3.4 | 0.6.1 | +------------------+---------------------------------------------+

Function Usefulness

When I had to hand pick a set of functions that I thought were the most useful I chose these and provided some comment on why:

.. code:: python

import ubelt as ub

ub.Path  # inherits from pathlib.Path with quality of life improvements
ub.UDict  # inherits from dict with keywise set operations and quality of life improvements
ub.Cacher  # configuration based on-disk caching
ub.CacheStamp  # indirect caching with corruption detection
ub.hash_data  # hash mutable python containers, useful with Cacher to config strings
ub.cmd  # combines the best of subprocess.Popen and os.system
ub.download  # download a file with a single command. Also see grabdata for the same thing, but caching from CacheStamp.
ub.JobPool   # easy multi-threading / multi-procesing / or single-threaded processing
ub.ProgIter  # a minimal progress iterator. It's single threaded, informative, and faster than tqdm.
ub.memoize  # like ``functools.cache``, but uses ub.hash_data if the args are not hashable.
ub.urepr  # readable representations of nested data structures

But a better way might to objectively measure the frequency of usage and built a histogram of usefulness. I generated this histogram using python dev/maintain/gen_api_for_docs.py, which roughly counts the number of times I've used a ubelt function in another project.

The objective top 5 are:

================================================================================================================================================ ================ Function name