API Reference

Converters from str to another type.

These functions can be used for the type parameter in methods of ArgumentParser and ArgParseBuilder or similar use cases (if necessary in combination with functools.partial()).

Overview

booleans	Mapping from strings to boolean values.
use_locale_default	Default value for int_conv() and float_conv() for parameter use_locale.
bool_conv	Convert a string to a boolean value.
int_conv	Convert a string to an integer value.
float_conv	Convert a string to a float value.
factor_conv	Convert a string with a factor.
duration	Convert duration string to seconds.
datetime_conv	Convert a string to a datetime.datetime.
date_conv	Convert a string to a class:datetime.date.
time_conv	Convert a string to a datetime.time.
range_conv	Convert a range string.
sequence	Convert a sequence string.

typeconvs.booleans = {'0': False, '1': True, 'f': False, 'false': False, 'n': False, 'no': False, 'off': False, 'on': True, 't': True, 'true': True, 'y': True, 'yes': True}

Mapping from strings to boolean values.

typeconvs.use_locale_default = False

Default value for int_conv() and float_conv() for parameter use_locale.

typeconvs.bool_conv(string, *, values=None)

Convert a string to a boolean value.

The string is converted to lower case before looking up the boolean value in values or booleans (if values is None).

Parameters

string (str) – input string

Value dict

mapping from strings to booleans

Returns

converted value

Return type

bool

Raises

ValueError – if the string cannot be converted

Changed in version 0.2.0: Renamed (old name: boolean)

typeconvs.int_conv(string, *, base=10, pred=None, use_locale=None)

Convert a string to an integer value.

>>> import locale
>>> locale.setlocale(locale.LC_ALL, 'de_DE.UTF-8')
'de_DE.UTF-8'
>>> int_conv('1.234', use_locale=True)
1234
>>> locale.setlocale(locale.LC_ALL, 'en_US.UTF-8')
'en_US.UTF-8'
>>> int_conv('1,234', use_locale=True)
1234
>>> int_conv('-1', pred=lambda x: x > 0)
Traceback (most recent call last):
  ...
ValueError: invalid value: '-1'

See int for an explanation of parameter base.

Parameters

• string (str) – input string

• base (int) – base (>= 2 and <= 36, or 0)

• pred – predicate function

• use_locale (bool or None) – True use current locale; None use use_locale_default

Returns

converted value

Return type

int

Raises

ValueError – if the string cannot be converted

typeconvs.float_conv(string, *, base=10, pred=None, use_locale=None)

Convert a string to a float value.

Parameters

• string (str) – input string

• base (int) – base (>= 2 and <= 36, or 0)

• pred – predicate function

• use_locale (bool or None) – True use current locale; None use use_locale_default

Returns

converted value

Return type

float

Raises

ValueError – if the string cannot be converted

typeconvs.factor_conv(string, *, conv, factors)

Convert a string with a factor.

The symbols from factors are compared to the end of string until one matches. The string is then shortend by the the length of the symbol and the rest converted with conv and multiplied by the factor that corresponds to the symbol.

>>> factors = {'h': 3600, 'm': 60, 's': 1}
>>> factor_conv('10m', conv=int, factors=factors)
600

Parameters

• string (str) – input string

• conv – converter function

• factors (dict) – mapping from symbol to factor

Returns

converted value

Raises

ValueError – if the string cannot be converted

typeconvs.duration(string, *, use_locale=None)

Convert duration string to seconds.

Format: [[H:]M:]S[.f]

See also: salmagundi.strings.parse_timedelta()

Parameters

• string (str) – duration string

• use_locale (bool or None) – True use current locale; None use use_locale_default

Returns

converted duration

Return type

float

Raises

ValueError – if the string cannot be converted

Changed in version 0.1.1: Add parameter use_locale

typeconvs.datetime_conv(string, *, format=None)

Convert a string to a datetime.datetime.

If format=None this function uses datetime.datetime.fromisoformat() else datetime.datetime.strptime().

Parameters

• string (str) – datetime string

• format (str or None) – format string

Returns

converted datetime

Return type

datetime.datetime

Raises

ValueError – if the string cannot be converted

Changed in version 0.2.0: Renamed (old name: datetime)

typeconvs.date_conv(string, *, format=None)

Convert a string to a class:datetime.date.

If format=None this function uses datetime.date.fromisoformat() else datetime.datetime.strptime().

Parameters

• string (str) – date string

• format – format string

Returns

converted date

Return type

datetime.date

Raises

ValueError – if the string cannot be converted

Changed in version 0.2.0: Renamed (old name: date)

typeconvs.time_conv(string, *, format=None)

Convert a string to a datetime.time.

If format=None this function uses datetime.time.fromisoformat() else datetime.datetime.strptime().

Parameters

• string (str) – time string

• format – format string

Returns

converted time

Return type

datetime.time

Raises

ValueError – if the string cannot be converted

Changed in version 0.2.0: Renamed (old name: time)

typeconvs.range_conv(string, *, conv=None, separator='-')

Convert a range string.

Range string: ‘<start><separator><end>[/<step>]’ (default: <step> = 1)

>>> list(range_conv('-2-4'))
[-2, -1, 0, 1, 2, 3, 4]

>>> list(range_conv('-2-4/2'))
[-2, 0, 2, 4]

>>> list(range_conv('4--2/-2'))
[4, 2, 0, -2]

>>> list(range_conv('4..-2/-2', separator='..'))
[4, 2, 0, -2]

>>> from itertools import chain
>>> list(chain.from_iterable(sequence('1, -2-4/2, 42', conv=range_conv)))
[1, -2, 0, 2, 4, 42]

Parameters

• string (str) – input string

• conv – converter function which returns an int or a float value (default: int)

• separator (str) – separator between <start> and <end>

Returns

generator that yields converted values

Raises

ValueError – if the string cannot be converted

New in version 0.2.0.

Changed in version 0.2.1: Add parameter separator

typeconvs.sequence(string, *, conv=None, separator=',')

Convert a sequence string.

>>> sequence('1, 2, 3', conv=float)
(1.0, 2.0, 3.0)

Parameters

• string (str) – input string

• conv – converter function

• separator (str) – separator between elements of sequence

Returns

generator that yields converted values

Raises

ValueError – if the string cannot be converted

New in version 0.2.0.