Source

jaraco.util / README

.. -*- restructuredtext -*-

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

.. contents::

Overview
--------

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

Highlights
----------

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

5.4
~~~

* Added context manager support in `timing.Stopwatch`.

5.3.1
~~~~~

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

5.3
~~~

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

5.2
~~~

* Added `string.indent`.

5.1
~~~

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

5.0
~~~

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

4.4
~~~

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

4.3
~~~

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

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
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.