API

Caching

class miniutils.caching.CachedProperty(*affects, settable=False, threadsafe=True, is_collection=False, allow_collection_mutation=True)

Marks this property to be cached. Delete this property to remove the cached value and force it to be rerun.

Parameters:

• affects – Strings that list the names of the other properties in this class that are directly invalidated when this property’s value is altered
• settable – Whether or not to allow this property to have values assigned directly to it
• threadsafe – Whether or not to restrict execution of this property’s code to a single thread at a time (safe for recursive calls)
• is_collection – Whether or not this property returns a collection (currently supports lists, sets, and dictionaries; others might not work exactly as expected)
• allow_collection_mutation – Whether or not the returned collection should allow its values to be altered

__init__(*affects, settable=False, threadsafe=True, is_collection=False, allow_collection_mutation=True)

Marks this property to be cached. Delete this property to remove the cached value and force it to be rerun.

Parameters:

• affects – Strings that list the names of the other properties in this class that are directly invalidated when this property’s value is altered
• settable – Whether or not to allow this property to have values assigned directly to it
• threadsafe – Whether or not to restrict execution of this property’s code to a single thread at a time (safe for recursive calls)
• is_collection – Whether or not this property returns a collection (currently supports lists, sets, and dictionaries; others might not work exactly as expected)
• allow_collection_mutation – Whether or not the returned collection should allow its values to be altered

Progress Bar

miniutils.progress_bar.progbar(iterable, *a, verbose=True, **kw)

Prints a progress bar as the iterable is iterated over

Parameters:

• iterable – The iterator to iterate over
• a – Arguments to get passed to tqdm (or tqdm_notebook, if in a Jupyter notebook)
• verbose – Whether or not to print the progress bar at all
• kw – Keyword arguments to get passed to tqdm

Returns:

The iterable that will report a progress bar

miniutils.progress_bar.parallel_progbar(*args, **kwargs)

Performs a parallel mapping of the given iterable, reporting a progress bar as values get returned

Parameters:

• mapper – The mapping function to apply to elements of the iterable
• iterable – The iterable to map
• nprocs – The number of processes (defaults to the number of cpu’s)
• starmap – If true, the iterable is expected to contain tuples and the mapper function gets each element of a tuple as an argument
• flatmap – If true, flatten out the returned values if the mapper function returns a list of objects
• shuffle – If true, randomly sort the elements before processing them. This might help provide more uniform runtimes if processing different objects takes different amounts of time.
• verbose – Whether or not to print the progress bar
• verbose_flatmap – If performing a flatmap, whether or not to report each object as it’s returned
• timeout – The number of seconds to wait for each worker process after completing
• kwargs – Any other keyword arguments to pass to the progress bar (see progbar)

Returns:

A list of the returned objects, in the same order as provided

miniutils.progress_bar.iparallel_progbar(*args, **kwargs)

Performs a parallel mapping of the given iterable, reporting a progress bar as values get returned. Yields objects as soon as they’re computed, but does not guarantee that they’ll be in the correct order.

Parameters:

• mapper – The mapping function to apply to elements of the iterable
• iterable – The iterable to map
• nprocs – The number of processes (defaults to the number of cpu’s)
• starmap – If true, the iterable is expected to contain tuples and the mapper function gets each element of a tuple as an argument
• flatmap – If true, flatten out the returned values if the mapper function returns a list of objects
• shuffle – If true, randomly sort the elements before processing them. This might help provide more uniform runtimes if processing different objects takes different amounts of time.
• verbose – Whether or not to print the progress bar
• verbose_flatmap – If performing a flatmap, whether or not to report each object as it’s returned
• max_cache – Maximum number of mapped objects to permit in the queue at once
• timeout – The number of seconds to wait for each worker process after completing
• kwargs – Any other keyword arguments to pass to the progress bar (see progbar)

Returns:

A list of the returned objects, in whatever order they’re done being computed

Python 2

class miniutils.py2_wrap.MakePython2(func=None, *, imports=None, global_values=None, copy_function_body=True, python2_path='python2')

Make a function execute within a Python 2 instance

Parameters:

• func – The function to wrap. If not specified, this class instance behaves like a decorator
• imports – Any import statements the function requires. Should be a list, where each element is either a string (e.g., 'sys' for import sys) or a tuple (e.g., ('os.path', 'path') for import os.path as pas)
• global_values – A dictionary of global variables the function relies on. Key must be strings, and values must be picklable
• copy_function_body – Whether or not to copy the function’s source code into the Python 2 instance
• python2_path – The path to the Python 2 executable to use

__init__(func=None, *, imports=None, global_values=None, copy_function_body=True, python2_path='python2')

Make a function execute within a Python 2 instance

Parameters:

• func – The function to wrap. If not specified, this class instance behaves like a decorator
• imports – Any import statements the function requires. Should be a list, where each element is either a string (e.g., 'sys' for import sys) or a tuple (e.g., ('os.path', 'path') for import os.path as pas)
• global_values – A dictionary of global variables the function relies on. Key must be strings, and values must be picklable
• copy_function_body – Whether or not to copy the function’s source code into the Python 2 instance
• python2_path – The path to the Python 2 executable to use

Pragma

Miscellaneous

Magic Contracting

miniutils.magic_contract.magic_contract(*args, **kwargs)

Drop-in replacement for pycontracts.contract decorator, except that it supports locally-visible types

Parameters:

• args – Arguments to pass to the contract decorator
• kwargs – Keyword arguments to pass to the contract decorator

Returns:

The contracted function

Simplifying Decorators

miniutils.opt_decorator.optional_argument_decorator(_decorator)

Decorate your decorator with this to allow it to always receive *args and **kwargs, making @deco equivalent to @deco()

Logging

miniutils.logs.enable_logging(log_level='NOTSET', *, logdir=None, use_colors=True, capture_warnings=True, format_str='%(asctime)s [%(launch_script)s | %(levelname)s]: %(message)s')

Timing

miniutils.timing.timed_call(func, *args, log_level='DEBUG', **kwargs)

Logs a function’s run time

Parameters:

• func – The function to run
• args – The args to pass to the function
• kwargs – The keyword args to pass to the function
• log_level – The log level at which to print the run time

Returns:

The function’s return value

miniutils.timing.make_timed(func)

A decorator to make a function print its execution time whenever it gets called

miniutils.timing.tic(log_level='DEBUG', fmt='{file}:{line} - {message} - {diff:0.6f}s (total={total:0.1f}s)', verbose=True)

A minimalistic printf-type timing utility. Call this function to start timing individual sections of code

Parameters:

• log_level – The level at which to log block run times
• fmt –

  The format string to use when logging times. Available arguments include:

  • file, line, func, code_text: The stack frame information which called this timer
  • diff: The time since the last timer printout was called
  • total: The time since this timing block was started
  • message: The message passed to this timing printout
• verbose – If False, suppress printing messages

Returns:

A function that reports run times when called