pytest_gee.utils
================

.. py:module:: pytest_gee.utils

.. autoapi-nested-parse::

   functions used to build the API that we don't want to expose to end users.

   .. danger::

       This module is for internal use only and should not be used directly.



Attributes
----------

.. autoapisummary::

   pytest_gee.utils.TASK_FINISHED_STATES


Functions
---------

.. autoapisummary::

   pytest_gee.utils._create_container
   pytest_gee.utils.build_fullpath
   pytest_gee.utils.check_serialized
   pytest_gee.utils.delete_assets
   pytest_gee.utils.export_asset
   pytest_gee.utils.get_assets
   pytest_gee.utils.get_task
   pytest_gee.utils.init_tree
   pytest_gee.utils.round_data
   pytest_gee.utils.wait


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

.. py:function:: _create_container(asset_request)

   Create a container for the asset request depending on the requested type.

   :param asset_request: the asset request specifying the type of asset to create. Convention is <asset_id>::<asset_type>

   :returns: the asset_id of the container


.. py:function:: build_fullpath(datadir, request, extension, basename = None, fullpath = None, with_test_class_names = False)

   Generate a fullpath from parameters of the test.

   :param datadir: Fixture embed_data.
   :param request: Pytest request object.
   :param extension: Extension of files compared by this check.
   :param basename: basename of the file to test/record. If not given the name of the test is used. Use either `basename` or `fullpath`.
   :param fullpath: complete path to use as a reference file. This option will ignore ``datadir`` fixture when reading *expected* files but will still use it to write *obtained* files. Useful if a reference file is located in the session data dir for example.
   :param with_test_class_names: if true it will use the test class name (if any) to compose the basename.


.. py:function:: check_serialized(object, path, datadir, original_datadir, request, force_regen = False, with_test_class_names = False)

   Check if the serialized GEE object is the same as the saved one.

   :param object: the earthnegine object to check
   :param path: the full path to the file to check against.
   :param datadir: Fixture embed_data.
   :param original_datadir: Fixture embed_data.
   :param request: Pytest request object.
   :param force_regen: if True, the file will be regenerated even if it exists.
   :param with_test_class_names: if true it will use the test class name (if any) to compose the basename.

   :raises AssertionError if the serialized object is different from the saved one.:


.. py:function:: delete_assets(asset_id, dry_run = True)

   Delete the selected asset and all its content.

   This method will delete all the files and folders existing in an asset folder.
   By default a dry run will be launched and if you are satisfyed with the displayed names, change the ``dry_run`` variable to ``False``.
   No other warnng will be displayed.

   .. warning::

       If this method is used on the root directory you will loose all your data, it's highly recommended to use a dry run first and carefully review the destroyed files.

   :param asset_id: the Id of the asset or a folder
   :param dry_run: whether or not a dry run should be launched. dry run will only display the files name without deleting them.

   :returns: a list of all the files deleted or to be deleted


.. py:function:: export_asset(object, asset_id, description)

   Export assets to the GEE platform, only working for very simple objects.

   :param object: the object to export
   :param asset_id: the name of the asset to create
   :param description: the description of the task

   :returns: the path of the created asset


.. py:function:: get_assets(folder)

   Get all the assets from the parameter folder. every nested asset will be displayed.

   :param folder: the initial GEE folder

   :returns: 'type', 'name' and 'id'
   :rtype: the asset list. each asset is a dict with 3 keys


.. py:function:: get_task(task_descripsion)

   Search for the described task in the user Task list return None if nothing is found.

   :param task_descripsion: the task description

   :returns: return the found task else None


.. py:function:: init_tree(structure, prefix, root)

   Create an EarthEngine folder tree from a dictionary.

   The input ditionary should described the structure of the folder you want to create.
   The keys are the folder names and the values are the subfolders.
   Once you reach an ``ee.FeatureCollection`` and/or an ``ee.Image`` set it in the dictionary and the function will export the object.

   :param structure: the structure of the folder to create
   :param prefix: the prefix to use on every item (folder, tasks, asset_id, etc.)
   :param root: the root folder of the test where to create the test folder.

   :returns: the path of the created folder

   .. rubric:: Examples

   >>> structure = {
   ...     "folder_1": {
   ...         "image": ee.image(1),
   ...         "fc": ee.FeatureCollection(ee.Geometry.Point([0, 0])),
   ...     },
   ... }
   ... init_tree(structure, "toto")


.. py:function:: round_data(data, prescision = 6)

   Recusrsively Round the values of a list to the given prescision.


.. py:function:: wait(task, timeout = 10 * 60)

   Wait until the selected process is finished or we reached timeout value.

   :param task: name of the running task or the Task object itself.
   :param timeout: timeout in seconds. if set to 0 the parameter is ignored. default to 1 minutes.

   :returns: the final state of the task


.. py:data:: TASK_FINISHED_STATES
   :type:  tuple[str, str, str]