hamyar_paygah.services.missions_list_service
============================================

.. py:module:: hamyar_paygah.services.missions_list_service

.. autoapi-nested-parse::

   Services to get missions list from server.



Attributes
----------

.. autoapisummary::

   hamyar_paygah.services.missions_list_service.CACHE_DIR
   hamyar_paygah.services.missions_list_service.HTTP_OK_STATUS


Functions
---------

.. autoapisummary::

   hamyar_paygah.services.missions_list_service._fetch_missions_list
   hamyar_paygah.services.missions_list_service._get_cache_file_path
   hamyar_paygah.services.missions_list_service._save_xml_cache
   hamyar_paygah.services.missions_list_service._load_xml_cache
   hamyar_paygah.services.missions_list_service.get_missions_list


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

.. py:data:: CACHE_DIR

.. py:data:: HTTP_OK_STATUS
   :value: 200


.. py:function:: _fetch_missions_list(server_address, from_date, to_date, region_id)
   :async:


   Fetch a list of missions for a specific region from the EMS SOAP service.

   This function sends an asynchronous SOAP request to the EMS reporting
   service and retrieves the raw XML response containing mission data for
   the given date range and region.

   The request uses a legacy SOAP endpoint with strict field names.
   In particular, the XML field named ``passsword`` is intentionally
   misspelled and must not be corrected, as changing it results in a
   ``BAD REQUEST`` response from the server.

   :param server_address: Base address of the EMS server (without trailing slash).
   :param from_date: Start date of the report range. The time component is
                     automatically set to ``00:00:00``.
   :param to_date: End date of the report range. The time component is
                   automatically set to ``23:59:59``.
   :param region_id: Numeric identifier of the region for which the report
                     is requested.

   :returns: The raw SOAP response body as a string. The returned value is
             unparsed XML and must be processed by the caller if structured
             data is required.

   :raises aiohttp.ClientError: If the HTTP request fails due to a network
       or connection error.


.. py:function:: _get_cache_file_path(region_id, date)

   Generate a cache file path for a given region and date.

   :param region_id: The ID of the region.
   :type region_id: int
   :param date: The date for which to generate the cache path.
   :type date: datetime.datetime

   :returns: The path to the cache file.
   :rtype: anyio.Path


.. py:function:: _save_xml_cache(path, xml_text)
   :async:


   Save XML response as compressed LZMA file.


.. py:function:: _load_xml_cache(path)
   :async:


   Load XML response from compressed LZMA cache file.


.. py:function:: get_missions_list(server_address, from_date, to_date, region_id, progress_callback = None)
   :async:


   Fetch missions list with caching mechanism.

   This function first checks if a cached response exists for the given
   region and date range. If a valid cache is found, it loads the XML
   data from the cache and parses it into a list of `Mission` objects.
   If no cache is available, it fetches the data from the server, saves
   it to the cache, and then parses it.

   :param server_address: The base address of the EMS server.
   :type server_address: str
   :param from_date: The start date of the missions query.
   :type from_date: datetime.datetime
   :param to_date: The end date of the missions query.
   :type to_date: datetime.datetime
   :param region_id: The region ID to filter missions by.
   :type region_id: int
   :param progress_callback: Optional function that receives two ints:
   :param processed_days:
   :param total_days.:

   :returns:

             A list of `Mission` objects parsed from the server response
                 or cache.
   :rtype: list[Mission]