.. -*- restructuredtext -*-
``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
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 IntervalGovernor to `timing` module. Allows one to decorate a
function, causing that function to only be called once per interval, despite
the number of calls attempted.
* 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
* 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
* 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:
+ Moved `make_rows`, `grouper`, `bisect`, `groupby_saved`, and
`FetchingQueue` to `itertools` module. Renamed groupby_saved to
+ 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.
+ ConstructDatetime is now DatetimeConstructor.construct_datetime
+ DatetimeRound is now datetime_round
+ GetNearestYearForDay is now get_nearest_year_for_day
+ Removed getPeriodSeconds, getDateFormatString, and GregorianDate
+ GetUniquePathname is now get_unique_pathname
+ GetUniqueFilename has been removed.
+ Removed deprecated add_options.
+ methods, attributes, and parameters on TimeStampFileHandler updated.
* Removed jaraco.filesystem.change (moved to jaraco.windows project).
* Added jaraco.util.filesystem.tempfile_context.
* Removed jaraco.util.excel (functionality moved to jaraco.office project).
* Removed jaraco.util.timers (functionality moved to jaraco.windows 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 `jaraco.util.properties`.
* Another attempt to avoid SandboxViolation errors on some Python
installations (Python 2 only).
* Address attribute error for some older versions of distribute and
* dictlib.RangeMap now uses PEP-8 naming. Use `sort_params` and
the constructor and `undefined_value`, `last_item`, and `first_item` class
* 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
* 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 `iter_.one` 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 `jaraco.net` 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 jaraco.net, 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 jaraco.site
* 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