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)[source]#

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)[source]#

Bases: object

deprecated(use, version)[source]#

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)[source]#

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)[source]#

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)[source]#

Bases: object

class store_result_in_grid(name=None)[source]#

Bases: object

class use_field_name_array_or_value(at_element)[source]#

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)[source]#

Wrap the function.

__init__(at_element)[source]#

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)[source]#

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)[source]#

Wrap the function.

__init__(at_element)[source]#

Initialize the decorator.

Parameters

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