skip to navigation
skip to content

jaraco.util 6.1

General utility modules that supply commonly-used functionality

Latest Version: 11.0


jaraco.util contains a number of nominally useful, reusable classes and functions. They’re designed to be intuitively named and self-documenting (many with extensive doctests). Browse the source for details.


Some of the more interesting modules include:

  • .dictlib contains RangeMap, a dictionary-like object that maps a range of values to a given value.

Status and License

jaraco.util provides miscellaneous utility functions used across projects developed by the author.

jaraco.util is written by Jason R. Coombs. It is licensed under an MIT-style permissive license.

You can install it with easy_install jaraco.util, or grab the code from the mercurial repository.



  • Added context module, with a null_context context manager. It is suitable for taking the place of a real context when no context is needed.


  • itertools.always_iterable now returns an empty iterable when the input is None. This approach appears to work better for the majority of use-cases.


  • Added itertools.is_empty.


  • Added context manager support in timing.Stopwatch.


  • Fixed issue with dictlib.RangeMap.get so that it now works as one would expect.


  • Added string.words for retrieving words from an identifier, even if it is camelCased.


  • Added string.indent.


  • Added functools.once, a rudimentary caching function to ensure an expensive or non-idempotent function is not expensive on subsequent calls and is idempotent.


  • Renamed method in KeyTransformingDict from key_transform to transform_key.
  • Fixed critical NameErrors in jaraco.util.logging.
  • Enabled custom parameters in logging.setup.


  • Extracted KeyTransformingDict from FoldedCaseKeyedDict with much more complete handling of key transformation.


  • Added jaraco.filesystem.recursive_glob, which acts like a regular glob, but recurses into sub-directories.


  • Added dictlib.DictStack for stacking dictionaries on one another.
  • Added string.global_format and string.namespace_format for formatting a string with globals and with both globals and locals.


  • Added jaraco.util.dictlib.IdentityOverrideMap
  • Added jaraco.util.itertools.always_iterable
  • All modules now use unicode literals, consistent with Python 3 syntax


The entire package was combed through for deprecated modules. Many of the modules and functions were moved or renamed for clarity and to match modern PEP-8 naming recommendations.

  • Renamed jaraco.util.iter_ to jaraco.util.itertools
  • Renamed jaraco.util.cmp_ to jaraco.util.cmp
  • Moved PasswordGenerator to jaraco.util.auth
  • Updated callable() to use technique that’s good for all late Python versions
  • Removed jaraco.util.odict (use py26compat.collections.OrderedDict for Python 2.6 and earlier).
  • Renamed many functions and methods to conform more to the PEP-8 convention:
    • jaraco.util
      • Moved make_rows, grouper, bisect, groupby_saved, and FetchingQueue to itertools module. Renamed groupby_saved to GroubySaved.
      • Moved trim to string module.
      • Moved Stopwatch to new timing module.
      • Moved splitter to string.Splitter.
      • Removed replaceLists.
      • Moved readChunks to filesystem.read_chunks.
      • Moved coerce_number and ordinalth to new numbers module.
      • Moved callable to jaraco.lang.python module.
      • Moved randbytes to random module.
    • jaraco.dateutil
      • ConstructDatetime is now DatetimeConstructor.construct_datetime
      • DatetimeRound is now datetime_round
      • GetNearestYearForDay is now get_nearest_year_for_day
      • Removed getPeriodSeconds, getDateFormatString, and GregorianDate backward-compatibility aliases.
    • jaraco.filesystem
      • GetUniquePathname is now get_unique_pathname
      • GetUniqueFilename has been removed.
    • jaraco.logging
      • Removed deprecated add_options.
      • methods, attributes, and parameters on TimeStampFileHandler updated.
  • Removed jaraco.filesystem.change (moved to project).
  • Added jaraco.util.filesystem.tempfile_context.
  • Removed jaraco.util.excel (functionality moved to project).
  • Removed jaraco.util.timers (functionality moved to project).
  • Removed jaraco.util.scratch (unused).
  • Removed jaraco.util.xml_.
  • Added jaraco.util.exceptions.suppress_exception.
  • Added jaraco.util.itertools.last.
  • Moved jaraco.util.dictlib.NonDataProperty to


  • Another attempt to avoid SandboxViolation errors on some Python installations (Python 2 only).


  • Address attribute error for some older versions of distribute and setuptools.


  • dictlib.RangeMap now uses PEP-8 naming. Use sort_params and key_match_comparator for the constructor and undefined_value, last_item, and first_item class attributes.
  • Added jaraco.util.bitutil.BitMask metaclass.


  • jaraco namespace package now supports py2exe
  • ItemsAsAttributes now works with dicts that customize __getitem__


  • jaraco.util.logging now supports ArgumentParser with add_arguments and setup. add_options has been replaced with add_arguments for both OptionParser and ArgumentParser and is deprecated.
  • Added jaraco.util.exceptions with a function for determining if a callable throws a specific exception.
  • Added is_decodable and is_binary to jaraco.util.string.


  • Added jaraco.util.dictlib.DictAdapter.
  • Added jaraco.util.dictlib.ItemsAsAttributes.
  • Added wallpaper script by Samuel Huckins with added support for Windows.
  • Added stream.Tee (for outputting to multiple streams).
  • Fix for NameErrors.
  • Added cross-platform getch function.
  • Added several new functions to iter_.
  • Enhanced EditableFile with support for non-ascii text and capturing a diff after changes are made.


  • Added jaraco.util.editor (with EditableFile for editing strings in a subprocess editor).


  • Removed apng from .image so the package now installs on Python 2.5 with only one error.


  • Added jaraco.util.iter_.window and .nwise
  • Added jaraco.util.filesystem.ensure_dir_exists decorator
  • Added jaraco.util.iter_.Peekable iterator wrapper
  • Moved jaraco.util.package to jaraco.develop project


  • Adding jaraco.util.concurrency


  • Added prorating calculator and console script calc-prorate.
  • Added iter_.peek
  • Renamed QuickTimer to Stopwatch - modified to PEP8 specs
  • Adding jaraco.filesystem.DirectoryStack
  • Added and iter_.first


  • Removed release module and moved its function to the package module.


  • Added skip_first to jaraco.util.iter_
  • Moved rss module to package.
  • Bug fixes in iter_.flatten.
  • Restored Python 2 compatibility and implemented 2to3 for deployment. jaraco.util is now easy_installable on Python 2 and Python 3.


  • More Python 3 changes.
  • Fixes bug in jaraco.util.meta.LeafClassesMeta.
  • Added jaraco.util.string.local_format


This version includes many backwards-incompatible changes.

  • May require Python 2.6
  • Removed powerball module
  • Refactored RangeMap: RangeValueUndefined, RangeItem/First/Last moved into RangeMap class. RangeValueUndefined, RangeItemFirst, and RangeItemLast are now instances, not classes. Renamed to UndefinedValue, Item, FirstItem, LastItem.
  • Renamed DictMap function to dict_map
  • Renamed iter_.evalAll to iter_.consume and evalN to consume_n
  • More Python 3 improvements
  • Added rss feed handler (this perhaps this belongs in, and may be moved in the future)
  • Renamed ciString to jaraco.util.string.FoldedCase and added support for sorting case-insensitive strings
  • Added some useful iterator tools.
  • Added bitutil, based on some functions in jaraco.input
  • Added some rich comparison mixins in jaraco.util.cmp_
  • Added PasswordGenerator from
  • Added logging module for commonly-used logging patterns


  • Minor fixes, primarily to deployment techniques
  • Mostly Python 3 compatible.
  • Final release before major refactoring.


  • First release with documentation.


  • Added package release script.
  • Added RelativePath, a class for manipulating file system paths
  • Added trim function


  • First release with no dependencies.


  • Initial release
File Type Py Version Uploaded on Size (md5) Source 2012-12-20 78KB