:py:mod:`dissect.target.helpers.configutil`
===========================================

.. py:module:: dissect.target.helpers.configutil


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   dissect.target.helpers.configutil.PeekableIterator
   dissect.target.helpers.configutil.ConfigurationParser
   dissect.target.helpers.configutil.Default
   dissect.target.helpers.configutil.Ini
   dissect.target.helpers.configutil.Txt
   dissect.target.helpers.configutil.Xml
   dissect.target.helpers.configutil.ListUnwrapper
   dissect.target.helpers.configutil.Json
   dissect.target.helpers.configutil.Yaml
   dissect.target.helpers.configutil.Toml
   dissect.target.helpers.configutil.ScopeManager
   dissect.target.helpers.configutil.Indentation
   dissect.target.helpers.configutil.SystemD
   dissect.target.helpers.configutil.ParserOptions
   dissect.target.helpers.configutil.ParserConfig



Functions
~~~~~~~~~

.. autoapisummary::
   :nosignatures:

   dissect.target.helpers.configutil.parse
   dissect.target.helpers.configutil.parse_config



Attributes
~~~~~~~~~~

.. autoapisummary::

   dissect.target.helpers.configutil.HAS_YAML
   dissect.target.helpers.configutil.HAS_TOML
   dissect.target.helpers.configutil.MATCH_MAP
   dissect.target.helpers.configutil.CONFIG_MAP
   dissect.target.helpers.configutil.KNOWN_FILES


.. py:data:: HAS_YAML
   :value: True

   

.. py:data:: HAS_TOML
   :value: True

   

.. py:class:: PeekableIterator(iterable)


   Source gotten from:
   https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html#peekable

   .. py:method:: __iter__()


   .. py:method:: __next__()


   .. py:method:: peek()



.. py:class:: ConfigurationParser(collapse: Union[bool, Iterable[str]] = False, collapse_inverse: bool = False, separator: tuple[str] = ('=', ), comment_prefixes: tuple[str] = (';', '#'))


   A configuration parser where you can configure certain aspects of the parsing mechanism.

   .. attribute:: parsed_data

      The resulting dictionary after parsing.

   :param collapse: A ``bool`` or an ``Iterator``:
                    If ``True``: it will collapse all the resulting dictionary values.
                    If an ``Iterable`` it will collapse on the keys defined in ``collapse``.
   :param collapse_inverse: Inverses the collapsing mechanism. Collapse on everything that is not inside ``collapse``.
   :param separator: Contains what values it should look for as a separator.
   :param comment_prefixes: Contains what constitutes as a comment.

   .. py:method:: __getitem__(item: Any) -> Union[dict, str]


   .. py:method:: __contains__(item: str) -> bool


   .. py:method:: parse_file(fh: TextIO) -> None
      :abstractmethod:

      Parse the contents of ``fh`` into key/value pairs.

      This function should **set** :attr:`parsed_data` as a side_effect.

      :param fh: The text to parse.


   .. py:method:: get(item: str, default: Optional[Any] = None) -> Any


   .. py:method:: read_file(fh: TextIO) -> None

      Parse a configuration file.

      :raises ConfigurationParsingError: If any exception occurs during during the parsing process.


   .. py:method:: keys() -> KeysView


   .. py:method:: items() -> ItemsView



.. py:class:: Default(*args, **kwargs)


   Bases: :py:obj:`ConfigurationParser`

   Parse a configuration file specified by ``separator`` and ``comment_prefixes``.

   This parser splits only on the first ``separator`` it finds:

       key<separator>value     -> {"key": "value"}

       key<separator>value

         continuation
                               -> {"key": "value continuation"}

       # Unless we collapse values, we add them to a list to not overwrite any values.
       key<separator>value1
       key<separator>value2
                               -> {key: [value1, value2]}

       <empty_space><comment>  -> skip

   .. py:method:: line_reader(fh: TextIO, strip_comments: bool = True) -> Iterator[str]


   .. py:method:: parse_file(fh: TextIO) -> None

      Parse the contents of ``fh`` into key/value pairs.

      This function should **set** :attr:`parsed_data` as a side_effect.

      :param fh: The text to parse.



.. py:class:: Ini(*args, **kwargs)


   Bases: :py:obj:`ConfigurationParser`

   Parses an ini file according using the built-in python ConfigParser

   .. py:method:: parse_file(fh: io.TextIO) -> None

      Parse the contents of ``fh`` into key/value pairs.

      This function should **set** :attr:`parsed_data` as a side_effect.

      :param fh: The text to parse.



.. py:class:: Txt(collapse: Union[bool, Iterable[str]] = False, collapse_inverse: bool = False, separator: tuple[str] = ('=', ), comment_prefixes: tuple[str] = (';', '#'))


   Bases: :py:obj:`ConfigurationParser`

   Read the file into ``content``, and show the bumber of bytes read.

   .. py:method:: parse_file(fh: TextIO) -> None

      Parse the contents of ``fh`` into key/value pairs.

      This function should **set** :attr:`parsed_data` as a side_effect.

      :param fh: The text to parse.



.. py:class:: Xml(collapse: Union[bool, Iterable[str]] = False, collapse_inverse: bool = False, separator: tuple[str] = ('=', ), comment_prefixes: tuple[str] = (';', '#'))


   Bases: :py:obj:`ConfigurationParser`

   Parses an XML file. Ignores any constructor parameters passed from ``ConfigurationParser`.

   .. py:method:: parse_file(fh: TextIO) -> None

      Parse the contents of ``fh`` into key/value pairs.

      This function should **set** :attr:`parsed_data` as a side_effect.

      :param fh: The text to parse.



.. py:class:: ListUnwrapper


   Provides utility functions to unwrap dictionary objects out of lists.

   .. py:method:: unwrap(data: Union[dict, list]) -> Union[dict, list]
      :staticmethod:

      Transforms a list with dictionaries to a dictionary.

      The order of the list is preserved. If no dictionary is found,
      the list remains untouched:

          ["value1", "value2"]    -> ["value1", "value2"]

          {"data": "value"}       -> {"data": "value"}

          [{"data": "value"}]     -> {
                                         "list_item0": {
                                              "data": "value"
                                         }
                                     }



.. py:class:: Json(collapse: Union[bool, Iterable[str]] = False, collapse_inverse: bool = False, separator: tuple[str] = ('=', ), comment_prefixes: tuple[str] = (';', '#'))


   Bases: :py:obj:`ConfigurationParser`

   Parses a JSON file.

   .. py:method:: parse_file(fh: TextIO)

      Parse the contents of ``fh`` into key/value pairs.

      This function should **set** :attr:`parsed_data` as a side_effect.

      :param fh: The text to parse.



.. py:class:: Yaml(collapse: Union[bool, Iterable[str]] = False, collapse_inverse: bool = False, separator: tuple[str] = ('=', ), comment_prefixes: tuple[str] = (';', '#'))


   Bases: :py:obj:`ConfigurationParser`

   Parses a Yaml file.

   .. py:method:: parse_file(fh: TextIO) -> None

      Parse the contents of ``fh`` into key/value pairs.

      This function should **set** :attr:`parsed_data` as a side_effect.

      :param fh: The text to parse.



.. py:class:: Toml(collapse: Union[bool, Iterable[str]] = False, collapse_inverse: bool = False, separator: tuple[str] = ('=', ), comment_prefixes: tuple[str] = (';', '#'))


   Bases: :py:obj:`ConfigurationParser`

   Parses a Toml file.

   .. py:method:: parse_file(fh: TextIO) -> None

      Parse the contents of ``fh`` into key/value pairs.

      This function should **set** :attr:`parsed_data` as a side_effect.

      :param fh: The text to parse.



.. py:class:: ScopeManager


   A (context)manager for dictionary scoping.

   This class provides utility functions to keep track of scopes inside a dictionary.

   .. attribute:: _parents

      A dictionary accounting what child belongs to which parent dictionary.

   .. attribute:: _root

      The initial dictionary.

   .. attribute:: _current

      The current dictionary.

   .. attribute:: _previous

      The node before the current (changed) node.

   .. py:method:: __enter__() -> ScopeManager


   .. py:method:: __exit__(type: Optional[ScopeManager.__exit__.type[BaseException]], value: Optional[BaseException], traceback: Optional[types.TracebackType]) -> None


   .. py:method:: push(name: str, keep_prev: bool = False) -> Literal[True]

      Push a new key to the :attr:`_current` dictionary and return that we did.


   .. py:method:: pop(keep_prev: bool = False) -> bool

      Pop :attr:`_current` and return whether we changed the :attr:`_parents` dictionary.


   .. py:method:: update(key: str, value: str) -> None

      Update the :attr:`_current` dictionary with ``key`` and ``value``.


   .. py:method:: update_prev(key: str, value: str) -> None

      Update the :attr:`_previous` dictionary with ``key`` and ``value``.


   .. py:method:: is_root() -> bool

      Utility function to check whether the current dictionary is a root dictionary.


   .. py:method:: clean() -> None

      Clean up the internal state.
      This is called automatically when :class:`ScopeManager` is used as a contextmanager.



.. py:class:: Indentation(*args, **kwargs)


   Bases: :py:obj:`Default`

   This parser is used for files that use a single level of indentation to specify a different scope.

   Examples of these files are the ``sshd_config`` file.
   Where "Match" statements use a single layer of indentation to specify a scope for the key value pairs.

   The parser parses this as the following:

     key value
       key2 value2
                      -> {"key value": {"key2": "value2"}}

   .. py:method:: parse_file(fh: TextIO) -> None

      Parse the contents of ``fh`` into key/value pairs.

      This function should **set** :attr:`parsed_data` as a side_effect.

      :param fh: The text to parse.



.. py:class:: SystemD(*args, **kwargs)


   Bases: :py:obj:`Indentation`

   A :class:`ConfigurationParser` that specifically parses systemd configuration files.

   .. rubric:: Examples

   >>> systemd_data = textwrap.dedent(
           '''
           [Section1]
           Key=Value
           [Section2]
           Key2=Value 2\
               Value 2 continued
           '''
       )
   >>> parser = SystemD(io.StringIO(systemd_data))
   >>> parser.parser_items
   {
       "Section1": {
           "Key": "Value
       },
       "Section2": {
           "Key2": "Value2 Value 2 continued
       }
   }

   .. py:method:: parse_file(fh: TextIO) -> None

      Parse the contents of ``fh`` into key/value pairs.

      This function should **set** :attr:`parsed_data` as a side_effect.

      :param fh: The text to parse.



.. py:class:: ParserOptions


   .. py:attribute:: collapse
      :type: Optional[Union[bool, set]]

      

   .. py:attribute:: collapse_inverse
      :type: Optional[bool]

      

   .. py:attribute:: separator
      :type: Optional[tuple[str]]

      

   .. py:attribute:: comment_prefixes
      :type: Optional[tuple[str]]

      


.. py:class:: ParserConfig


   .. py:attribute:: parser
      :type: type[ConfigurationParser]

      

   .. py:attribute:: collapse
      :type: Optional[Union[bool, set]]

      

   .. py:attribute:: collapse_inverse
      :type: Optional[bool]

      

   .. py:attribute:: separator
      :type: Optional[tuple[str]]

      

   .. py:attribute:: comment_prefixes
      :type: Optional[tuple[str]]

      

   .. py:method:: create_parser(options: Optional[ParserOptions] = None) -> ConfigurationParser



.. py:data:: MATCH_MAP
   :type: dict[str, ParserConfig]

   

.. py:data:: CONFIG_MAP
   :type: dict[tuple[str, Ellipsis], ParserConfig]

   

.. py:data:: KNOWN_FILES
   :type: dict[str, type[ConfigurationParser]]

   

.. py:function:: parse(path: Union[dissect.target.filesystem.FilesystemEntry, dissect.target.helpers.fsutil.TargetPath], hint: Optional[str] = None, *args, **kwargs) -> configparser.ConfigParser

   Parses the content of an ``path`` or ``entry`` to a dictionary.

   :param path: The path to either a directory or file.
   :param hint: What kind of parser should be used.
   :param collapse: Whether it should collapse everything or just a certain set of keys.
   :param collapse_inverse: Invert the collapse function to collapse everything but the keys inside ``collapse``.
   :param separator: The separator that should be used for parsing.
   :param comment_prefixes: What is specified as a comment.

   :raises FileNotFoundError: If the ``path`` is not a file.


.. py:function:: parse_config(entry: dissect.target.filesystem.FilesystemEntry, hint: Optional[str] = None, options: Optional[ParserOptions] = None) -> configparser.ConfigParser