ConfigUpdater 4.0__py3-none-any.whl

configupdater/document.py

@@ -0,0 +1,417 @@
+"""This module focus in the top level data layer API of ConfigUpdater, i.e.
+how to access and modify the sections of the configurations.
+
+Differently from :mod:`configparser`, the different aspects of the ConfigUpdater API are
+split between several modules.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, MutableMapping
+from configparser import (
+    ConfigParser,
+    DuplicateSectionError,
+    NoOptionError,
+    NoSectionError,
+)
+from enum import Enum
+from typing import Any, Self, TypeVar, overload
+
+from .block import Comment, Space
+from .container import Container
+from .option import Option
+from .section import Section
+
+# Used in parser getters to indicate the default behaviour when a specific
+# option is not found it to raise an exception. Created to enable 'None' as
+# a valid fallback value.
+_UniqueValues = Enum("_UniqueValues", "_UNSET")
+_UNSET = _UniqueValues._UNSET
+
+T = TypeVar("T")
+
+ConfigContent = Section | Comment | Space
+
+
+class Document(Container[ConfigContent], MutableMapping[str, Section]):
+    """Access to the data manipulation API from **ConfigUpdater**.
+
+    A ``Document`` object tries to implement a familiar *dict-like* interface,
+    via :class:`MutableMapping`. However, it also tries to be as compatible as possible
+    with the stdlib's :class:`~configparser.ConfigParser`. This means that there are a
+    few methods that will work differently from what users familiar with *dict-like*
+    interfaces would expect. The most notable example is :meth:`get`.
+
+    A important difference between ConfigUpdater's ``Document`` model and
+    :class:`~configparser.ConfigParser` is the behaviour of the :class:`Section`
+    objects.
+    If we represent the type of a *dict-like* (or :class:`MutableMapping`) object by
+    ``M[K, V]``, where ``K`` is the type of its keys and ``V`` is the type of the
+    associated values, ConfigUpdater's sections would be equivalent to
+    ``M[str, Option]``, while ConfigParser's would be ``M[str, str]``.
+
+    This means that when you try to access a key inside a section in ConfigUpdater, you
+    are going to receive a :class:`Option` object, not its value.
+    To access the value of the option you need to call :class:`Option.value`.
+    """
+
+    def _get_section_idx(self, name: str) -> int:
+        return next(
+            i
+            for i, entry in enumerate(self._structure)
+            if isinstance(entry, Section) and entry.name == name
+        )
+
+    def optionxform(self, optionstr: str) -> str:
+        """Converts an option key for unification
+
+        By default it uses :meth:`str.lower`, which means that ConfigUpdater will
+        compare options in a case insensitive way.
+
+        This implementation mimics ConfigParser API, and can be configured as described
+        in :meth:`configparser.ConfigParser.optionxform`.
+
+        Warning:
+            As in ConfigParser, a custom ``optionxform`` must be idempotent, i.e.
+            ``optionxform(optionxform(key)) == optionxform(key)``. The keys that
+            ConfigUpdater returns, e.g. when iterating over a section, are already
+            transformed and are transformed again when they are used for a lookup.
+            :meth:`str.lower`, :meth:`str.upper` and :class:`str` (to keep keys
+            case-sensitive) satisfy this, while something like
+            ``lambda key: "prefix_" + key`` does not.
+
+        Args:
+             optionstr (str): key name
+
+        Returns:
+            str: unified option name
+        """
+        return optionstr.lower()
+
+    def validate_format(self, **kwargs: Any) -> bool:
+        """Call ConfigParser to validate config
+
+        Args:
+            kwargs: are passed to :class:`configparser.ConfigParser`
+
+        Raises:
+            configparser.ParsingError: if syntax errors are found
+
+        Returns:
+            ``True`` when no error is found
+        """
+        kwargs.pop("space_around_delimiters", None)
+        parser = ConfigParser(**kwargs)
+        parser.read_string(str(self))
+        return True
+
+    def iter_sections(self) -> Iterator[Section]:
+        """Iterate only over section blocks"""
+        return (block for block in self._structure if isinstance(block, Section))
+
+    def section_blocks(self) -> list[Section]:
+        """Returns all section blocks
+
+        Returns:
+            list: list of :class:`Section` blocks
+        """
+        return list(self.iter_sections())
+
+    def sections(self) -> list[str]:
+        """Return a list of section names
+
+        Returns:
+            list: list of section names
+        """
+        return [section.name for section in self.iter_sections()]
+
+    def __iter__(self) -> Iterator[str]:
+        return (b.name for b in self.iter_blocks() if isinstance(b, Section))
+
+    def __str__(self) -> str:
+        return "".join(str(block) for block in self._structure)
+
+    def __getitem__(self, key: str) -> Section:
+        for section in self.section_blocks():
+            if section.name == key:
+                return section
+
+        raise KeyError(f"No section `{key}` found", {"key": key})
+
+    def __setitem__(self, key: str, value: Section) -> None:
+        if not isinstance(value, Section):
+            raise ValueError("Value must be of type Section!")
+        if key in self:
+            idx = self._get_section_idx(key)
+            self.__getitem__(key).detach()
+            value.attach(self)
+            self._structure.insert(idx, value)
+        else:
+            if value.name != key:
+                raise ValueError(
+                    f"Set key `{key}` does not equal option key `{value.name}`"
+                )
+            self.add_section(value)
+
+    def __delitem__(self, key: str) -> None:
+        if not self.remove_section(key):
+            raise KeyError(f"No section `{key}` found", {"key": key})
+
+    # MutableMapping[str, Section] accepts key: object, which is fine here since
+    # the key is only compared with the section names
+    def __contains__(self, key: object) -> bool:
+        """Returns whether the given section exists.
+
+        Args:
+            key (str): name of section
+
+        Returns:
+            bool: whether the section exists
+        """
+        return next((True for s in self.iter_sections() if s.name == key), False)
+
+    has_section = __contains__
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, self.__class__):
+            return self._structure == other._structure
+        else:
+            return False
+
+    def clear(self) -> None:
+        for block in self._structure:
+            block.detach()
+        self._structure.clear()
+
+    def add_section(self, section: str | Section) -> None:
+        """Create a new section in the configuration.
+
+        Raise DuplicateSectionError if a section by the specified name
+        already exists. Raise ValueError if name is DEFAULT.
+
+        Args:
+            section (str or :class:`Section`): name or Section type
+        """
+        if isinstance(section, str):
+            # create a new section
+            section_obj = Section(section)
+        elif isinstance(section, Section):
+            section_obj = section
+        else:
+            raise ValueError("Parameter must be a string or Section type!")
+
+        if self.has_section(section_obj.name):
+            raise DuplicateSectionError(section_obj.name)
+
+        # Ensure a newline before the new section if the last block
+        # doesn't end with one (e.g. file without trailing newline)
+        if self._structure and not str(self._structure[-1]).endswith("\n"):
+            space = Space(container=self)
+            space.add_line("\n")
+            self._structure.append(space)
+
+        section_obj.attach(self)
+        self._structure.append(section_obj)
+
+    def options(self, section: str) -> list[str]:
+        """Returns list of configuration options for the named section.
+
+        Args:
+            section (str): name of section
+
+        Returns:
+            list: list of option names
+        """
+        if not self.has_section(section):
+            raise NoSectionError(section) from None
+        return self.__getitem__(section).options()
+
+    # The following is a pragmatic violation of Liskov substitution principle:
+    # As dicts, Mappings should have get(self, key: str, default: T) -> T
+    # but ConfigParser overwrites it and uses the function to offer a different
+    # functionality
+    @overload  # type: ignore[override]
+    def get(self, section: str, option: str) -> Option: ...
+
+    @overload
+    def get(self, section: str, option: str, fallback: T) -> Option | T: ...
+
+    def get(
+        self, section: str, option: str, fallback: T | _UniqueValues = _UNSET
+    ) -> Option | T:
+        """Gets an option object for a given section or a fallback value.
+
+        Warning:
+            Please notice this method works differently from what is expected of
+            :meth:`MutableMapping.get` (or :meth:`dict.get`).
+            Similarly to :meth:`configparser.ConfigParser.get`, will take least 2
+            arguments, and the second argument does not correspond to a default value.
+
+            This happens because this function is not designed to return a
+            :obj:`Section` of the :obj:`ConfigUpdater` document, but instead a nested
+            :obj:`Option`.
+
+            See :meth:`get_section`, if instead, you want to retrieve a :obj:`Section`.
+
+        Args:
+            section (str): section name
+            option (str): option name
+            fallback (T): if the key is not found and fallback is provided, the
+              ``fallback`` value will be returned. ``None`` is a valid fallback value.
+
+        .. attention::
+            When ``option`` is not present, the ``fallback`` value itself is
+            returned. If you want instead to obtain a new ``Option`` object
+            with a default value associated with it, you can try the following::
+
+                configupdater.get("section", "option", fallback=Option("name", value))
+
+            ... which roughly corresponds to::
+
+                configupdater["section"].get("option", Option("name", value))
+
+
+        Raises:
+            :class:`NoSectionError`: if ``section`` cannot be found
+            :class:`NoOptionError`: if the option cannot be found and no ``fallback``
+                was given
+
+        Returns:
+            :class:`Option` object holding key/value pair when it exists.  Otherwise,
+            the value passed via the ``fallback`` argument itself (type ``T``).
+        """
+        section_obj = self.get_section(section, _UNSET)
+        if section_obj is _UNSET:
+            raise NoSectionError(section) from None
+
+        value = section_obj.get(option, fallback)
+        # ^  we checked section_obj against _UNSET, so we are sure about its type
+
+        if value is _UNSET:
+            raise NoOptionError(self.optionxform(option), section)
+
+        return value
+
+    @overload
+    def get_section(self, name: str) -> Section | None: ...
+
+    @overload
+    def get_section(self, name: str, default: T) -> Section | T: ...
+
+    def get_section(self, name: str, default: T | None = None) -> Section | T | None:
+        """This method works similarly to :meth:`dict.get`, and allows you
+        to retrieve an entire section by its name, or provide a ``default`` value in
+        case it cannot be found.
+        """
+        return next((s for s in self.iter_sections() if s.name == name), default)
+
+    # The following is a pragmatic violation of Liskov substitution principle
+    # For some reason MutableMapping.items return a Set-like object
+    # but we want to preserve ordering
+    @overload  # type: ignore[override]
+    def items(self) -> list[tuple[str, Section]]: ...
+
+    @overload
+    def items(self, section: str) -> list[tuple[str, Option]]: ...
+
+    def items(
+        self, section: str | _UniqueValues = _UNSET
+    ) -> list[tuple[str, Section]] | list[tuple[str, Option]]:
+        """Return a list of (name, value) tuples for options or sections.
+
+        If section is given, return a list of tuples with (name, value) for
+        each option in the section. Otherwise, return a list of tuples with
+        (section_name, section_type) for each section.
+
+        Args:
+            section (str): optional section name, default UNSET
+
+        Returns:
+            list: list of :class:`Section` or :class:`Option` objects
+        """
+        if section is _UNSET:
+            return [(sect.name, sect) for sect in self.iter_sections()]
+
+        section_obj = self.__getitem__(section)
+        return [(opt.key, opt) for opt in section_obj.iter_options()]
+
+    def has_option(self, section: str, option: str) -> bool:
+        """Checks for the existence of a given option in a given section.
+
+        Args:
+            section (str): name of section
+            option (str): name of option
+
+        Returns:
+            bool: whether the option exists in the given section
+        """
+        return option in self.get_section(section, {})
+
+    def set(
+        self,
+        section: str,
+        option: str,
+        value: str | Iterable[str] | None = None,
+    ) -> Self:
+        """Set an option.
+
+        A new option keeps the given ``option`` name as
+        :attr:`~configupdater.Option.raw_key`, see :meth:`~configupdater.Section.set`.
+        Unlike :meth:`configparser.ConfigParser.set`, which writes the key transformed
+        by ``optionxform`` (lowercase by default), the file gets the given spelling.
+
+        Args:
+            section: section name
+            option: option name
+            value: value, default None
+        """
+        try:
+            section_obj = self.__getitem__(section)
+        except KeyError:
+            raise NoSectionError(section) from None
+        section_obj.set(option, value)
+        return self
+
+    def remove_option(self, section: str, option: str) -> bool:
+        """Remove an option.
+
+        Args:
+            section (str): section name
+            option (str): option name
+
+        Returns:
+            bool: whether the option was actually removed
+        """
+        try:
+            section_obj = self.__getitem__(section)
+        except KeyError:
+            raise NoSectionError(section) from None
+        try:
+            del section_obj[option]
+        except KeyError:
+            return False
+        return True
+
+    def remove_section(self, name: str) -> bool:
+        """Remove a file section.
+
+        Args:
+            name: name of the section
+
+        Returns:
+            bool: whether the section was actually removed
+        """
+        try:
+            idx = self._get_section_idx(name)
+            del self._structure[idx]
+            return True
+        except StopIteration:
+            return False
+
+    def to_dict(self) -> dict[str, dict[str, str | None]]:
+        """Transform to dictionary
+
+        Returns:
+            dict: dictionary with same content
+        """
+        return {sect.name: sect.to_dict() for sect in self.iter_sections()}

configupdater/option.py

@@ -0,0 +1,263 @@
+"""Options are the ultimate mean of configuration inside a configuration value.
+
+They are always associated with a :attr:`~Option.key` (or the name of the configuration
+parameter) and a :attr:`~Option.value`.
+
+Options can also have multi-line values that are usually interpreted as a list of
+values.
+
+When editing configuration files with ConfigUpdater, a handy way of setting a multi-line
+(or comma separated value) for an specific option is to use the
+:meth:`~Option.set_values` method.
+"""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Any, Self, cast
+
+if TYPE_CHECKING:
+    from .document import Document
+    from .section import Section
+
+from .block import AssignMultilineValueError, Block
+
+
+def is_multi_line(value: Any) -> bool:
+    """Checks if a given value has multiple lines"""
+    if isinstance(value, str):
+        return "\n" in value
+    else:
+        return False
+
+
+class NoneValueDisallowed(SyntaxWarning):
+    """Warns that an option without a value is omitted from the output.
+
+    This happens when such an option is converted to a string while the
+    :class:`~configupdater.ConfigUpdater` does not use ``allow_no_value=True``.
+    """
+
+    @classmethod
+    def warn(cls, option: str) -> None:
+        msg = (
+            f"Cannot represent <{option} = None>, the option is omitted. "
+            "Please use ``allow_no_value=True`` with ``ConfigUpdater``."
+        )
+        warnings.warn(msg, cls, stacklevel=2)
+
+
+class Option(Block):
+    """Option block holding a key/value pair.
+
+    ``space_around_delimiters`` decides whether the delimiter is surrounded by spaces
+    when the option is rendered after a change. ``True`` and ``False`` take precedence
+    over the syntax options of the :class:`~configupdater.ConfigUpdater` holding the
+    option. ``None`` (the default) follows its ``space_around_delimiters`` and adds
+    spaces if the option does not belong to a :class:`~configupdater.ConfigUpdater`.
+    """
+
+    def __init__(
+        self,
+        key: str,
+        value: str | None = None,
+        container: Section | None = None,
+        delimiter: str = "=",
+        space_around_delimiters: bool | None = None,
+        line: str | None = None,
+    ):
+        super().__init__(container=container)
+        self._key = key
+        self._values: list[str | None] = [] if value is None else [value]
+        self._value_is_none = value is None
+        self._delimiter = delimiter
+        self._value: str | None = None  # will be filled after join_multiline_value
+        self._updated = False
+        self._multiline_value_joined = False
+        self._space_around_delimiters = space_around_delimiters
+        if line:
+            super().add_line(line)
+        if value is not None:
+            self._set_value(value)
+
+    def add_value(self, value: str | None) -> None:
+        """PRIVATE: this function is not part of the public API of Option.
+        It is only used internally by other classes of the package during parsing.
+        """
+        self._value_is_none = value is None
+        self._values.append(value)
+
+    def add_line(self, line: str) -> Self:
+        """PRIVATE: this function is not part of the public API of Option.
+        It is only used internally by other classes of the package during parsing.
+        """
+        super().add_line(line)
+        self.add_value(line.strip())
+        return self
+
+    def _join_multiline_value(self) -> None:
+        if not self._multiline_value_joined and not self._value_is_none:
+            # do what `_join_multiline_value` in ConfigParser would do
+            self._value = "\n".join(cast(list[str], self._values)).rstrip()
+            self._multiline_value_joined = True
+
+    def _get_delim(self, determine_suffix: bool = True) -> str:
+        document = self._document()
+        opts = getattr(document, "syntax_options", None) or {}
+        value = self._value
+        space = self._space_around_delimiters
+        if space is None:
+            space = opts.get("space_around_delimiters", True)
+        # no space is needed if we use multi-line arguments
+        suffix = "" if determine_suffix and str(value).startswith("\n") else " "
+        delim = f" {self._delimiter}{suffix}" if space else self._delimiter
+        return delim
+
+    def value_start_idx(self) -> int:
+        """Index where the value of the option starts, good for indentation"""
+        delim = self._get_delim(determine_suffix=False)
+        return len(f"{self._key}{delim}")
+
+    def __str__(self) -> str:
+        if not self.updated:
+            return super().__str__()
+
+        document = self._document()
+        opts = getattr(document, "syntax_options", None) or {}
+        value = self._value
+
+        if value is None:
+            if document is None or opts.get("allow_no_value"):
+                return f"{self._key}\n"
+            NoneValueDisallowed.warn(self._key)
+            return ""
+
+        delim = self._get_delim()
+        return f"{self._key}{delim}{value}\n"
+
+    def __repr__(self) -> str:
+        return f"<Option: {self._key} = {self.value!r}>"
+
+    def _instantiate_copy(self) -> Self:
+        """Will be called by :meth:`Block.__deepcopy__`"""
+        self._join_multiline_value()
+        return self.__class__(
+            self._key,
+            self._value,
+            container=None,
+            delimiter=self._delimiter,
+            space_around_delimiters=self._space_around_delimiters,
+        )
+
+    def _document(self) -> Document | None:
+        if self._container is None:
+            return None
+        return cast("Section", self._container)._container
+
+    @property
+    def section(self) -> Section:
+        return cast("Section", self.container)
+
+    @property
+    def key(self) -> str:
+        """Key string associated with the option.
+
+        Please notice that the option key is normalized with
+        :meth:`~configupdater.document.Document.optionxform`.
+
+        When the option object is :obj:`detached <configupdater.block.Block.detach>`,
+        this method will raise a :obj:`NotAttachedError`.
+        """
+        return self.section.document.optionxform(self._key)
+
+    @key.setter
+    def key(self, value: str) -> None:
+        self._join_multiline_value()
+        self._key = value
+        self._updated = True
+
+    @property
+    def raw_key(self) -> str:
+        """Equivalent to :obj:`key`, but before applying :meth:`optionxform`."""
+        return self._key
+
+    @property
+    def value(self) -> str | None:
+        """Value associated with the given option."""
+        self._join_multiline_value()
+        return self._value
+
+    @value.setter
+    def value(self, value: str | None) -> None:
+        if is_multi_line(value):
+            raise AssignMultilineValueError(self)
+        self._set_value(value)
+
+    def _set_value(self, value: str | None) -> None:
+        self._updated = True
+        self._multiline_value_joined = True
+        self._value = value
+        self._values = [value]
+
+    def as_list(self, separator: str = "\n") -> list[str]:
+        """Returns the (multi-line/element) value as a list
+
+        Empty list if value is None, single-element list for a one-element
+        value and an element for each line in a multi-element value.
+
+        Args:
+            separator (str): separator for values, default: line separator
+        """
+        if self._value_is_none:
+            return []
+        else:
+            return [v.strip() for v in cast(str, self.value).strip().split(separator)]
+
+    def append(self, value: str, **kwargs: Any) -> Option:
+        """Append a value to a mult-line value
+
+        Args:
+            value (str): value
+            kwargs: keyword arguments for `set_values`
+        """
+        sep = kwargs.get("separator")
+        new_values = self.as_list() if sep is None else self.as_list(separator=sep)
+
+        new_values.append(value)
+        self.set_values(new_values, **kwargs)
+        return self
+
+    def set_values(
+        self,
+        values: Iterable[str],
+        separator: str = "\n",
+        indent: str | None = None,
+        prepend_newline: bool = True,
+    ) -> None:
+        """Sets the value to a given list of options, e.g. multi-line values
+
+        Args:
+            values (iterable): sequence of values
+            separator (str): separator for values, default: line separator
+            indent (optional str): indentation in case of line separator.
+                If prepend_newline is `True` 4 whitespaces by default, otherwise
+                determine automatically if `None`.
+            prepend_newline (bool): start with a new line or not, resp.
+        """
+        values = list(values).copy()
+        self._updated = True
+        self._multiline_value_joined = True
+        self._values = cast(list[str | None], values)
+
+        if indent is None:
+            indent = 4 * " " if prepend_newline else self.value_start_idx() * " "
+
+        # The most common case of multiline values being preceded by a new line
+        if prepend_newline and "\n" in separator:
+            values = ["", *values]
+            separator = separator + indent
+        elif "\n" in separator:
+            separator = separator + indent
+
+        self._value = separator.join(values)