hermes.model.path
=================

.. py:module:: hermes.model.path


Attributes
----------

.. autoapisummary::

   hermes.model.path._log


Classes
-------

.. autoapisummary::

   hermes.model.path.ContextPathGrammar
   hermes.model.path.ContextPath


Functions
---------

.. autoapisummary::

   hermes.model.path.set_in_dict


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

.. py:data:: _log

.. py:function:: set_in_dict(target: dict, key: str, value: object, kwargs)

.. py:class:: ContextPathGrammar

   The pyparsing grammar for ContextGrammar paths.


   .. py:attribute:: key


   .. py:attribute:: index


   .. py:attribute:: field


   .. py:attribute:: path


   .. py:method:: parse(text: str) -> pyparsing.ParseResults
      :classmethod:


      Parse a ContextPath string representation into its individual tokens.

      :param text: The path to parse.
      :return: The pyparsing.ParseResult.



.. py:class:: ContextPath(item: str | int | List[str | int], parent: Optional[ContextPath] = None)

   This class is used to access the different contexts.

   On the one hand, the class allows you to define and manage paths.
   You can simply build them up like follows:

   >>> path = ContextPath('spam')['eggs'][1]['ham']

   will result in a `path` like `spam.eggs[1].ham`.

   hint ::
       The paths are idenpendent from any context.
       You can create and even re-use them independently for different contexts.

       To construct wildcard paths, you can use the `'*'` as accessor.

   If you need a shortcut for building paths from a list of accessors, you can use :py:meth:`ContextPath.make`.
   To parse the string representation, use :py:meth:`ContextPath.parse`.


   .. py:attribute:: merge_strategies
      :value: None



   .. py:attribute:: _type
      :value: None



   .. py:method:: init_merge_strategies()
      :classmethod:



   .. py:property:: parent
      :type: Optional[ContextPath]


      Accessor to the parent node.


   .. py:property:: path
      :type: List[ContextPath]


      Get the whole path from the root as list of items.


   .. py:method:: __getitem__(item: str | int) -> ContextPath

      Create a sub-path for the given `item`.



   .. py:method:: __str__() -> str

      Get the string representation of the path.
      The result is parsable by :py:meth:`ContextPath.parse`



   .. py:method:: __repr__() -> str


   .. py:method:: __eq__(other: ContextPath) -> bool

      This match includes semantics for wildcards.
      Items that access `'*'` will automatically match everything (except for None).



   .. py:method:: __contains__(other: ContextPath) -> bool

      Check whether `other` is a true child of this path.



   .. py:method:: new() -> Any

      Create a new instance of the container this node represents.

      For this to work, the node need to have at least on child node derive (e.g., by using ``self["child"]``).



   .. py:method:: _get_item(target: dict | list, path: ContextPath) -> Optional[ContextPath]
      :staticmethod:



   .. py:method:: _find_in_parent(target: dict, path: ContextPath) -> Any


   .. py:method:: _find_setter(target: dict | list, path: ContextPath, value: Any = None, **kwargs) -> Callable


   .. py:method:: _set_item(target: dict | list, path: ContextPath, value: Any, **kwargs) -> Optional[ContextPath]


   .. py:method:: resolve(target: list | dict, create: bool = False, query: Any = None) -> (ContextPath, list | dict, ContextPath)

      Resolve a given path relative to a given target.

      The method will incrementally try to resolve the entries in the `_target.path`.
      It stops when the requested item was found or when the resolution could not be completed.
      If you set `create` to true, the method tries to create the direct target that contains the selected node.

      :param target: Container to resolve node in.
      :param create: Flags whether missing containers should be created.
      :param query:
      :return: The method returns a tuple with the following values:
          - The path to the last item that could be resolved (e.g., the container of the requested element).
          - The container for the path from the first return value.
          - The rest of the path that could not be resolved.



   .. py:method:: get_from(target: dict | list) -> Any

      Expand the path and return the referenced data from a concrete container.

      :param target: The list or dict that this path points into.
      :return: The value stored at path.



   .. py:method:: update(target: Dict[str, Any] | List, value: Any, tags: Optional[dict] = None, **kwargs)

      Update the data stored at the path in a concrete container.

      How this method actually behaves heavily depends on the active MergeStrategy for the path.

      :param target: The dict inside which the value should be stored.
      :param value: The value to store.
      :param tags: Dictionary containing the tags for all stored values.
      :param kwargs: The tag attibutes for the new value.



   .. py:method:: make(path: Iterable[str | int]) -> ContextPath
      :classmethod:


      Convert a list of item accessors into a ContextPath.

      :param path: The items in the order of access.
      :return: A ContextPath that reference the selected value.



   .. py:method:: parse(path: str) -> ContextPath
      :classmethod:


      Parse a string representation of a ContextPath into a proper object.

      :param path: The path to parse.
      :return: A new ContextPath that references the selected path.