hamyar_paygah.utils.xml_utils
=============================

.. py:module:: hamyar_paygah.utils.xml_utils

.. autoapi-nested-parse::

   Utility functions relate to XML.



Attributes
----------

.. autoapisummary::

   hamyar_paygah.utils.xml_utils.E


Functions
---------

.. autoapisummary::

   hamyar_paygah.utils.xml_utils.get_text
   hamyar_paygah.utils.xml_utils.get_integer
   hamyar_paygah.utils.xml_utils.get_bool
   hamyar_paygah.utils.xml_utils.get_time
   hamyar_paygah.utils.xml_utils.get_enum_from_boolean_flags


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

.. py:data:: E

.. py:function:: get_text(document, tag, namespaces, prefix = 'a')

   Return the text content of a direct child element.

   :param document: Parent XML element containing the child.
   :param tag: Child element tag name (without namespace prefix).
   :param namespaces: Mapping of namespace prefixes to URIs.
   :param prefix: Namespace prefix used in lookup. Defaults to "a".

   :returns:     The element text if found and valid. Returns None if
                 - The element does not exist.
                 - The element text is None.
                 - The element text is "-" or "#".
   :rtype: str | None


.. py:function:: get_integer(document, tag, namespaces)

   Return the integer value of a child element's text content.

   The function retrieves the element text using ``get_text`` and attempts
   to convert it to an integer. If direct conversion fails, it extracts the
   first integer sequence found in the text.

   :param document: Parent XML element containing the child.
   :param tag: Child element tag name (without namespace prefix).
   :param namespaces: Mapping of namespace prefixes to URIs.

   :returns:     The parsed integer if found. Returns `None` if
                 - The element does not exist.
                 - The element text is None or empty.
                 - No integer value can be extracted.
   :rtype: int | None


.. py:function:: get_bool(document, tag, namespaces)

   Return the boolean value of a child element's text content.

   The function retrieves the element text using ``get_text`` and returns
   True only if the text is exactly "true" (case-insensitive).
   All other values, including missing or empty elements, return False.

   :param document: Parent XML element containing the child.
   :param tag: Child element tag name (without namespace prefix).
   :param namespaces: Mapping of namespace prefixes to URIs.

   :returns:     True if the element text equals "true" (case-insensitive).
                 Otherwise, False.
   :rtype: bool


.. py:function:: get_time(document, tag, namespaces)

   Return the time value of a child element's text content.

   The function retrieves the element text using ``get_text`` and attempts
   to parse it using the format "%H:%M:%S".

   :param document: Parent XML element containing the child.
   :param tag: Child element tag name (without namespace prefix).
   :param namespaces: Mapping of namespace prefixes to URIs.

   :returns:     A ``datetime.time`` object if parsing succeeds.
                 Returns `None` if:
                 - The element does not exist.
                 - The element text is None.
                 - The text does not match the "%H:%M:%S" format.
   :rtype: datetime.time


.. py:function:: get_enum_from_boolean_flags(document, namespaces, enum_type)

   Extract an enum member from boolean SOAP flag elements.

   Iterates over all members of ``enum_type`` and evaluates the XML
   element whose tag name matches ``member.value`` using ``get_bool()``.

   If one or more flags evaluate to ``True``, the last matching enum
   member in iteration order is returned. If no flags evaluate to
   ``True``, ``None`` is returned.

   This function assumes that each enum member's value corresponds
   to the XML tag name of a boolean flag element.

   :param document: XML SOAP response element.
   :param namespaces: Namespace mapping used for XPath lookups.
   :param enum_type: Enum type whose members map to boolean flag tags.

   :returns:     The matching enum member, or ``None`` if no flag is set.
   :rtype: E | None