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 theplugins
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 anintermediate 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 bybytes
or simply the equivalentdict
) you can also pass aCallable[[IntermediateRepr], T]
function for any desiredT
.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 adict
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 (seeConfigParser
andConfigUpdater
). By default it uses the standard configuration of the selected parser (depending on the choice ofini_loads_fn
).
Tip
Most of the times the usage of
Translator
(or its deterministic variantsLiteTranslator
,FullTranslator
) is preferred overBaseTranslator
(unless you are vendoringini2toml
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]]¶
- 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 outini_loads_fn
andtoml_dumps_fn
is will always try to use thefull
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 outini_loads_fn
andtoml_dumps_fn
is will always try to use thelite
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 theini2toml
, to convert strings representing.ini/.cfg
files into theTOML
syntax.It follows the public API defined in
ini2toml.types.Translator
, and is very similar toBaseTranslator
. The main difference is thatTranslator
will try to automatically figure out the values forplugins
,ini_loads_fn
andtoml_dumps_fn
when they are not passed, based on the installed Python packages (and available entry-points), whileBaseTranslator
requires the user to explicitly set these parameters.For most of the users
Translator
is recommended overBaseTranslator
. Most of the timesTranslator
(or its deterministic variantsLiteTranslator
,FullTranslator
) is recommended overBaseTranslator
.See
BaseTranslator
for a description of the instantiation parameters.