Utility functions

Conversions

momotor.options.convert.convert_duration(t)

Convert a string containing a duration into a float. The duration is defined as “hh:mm:ss” (hours, minutes, seconds). The seconds can contain decimals.

>>> convert_duration('1')
1.0

>>> convert_duration('1.5')
1.5

>>> convert_duration('10')
10.0

>>> convert_duration('100')
100.0

>>> convert_duration('1:00')
60.0

>>> convert_duration('10:00')
600.0

>>> convert_duration('100:00')
6000.0

>>> convert_duration('1:00:00')
3600.0

>>> convert_duration('1:00:00')
3600.0

>>> convert_duration('10:00:00')
36000.0

>>> convert_duration('100:00:00')
360000.0

>>> convert_duration('123:45:67.89')
445567.89

>>> convert_duration(1)
1.0

>>> convert_duration(1.0)
1.0
Parameters:

t (str | int | float | None)

Return type:

float | None

Returns:

momotor.options.convert.convert_intlist(il, empty_values=False)

Convert a string containing a comma-separated sequence of integer values into a tuple of integers. Allows a range to be specified using .. as separator, e.g. “100..109”. If empty_values is True, empty values in the list are allowed and returned as None

>>> convert_intlist("")
()

>>> convert_intlist("", empty_values=True)
(None,)

>>> convert_intlist("0")
(0,)

>>> convert_intlist("0,1")
(0, 1)

>>> convert_intlist("0,,1")
Traceback (most recent call last):
...
ValueError: '0,,1' is not a valid list of integers: empty values not allowed

>>> convert_intlist("0,,1", empty_values=True)
(0, None, 1)

>>> convert_intlist("0, ,1", empty_values=True)
(0, None, 1)

>>> convert_intlist("0,1,100..109")
(0, 1, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109)

>>> convert_intlist("0, 1, 100 .. 109")
(0, 1, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109)

>>> convert_intlist("0,", empty_values=True)
(0, None)

>>> convert_intlist("0,1,X")
Traceback (most recent call last):
...
ValueError: '0,1,X' is not a valid list of integers: invalid literal for int() with base 10: 'X'

>>> convert_intlist("0..")
Traceback (most recent call last):
...
ValueError: '0..' is not a valid list of integers: incomplete range 0..

>>> convert_intlist("0..", empty_values=True)
Traceback (most recent call last):
...
ValueError: '0..' is not a valid list of integers: incomplete range 0..
Parameters:

  • il (str) – string to convert

  • empty_values (bool) – allow empty values in the list. These will be converted to None

Return type:

tuple[int | None, ...]

Returns:

tuple of integers

Raises:

ValueError – if any section of the list cannot be parsed as an integer

momotor.options.convert.convert_size(t)

Convert a size into an integer. If size ends with “i” or “ib”, the value is a binary (IEC) value, otherwise it is a decimal (SI) value. (See https://en.wikipedia.org/wiki/Binary_prefix)

Supported unit prefixes are:

Decimal

Binary

Value

SI

Value

IEC

1

(none)

1

(none)

1000

k

kilo

1024

Ki

kibi

1000​2

M

mega

1024​2

Mi

mebi

1000​3

G

giga

1024​3

Gi

gibi

1000​4

T

tera

1024​4

Ti

tebi

1000​5

P

peta

1024​5

Pi

pebi

1000​6

E

exa

1024​6

Ei

exbi

1000​7

Z

zetta

1024​7

Zi

zebi

1000​8

Y

yotta

1024​8

Yi

yobi

Case of unit is ignored, i.e. MiB == mib == MIB

>>> convert_size('16')
16

>>> convert_size('16B')
16

>>> convert_size('16 B')
16

>>> convert_size('16k')
16000

>>> convert_size('16kb')
16000

>>> convert_size('16ki')
16384

>>> convert_size('16kib')
16384

>>> convert_size('16MiB')
16777216

>>> convert_size('16gib')
17179869184

>>> convert_size('16TIB')
17592186044416
Parameters:

t (str | int | None)

Return type:

int | None

Returns:

Documentation

momotor.options.doc.annotate_docstring(*args, **kwargs)

Decorator to help write better docstrings.

The arguments of the decorator are applied using str.format() to the __doc__ of the function, class or method decorated.

Examples:

@annotate_docstring(placeholder='test')
def some_function():
    """ This is a {placeholder}. """
    pass

@annotate_docstring(placeholder='test')
class SomeClass:
   """ This is a {placeholder}. """

    @annotate_docstring(placeholder='test')
    def some_method(self):
        """ This is a {placeholder}. """
        pass

In the example above, all docstrings will read:

This is a test.
Parameters:
Returns:

the decorated object with annotated doc string

File filters

momotor.options.filter_files.filter_files(files, class_name)

Filter a FilterableTuple of File objects on the name and class attributes.

The class_name argument contains the class and name to filter on, in the format <class>#<name>. The name part can contain wildcards, and is optional.

Parameters:
Return type:

FilterableTuple[File]

Returns:

momotor.options.filter_files.ifilter_files(files, class_name)

Return an iterable that filters a FilterableTuple of File objects on the name and class attributes.

The class_name argument contains the class and name to filter on, in the format <class>#<name>. The name part can contain wildcards, and is optional.

Parameters:
Return type:

Iterable[File]

Returns:

Splitting

momotor.options.split.multi_split(s, extra_sep=None, maxsplit=0)

Split a string on multiple separators.

Only splits on whitespace by default, but extra_sep can provide other separators to split the string on. If maxsplit is nonzero, at most maxsplit splits occur, and the remainder of the string is returned as the final element.

Parameters:

  • s (str) – string to process

  • extra_sep (Iterable) – extra separators to split the string on

  • maxsplit (int) – maximum number of splits

Return type:

Iterable[str]

Returns:

>>> list(multi_split('testing'))
['testing']

>>> list(multi_split('testing one two three'))
['testing', 'one', 'two', 'three']

>>> list(multi_split('testing,one two three'))
['testing,one', 'two', 'three']

>>> list(multi_split('testing,one two three', ','))
['testing', 'one', 'two', 'three']

>>> list(multi_split('testing,one two three', ',', 1))
['testing', 'one two three']

>>> list(multi_split('testing,, one   two ,, three', ','))
['testing', 'one', 'two', 'three']

>>> list(multi_split('   testing,, one   two ,, three   ', ','))
['testing', 'one', 'two', 'three']