ini2toml.api

Public API available for general usage.

In addition to the classes and functions “exported” by this module, the following are also part of the public API:

  • The public members of the types module.

  • The public members of the errors module.

  • The activate function in each submodule of the plugins package

Please notice there might be classes of similar names exported by both api and types. When this happens, the classes in types are not concrete implementations, but instead act as protocols (i.e. abstract descriptions for checking structural polymorphism during static analysis). These should be preferred when writing type hints and signatures.

Plugin authors can also use functions exported by transformations.

class ini2toml.api.BaseTranslator(ini_loads_fn: Callable[[str, Mapping], IntermediateRepr], toml_dumps_fn: Callable[[IntermediateRepr], T], plugins: Sequence[Callable[[Translator], None]] = (), profiles: Sequence[Profile] = (), profile_augmentations: Sequence[ProfileAugmentation] = (), ini_parser_opts: Mapping = mappingproxy({}))[source]

Bases: Generic[T]

Translator object that follows the public API defined in ini2toml.types.Translator. See Developer Guide for a quick explanation of concepts such as plugins, profiles, profile augmentations, etc.

Parameters:

  • ini_loads_fn –

    function to convert the .ini/.cfg file into an intermediate representation object. Possible values for this argument include:

    • ini2toml.drivers.configparser.parse() (when comments can be simply removed)

    • ini2toml.drivers.configupdater.parse() (when you wish to preserve comments in the TOML output)

  • toml_dumps_fn –

    function to convert the intermediate representation object into (ideally) a TOML string. If you don’t exactly need a TOML string (maybe you want your TOML to be represented by bytes or simply the equivalent dict) you can also pass a Callable[[IntermediateRepr], T] function for any desired T.

    Possible values for this argument include:

    • ini2toml.drivers.lite_toml.convert() (when comments can be simply removed)

    • ini2toml.drivers.full_toml.convert() (when you wish to preserve comments in the TOML output)

    • ini2toml.drivers.plain_builtins.convert() (when you wish to retrieve a dict equivalent to the TOML, instead of string with the TOML syntax)

  • plugins (List[Callable[[ini2toml.types.Translator], None]]) – list of plugins activation functions. By default no plugin will be activated.

  • profiles (Dict[str, ini2toml.types.Profile]) – list of profile objects, by default no profile will be pre-loaded (plugins can still add them).

  • profile_augmentations – list of profile augmentations. By default no profile augmentation will be preloaded (plugins can still add them)

  • ini_parser_opts – syntax options for parsing .ini/.cfg files (see ConfigParser and ConfigUpdater). By default it uses the standard configuration of the selected parser (depending on the choice of ini_loads_fn).

Tip

Most of the times the usage of Translator (or its deterministic variants LiteTranslator, FullTranslator) is preferred over BaseTranslator (unless you are vendoring ini2toml and wants to reduce the number of files included in your project).

augment_profiles(fn: Callable[[Profile], None], active_by_default: bool = False, name: str = '', help_text: str = '')[source]

Register a profile augmentation function to be called after the profile is selected and before the actual translation (see Developer Guide).

dumps(irepr: IntermediateRepr) → T[source]
loads(text: str) → IntermediateRepr[source]
plugins: List[Callable[[Translator], None]]
profiles: Dict[str, Profile]
translate(ini: str, profile_name: str, active_augmentations: Mapping[str, bool] = mappingproxy({})) → T[source]
class ini2toml.api.FullTranslator(plugins: Sequence[Callable[[Translator], None]] | None = None, profiles: Sequence[Profile] = (), profile_augmentations: Sequence[ProfileAugmentation] = (), ini_parser_opts: Mapping = mappingproxy({}), ini_loads_fn: Callable[[str, Mapping], IntermediateRepr] | None = None, toml_dumps_fn: Callable[[IntermediateRepr], str] | None = None)[source]

Bases: Translator

Similar to Translator, but instead of trying to figure out ini_loads_fn and toml_dumps_fn is will always try to use the full flavour (best effort to maintain comments).

class ini2toml.api.LiteTranslator(plugins: Sequence[Callable[[Translator], None]] | None = None, profiles: Sequence[Profile] = (), profile_augmentations: Sequence[ProfileAugmentation] = (), ini_parser_opts: Mapping = mappingproxy({}), ini_loads_fn: Callable[[str, Mapping], IntermediateRepr] | None = None, toml_dumps_fn: Callable[[IntermediateRepr], str] | None = None)[source]

Bases: Translator

Similar to Translator, but instead of trying to figure out ini_loads_fn and toml_dumps_fn is will always try to use the lite flavour (ignoring comments).

class ini2toml.api.Translator(plugins: Sequence[Callable[[Translator], None]] | None = None, profiles: Sequence[Profile] = (), profile_augmentations: Sequence[ProfileAugmentation] = (), ini_parser_opts: Mapping = mappingproxy({}), ini_loads_fn: Callable[[str, Mapping], IntermediateRepr] | None = None, toml_dumps_fn: Callable[[IntermediateRepr], str] | None = None)[source]

Bases: BaseTranslator[str]

Translator is the main public Python API exposed by the ini2toml, to convert strings representing .ini/.cfg files into the TOML syntax.

It follows the public API defined in ini2toml.types.Translator, and is very similar to BaseTranslator. The main difference is that Translator will try to automatically figure out the values for plugins, ini_loads_fn and toml_dumps_fn when they are not passed, based on the installed Python packages (and available entry-points), while BaseTranslator requires the user to explicitly set these parameters.

For most of the users Translator is recommended over BaseTranslator. Most of the times Translator (or its deterministic variants LiteTranslator, FullTranslator) is recommended over BaseTranslator.

See BaseTranslator for a description of the instantiation parameters.