eodag 3.0.0b3__py3-none-any.whl → 3.1.0__py3-none-any.whl

eodag/utils/__init__.py

@@ -54,14 +54,10 @@ from typing import (
     TYPE_CHECKING,
     Any,
     Callable,
-    Dict,
     Iterable,
     Iterator,
-    List,
     Mapping,
     Optional,
-    Tuple,
-    Type,
     Union,
     cast,
 )
@@ -79,16 +75,12 @@ from urllib.parse import (  # noqa; noqa
 )
 from urllib.request import url2pathname
 
-if sys.version_info >= (3, 9):
-    from typing import Annotated, get_args, get_origin  # noqa
-else:
-    from typing_extensions import Annotated, get_args, get_origin  # type: ignore # noqa
-
 if sys.version_info >= (3, 12):
     from typing import Unpack  # type: ignore # noqa
 else:
     from typing_extensions import Unpack  # noqa
 
+
 import click
 import orjson
 import shapefile
@@ -99,7 +91,7 @@ from dateutil.tz import UTC
 from jsonpath_ng import jsonpath
 from jsonpath_ng.ext import parse
 from jsonpath_ng.jsonpath import Child, Fields, Index, Root, Slice
-from requests import HTTPError
+from requests import HTTPError, Response
 from shapely.geometry import Polygon, shape
 from shapely.geometry.base import GEOMETRY_TYPES, BaseGeometry
 from tqdm.auto import tqdm
@@ -110,7 +102,7 @@ from eodag.utils.exceptions import MisconfiguredError
 if TYPE_CHECKING:
     from jsonpath_ng import JSONPath
 
-    from eodag.api.product import EOProduct
+    from eodag.api.product._product import EOProduct
 
 
 logger = py_logging.getLogger("eodag.utils")
@@ -123,11 +115,16 @@ eodag_version = metadata("eodag")["Version"]
 USER_AGENT = {"User-Agent": f"eodag/{eodag_version}"}
 
 HTTP_REQ_TIMEOUT = 5  # in seconds
+DEFAULT_SEARCH_TIMEOUT = 20  # in seconds
 DEFAULT_STREAM_REQUESTS_TIMEOUT = 60  # in seconds
 
+REQ_RETRY_TOTAL = 3
+REQ_RETRY_BACKOFF_FACTOR = 2
+REQ_RETRY_STATUS_FORCELIST = [401, 429, 500, 502, 503, 504]
+
 # default wait times in minutes
-DEFAULT_DOWNLOAD_WAIT = 2  # in minutes
-DEFAULT_DOWNLOAD_TIMEOUT = 20  # in minutes
+DEFAULT_DOWNLOAD_WAIT = 0.2  # in minutes
+DEFAULT_DOWNLOAD_TIMEOUT = 10  # in minutes
 
 JSONPATH_MATCH = re.compile(r"^[\{\(]*\$(\..*)*$")
 WORKABLE_JSONPATH_MATCH = re.compile(r"^\$(\.[a-zA-Z0-9-_:\.\[\]\"\(\)=\?\*]+)*$")
@@ -143,6 +140,13 @@ DEFAULT_MAX_ITEMS_PER_PAGE = 50
 # default product-types start date
 DEFAULT_MISSION_START_DATE = "2015-01-01T00:00:00Z"
 
+# update missing mimetypes
+mimetypes.add_type("text/xml", ".xsd")
+mimetypes.add_type("application/x-grib", ".grib")
+mimetypes.add_type("application/x-grib2", ".grib2")
+# jp2 is missing on windows
+mimetypes.add_type("image/jp2", ".jp2")
+
 
 def _deprecated(reason: str = "", version: Optional[str] = None) -> Callable[..., Any]:
     """Simple decorator to mark functions/methods/classes as deprecated.
@@ -237,9 +241,10 @@ class FloatRange(click.types.FloatParamType):
 def slugify(value: Any, allow_unicode: bool = False) -> str:
     """Copied from Django Source code, only modifying last line (no need for safe
     strings).
+
     source: https://github.com/django/django/blob/master/django/utils/text.py
 
-    Convert to ASCII if 'allow_unicode' is False. Convert spaces to hyphens.
+    Convert to ASCII if ``allow_unicode`` is ``False``. Convert spaces to hyphens.
     Remove characters that aren't alphanumerics, underscores, or hyphens.
     Convert to lowercase. Also strip leading and trailing whitespace.
     """
@@ -298,7 +303,7 @@ def strip_accents(s: str) -> str:
 
 def uri_to_path(uri: str) -> str:
     """
-    Convert a file URI (e.g. 'file:///tmp') to a local path (e.g. '/tmp')
+    Convert a file URI (e.g. ``file:///tmp``) to a local path (e.g. ``/tmp``)
     """
     if not uri.startswith("file"):
         raise ValueError("A file URI must be provided (e.g. 'file:///tmp'")
@@ -314,7 +319,7 @@ def path_to_uri(path: str) -> str:
     return Path(path).as_uri()
 
 
-def mutate_dict_in_place(func: Callable[[Any], Any], mapping: Dict[Any, Any]) -> None:
+def mutate_dict_in_place(func: Callable[[Any], Any], mapping: dict[Any, Any]) -> None:
     """Apply func to values of mapping.
 
     The mapping object's values are modified in-place. The function is recursive,
@@ -332,11 +337,11 @@ def mutate_dict_in_place(func: Callable[[Any], Any], mapping: Dict[Any, Any]) ->
             mapping[key] = func(value)
 
 
-def merge_mappings(mapping1: Dict[Any, Any], mapping2: Dict[Any, Any]) -> None:
-    """Merge two mappings with string keys, values from `mapping2` overriding values
-    from `mapping1`.
+def merge_mappings(mapping1: dict[Any, Any], mapping2: dict[Any, Any]) -> None:
+    """Merge two mappings with string keys, values from ``mapping2`` overriding values
+    from ``mapping1``.
 
-    Do its best to detect the key in `mapping1` to override. For example::
+    Do its best to detect the key in ``mapping1`` to override. For example:
 
     >>> mapping2 = {"keya": "new"}
     >>> mapping1 = {"keyA": "obsolete"}
@@ -344,12 +349,11 @@ def merge_mappings(mapping1: Dict[Any, Any], mapping2: Dict[Any, Any]) -> None:
     >>> mapping1
     {'keyA': 'new'}
 
-    If mapping2 has a key that cannot be detected in mapping1, this new key is added
-    to mapping1 as is.
+    If ``mapping2`` has a key that cannot be detected in ``mapping1``, this new key is
+    added to ``mapping1`` as is.
 
     :param mapping1: The mapping containing values to be overridden
-    :param mapping2: The mapping containing values that will override the
-                     first mapping
+    :param mapping2: The mapping containing values that will override the first mapping
     """
     # A mapping between mapping1 keys as lowercase strings and original mapping1 keys
     m1_keys_lowercase = {key.lower(): key for key in mapping1}
@@ -416,7 +420,7 @@ def get_timestamp(date_time: str) -> float:
     If the datetime has no offset, it is assumed to be an UTC datetime.
 
     :param date_time: The datetime string to return as timestamp
-    :returns: The timestamp corresponding to the date_time string in seconds
+    :returns: The timestamp corresponding to the ``date_time`` string in seconds
     """
     dt = isoparse(date_time)
     if not dt.tzinfo:
@@ -425,12 +429,39 @@ def get_timestamp(date_time: str) -> float:
 
 
 def datetime_range(start: dt, end: dt) -> Iterator[dt]:
-    """Generator function for all dates in-between start and end date."""
+    """Generator function for all dates in-between ``start`` and ``end`` date."""
     delta = end - start
     for nday in range(delta.days + 1):
         yield start + datetime.timedelta(days=nday)
 
 
+def is_range_in_range(valid_range: str, check_range: str) -> bool:
+    """Check if the check_range is completely within the valid_range.
+
+    This function checks if both the start and end dates of the check_range
+    are within the start and end dates of the valid_range.
+
+    :param valid_range: The valid date range in the format 'YYYY-MM-DD/YYYY-MM-DD'.
+    :param check_range: The date range to check in the format 'YYYY-MM-DD/YYYY-MM-DD'.
+    :returns: True if check_range is within valid_range, otherwise False.
+    """
+    if "/" not in valid_range or "/" not in check_range:
+        return False
+
+    # Split the date ranges into start and end dates
+    start_valid, end_valid = valid_range.split("/")
+    start_check, end_check = check_range.split("/")
+
+    # Convert the strings to datetime objects using fromisoformat
+    start_valid_dt = datetime.datetime.fromisoformat(start_valid)
+    end_valid_dt = datetime.datetime.fromisoformat(end_valid)
+    start_check_dt = datetime.datetime.fromisoformat(start_check)
+    end_check_dt = datetime.datetime.fromisoformat(end_check)
+
+    # Check if check_range is within valid_range
+    return start_valid_dt <= start_check_dt and end_valid_dt >= end_check_dt
+
+
 class DownloadedCallback:
     """Example class for callback after each download in :meth:`~eodag.api.core.EODataAccessGateway.download_all`"""
 
@@ -445,15 +476,15 @@ class DownloadedCallback:
 class ProgressCallback(tqdm):
     """A callable used to render progress to users for long running processes.
 
-    It inherits from `tqdm.auto.tqdm`, and accepts the same arguments on
-    instantiation: `iterable`, `desc`, `total`, `leave`, `file`, `ncols`,
-    `mininterval`, `maxinterval`, `miniters`, `ascii`, `disable`, `unit`,
-    `unit_scale`, `dynamic_ncols`, `smoothing`, `bar_format`, `initial`,
-    `position`, `postfix`, `unit_divisor`.
+    It inherits from :class:`tqdm.auto.tqdm`, and accepts the same arguments on
+    instantiation: ``iterable``, ``desc``, ``total``, ``leave``, ``file``, ``ncols``,
+    ``mininterval``, ``maxinterval``, ``miniters``, ``ascii``, ``disable``, ``unit``,
+    ``unit_scale``, ``dynamic_ncols``, ``smoothing``, ``bar_format``, ``initial``,
+    ``position``, ``postfix``, ``unit_divisor``.
 
-    It can be globally disabled using `eodag.utils.logging.setup_logging(0)` or
-    `eodag.utils.logging.setup_logging(level, no_progress_bar=True)`, and
-    individually disabled using `disable=True`.
+    It can be globally disabled using ``eodag.utils.logging.setup_logging(0)`` or
+    ``eodag.utils.logging.setup_logging(level, no_progress_bar=True)``, and
+    individually disabled using ``disable=True``.
     """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
@@ -488,8 +519,8 @@ class ProgressCallback(tqdm):
         """Returns another progress callback using the same initial
         keyword-arguments.
 
-        Optional `args` and `kwargs` parameters will be used to create a
-        new `~eodag.utils.ProgressCallback` instance, overriding initial
+        Optional ``args`` and ``kwargs`` parameters will be used to create a
+        new :class:`~eodag.utils.ProgressCallback` instance, overriding initial
         `kwargs`.
         """
 
@@ -511,7 +542,7 @@ def get_progress_callback() -> tqdm:
 
 
 def repeatfunc(func: Callable[..., Any], n: int, *args: Any) -> starmap:
-    """Call `func` `n` times with `args`"""
+    """Call ``func`` ``n`` times with ``args``"""
     return starmap(func, repeat(args, n))
 
 
@@ -526,12 +557,12 @@ def makedirs(dirpath: str) -> None:
 
 
 def rename_subfolder(dirpath: str, name: str) -> None:
-    """Rename first subfolder found in dirpath with given name,
-    raise RuntimeError if no subfolder can be found
+    """Rename first subfolder found in ``dirpath`` with given ``name``,
+    raise :class:`RuntimeError` if no subfolder can be found
 
     :param dirpath: path to the directory containing the subfolder
     :param name: new name of the subfolder
-    :raises: RuntimeError
+    :raises: :class:`RuntimeError`
 
     Example:
 
@@ -545,16 +576,20 @@ def rename_subfolder(dirpath: str, name: str) -> None:
     ...     rename_subfolder(tmpdir, "otherfolder")
     ...     assert not os.path.isdir(somefolder) and os.path.isdir(otherfolder)
 
-    Before:
+    Before::
+
         $ tree <tmp-folder>
         <tmp-folder>
         └── somefolder
             └── somefile
-    After:
+
+    After::
+
         $ tree <tmp-folder>
         <tmp-folder>
         └── otherfolder
             └── somefile
+
     """
     try:
         subdir, *_ = (p for p in glob(os.path.join(dirpath, "*")) if os.path.isdir(p))
@@ -567,10 +602,50 @@ def rename_subfolder(dirpath: str, name: str) -> None:
     )
 
 
+def rename_with_version(file_path: str, suffix: str = "old") -> str:
+    """
+    Renames a file by appending and incrementing a version number if a conflict exists.
+
+    :param file_path: full path of the file to rename
+    :param suffix: suffix preceding version number in case of name conflict
+    :returns: new file path with the version appended or incremented
+
+    Example:
+
+    >>> import tempfile
+    >>> from pathlib import Path
+    >>> with tempfile.TemporaryDirectory() as tmpdir:
+    ...     file_path = (Path(tmpdir) / "foo.txt")
+    ...     file_path.touch()
+    ...     (Path(tmpdir) / "foo_old1.txt").touch()
+    ...     expected = str(Path(tmpdir) / "foo_old2.txt")
+    ...     assert expected == rename_with_version(str(file_path))
+
+    """
+    if not os.path.isfile(file_path):
+        raise FileNotFoundError(f"The file '{file_path}' does not exist.")
+
+    dir_path, file_name = os.path.split(file_path)
+    file_base, file_ext = os.path.splitext(file_name)
+
+    new_file_path = file_path
+
+    # loop and iterate on conflicting existing files
+    version = 0
+    while os.path.exists(new_file_path):
+        version += 1
+        new_file_name = f"{file_base}_{suffix}{version}{file_ext}"
+        new_file_path = os.path.join(dir_path, new_file_name)
+
+    # Rename the file
+    os.rename(file_path, new_file_path)
+    return new_file_path
+
+
 def format_dict_items(
-    config_dict: Dict[str, Any], **format_variables: Any
-) -> Dict[Any, Any]:
-    r"""Recursive apply string.format(\**format_variables) to dict elements
+    config_dict: dict[str, Any], **format_variables: Any
+) -> dict[Any, Any]:
+    r"""Recursively apply :meth:`str.format` to ``**format_variables`` on ``config_dict`` values
 
     >>> format_dict_items(
     ...     {"foo": {"bar": "{a}"}, "baz": ["{b}?", "{b}!"]},
@@ -578,7 +653,7 @@ def format_dict_items(
     ... ) == {"foo": {"bar": "qux"}, "baz": ["quux?", "quux!"]}
     True
 
-    :param config_dict: Dictionnary having values that need to be parsed
+    :param config_dict: Dictionary having values that need to be parsed
     :param format_variables: Variables used as args for parsing
     :returns: Updated dict
     """
@@ -586,9 +661,9 @@ def format_dict_items(
 
 
 def jsonpath_parse_dict_items(
-    jsonpath_dict: Dict[str, Any], values_dict: Dict[str, Any]
-) -> Dict[Any, Any]:
-    """Recursive parse jsonpath elements in dict
+    jsonpath_dict: dict[str, Any], values_dict: dict[str, Any]
+) -> dict[Any, Any]:
+    """Recursively parse :class:`jsonpath_ng.JSONPath` elements in dict
 
     >>> import jsonpath_ng.ext as jsonpath
     >>> jsonpath_parse_dict_items(
@@ -597,7 +672,7 @@ def jsonpath_parse_dict_items(
     ... ) == {'foo': {'bar': 'baz'}, 'qux': ['quux', 'quux']}
     True
 
-    :param jsonpath_dict: Dictionnary having values that need to be parsed
+    :param jsonpath_dict: Dictionary having :class:`jsonpath_ng.JSONPath` values that need to be parsed
     :param values_dict: Values dict used as args for parsing
     :returns: Updated dict
     """
@@ -605,13 +680,13 @@ def jsonpath_parse_dict_items(
 
 
 def update_nested_dict(
-    old_dict: Dict[Any, Any],
-    new_dict: Dict[Any, Any],
+    old_dict: dict[Any, Any],
+    new_dict: dict[Any, Any],
     extend_list_values: bool = False,
     allow_empty_values: bool = False,
     allow_extend_duplicates: bool = True,
-) -> Dict[Any, Any]:
-    """Update recursively old_dict items with new_dict ones
+) -> dict[Any, Any]:
+    """Update recursively ``old_dict`` items with ``new_dict`` ones
 
     >>> update_nested_dict(
     ...     {"a": {"a.a": 1, "a.b": 2}, "b": 3},
@@ -690,10 +765,10 @@ def update_nested_dict(
 
 
 def items_recursive_apply(
-    input_obj: Union[Dict[Any, Any], List[Any]],
+    input_obj: Union[dict[Any, Any], list[Any]],
     apply_method: Callable[..., Any],
     **apply_method_parameters: Any,
-) -> Union[Dict[Any, Any], List[Any]]:
+) -> Union[dict[Any, Any], list[Any]]:
     """Recursive apply method to items contained in input object (dict or list)
 
     >>> items_recursive_apply(
@@ -731,10 +806,10 @@ def items_recursive_apply(
 
 
 def dict_items_recursive_apply(
-    config_dict: Dict[Any, Any],
+    config_dict: dict[Any, Any],
     apply_method: Callable[..., Any],
     **apply_method_parameters: Any,
-) -> Dict[Any, Any]:
+) -> dict[Any, Any]:
     """Recursive apply method to dict elements
 
     >>> dict_items_recursive_apply(
@@ -743,12 +818,12 @@ def dict_items_recursive_apply(
     ... ) == {'foo': {'bar': 'BAZ!'}, 'qux': ['A!', 'B!']}
     True
 
-    :param config_dict: Input nested dictionnary
+    :param config_dict: Input nested dictionary
     :param apply_method: Method to be applied to dict elements
     :param apply_method_parameters: Optional parameters passed to the method
     :returns: Updated dict
     """
-    result_dict: Dict[Any, Any] = deepcopy(config_dict)
+    result_dict: dict[Any, Any] = deepcopy(config_dict)
     for dict_k, dict_v in result_dict.items():
         if isinstance(dict_v, dict):
             result_dict[dict_k] = dict_items_recursive_apply(
@@ -756,7 +831,7 @@ def dict_items_recursive_apply(
             )
         elif any(isinstance(dict_v, t) for t in (list, tuple)):
             result_dict[dict_k] = list_items_recursive_apply(
-                dict_v, apply_method, **apply_method_parameters
+                list(dict_v), apply_method, **apply_method_parameters
             )
         else:
             result_dict[dict_k] = apply_method(
@@ -767,10 +842,10 @@ def dict_items_recursive_apply(
 
 
 def list_items_recursive_apply(
-    config_list: List[Any],
+    config_list: list[Any],
     apply_method: Callable[..., Any],
     **apply_method_parameters: Any,
-) -> List[Any]:
+) -> list[Any]:
     """Recursive apply method to list elements
 
     >>> list_items_recursive_apply(
@@ -803,8 +878,8 @@ def list_items_recursive_apply(
 
 
 def items_recursive_sort(
-    input_obj: Union[List[Any], Dict[Any, Any]],
-) -> Union[List[Any], Dict[Any, Any]]:
+    input_obj: Union[list[Any], dict[Any, Any]],
+) -> Union[list[Any], dict[Any, Any]]:
     """Recursive sort dict items contained in input object (dict or list)
 
     >>> items_recursive_sort(
@@ -828,7 +903,7 @@ def items_recursive_sort(
         return input_obj
 
 
-def dict_items_recursive_sort(config_dict: Dict[Any, Any]) -> Dict[Any, Any]:
+def dict_items_recursive_sort(config_dict: dict[Any, Any]) -> dict[Any, Any]:
     """Recursive sort dict elements
 
     >>> dict_items_recursive_sort(
@@ -836,10 +911,10 @@ def dict_items_recursive_sort(config_dict: Dict[Any, Any]) -> Dict[Any, Any]:
     ... ) == {"a": ["b", {0: 1, 1: 2, 2: 0}], "b": {"a": 0, "b": "c"}}
     True
 
-    :param config_dict: Input nested dictionnary
+    :param config_dict: Input nested dictionary
     :returns: Updated dict
     """
-    result_dict: Dict[Any, Any] = deepcopy(config_dict)
+    result_dict: dict[Any, Any] = deepcopy(config_dict)
     for dict_k, dict_v in result_dict.items():
         if isinstance(dict_v, dict):
             result_dict[dict_k] = dict_items_recursive_sort(dict_v)
@@ -851,7 +926,7 @@ def dict_items_recursive_sort(config_dict: Dict[Any, Any]) -> Dict[Any, Any]:
     return dict(sorted(result_dict.items()))
 
 
-def list_items_recursive_sort(config_list: List[Any]) -> List[Any]:
+def list_items_recursive_sort(config_list: list[Any]) -> list[Any]:
     """Recursive sort dicts in list elements
 
     >>> list_items_recursive_sort(["b", {2: 0, 0: 1, 1: 2}])
@@ -860,7 +935,7 @@ def list_items_recursive_sort(config_list: List[Any]) -> List[Any]:
     :param config_list: Input list containing nested lists/dicts
     :returns: Updated list
     """
-    result_list: List[Any] = deepcopy(config_list)
+    result_list: list[Any] = deepcopy(config_list)
     for list_idx, list_v in enumerate(result_list):
         if isinstance(list_v, dict):
             result_list[list_idx] = dict_items_recursive_sort(list_v)
@@ -873,7 +948,7 @@ def list_items_recursive_sort(config_list: List[Any]) -> List[Any]:
 
 
 def string_to_jsonpath(*args: Any, force: bool = False) -> Union[str, JSONPath]:
-    """Get jsonpath for "$.foo.bar" like string
+    """Get :class:`jsonpath_ng.JSONPath` for ``$.foo.bar`` like string
 
     >>> string_to_jsonpath(None, "$.foo.bar")
     Child(Child(Root(), Fields('foo')), Fields('bar'))
@@ -887,7 +962,7 @@ def string_to_jsonpath(*args: Any, force: bool = False) -> Union[str, JSONPath]:
     Fields('foo')
 
     :param args: Last arg as input string value, to be converted
-    :param force: force conversion even if input string is not detected as a jsonpath
+    :param force: force conversion even if input string is not detected as a :class:`jsonpath_ng.JSONPath`
     :returns: Parsed value
     """
     path_str: str = args[-1]
@@ -950,7 +1025,7 @@ def string_to_jsonpath(*args: Any, force: bool = False) -> Union[str, JSONPath]:
 
 
 def format_string(key: str, str_to_format: Any, **format_variables: Any) -> Any:
-    """Format "{foo}" like string
+    """Format ``"{foo}"``-like string
 
     >>> format_string(None, "foo {bar}, {baz} ?", **{"bar": "qux", "baz": "quux"})
     'foo qux, quux ?'
@@ -973,7 +1048,7 @@ def format_string(key: str, str_to_format: Any, **format_variables: Any) -> Any:
         # defaultdict usage will return "" for missing keys in format_args
         try:
             result = str_to_format.format_map(defaultdict(str, **format_variables))
-        except TypeError as e:
+        except (ValueError, TypeError) as e:
             raise MisconfiguredError(
                 f"Unable to format str={str_to_format} using {str(format_variables)}: {str(e)}"
             )
@@ -986,9 +1061,9 @@ def format_string(key: str, str_to_format: Any, **format_variables: Any) -> Any:
 
 
 def parse_jsonpath(
-    key: str, jsonpath_obj: Union[str, jsonpath.Child], **values_dict: Dict[str, Any]
+    key: str, jsonpath_obj: Union[str, jsonpath.Child], **values_dict: dict[str, Any]
 ) -> Optional[str]:
-    """Parse jsonpah in jsonpath_obj using values_dict
+    """Parse jsonpah in ``jsonpath_obj`` using ``values_dict``
 
     >>> import jsonpath_ng.ext as jsonpath
     >>> parse_jsonpath(None, parse("$.foo.bar"), **{"foo": {"bar": "baz"}})
@@ -1006,7 +1081,7 @@ def parse_jsonpath(
         return jsonpath_obj
 
 
-def nested_pairs2dict(pairs: Union[List[Any], Any]) -> Union[Any, Dict[Any, Any]]:
+def nested_pairs2dict(pairs: Union[list[Any], Any]) -> Union[Any, dict[Any, Any]]:
     """Create a dict using nested pairs
 
     >>> nested_pairs2dict([["foo", [["bar", "baz"]]]])
@@ -1028,12 +1103,12 @@ def nested_pairs2dict(pairs: Union[List[Any], Any]) -> Union[Any, Dict[Any, Any]
 
 
 def get_geometry_from_various(
-    locations_config: List[Dict[str, Any]] = [], **query_args: Any
+    locations_config: list[dict[str, Any]] = [], **query_args: Any
 ) -> BaseGeometry:
-    """Creates a shapely geometry using given query kwargs arguments
+    """Creates a ``shapely.geometry`` using given query kwargs arguments
 
     :param locations_config: (optional) EODAG locations configuration
-    :param query_args: Query kwargs arguments from core.search() method
+    :param query_args: Query kwargs arguments from :meth:`~eodag.api.core.EODataAccessGateway.search`
     :returns: shapely Geometry found
     :raises: :class:`ValueError`
     """
@@ -1117,7 +1192,7 @@ def get_geometry_from_various(
 class MockResponse:
     """Fake requests response"""
 
-    def __init__(self, json_data: Any, status_code: int) -> None:
+    def __init__(self, json_data: Any = None, status_code: int = 200) -> None:
         self.json_data = json_data
         self.status_code = status_code
         self.content = json_data
@@ -1126,10 +1201,21 @@ class MockResponse:
         """Return json data"""
         return self.json_data
 
+    def __iter__(self):
+        yield self
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        pass
+
     def raise_for_status(self) -> None:
         """raises an exception when the status is not ok"""
         if self.status_code != 200:
-            raise HTTPError()
+            response = Response()
+            response.status_code = self.status_code
+            raise HTTPError(response=response)
 
 
 def md5sum(file_path: str) -> str:
@@ -1163,7 +1249,7 @@ def obj_md5sum(data: Any) -> str:
 
 @functools.lru_cache()
 def cached_parse(str_to_parse: str) -> JSONPath:
-    """Cached jsonpath_ng.ext.parse
+    """Cached :func:`jsonpath_ng.ext.parse`
 
     >>> cached_parse.cache_clear()
     >>> cached_parse("$.foo")
@@ -1179,8 +1265,8 @@ def cached_parse(str_to_parse: str) -> JSONPath:
     >>> cached_parse.cache_info()
     CacheInfo(hits=1, misses=2, maxsize=128, currsize=2)
 
-    :param str_to_parse: string to parse as jsonpath
-    :returns: parsed jsonpath
+    :param str_to_parse: string to parse as :class:`jsonpath_ng.JSONPath`
+    :returns: parsed :class:`jsonpath_ng.JSONPath`
     """
     return parse(str_to_parse)
 
@@ -1193,8 +1279,8 @@ def _mutable_cached_yaml_load(config_path: str) -> Any:
         return yaml.load(fh, Loader=yaml.SafeLoader)
 
 
-def cached_yaml_load(config_path: str) -> Dict[str, Any]:
-    """Cached yaml.load
+def cached_yaml_load(config_path: str) -> dict[str, Any]:
+    """Cached :func:`yaml.load`
 
     :param config_path: path to the yaml configuration file
     :returns: loaded yaml configuration
@@ -1203,13 +1289,13 @@ def cached_yaml_load(config_path: str) -> Dict[str, Any]:
 
 
 @functools.lru_cache()
-def _mutable_cached_yaml_load_all(config_path: str) -> List[Any]:
+def _mutable_cached_yaml_load_all(config_path: str) -> list[Any]:
     with open(config_path, "r") as fh:
         return list(yaml.load_all(fh, Loader=yaml.Loader))
 
 
-def cached_yaml_load_all(config_path: str) -> List[Any]:
-    """Cached yaml.load_all
+def cached_yaml_load_all(config_path: str) -> list[Any]:
+    """Cached :func:`yaml.load_all`
 
     Load all configurations stored in the configuration file as separated yaml documents
 
@@ -1221,7 +1307,7 @@ def cached_yaml_load_all(config_path: str) -> List[Any]:
 
 def get_bucket_name_and_prefix(
     url: str, bucket_path_level: Optional[int] = None
-) -> Tuple[Optional[str], Optional[str]]:
+) -> tuple[Optional[str], Optional[str]]:
     """Extract bucket name and prefix from URL
 
     :param url: (optional) URL to use as product.location
@@ -1234,7 +1320,9 @@ def get_bucket_name_and_prefix(
     subdomain = netloc.split(".")[0]
     path = path.strip("/")
 
-    if scheme and bucket_path_level is None:
+    if "/" in path and scheme and subdomain == "s3" and bucket_path_level is None:
+        bucket, prefix = path.split("/", 1)
+    elif scheme and bucket_path_level is None:
         bucket = subdomain
         prefix = path
     elif not scheme and bucket_path_level is None:
@@ -1274,15 +1362,16 @@ def flatten_top_directories(
 
 def deepcopy(sth: Any) -> Any:
     """Customized and faster deepcopy inspired by https://stackoverflow.com/a/45858907
-    `_copy_list` and `_copy_dict` available for the moment
+
+    ``_copy_list`` and ``_copy_dict`` dispatchers available for the moment
 
     :param sth: Object to copy
     :returns: Copied object
     """
-    _dispatcher: Dict[Type[Any], Callable[..., Any]] = {}
+    _dispatcher: dict[type[Any], Callable[..., Any]] = {}
 
     def _copy_list(
-        input_list: List[Any], dispatch: Dict[Type[Any], Callable[..., Any]]
+        input_list: list[Any], dispatch: dict[type[Any], Callable[..., Any]]
     ):
         ret = input_list.copy()
         for idx, item in enumerate(ret):
@@ -1292,7 +1381,7 @@ def deepcopy(sth: Any) -> Any:
         return ret
 
     def _copy_dict(
-        input_dict: Dict[Any, Any], dispatch: Dict[Type[Any], Callable[..., Any]]
+        input_dict: dict[Any, Any], dispatch: dict[type[Any], Callable[..., Any]]
     ):
         ret = input_dict.copy()
         for key, value in ret.items():
@@ -1339,7 +1428,7 @@ def cast_scalar_value(value: Any, new_type: Any) -> Any:
 
     :param value: the scalar value to convert
     :param new_type: the wanted type
-    :returns: scalar value converted to new_type
+    :returns: scalar ``value`` converted to ``new_type``
     """
     if isinstance(value, str) and new_type is bool:
         # Bool is a type with special meaning in Python, thus the special
@@ -1369,24 +1458,42 @@ class StreamResponse:
 
 
 def guess_file_type(file: str) -> Optional[str]:
-    """guess the mime type of a file or URL based on its extension"""
-    mimetypes.add_type("text/xml", ".xsd")
-    mimetypes.add_type("application/x-grib", ".grib")
+    """Guess the mime type of a file or URL based on its extension,
+    using eodag extended mimetypes definition
+
+    >>> guess_file_type('foo.tiff')
+    'image/tiff'
+    >>> guess_file_type('foo.grib')
+    'application/x-grib'
+
+    :param file: file url or path
+    :returns: guessed mime type
+    """
     mime_type, _ = mimetypes.guess_type(file, False)
+    if mime_type == "text/xml":
+        return "application/xml"
     return mime_type
 
 
 def guess_extension(type: str) -> Optional[str]:
-    """guess extension from mime type"""
-    mimetypes.add_type("text/xml", ".xsd")
-    mimetypes.add_type("application/x-grib", ".grib")
+    """Guess extension from mime type, using eodag extended mimetypes definition
+
+    >>> guess_extension('image/tiff')
+    '.tiff'
+    >>> guess_extension('application/x-grib')
+    '.grib'
+
+    :param type: mime type
+    :returns: guessed file extension
+    """
     return mimetypes.guess_extension(type, strict=False)
 
 
 def get_ssl_context(ssl_verify: bool) -> ssl.SSLContext:
     """
-    Returns an SSL context based on ssl_verify argument.
-    :param ssl_verify: ssl_verify parameter
+    Returns an SSL context based on ``ssl_verify`` argument.
+
+    :param ssl_verify: :attr:`~eodag.config.PluginConfig.ssl_verify` parameter
     :returns: An SSL context object.
     """
     ctx = ssl.create_default_context()
@@ -1399,7 +1506,7 @@ def get_ssl_context(ssl_verify: bool) -> ssl.SSLContext:
     return ctx
 
 
-def sort_dict(input_dict: Dict[str, Any]) -> Dict[str, Any]:
+def sort_dict(input_dict: dict[str, Any]) -> dict[str, Any]:
     """
     Recursively sorts a dict by keys.
 
@@ -1413,3 +1520,18 @@ def sort_dict(input_dict: Dict[str, Any]) -> Dict[str, Any]:
         k: sort_dict(v) if isinstance(v, dict) else v
         for k, v in sorted(input_dict.items())
     }
+
+
+def dict_md5sum(input_dict: dict[str, Any]) -> str:
+    """
+    Hash nested dictionary
+
+    :param input_dict: input dict
+    :returns: hash
+
+    >>> hd = dict_md5sum({"b": {"c": 1, "a": 2, "b": 3}, "a": 4})
+    >>> hd
+    'a195bcef1bb3b419e9e74b7cc5db8098'
+    >>> assert(dict_md5sum({"a": 4, "b": {"b": 3, "c": 1, "a": 2}}) == hd)
+    """
+    return obj_md5sum(sort_dict(input_dict))