Common Utilities¶

blocks.utils.utils.change_recursion_limit(*args, **kwds)[source]¶: Temporarily changes the recursion limit.

blocks.utils.utils.dict_subset(dict_, keys, pop=False, must_have=True)[source]¶

Return a subset of a dictionary corresponding to a set of keys.

Parameters:	dict (dict) – The dictionary. keys (iterable) – The keys of interest. pop (bool) – If `True`, the pairs corresponding to the keys of interest are popped from the dictionary. must_have (bool) – If `True`, a ValueError will be raised when trying to retrieve a key not present in the dictionary.
Returns:	result – An ordered dictionary of retrieved pairs. The order is the same as in the `keys` argument.
Return type:	`OrderedDict`

blocks.utils.utils.dict_union(*dicts, **kwargs)[source]¶

Return union of a sequence of disjoint dictionaries.

Parameters:	dicts (dicts) – A set of dictionaries with no keys in common. If the first dictionary in the sequence is an instance of OrderedDict, the result will be OrderedDict. **kwargs – Keywords and values to add to the resulting dictionary.
Raises:	`ValueError` – If a key appears twice in the dictionaries or keyword arguments.

blocks.utils.utils.extract_args(expected, *args, **kwargs)[source]¶

Route keyword and positional arguments to a list of names.

A frequent situation is that a method of the class gets to know its positional arguments only when an instance of the class has been created. In such cases the signature of such method has to be *args, **kwargs. The downside of such signatures is that the validity of a call is not checked.

Use extract_args() if your method knows at runtime, but not at evaluation/compile time, what arguments it actually expects, in order to check that they are correctly received.

Parameters:	expected (list of str) – A list of strings denoting names for the expected arguments, in order. args (iterable) – Positional arguments that have been passed. kwargs (Mapping) – Keyword arguments that have been passed.
Returns:	routed_args – An OrderedDict mapping the names in expected to values drawn from either args or kwargs in the usual Python fashion.
Return type:	OrderedDict
Raises:	`KeyError` – If a keyword argument is passed, the key for which is not contained within expected. `TypeError` – If an expected argument is accounted for in both the positional and keyword arguments. `ValueError` – If certain arguments in expected are not assigned a value by either a positional or keyword argument.

blocks.utils.utils.find_bricks(top_bricks, predicate)[source]¶

Walk the brick hierarchy, return bricks that satisfy a predicate.

Parameters:	top_bricks (list) – A list of root bricks to search downward from. predicate (callable) – A callable that returns True for bricks that meet the desired criteria or False for those that don’t.
Returns:	found – A list of all bricks that are descendants of any element of top_bricks that satisfy predicate.
Return type:	list

blocks.utils.utils.ipdb_breakpoint(x)[source]¶

A simple hook function for put_hook() that runs ipdb.

Parameters:	x (`ndarray`) – The value of the hooked variable.

blocks.utils.utils.pack(arg)[source]¶

Pack variables into a list.

Parameters:	arg (object) – Either a list or tuple, or any other Python object. Lists will be returned as is, and tuples will be cast to lists. Any other variable will be returned in a singleton list.
Returns:	List containing the arguments
Return type:	list

blocks.utils.utils.print_shape(x, header=None)[source]¶

blocks.utils.utils.print_sum(x, header=None)[source]¶

blocks.utils.utils.repr_attrs(instance, *attrs)[source]¶

Prints a representation of an object with certain attributes.

Parameters:	instance (object) – The object of which to print the string representation *attrs – Names of attributes that should be printed.

Examples

>>> class A(object):
...     def __init__(self, value):
...         self.value = value
>>> a = A('a_value')
>>> repr(a)  
<blocks.utils.A object at 0x7fb2b4741a10>
>>> repr_attrs(a, 'value')  
<blocks.utils.A object at 0x7fb2b4741a10: value=a_value>

blocks.utils.utils.reraise_as(new_exc)[source]¶

Reraise an exception as a different type or with a message.

This function ensures that the original traceback is kept, making for easier debugging.

Parameters:	new_exc (`Exception` or `str`) – The new error to be raised e.g. (ValueError(“New message”)) or a string that will be prepended to the original exception message

Notes

Note that when reraising exceptions, the arguments of the original exception are cast to strings and appended to the error message. If you want to retain the original exception arguments, please use:

>>> try:
...     1 / 0
... except Exception as e:
...     reraise_as(Exception("Extra information", *e.args))
Traceback (most recent call last):
  ...
Exception: 'Extra information, ...

Examples

>>> class NewException(Exception):
...     def __init__(self, message):
...         super(NewException, self).__init__(message)
>>> try:
...     do_something_crazy()
... except Exception:
...     reraise_as(NewException("Informative message"))
Traceback (most recent call last):
  ...
NewException: Informative message ...

blocks.utils.utils.unpack(arg, singleton=False)[source]¶

Unpack variables from a list or tuple.

Parameters:	arg (object) – Either a list or tuple, or any other Python object. If passed a list or tuple of length one, the only element of that list will be returned. If passed a tuple of length greater than one, it will be cast to a list before returning. Any other variable will be returned as is. singleton (bool) – If `True`, arg is expected to be a singleton (a list or tuple with exactly one element) and an exception is raised if this is not the case. `False` by default.
Returns:	A list of length greater than one, or any other Python object except tuple.
Return type:	object

Theano Utilities¶

blocks.utils.theano_utils.check_theano_variable(variable, n_dim, dtype_prefix)[source]¶

Check number of dimensions and dtype of a Theano variable.

If the input is not a Theano variable, it is converted to one. None input is handled as a special case: no checks are done.

Parameters:	variable (`TensorVariable` or convertible to one) – A variable to check. n_dim (int) – Expected number of dimensions or None. If None, no check is performed. dtype_prefix (str) – Expected dtype prefix or None. If None, no check is performed.

blocks.utils.theano_utils.is_graph_input(variable)[source]¶

Check if variable is a user-provided graph input.

To be considered an input the variable must have no owner, and not be a constant or shared variable.

Parameters:	variable (`TensorVariable`) –
Returns:	`True` If the variable is a user-provided input to the graph.
Return type:	bool

blocks.utils.theano_utils.is_shared_variable(variable)[source]¶

Check if a variable is a Theano shared variable.

Notes

This function excludes shared variables that store the state of Theano random number generators.

blocks.utils.theano_utils.put_hook(variable, hook_fn, *args)[source]¶

Put a hook on a Theano variables.

Ensures that the hook function is executed every time when the value of the Theano variable is available.

Parameters:	variable (`TensorVariable`) – The variable to put a hook on. hook_fn (function) – The hook function. Should take a single argument: the variable’s value. args (list*) – Positional arguments to pass to the hook function.

blocks.utils.theano_utils.shared_floatx(value, name=None, borrow=False, dtype=None, **kwargs)[source]¶

Transform a value into a shared variable of type floatX.

Parameters:	value (`ndarray`) – The value to associate with the Theano shared. name (`str`, optional) – The name for the shared variable. Defaults to None. borrow (`bool`, optional) – If set to True, the given value will not be copied if possible. This can save memory and speed. Defaults to False. dtype (`str`, optional) – The dtype of the shared variable. Default value is `config.floatX`. **kwargs – Keyword arguments to pass to the `shared()` function.
Returns:	A Theano shared variable with the requested value and dtype.
Return type:	`tensor.TensorSharedVariable`

blocks.utils.theano_utils.shared_floatx_nans(shape, **kwargs)[source]¶

Creates a shared variable array filled with nans.

Parameters:	shape (tuple) – A tuple of integers representing the shape of the array. **kwargs – Keyword arguments to pass to the `shared_floatx()` function.
Returns:	A Theano shared variable filled with nans.
Return type:	class:’tensor.TensorSharedVariable’

blocks.utils.theano_utils.shared_floatx_zeros(shape, **kwargs)[source]¶

Creates a shared variable array filled with zeros.

Parameters:	shape (tuple) – A tuple of integers representing the shape of the array. **kwargs – Keyword arguments to pass to the `shared_floatx()` function.
Returns:	A Theano shared variable filled with zeros.
Return type:	class:’tensor.TensorSharedVariable’

blocks.utils.theano_utils.shared_floatx_zeros_matching(shared_variable, name=None, **kwargs)[source]¶

Create another shared variable with matching shape and broadcast.

Parameters:	shared_variable (:class:'tensor.TensorSharedVariable') – A Theano shared variable with the desired shape and broadcastable flags. name (`str`, optional) – The name for the shared variable. Defaults to None. **kwargs – Keyword arguments to pass to the `shared_floatx_zeros()` function.
Returns:	A new shared variable, initialized to all zeros, with the same shape and broadcastable flags as shared_variable.
Return type:	class:’tensor.TensorSharedVariable’

blocks.utils.theano_utils.shared_like(variable, name=None, **kwargs)[source]¶

Construct a shared variable to hold the value of a tensor variable.

Parameters:	variable (`TensorVariable`) – The variable whose dtype and ndim will be used to construct the new shared variable. name (`str` or `None`) – The name of the shared variable. If None, the name is determined based on variable’s name. **kwargs – Keyword arguments to pass to the `shared()` function.