ConfigUpdater 4.0__py3-none-any.whl

configupdater/__init__.py

@@ -0,0 +1,18 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # Change here if project is renamed and does not equal the package name
+    dist_name = "ConfigUpdater"
+    __version__ = version(dist_name)
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "unknown"
+finally:
+    del version, PackageNotFoundError
+
+from . import configupdater, parser
+
+# import everything and rely on __ALL__
+from .configupdater import *
+from .parser import *
+
+__all__ = list(set(configupdater.__all__ + parser.__all__))

configupdater/block.py

@@ -0,0 +1,207 @@
+"""Together with :mod:`~configupdater.container` this module forms the basis of
+the class hierarchy in **ConfigUpdater**.
+
+The :class:`Block` is the parent class of everything that can be nested inside a
+configuration file, e.g. comments, sections, options and even sequences of white space.
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import TYPE_CHECKING, Any, Self, TypeVar
+
+if TYPE_CHECKING:
+    from .builder import BlockBuilder
+    from .container import Container
+
+T = TypeVar("T")
+
+
+def _short_repr(block: object) -> str:
+    if isinstance(block, str):
+        return block
+    name = getattr(block, "raw_key", None) or getattr(block, "name", None)
+    name = f" {name!r}" if name else ""
+    return f"<{block.__class__.__name__}{name}>"
+
+
+class NotAttachedError(Exception):
+    """Raised when a block needs a container but is not attached to one.
+
+    Insert the block first, e.g. with ``section[key] = option`` or one of the
+    ``add_before``/``add_after`` builders.
+    """
+
+    def __init__(self, block: str | Block = "The block"):
+        super().__init__(
+            f"{_short_repr(block)} is not attached to a container yet. "
+            "Try to insert it first."
+        )
+
+
+class AlreadyAttachedError(Exception):
+    """Raised when a block is inserted while it is attached to another container.
+
+    A block belongs to exactly one container. Remove it from the old one first with
+    ``detach`` or insert a copy made with :func:`copy.deepcopy`.
+    """
+
+    def __init__(self, block: str | Block = "The block"):
+        super().__init__(
+            f"{_short_repr(block)} has been already attached to a container. "
+            "Try to remove it first using ``detach`` or create a copy using "
+            "stdlib's ``copy.deepcopy``."
+        )
+
+
+class AssignMultilineValueError(Exception):
+    """Raised when a multi-line value is assigned to an option's ``value``.
+
+    Use the option's ``set_values`` or ``append`` method for multi-line values.
+    """
+
+    def __init__(self, block: str | Block = "The block"):
+        super().__init__(
+            f"Trying to assign a multi-line value to {_short_repr(block)}. "
+            "Use the ``set_values`` or ``append`` method to accomplish that."
+        )
+
+
+class Block:
+    """Abstract Block type holding lines
+
+    Block objects hold original lines from the configuration file and hold
+    a reference to a container wherein the object resides.
+
+    The type variable ``T`` is a reference for the type of the sibling blocks
+    inside the container.
+    """
+
+    def __init__(self, container: Container[Any] | None = None) -> None:
+        self._container = container
+        self._lines: list[str] = []
+        self._updated = False
+
+    def __str__(self) -> str:
+        return "".join(self._lines)
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}: {str(self)!r}>"
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, self.__class__):
+            return str(self) == str(other)
+        else:
+            return False
+
+    def __deepcopy__(self, memo: dict[int, Any]) -> Self:
+        clone = self._instantiate_copy()
+        clone._lines = deepcopy(self._lines, memo)
+        clone._updated = self._updated
+        memo[id(self)] = clone
+        return clone
+
+    def _instantiate_copy(self) -> Self:
+        """Auxiliary method that allows subclasses calling ``__deepcopy__``"""
+        return self.__class__(container=None)  # allow overwrite for different init args
+        # ^  A fresh copy should always be made detached from any container
+
+    def add_line(self, line: str) -> Self:
+        """PRIVATE: this function is not part of the public API of Block.
+        It is only used internally by other classes of the package during parsing.
+
+        Add a line to the current block
+
+        Args:
+            line (str): one line to add
+        """
+        self._lines.append(line)
+        return self
+
+    @property
+    def lines(self) -> list[str]:
+        return self._lines
+
+    @property
+    def container(self) -> Container[Any]:
+        """Container holding the block"""
+        if self._container is None:
+            raise NotAttachedError(self)
+        return self._container
+
+    @property
+    def container_idx(self) -> int:
+        """Index of the block within its container"""
+        for idx, block in enumerate(self.container.structure):
+            if block is self:
+                return idx
+        raise ValueError(f"{self!r} is not in the container")
+
+    @property
+    def updated(self) -> bool:
+        """True if the option was changed/updated, otherwise False"""
+        # if no lines were added, treat it as updated since we added it
+        return self._updated or not self._lines
+
+    def _builder(self, idx: int) -> BlockBuilder:
+        from .builder import BlockBuilder
+
+        return BlockBuilder(self.container, idx)
+
+    @property
+    def add_before(self) -> BlockBuilder:
+        """Block builder inserting a new block before the current block"""
+        return self._builder(self.container_idx)
+
+    @property
+    def add_after(self) -> BlockBuilder:
+        """Block builder inserting a new block after the current block"""
+        return self._builder(self.container_idx + 1)
+
+    @property
+    def next_block(self) -> Block | None:
+        """Next block in the current container"""
+        idx = self.container_idx + 1
+        if idx < len(self.container):
+            block: Block = self.container.structure[idx]
+            return block
+        else:
+            return None
+
+    @property
+    def previous_block(self) -> Block | None:
+        """Previous block in the current container"""
+        idx = self.container_idx - 1
+        if idx >= 0:
+            block: Block = self.container.structure[idx]
+            return block
+        else:
+            return None
+
+    def detach(self) -> Self:
+        """Remove and return this block from container"""
+        self.container._remove_block(self.container_idx)
+        self._container = None
+        return self
+
+    def has_container(self) -> bool:
+        """Checks if this block has a container attached"""
+        return self._container is not None
+
+    def attach(self, container: Container[Any]) -> Self:
+        """PRIVATE: Don't use this as a user!
+
+        Rather use `add_*` or the bracket notation
+        """
+        if self._container is not None and self._container is not container:
+            raise AlreadyAttachedError(self)
+        self._container = container
+        return self
+
+
+class Comment(Block):
+    """Comment block"""
+
+
+class Space(Block):
+    """Vertical space block of new lines"""

configupdater/builder.py

@@ -0,0 +1,131 @@
+"""Core of the fluent API used by **ConfigUpdater** to make editing configuration files
+easier.
+"""
+
+from __future__ import annotations
+
+from configparser import DuplicateOptionError, DuplicateSectionError
+from typing import TYPE_CHECKING, Any, Self
+
+if TYPE_CHECKING:
+    from .block import Block
+    from .container import Container
+    from .section import Section
+
+
+class BlockBuilder:
+    """Builder that injects blocks at a given index position."""
+
+    def __init__(self, container: Container[Any], idx: int) -> None:
+        self._container = container
+        self._idx = idx
+
+    def _insert(self, block: Block) -> Self:
+        self._container.structure.insert(self._idx, block)
+        self._idx += 1
+        return self
+
+    def comment(self, text: str, comment_prefix: str = "#") -> Self:
+        """Creates a comment block
+
+        Args:
+            text (str): content of comment without #
+            comment_prefix (str): character indicating start of comment
+
+        Returns:
+            self for chaining
+        """
+        from .block import Comment
+
+        comment = Comment(self._container)
+        if not text.startswith(comment_prefix):
+            text = f"{comment_prefix} {text}"
+        if not text.endswith("\n"):
+            text = "{}{}".format(text, "\n")
+        return self._insert(comment.add_line(text))
+
+    def section(self, section: str | Section) -> Self:
+        """Creates a section block
+
+        Args:
+            section (str or :class:`Section`): name of section or object
+
+        Returns:
+            self for chaining
+        """
+        from .document import Document
+        from .section import Section
+
+        container = self._container
+        if not isinstance(container, Document):
+            raise ValueError("Sections can only be added at section level!")
+
+        if isinstance(section, str):
+            # create a new section
+            section = Section(section)
+        elif not isinstance(section, Section):
+            # Runtime check for callers that ignore the type hints
+            raise ValueError(
+                "Parameter must be a string or Section type!", {"container": section}
+            )
+
+        if container.has_section(section.name):
+            raise DuplicateSectionError(section.name)
+
+        section.attach(container)
+        return self._insert(section)
+
+    def space(self, newlines: int = 1) -> Self:
+        """Creates a vertical space of newlines
+
+        Args:
+            newlines (int): number of empty lines
+
+        Returns:
+            self for chaining
+        """
+        from .block import Space
+
+        space = Space(container=self._container)
+        for _ in range(newlines):
+            space.add_line("\n")
+        return self._insert(space)
+
+    def option(
+        self,
+        key: str,
+        value: str | None = None,
+        *,
+        delimiter: str | None = None,
+        space_around_delimiters: bool | None = None,
+    ) -> Self:
+        """Creates a new option inside a section
+
+        Args:
+            key (str): key of the option
+            value (str or None): value of the option
+            delimiter (str or None): delimiter between key and value, by default
+                the first of the ``delimiters`` given to
+                :class:`~configupdater.ConfigUpdater`
+            space_around_delimiters (bool or None): surround the delimiter with
+                spaces, by default as given to :class:`~configupdater.ConfigUpdater`.
+
+        Returns:
+            self for chaining
+        """
+        from .section import Section
+
+        if not isinstance(self._container, Section):
+            msg = "Options can only be added inside a section!"
+            raise ValueError(msg, {"container": self._container})
+        section = self._container
+        option = section.create_option(
+            key,
+            value,
+            delimiter=delimiter,
+            space_around_delimiters=space_around_delimiters,
+        )
+        if option.key in section.options():
+            raise DuplicateOptionError(section.name, option.key)
+        option.value = value
+        return self._insert(option)

configupdater/configupdater.py

@@ -0,0 +1,217 @@
+"""As the main entry point of the ConfigUpdater library, this module is responsible
+for combining the data layer provided by the :mod:`configupdater.document` module
+and the parsing capabilities of :mod:`configupdater.parser`.
+
+To complete the API, this module adds file handling functions, so that you can read a
+configuration file from the disk, change it to your liking and save the updated
+content.
+"""
+
+from __future__ import annotations
+
+import io
+from collections.abc import Iterable, Mapping
+from configparser import Error
+from types import MappingProxyType as ReadOnlyMapping
+from typing import Any, Self, TextIO
+
+from .block import (
+    AlreadyAttachedError,
+    AssignMultilineValueError,
+    Comment,
+    NotAttachedError,
+    Space,
+)
+from .document import Document
+from .option import NoneValueDisallowed, Option
+from .parser import Parser, PathLike
+from .section import Section
+
+__all__ = [
+    "AlreadyAttachedError",
+    "AssignMultilineValueError",
+    "Comment",
+    "ConfigUpdater",
+    "NoConfigFileReadError",
+    "NoneValueDisallowed",
+    "NotAttachedError",
+    "Option",
+    "Parser",
+    "Section",
+    "Space",
+]
+
+
+class NoConfigFileReadError(Error):
+    """Raised when no configuration file was read but update requested."""
+
+    def __init__(self) -> None:
+        super().__init__("No configuration file was yet read! Use .read(...) first.")
+
+
+class ConfigUpdater(Document):
+    """Tool to parse and modify existing ``cfg`` files.
+
+    ConfigUpdater follows the API of ConfigParser with some differences:
+
+      * inline comments are treated as part of a key's value,
+      * only a single config file can be updated at a time,
+      * the original case of sections and keys are kept,
+      * control over the position of a new section/key.
+
+    Following features are **deliberately not** implemented:
+
+      * interpolation of values,
+      * propagation of parameters from the default section,
+      * conversions of values,
+      * passing key/value-pairs with ``default`` argument,
+      * non-strict mode allowing duplicate sections and keys.
+
+    **ConfigUpdater** objects can be created by passing the same kind of arguments
+    accepted by the :class:`Parser`. After a ConfigUpdater object is created, you can
+    load some content into it by calling any of the ``read*`` methods
+    (:meth:`read`, :meth:`read_file` and :meth:`read_string`).
+
+    Once the content is loaded you can use the ConfigUpdater object more or less in the
+    same way you would use a nested dictionary. Please have a look into
+    :class:`Document` to understand the main differences.
+
+    When you are done changing the configuration file, you can call :meth:`write` or
+    :meth:`update_file` methods.
+    """
+
+    def __init__(
+        self,
+        allow_no_value: bool = False,
+        *,
+        delimiters: tuple[str, ...] = ("=", ":"),
+        comment_prefixes: tuple[str, ...] = ("#", ";"),
+        inline_comment_prefixes: tuple[str, ...] | None = None,
+        strict: bool = True,
+        empty_lines_in_values: bool = True,
+        space_around_delimiters: bool = True,
+    ) -> None:
+        self._parser_opts: dict[str, Any] = {
+            "allow_no_value": allow_no_value,
+            "delimiters": delimiters,
+            "comment_prefixes": comment_prefixes,
+            "inline_comment_prefixes": inline_comment_prefixes,
+            "strict": strict,
+            "empty_lines_in_values": empty_lines_in_values,
+            "space_around_delimiters": space_around_delimiters,
+        }
+        self._syntax_options = ReadOnlyMapping(self._parser_opts)
+        self._filename: PathLike | None = None
+        self._encoding: str | None = None
+        super().__init__()
+
+    def _instantiate_copy(self) -> Self:
+        """Will be called by ``Container.__deepcopy__``"""
+        clone = self.__class__(**self._parser_opts)
+        clone.optionxform = self.optionxform  # type: ignore[method-assign]
+        clone._filename = self._filename
+        clone._encoding = self._encoding
+        return clone
+
+    def _parser(self, **kwargs: Any) -> Parser:
+        opts = {"optionxform": self.optionxform, **self._parser_opts, **kwargs}
+        return Parser(**opts)
+
+    @property
+    def syntax_options(self) -> Mapping[str, Any]:
+        return self._syntax_options
+
+    def read(self, filename: PathLike, encoding: str | None = None) -> Self:
+        """Read and parse a filename.
+
+        ``filename`` and ``encoding`` are remembered, so that :meth:`update_file`
+        writes the file back with the encoding it was read with.
+
+        Args:
+            filename (str): path to file
+            encoding (str): encoding of file, default None, i.e. the locale encoding
+                (UTF-8 in UTF-8 mode) like in :func:`open`
+        """
+        encoding = io.text_encoding(encoding)
+        self.clear()
+        self._filename = filename
+        self._encoding = encoding
+        return self._parser().read(filename, encoding=encoding, into=self)
+
+    def read_file(self, f: Iterable[str], source: str | None = None) -> Self:
+        """Like read() but the argument must be a file-like object.
+
+        The ``f`` argument must be iterable, returning one line at a time.
+        Optional second argument is the ``source`` specifying the name of the
+        file being read. If not given, it is taken from f.name. If ``f`` has no
+        ``name`` attribute, ``<???>`` is used.
+
+        If ``f`` has a ``name`` attribute, like a file opened with :func:`open`,
+        :meth:`update_file` writes to this file using ``f.encoding`` (the default
+        encoding if ``f`` has none). Otherwise, the file and encoding of a previous
+        ``read*`` call are kept for :meth:`update_file`.
+
+        Args:
+            f: file like object
+            source (str): reference name for file object, default None
+        """
+        self.clear()
+        if hasattr(f, "name"):
+            self._filename = f.name
+            self._encoding = getattr(f, "encoding", None)
+        return self._parser().read_file(f, source, self)
+
+    def read_string(self, string: str, source: str = "<string>") -> Self:
+        """Read configuration from a given string.
+
+        The file and encoding of a previous ``read*`` call are kept for
+        :meth:`update_file`.
+
+        Args:
+            string (str): string containing a configuration
+            source (str): reference name for file object, default '<string>'
+        """
+        self.clear()
+        return self._parser().read_string(string, source, self)
+
+    def write(self, fp: TextIO, validate: bool = True) -> None:
+        # TODO: For Python>=3.8 instead of TextIO we can define a Writeable protocol
+        """Write an .cfg/.ini-format representation of the configuration state.
+
+        Args:
+            fp (file-like object): open file handle
+            validate (Boolean): validate format before writing
+        """
+        if validate:
+            self.validate_format()
+        fp.write(str(self))
+
+    def update_file(self, validate: bool = True) -> Self:
+        """Update the read-in configuration file.
+
+        The file is written with the encoding it was read with, see :meth:`read` and
+        :meth:`read_file`.
+
+        Args:
+            validate (Boolean): validate format before writing
+        """
+        if self._filename is None:
+            raise NoConfigFileReadError()
+        if validate:  # validate BEFORE opening the file!
+            self.validate_format()
+        encoding = io.text_encoding(self._encoding)
+        with open(self._filename, "w", encoding=encoding) as fb:
+            self.write(fb, validate=False)
+        return self
+
+    def validate_format(self, **kwargs: Any) -> bool:
+        """Given the current state of the ``ConfigUpdater`` object (e.g. after
+        modifications), validate its INI/CFG textual representation by parsing it with
+        :class:`~configparser.ConfigParser`.
+
+        The ConfigParser object is instead with the same arguments as the original
+        ConfigUpdater object, but the ``kwargs`` can be used to overwrite them.
+
+        See :meth:`~configupdater.document.Document.validate_format`.
+        """
+        return super().validate_format(**{**self._parser_opts, **kwargs})

configupdater/container.py

@@ -0,0 +1,88 @@
+"""Together with :mod:`~configupdater.block` this module forms the basis of
+the class hierarchy in **ConfigUpdater**.
+
+The :class:`Container` is the parent class of everything that can contain configuration
+blocks, e.g. a section or the entire file itself.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from copy import deepcopy
+from textwrap import indent
+from typing import TYPE_CHECKING, Any, Generic, Self, TypeVar
+
+if TYPE_CHECKING:
+    from .block import Block
+
+T = TypeVar("T", bound="Block")
+
+
+class Container(Generic[T]):
+    """Abstract Mixin Class describing a container that holds blocks of type ``T``"""
+
+    _structure: list[T]
+
+    def __init__(self) -> None:
+        self._structure = []
+
+    def _repr_blocks(self) -> str:
+        blocks = "\n".join(repr(block) for block in self._structure)
+        blocks = indent(blocks, " " * 4)
+        return f"[\n{blocks.rstrip()}\n]" if blocks.strip() else "[]"
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__} {self._repr_blocks()}>"
+
+    def __deepcopy__(self, memo: dict[int, Any]) -> Self:
+        clone = self._instantiate_copy()
+        memo[id(self)] = clone
+        return clone._copy_structure(self._structure, memo)
+
+    def _copy_structure(self, structure: list[T], memo: dict[int, Any]) -> Self:
+        """``__deepcopy__`` auxiliary method also useful with multi-inheritance"""
+        self._structure = [b.attach(self) for b in deepcopy(structure, memo)]
+        return self
+
+    def _instantiate_copy(self) -> Self:
+        """Auxiliary method that allows subclasses calling ``__deepcopy__``"""
+        return self.__class__()  # allow overwrite for different init args
+
+    @property
+    def structure(self) -> list[T]:
+        return self._structure
+
+    @property
+    def first_block(self) -> T | None:
+        if self._structure:
+            return self._structure[0]
+        else:
+            return None
+
+    @property
+    def last_block(self) -> T | None:
+        if self._structure:
+            return self._structure[-1]
+        else:
+            return None
+
+    def _remove_block(self, idx: int) -> Self:
+        """Remove block at index idx within container
+
+        Use `.container_idx` of a block to get the index.
+        Not meant for users, rather use block.detach() instead!
+        """
+        del self._structure[idx]
+        return self
+
+    def iter_blocks(self) -> Iterator[T]:
+        """Iterate over all blocks inside container."""
+        return iter(self._structure)
+
+    def __len__(self) -> int:
+        """Number of blocks in container"""
+        return len(self._structure)
+
+    def append(self, block: T) -> Self:
+        self._structure.append(block)
+        return self