ini2toml.transformations

Reusable value and type casting transformations

This module is stable on a “best effort”-basis, and small backwards incompatibilities can be introduced in “minor”/”patch” version bumps (it will not be considered a regression automatically). While it can be used by plugin writers, it is not intended for general public use.

ini2toml.transformations.CP = ('#', ';')

Default Comment Prefixes

ini2toml.transformations.CoerceFn

Functions that know how to parser/coerce string values into different types

alias of Callable[[str], T]

ini2toml.transformations.Scalar

Simple data types with TOML correspondence

alias of int | float | bool | str

ini2toml.transformations.Transformation

There are 2 main types of transformation:

• The first one is a simple transformation that processes a string value (coming from an option in the original CFG/INI file) into a value with an equivalent TOML data type. For example: transforming "2" (string) into 2 (integer).

• The second one tries to preserve metadata (such as comments) from the original CFG/INI file. This kind of transformation processes a string value into an intermediary representation (e.g. Commented, CommentedList, CommentedKV) that needs to be properly handled before adding to the TOML document.

In a higher level we can also consider an ensemble of transformations that transform an entire table of the TOML document.

alias of Callable[[str], Any] | Callable[[M], M]

ini2toml.transformations.apply(x, fn)

Useful to reduce over a list of functions

ini2toml.transformations.coerce_bool(value: str) → bool

Convert the value based on is_true() and is_false().

ini2toml.transformations.coerce_scalar(value: str) → int | float | bool | str

Try to convert the given string to a proper “scalar” type (e.g. integer, float, bool, …) with an direct TOML equivalent. If the conversion is unknown or not possible, it will return the same input value (as string).

Note

This function “guesses” the value type based in heuristics and/or regular expressions, therefore there is no guarantee the output has the same type as intended by the original author.

Note

Currently date/time-related types are not supported.

ini2toml.transformations.deprecated(name: str, fn: ~ini2toml.transformations.TF = <function noop>, instead: str = '') → TF

Wrapper around the fn transformation to warn user about deprecation.

ini2toml.transformations.is_false(value: str) → bool

value in ("false", "0", "no", "off", "none", "null", "nil")

ini2toml.transformations.is_float(value: str) → bool

ini2toml.transformations.is_true(value: str) → bool

value in ("true", "1", "yes", "on")

ini2toml.transformations.kebab_case(field: str) → str

ini2toml.transformations.noop(x: T) → T

Return the value unchanged

ini2toml.transformations.pipe(fn1: Callable[[S], T], fn2: Callable[[T], U]) → Callable[[S], U]

ini2toml.transformations.pipe(fn1: Callable[[S], T], fn2: Callable[[T], U], fn3: Callable[[U], V]) → Callable[[S], V]

ini2toml.transformations.pipe(fn1: Callable[[S], T], fn2: Callable[[T], U], fn3: Callable[[U], V], fn4: Callable[[V], X]) → Callable[[S], X]

ini2toml.transformations.pipe(fn1: Callable[[S], T], fn2: Callable[[T], U], fn3: Callable[[U], V], fn4: Callable[[V], X], fn5: Callable[[X], Y]) → Callable[[S], Y]

ini2toml.transformations.pipe(fn1: Callable[[S], T], fn2: Callable[[T], U], fn3: Callable[[U], V], fn4: Callable[[V], X], fn5: Callable[[X], Y], *fn: Callable[[Y], Y]) → Callable[[S], Y]

Compose 1-argument functions respecting the sequence they should be applied:

pipe(fn1, fn2, fn3, ..., fnN)(x) == fnN(...(fn3(fn2(fn1(x)))))

ini2toml.transformations.remove_comments(text: str, comment_mark='#') → str

>>> remove_comments("\nhello\n#comment\nworld\n")
'\nhello\nworld\n'
>>> remove_comments("\n  hello\n\nworld\n")
'\n  hello\n\nworld\n'
>>> remove_comments("\nhello\n  \nworld\n")
'\nhello\n  \nworld\n'

ini2toml.transformations.remove_prefixes(text: str, prefixes: Sequence[str])

ini2toml.transformations.split_comment(value: str, *, comment_prefixes=CP) → Commented[str]

ini2toml.transformations.split_comment(value: str, coerce_fn: Callable[[str], T], comment_prefixes=CP) → Commented[T]

Split a “comment suffix” from the value.

ini2toml.transformations.split_kv_pairs(value: str, key_sep: str = '=', *, pair_sep=',', subsplit_dangling=True, comment_prefixes=CP) → CommentedKV[str]

ini2toml.transformations.split_kv_pairs(value: str, key_sep: str = '=', *, coerce_fn: Callable[[str], T], pair_sep=',', subsplit_dangling=True, comment_prefixes=CP) → CommentedKV[T]

ini2toml.transformations.split_kv_pairs(value: str, key_sep: str, coerce_fn: Callable[[str], T], pair_sep=',', subsplit_dangling=True, comment_prefixes=CP) → CommentedKV[T]

Value encoded as a (potentially) dangling list of key-value pairs.

This function will first try to split the value by lines (dangling list) using str.splitlines(). Then, if subsplit_dangling=True, it will split each line using pair_sep. As a result a list of key-value pairs is obtained. For each item in this list, the key is separated from the value by key_sep. coerce_fn is used to convert the value in each pair.

ini2toml.transformations.split_list(value: str, sep: str = ',', *, subsplit_dangling=True, comment_prefixes=CP, force_multiline=False) → CommentedList[str]

ini2toml.transformations.split_list(value: str, sep: str = ',', *, coerce_fn: Callable[[str], T], subsplit_dangling=True, comment_prefixes=CP, force_multiline=False) → CommentedList[T]

ini2toml.transformations.split_list(value: str, sep: str, coerce_fn: Callable[[str], T], subsplit_dangling=True, comment_prefixes=CP, force_multiline=False) → CommentedList[T]

Value encoded as a (potentially) dangling list values separated by sep.

This function will first try to split the value by lines (dangling list) using str.splitlines(). Then, if subsplit_dangling=True, it will split each line using sep. As a result a list of items is obtained. For each item in this list coerce_fn is applied.

ini2toml.transformations.split_scalar(value: str, *, comment_prefixes=('#', ';')) → Commented[int | float | bool | str]

Combination of split_comment() and coerce_scalar().