jaraco.util 5.5

General utility modules that supply commonly-used functionality

Contents

• Overview

• Highlights

• Status and License

• Changes

  • 5.5

  • 5.4

  • 5.3.1

  • 5.3

  • 5.2

  • 5.1

  • 5.0

  • 4.4

  • 4.3

  • 4.2

  • 4.1

  • 4.0

  • 3.9.2

  • 3.9.1

  • 3.9

  • 3.8.1

  • 3.8

  • 3.7

  • 3.6

  • 3.5.1

  • 3.5

  • 3.4

  • 3.3

  • 3.2

  • 3.1

  • 3.0.1

  • 3.0

  • 2.3

  • 2.2

  • 2.1

  • 2.0

  • 1.0

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.

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

Changes

5.5

• Added itertools.is_empty.

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