A Collection of Utilities

Math

pytools.levi_civita(tup)

Compute an entry of the Levi-Civita tensor for the indices tuple.

pytools.perm(n, k)

Return P(n, k), the number of permutations of length k drawn from n choices.

pytools.comb(n, k)

Return C(n, k), the number of combinations (subsets) of length k drawn from n choices.

Assertive accessors

pytools.one(iterable)

Return the first entry of iterable. Assert that iterable has only that one entry.

pytools.is_single_valued(iterable, equality_pred=<built-in function eq>)

pytools.all_roughly_equal(iterable, threshold)

pytools.single_valued(iterable, equality_pred=<built-in function eq>)

Return the first entry of iterable; Assert that other entries are the same with the first entry of iterable.

Memoization

pytools.memoize(*args, **kwargs)

Stores previously computed function values in a cache.

Two keyword-only arguments are supported:

Parameters:

• use_kwargs – Allows the caller to use keyword arguments. Defaults to False. Setting this to True has a non-negligible performance impact.
• key – A function receiving the same arguments as the decorated function which computes and returns the cache key.

pytools.memoize_on_first_arg(function, cache_dict_name=None)

Like memoize_method(), but for functions that take the object to do memoization as first argument.

Supports cache deletion via function_name.clear_cache(self).

Note

clear_cache support requires Python 2.5 or newer.

pytools.memoize_method(method)

Supports cache deletion via method_name.clear_cache(self).

Note

clear_cache support requires Python 2.5 or newer.

pytools.memoize_method_with_uncached(uncached_args=None, uncached_kwargs=None)

Supports cache deletion via method_name.clear_cache(self).

Parameters:uncached_args – a list of argument numbers (0-based, not counting ‘self’ argument)

pytools.memoize_in(container, identifier)

Adds a cache to a function nested inside a method. The cache is attached to object.

Requires Python 2.5 or newer.

Argmin/max

pytools.argmin2(iterable, return_value=False)

pytools.argmax2(iterable, return_value=False)

pytools.argmin(iterable)

pytools.argmax(iterable)

Cartesian products

pytools.cartesian_product(list1, list2)

pytools.distinct_pairs(list1, list2)

Permutations, Tuples, Integer sequences

pytools.wandering_element(length, wanderer=1, landscape=0)

pytools.indices_in_shape(shape)

pytools.generate_nonnegative_integer_tuples_below(n, length=None, least=0)

n may be a sequence, in which case length must be None.

pytools.generate_nonnegative_integer_tuples_summing_to_at_most(n, length)

Enumerate all non-negative integer tuples summing to at most n, exhausting the search space by varying the first entry fastest, and the last entry the slowest.

pytools.generate_all_nonnegative_integer_tuples(length, least=0)

pytools.generate_all_integer_tuples_below(n, length, least_abs=0)

pytools.generate_all_integer_tuples(length, least_abs=0)

pytools.generate_permutations(original)

Generate all permutations of the list original.

Nicked from http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/252178

pytools.generate_unique_permutations(original)

Generate all unique permutations of the list original.

Graph Algorithms

pytools.a_star(initial_state, goal_state, neighbor_map, estimate_remaining_cost=None, get_step_cost=<function <lambda>>)

With the default cost and heuristic, this amounts to Dijkstra’s algorithm.

Formatting

class pytools.Table

An ASCII table generator.

add_row(row)

__str__()

Return str(self).

latex(skip_lines=0, hline_after=None)

pytools.string_histogram(iterable, min_value=None, max_value=None, bin_count=20, width=70, bin_starts=None, use_unicode=True)

pytools.word_wrap(text, width, wrap_using='\n')

A word-wrap function that preserves existing line breaks and most spaces in the text. Expects that existing line breaks are posix newlines (\n).

Debugging

pytools.typedump(val, max_seq=5, special_handlers=None)

pytools.invoke_editor(s, filename='edit.txt', descr='the file')

Progress bars

class pytools.ProgressBar(descr, total, initial=0, length=40)

draw()

progress(steps=1)

set_progress(done)

finished()

__enter__()

__exit__(exc_type, exc_val, exc_tb)

Name generation

pytools.generate_unique_names(prefix)

pytools.generate_numbered_unique_names(prefix, num=None)

class pytools.UniqueNameGenerator(existing_names=None, forced_prefix='')

is_name_conflicting(name)

add_name(name)

add_names(names)

__call__(based_on='id')

Call self as a function.

Functions for dealing with (large) auxiliary files

pytools.download_from_web_if_not_present(url, local_name=None)

New in version 2017.5.

Helpers for numpy

pytools.reshaped_view(a, newshape)

Create a new view object with shape newshape without copying the data of a. This function is different from numpy.reshape by raising an exception when data copy is necessary.

Parameters:

• a – a numpy.ndarray object.
• newshape – an int object or a tuple of int objects.

New in version 2018.4.

Timing data

pytools.SUPPORTS_PROCESS_TIME

A bool indicating whether ProcessTimer measures elapsed process time (available on Python 3.3+).

class pytools.ProcessTimer

Measures elapsed wall time and process time.

__enter__()

__exit__(exc_type, exc_val, exc_tb)

done()

Timing data attributes:

wall_elapsed

process_elapsed

Only available in Python 3.3+.

New in version 2018.5.

Log utilities

class pytools.ProcessLogger(logger, description, silent_level=None, noisy_level=None, long_threshold_seconds=None)

Logs the completion time of a (presumably) lengthy process to logging. Only uses a high log level if the process took perceptible time.

__init__(logger, description, silent_level=None, noisy_level=None, long_threshold_seconds=None)

Initialize self. See help(type(self)) for accurate signature.

done(extra_msg=None, *extra_fmt_args)

__enter__()

__exit__(exc_type, exc_val, exc_tb)

class pytools.DebugProcessLogger(logger, description, silent_level=None, noisy_level=None, long_threshold_seconds=None)

class pytools.log_process(logger, description=None)

A decorator that uses ProcessLogger to log data about calls to the wrapped function.