signature_string

odl.util.utility.signature_string(posargs, optargs, sep=', ', mod='!r')

Return a stringified signature from given arguments.

Parameters:

posargssequence

Positional argument values, always included in the returned string. They appear in the string as (roughly):

sep.join(str(arg) for arg in posargs)

optargssequence of 3-tuples

Optional arguments with names and defaults, given in the form:

[(name1, value1, default1), (name2, value2, default2), ...]

Only those parameters that are different from the given default are included as name=value keyword pairs.

Note: The comparison is done by using if value == default:, which is not valid for, e.g., NumPy arrays.

sepstring or sequence of strings, optional

Separator(s) for the argument strings. A provided single string is used for all joining operations. A given sequence must have 3 entries pos_sep, opt_sep, part_sep. The pos_sep and opt_sep strings are used for joining the respective sequences of argument strings, and part_sep joins these two joined strings.

modstring or callable or sequence, optional

Format modifier(s) for the argument strings. In its most general form, mod is a sequence of 2 sequences pos_mod, opt_mod with len(pos_mod) == len(posargs) and len(opt_mod) == len(optargs). Each entry m in those sequences can be eiter a string, resulting in the following stringification of arg:

arg_fmt = {{{}}}.format(m)
arg_str = arg_fmt.format(arg)

For a callable to_str, the stringification is simply arg_str = to_str(arg).

The entries pos_mod, opt_mod of mod can also be strings or callables instead of sequences, in which case the modifier applies to all corresponding arguments.

Finally, if mod is a string or callable, it is applied to all arguments.

The default behavior is to apply the "{!r}" (repr) conversion. For floating point scalars, the number of digits printed is determined by the precision value in NumPy's printing options, which can be temporarily modified with npy_printoptions.

Returns:

signaturestring

Stringification of a signature, typically used in the form:

'{}({})'.format(self.__class__.__name__, signature)

Examples

Usage with non-trivial entries in both sequences, with a typical use case:

>>> posargs = [1, 'hello', None]
>>> optargs = [('dtype', 'float32', 'float64')]
>>> signature_string(posargs, optargs)
"1, 'hello', None, dtype='float32'"
>>> '{}({})'.format('MyClass', signature_string(posargs, optargs))
"MyClass(1, 'hello', None, dtype='float32')"

Empty sequences and optargs values equal to default are omitted:

>>> posargs = ['hello']
>>> optargs = [('size', 1, 1)]
>>> signature_string(posargs, optargs)
"'hello'"
>>> posargs = []
>>> optargs = [('size', 2, 1)]
>>> signature_string(posargs, optargs)
'size=2'
>>> posargs = []
>>> optargs = [('size', 1, 1)]
>>> signature_string(posargs, optargs)
''

Using a different separator, globally or per argument "category":

>>> posargs = [1, 'hello', None]
>>> optargs = [('dtype', 'float32', 'float64'),
...            ('order', 'F', 'C')]
>>> signature_string(posargs, optargs)
"1, 'hello', None, dtype='float32', order='F'"
>>> signature_string(posargs, optargs, sep=(',', ',', ', '))
"1,'hello',None, dtype='float32',order='F'"

Using format modifiers:

>>> posargs = ['hello', 2.345]
>>> optargs = [('extent', 1.442, 1.0), ('spacing', 0.0151, 1.0)]
>>> signature_string(posargs, optargs)
"'hello', 2.345, extent=1.442, spacing=0.0151"
>>> # Print only two significant digits for all arguments.
>>> # NOTE: this also affects the string!
>>> mod = ':.2'
>>> signature_string(posargs, optargs, mod=mod)
'he, 2.3, extent=1.4, spacing=0.015'
>>> mod = [['', ''], [':.3', ':.2']]  # one modifier per argument
>>> signature_string(posargs, optargs, mod=mod)
"'hello', 2.345, extent=1.44, spacing=0.015"

Using callables for stringification:

>>> posargs = ['arg1', np.ones(3)]
>>> optargs = []
>>> signature_string(posargs, optargs, mod=[['', array_str], []])
"'arg1', [ 1., 1., 1.]"

The number of printed digits in floating point numbers can be changed with npy_printoptions:

>>> posargs = ['hello', 0.123456789012345]
>>> optargs = [('extent', 1.234567890123456, 1.0)]
>>> signature_string(posargs, optargs)  # default is 8 digits
"'hello', 0.12345679, extent=1.2345679"
>>> with npy_printoptions(precision=2):
...     sig_str = signature_string(posargs, optargs)
>>> sig_str
"'hello', 0.12, extent=1.2"