landlab.utils.decorators module

General decorators for the landlab library.

General Landlab decorators

use_field_name_or_array(at_element)	Decorate a function so that it accepts a field name or array.
make_return_array_immutable(func)	Decorate a function so that its return array is read-only.
deprecated(use, version)	Mark a function as deprecated.

add_signature_to_doc(func)

Add a function signature to the first line of a docstring.

Add the signature of a function to the first line of its docstring. This is useful for functions that are decorated in such a way that its signature changes.

Parameters:

func (function) – Function to add signature to.

Returns:

The new docstring with the function signature on the first line.

Return type:

str

Examples

>>> from landlab.utils.decorators import add_signature_to_doc

>>> def foo(arg1, kwd=None):
...     '''Do something.'''
...     pass
...
>>> print(add_signature_to_doc(foo))
foo(arg1, kwd=None)

Do something.

class cache_result_in_object(cache_as=None)

Bases: object

deprecated(use, version)

Mark a function as deprecated.

Parameters:

• use (str) – Name of replacement function to use.

• version (str) – Version number when function was marked as deprecated.

Returns:

A wrapped function that issues a deprecation warning.

Return type:

func

make_return_array_immutable(func)

Decorate a function so that its return array is read-only.

Parameters:

func (function) – A function that returns a numpy array.

Returns:

A wrapped function that returns a read-only view of an array.

Return type:

func

read_only_array(func)

Decorate a function so that its return array is read-only.

Parameters:

func (function) – A function that returns a numpy array.

Returns:

A wrapped function that returns a read-only numpy array.

Return type:

func

class store_result_in_dataset(dataset=None, name=None)

Bases: object

class store_result_in_grid(name=None)

Bases: object

class use_field_name_array_or_value(at_element)

Bases: object

Decorate a function so that it accepts a field name, array, or value.

Parameters:

• func (function) – A function that accepts a grid and array as arguments.

• at_element (str) – The element type that the field is defined on (‘node’, ‘cell’, etc.)

Returns:

A wrapped function that accepts a grid and either a field name, a numpy array, or a value as arguments.

Return type:

func

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5), xy_spacing=(1, 2))

>>> def my_func(grid, vals):
...     return grid.area_of_cell * vals
...
>>> my_func(grid, np.arange(grid.number_of_cells))
array([  0.,   2.,   4.,   6.,   8.,  10.])

Decorate the function so that the second argument can be array-like, the name of a field contained withing the grid, or a value (float, int, etc.). The decorator takes a single argument that is the name (as a str) of the grid element that the values are defined on (“node”, “cell”, etc.).

>>> from landlab.utils.decorators import use_field_name_array_or_value
>>> @use_field_name_array_or_value("cell")
... def my_func(grid, vals):
...     return grid.area_of_cell * vals
...

The array of values now can be list or anything that can be converted to a numpy array.

>>> my_func(grid, [0, 1, 2, 3, 4, 5])
array([  0.,   2.,   4.,   6.,   8.,  10.])

The array of values doesn’t have to be flat.

>>> vals = np.array([[0, 1, 2], [3, 4, 5]])
>>> my_func(grid, vals)
array([  0.,   2.,   4.,   6.,   8.,  10.])

The array of values can be a field name.

>>> _ = grid.add_field("elevation", [0, 1, 2, 3, 4, 5], at="cell")
>>> my_func(grid, "elevation")
array([  0.,   2.,   4.,   6.,   8.,  10.])

The array of values can be a value (float, int, etc.).

>>> my_func(grid, 4.0)
array([ 8.,  8.,  8.,  8.,  8.,  8.])

Initialize the decorator.

Parameters:

at_element (str) – The element type that the field is defined on (‘node’, ‘cell’, etc.)

__call__(func)

Wrap the function.

__init__(at_element)

Initialize the decorator.

Parameters:

at_element (str) – The element type that the field is defined on (‘node’, ‘cell’, etc.)

class use_field_name_or_array(at_element)

Bases: object

Decorate a function so that it accepts a field name or array.

Parameters:

• func (function) – A function that accepts a grid and array as arguments.

• at_element (str) – The element type that the field is defined on (‘node’, ‘cell’, etc.)

Returns:

A wrapped function that accepts a grid and either a field name or a numpy array.

Return type:

func

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5), xy_spacing=(1, 2))

>>> def my_func(grid, vals):
...     return grid.area_of_cell * vals
...
>>> my_func(grid, np.arange(grid.number_of_cells))
array([  0.,   2.,   4.,   6.,   8.,  10.])

Decorate the function so that the second argument can be array-like or the name of a field contained withing the grid. The decorator takes a single argument that is the name (as a str) of the grid element that the values are defined on (“node”, “cell”, etc.).

>>> from landlab.utils.decorators import use_field_name_or_array
>>> @use_field_name_or_array("cell")
... def my_func(grid, vals):
...     return grid.area_of_cell * vals
...

The array of values now can be list or anything that can be converted to a numpy array.

>>> my_func(grid, [0, 1, 2, 3, 4, 5])
array([  0.,   2.,   4.,   6.,   8.,  10.])

The array of values doesn’t have to be flat.

>>> vals = np.array([[0, 1, 2], [3, 4, 5]])
>>> my_func(grid, vals)
array([  0.,   2.,   4.,   6.,   8.,  10.])

The array of values can be a field name.

>>> _ = grid.add_field("elevation", [0, 1, 2, 3, 4, 5], at="cell")
>>> my_func(grid, "elevation")
array([  0.,   2.,   4.,   6.,   8.,  10.])

Initialize the decorator.

Parameters:

at_element (str) – The element type that the field is defined on (‘node’, ‘cell’, etc.)

__call__(func)

Wrap the function.

__init__(at_element)

Initialize the decorator.

Parameters:

at_element (str) – The element type that the field is defined on (‘node’, ‘cell’, etc.)