4912144402087936

Committed 20 Apr 2024 07:16PM UTC coverage: 96.759%. Remained the same

Build # 4912144402087936

Build Type

push

cirrus-ci

Committed by

abravalheri

Commit Message

Improve API documentation (#101)

Run Details

714 of 749 branches covered (95.33%)

Branch coverage included in aggregate %.

7 of 7 new or added lines in 2 files covered. (100.0%)

12 existing lines in 3 files now uncovered.

1555 of 1596 relevant lines covered (97.43%)

10.68 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

95.92

/src/ini2toml/translator.py

import logging
from typing import Mapping, Optional, Sequence

from . import types  # Structural/Abstract types
from .base_translator import EMPTY, BaseTranslator
from .plugins import list_from_entry_points as list_all_plugins

_logger = logging.getLogger(__name__)


# TODO: Once MyPy/other type checkers handle ``partial`` and ``partialmethod``
#       we probably can use them to simply the implementations in this module.


class Translator(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 :class:`ini2toml.types.Translator`, and is very
    similar to :class:`~ini2toml.base_translator.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 :class:`~ini2toml.base_translator.BaseTranslator` for a description of the
    instantiation parameters.

    .. _entry-points: https://packaging.python.org/specifications/entry-points/
    """

    def __init__(
        self,
        plugins: Optional[Sequence[types.Plugin]] = None,
        profiles: Sequence[types.Profile] = (),
        profile_augmentations: Sequence[types.ProfileAugmentation] = (),
        ini_parser_opts: Mapping = EMPTY,
        ini_loads_fn: Optional[types.IniLoadsFn] = None,
        toml_dumps_fn: Optional[types.TomlDumpsFn] = None,
    ):
        super().__init__(
            ini_loads_fn=ini_loads_fn or _discover_ini_loads_fn(),
            toml_dumps_fn=toml_dumps_fn or _discover_toml_dumps_fn(),
            plugins=list_all_plugins() if plugins is None else plugins,
            ini_parser_opts=ini_parser_opts,
            profiles=profiles,
            profile_augmentations=profile_augmentations,
        )


def _discover_ini_loads_fn() -> types.IniLoadsFn:
    try:
        from .drivers.configupdater import parse
    except ImportError:  # pragma: no cover
        from .drivers.configparser import parse

    return parse


def _discover_toml_dumps_fn() -> types.TomlDumpsFn:
    try:
        from .drivers.full_toml import convert
    except ImportError:  # pragma: no cover
        try:
            from .drivers.lite_toml import convert
        except ImportError:
            msg = "Please install either `ini2toml[full]` or `ini2toml[lite]`"
            _logger.warning(f"{msg}. `ini2toml` (alone) is not valid.")
            raise

    return convert


class LiteTranslator(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).
    """

    def __init__(
        self,
        plugins: Optional[Sequence[types.Plugin]] = None,
        profiles: Sequence[types.Profile] = (),
        profile_augmentations: Sequence[types.ProfileAugmentation] = (),
        ini_parser_opts: Mapping = EMPTY,
        ini_loads_fn: Optional[types.IniLoadsFn] = None,
        toml_dumps_fn: Optional[types.TomlDumpsFn] = None,
    ):
        if ini_loads_fn:
            parse = ini_loads_fn
        else:
            from .drivers.configparser import parse

        if toml_dumps_fn:
            convert = toml_dumps_fn
        else:
            from .drivers.lite_toml import convert

        super().__init__(
            ini_loads_fn=parse,
            toml_dumps_fn=convert,
            plugins=plugins,
            ini_parser_opts=ini_parser_opts,
            profiles=profiles,
            profile_augmentations=profile_augmentations,
        )


class FullTranslator(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).
    """

    def __init__(
        self,
        plugins: Optional[Sequence[types.Plugin]] = None,
        profiles: Sequence[types.Profile] = (),
        profile_augmentations: Sequence[types.ProfileAugmentation] = (),
        ini_parser_opts: Mapping = EMPTY,
        ini_loads_fn: Optional[types.IniLoadsFn] = None,
        toml_dumps_fn: Optional[types.TomlDumpsFn] = None,
    ):
        if ini_loads_fn:
            parse = ini_loads_fn
        else:
            from .drivers.configupdater import parse

        if toml_dumps_fn:
            convert = toml_dumps_fn
        else:
            from .drivers.full_toml import convert

        super().__init__(
            ini_loads_fn=parse,
            toml_dumps_fn=convert,
            plugins=plugins,
            ini_parser_opts=ini_parser_opts,
            profiles=profiles,
            profile_augmentations=profile_augmentations,
        )

1	import logging	11✔
2	from typing import Mapping, Optional, Sequence	11✔
3
4	from . import types # Structural/Abstract types	11✔
5	from .base_translator import EMPTY, BaseTranslator	11✔
6	from .plugins import list_from_entry_points as list_all_plugins	11✔
7
8	_logger = logging.getLogger(__name__)	11✔
9
10
11	# TODO: Once MyPy/other type checkers handle ``partial`` and ``partialmethod``
12	# we probably can use them to simply the implementations in this module.
13
14
15	class Translator(BaseTranslator[str]):	11✔
16	"""``Translator`` is the main public Python API exposed by the ``ini2toml``,
17	to convert strings representing ``.ini/.cfg`` files into the ``TOML`` syntax.
18
19	It follows the public API defined in :class:`ini2toml.types.Translator`, and is very
20	similar to :class:`~ini2toml.base_translator.BaseTranslator`.
21	The main difference is that ``Translator`` will try to automatically figure out the
22	values for ``plugins``, ``ini_loads_fn`` and ``toml_dumps_fn`` when they are not
23	passed, based on the installed Python packages (and available `entry-points`_),
24	while ``BaseTranslator`` requires the user to explicitly set these parameters.
25
26	For most of the users ``Translator`` is recommended over ``BaseTranslator``.
27	Most of the times ``Translator`` (or its deterministic variants ``LiteTranslator``,
28	``FullTranslator``) is recommended over ``BaseTranslator``.
29
30	See :class:`~ini2toml.base_translator.BaseTranslator` for a description of the
31	instantiation parameters.
32
33	.. _entry-points: https://packaging.python.org/specifications/entry-points/
34	"""
35
36	def __init__(	11✔
37	self,
38	plugins: Optional[Sequence[types.Plugin]] = None,
39	profiles: Sequence[types.Profile] = (),
40	profile_augmentations: Sequence[types.ProfileAugmentation] = (),
41	ini_parser_opts: Mapping = EMPTY,
42	ini_loads_fn: Optional[types.IniLoadsFn] = None,
43	toml_dumps_fn: Optional[types.TomlDumpsFn] = None,
44	):
45	super().__init__(	11✔
46	ini_loads_fn=ini_loads_fn or _discover_ini_loads_fn(),
47	toml_dumps_fn=toml_dumps_fn or _discover_toml_dumps_fn(),
48	plugins=list_all_plugins() if plugins is None else plugins,
49	ini_parser_opts=ini_parser_opts,
50	profiles=profiles,
51	profile_augmentations=profile_augmentations,
52	)
53
54
55	def _discover_ini_loads_fn() -> types.IniLoadsFn:	11✔
56	try:	11✔
57	from .drivers.configupdater import parse	11✔
58	except ImportError: # pragma: no cover
59	from .drivers.configparser import parse
60
61	return parse	11✔
62
63
64	def _discover_toml_dumps_fn() -> types.TomlDumpsFn:	11✔
65	try:	11✔
66	from .drivers.full_toml import convert	11✔
67	except ImportError: # pragma: no cover
68	try:
69	from .drivers.lite_toml import convert
70	except ImportError:
71	msg = "Please install either `ini2toml[full]` or `ini2toml[lite]`"
72	_logger.warning(f"{msg}. `ini2toml` (alone) is not valid.")
73	raise
74
75	return convert	11✔
76
77
78	class LiteTranslator(Translator):	11✔
79	"""Similar to ``Translator``, but instead of trying to figure out ``ini_loads_fn``
80	and ``toml_dumps_fn`` is will always try to use the ``lite`` flavour
81	(ignoring comments).
82	"""
83
84	def __init__(	11✔
85	self,
86	plugins: Optional[Sequence[types.Plugin]] = None,
87	profiles: Sequence[types.Profile] = (),
88	profile_augmentations: Sequence[types.ProfileAugmentation] = (),
89	ini_parser_opts: Mapping = EMPTY,
90	ini_loads_fn: Optional[types.IniLoadsFn] = None,
91	toml_dumps_fn: Optional[types.TomlDumpsFn] = None,
92	):
93	if ini_loads_fn:	11✔
94	parse = ini_loads_fn	11✔
95	else:
96	from .drivers.configparser import parse	11✔
97
98	if toml_dumps_fn:	11✔
99	convert = toml_dumps_fn	11✔
100	else:
101	from .drivers.lite_toml import convert	11✔
102
103	super().__init__(	11✔
104	ini_loads_fn=parse,
105	toml_dumps_fn=convert,
106	plugins=plugins,
107	ini_parser_opts=ini_parser_opts,
108	profiles=profiles,
109	profile_augmentations=profile_augmentations,
110	)
111
112
113	class FullTranslator(Translator):	11✔
114	"""Similar to ``Translator``, but instead of trying to figure out ``ini_loads_fn``
115	and ``toml_dumps_fn`` is will always try to use the ``full`` flavour
116	(best effort to maintain comments).
117	"""
118
119	def __init__(	11✔
120	self,
121	plugins: Optional[Sequence[types.Plugin]] = None,
122	profiles: Sequence[types.Profile] = (),
123	profile_augmentations: Sequence[types.ProfileAugmentation] = (),
124	ini_parser_opts: Mapping = EMPTY,
125	ini_loads_fn: Optional[types.IniLoadsFn] = None,
126	toml_dumps_fn: Optional[types.TomlDumpsFn] = None,
127	):
128	if ini_loads_fn:	11!
UNCOV 129	parse = ini_loads_fn	×
130	else:
131	from .drivers.configupdater import parse	11✔
132
133	if toml_dumps_fn:	11✔
134	convert = toml_dumps_fn	11✔
135	else:
136	from .drivers.full_toml import convert	11✔
137
138	super().__init__(	11✔
139	ini_loads_fn=parse,
140	toml_dumps_fn=convert,
141	plugins=plugins,
142	ini_parser_opts=ini_parser_opts,
143	profiles=profiles,
144	profile_augmentations=profile_augmentations,
145	)

abravalheri / ini2toml / 4912144402087936

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous