jaraco.util 4.2.2

General utility modules that supply commonly-used functionality

.. -*- restructuredtext -*-

jaraco.util
===========

.. contents::

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
<http://www.opensource.org/licenses/mit-license.php>`_.

You can install it with ``easy_install jaraco.util``, or grab the code
from the `mercurial repository
<http://bitbucket.org/jaraco/jaraco.util>`_.

Changes
-------

4.2
~~~

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

4.1
~~~

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

4.0
~~~

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

3.9.2
~~~~~

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

3.9.1
~~~~~

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

3.9
~~~

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

3.8.1
~~~~~

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

3.8
~~~

* `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`.

3.7
~~~

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


3.6
~~~

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

3.5.1
~~~~~

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

3.5
~~~

* 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

3.4
~~~

* Adding jaraco.util.concurrency

3.3
~~~

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

3.2
~~~

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

3.1
~~~~~

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

3.0.1
~~~~~

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

3.0
~~~

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

2.3
~~~

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

2.2
~~~

* First release with documentation.

2.1
~~~

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

2.0
~~~

* First release with no dependencies.

1.0
~~~

* Initial release