Utility functions

This page is the API reference for the small helper modules that the option, parser, and scheduler code share. The converters turn option strings into typed values. The other helpers format documentation, filter file lists, and split option text. Most users call these helpers only through OptionDefinition.

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) – Seconds as a number or string, mm:ss, hh:mm:ss, or None.

Return type:

float | None

Returns:

Duration in seconds as a float, or None.

Raises:

ValueError – If the duration cannot be parsed.

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) – Size as bytes or a string with a unit suffix, or None.

Return type:

int | None

Returns:

Size in bytes, or None.

Raises:

ValueError – If the size or unit cannot be parsed.

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

Added in version 2.0.0.

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:
  • files (FilterableTuple[File]) – List of files to filter

  • class_name (str) – File class and optional glob pattern, such as source#*.py.

Return type:

FilterableTuple[File]

Returns:

Matching files in their original order.

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:
  • files (FilterableTuple[File]) – List of files to filter

  • class_name (str) – File class and optional glob pattern, such as source#*.py.

Return type:

Iterable[File]

Returns:

Matching files in their original order.

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[str] | None) – extra separators to split the string on

  • maxsplit (int) – maximum number of splits

Return type:

Iterable[str]

Returns:

A list of substrings. Leading or trailing extra separators can produce empty strings. Quotes have no special meaning.

>>> 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']