1. Jason R. Coombs
  2. jaraco.util


jaraco.util / README

.. -*- restructuredtext -*-


.. contents::


``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 `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:

  - jaraco.util

    + 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.

  - 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 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
  `key_match_comparator` for
  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
  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 `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