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

eodag/plugins/search/base.py

@@ -18,7 +18,7 @@
 from __future__ import annotations
 
 import logging
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Annotated, get_args
 
 import orjson
 from pydantic.fields import Field, FieldInfo
@@ -35,11 +35,9 @@ from eodag.types.queryables import Queryables
 from eodag.types.search_args import SortByList
 from eodag.utils import (
     GENERIC_PRODUCT_TYPE,
-    Annotated,
     copy_deepcopy,
     deepcopy,
     format_dict_items,
-    get_args,
     update_nested_dict,
 )
 from eodag.utils.exceptions import ValidationError
@@ -95,9 +93,9 @@ class Search(PluginTopic):
     ) -> Tuple[List[EOProduct], Optional[int]]:
         """Implementation of how the products must be searched goes here.
 
-        This method must return a tuple with (1) a list of EOProduct instances (see eodag.api.product module)
-        which will be processed by a Download plugin (2) and the total number of products matching
-        the search criteria. If ``prep.count`` is False, the second element returned must be ``None``.
+        This method must return a tuple with (1) a list of :class:`~eodag.api.product._product.EOProduct` instances
+        which will be processed by a :class:`~eodag.plugins.download.base.Download` plugin (2) and the total number of
+        products matching the search criteria. If ``prep.count`` is False, the second element returned must be ``None``.
         """
         raise NotImplementedError("A Search plugin must implement a method named query")
 
@@ -108,9 +106,9 @@ class Search(PluginTopic):
     def discover_queryables(
         self, **kwargs: Any
     ) -> Optional[Dict[str, Annotated[Any, FieldInfo]]]:
-        """Fetch queryables list from provider using `discover_queryables` conf
+        """Fetch queryables list from provider using :attr:`~eodag.config.PluginConfig.discover_queryables` conf
 
-        :param kwargs: additional filters for queryables (`productType` and other search
+        :param kwargs: additional filters for queryables (``productType`` and other search
                        arguments)
         :returns: fetched queryable parameters dict
         """
@@ -179,6 +177,27 @@ class Search(PluginTopic):
         else:
             return {}
 
+    def get_product_type_cfg_value(self, key: str, default: Any = None) -> Any:
+        """
+        Get the value of a configuration option specific to the current product type.
+
+        This method retrieves the value of a configuration option from the
+        ``product_type_config`` attribute. If the option is not found, the provided
+        default value is returned.
+
+        :param key: The configuration option key.
+        :type key: str
+        :param default: The default value to be returned if the option is not found (default is None).
+        :type default: Any
+
+        :return: The value of the specified configuration option or the default value.
+        :rtype: Any
+        """
+        product_type_cfg = getattr(self.config, "product_type_config", {})
+        non_none_cfg = {k: v for k, v in product_type_cfg.items() if v}
+
+        return non_none_cfg.get(key, default)
+
     def get_metadata_mapping(
         self, product_type: Optional[str] = None
     ) -> Dict[str, Union[str, List[str]]]:
@@ -194,10 +213,10 @@ class Search(PluginTopic):
         return self.config.metadata_mapping
 
     def get_sort_by_arg(self, kwargs: Dict[str, Any]) -> Optional[SortByList]:
-        """Extract the "sort_by" argument from the kwargs or the provider default sort configuration
+        """Extract the ``sort_by`` argument from the kwargs or the provider default sort configuration
 
         :param kwargs: Search arguments
-        :returns: The "sort_by" argument from the kwargs or the provider default sort configuration
+        :returns: The ``sort_by`` argument from the kwargs or the provider default sort configuration
         """
         # remove "sort_by" from search args if exists because it is not part of metadata mapping,
         # it will complete the query string or body once metadata mapping will be done
@@ -216,16 +235,16 @@ class Search(PluginTopic):
         self, sort_by_arg: SortByList
     ) -> Tuple[str, Dict[str, List[Dict[str, str]]]]:
         """Build the sorting part of the query string or body by transforming
-        the "sort_by" argument into a provider-specific string or dictionnary
+        the ``sort_by`` argument into a provider-specific string or dictionary
 
-        :param sort_by_arg: the "sort_by" argument in EODAG format
-        :returns: The "sort_by" argument in provider-specific format
+        :param sort_by_arg: the ``sort_by`` argument in EODAG format
+        :returns: The ``sort_by`` argument in provider-specific format
         """
         if not hasattr(self.config, "sort"):
             raise ValidationError(f"{self.provider} does not support sorting feature")
         # TODO: remove this code block when search args model validation is embeded
         # remove duplicates
-        sort_by_arg = list(set(sort_by_arg))
+        sort_by_arg = list(dict.fromkeys(sort_by_arg))
 
         sort_by_qs: str = ""
         sort_by_qp: Dict[str, Any] = {}

eodag/plugins/search/build_search_result.py

@@ -20,16 +20,27 @@ from __future__ import annotations
 import hashlib
 import logging
 from datetime import datetime, timedelta, timezone
-from typing import TYPE_CHECKING, Any, Dict, List, Optional, Set, Tuple, cast
+from typing import (
+    TYPE_CHECKING,
+    Annotated,
+    Any,
+    Dict,
+    List,
+    Optional,
+    Set,
+    Tuple,
+    cast,
+    get_args,
+)
 from urllib.parse import quote_plus, unquote_plus
 
 import geojson
 import orjson
 from dateutil.parser import isoparse
+from dateutil.tz import tzutc
 from jsonpath_ng import Child, Fields, Root
 from pydantic import create_model
 from pydantic.fields import FieldInfo
-from typing_extensions import get_args
 
 from eodag.api.product import EOProduct
 from eodag.api.product.metadata_mapping import (
@@ -47,7 +58,6 @@ from eodag.types import json_field_definition_to_python, model_fields_to_annotat
 from eodag.types.queryables import CommonQueryables
 from eodag.utils import (
     DEFAULT_MISSION_START_DATE,
-    Annotated,
     deepcopy,
     dict_items_recursive_sort,
     get_geometry_from_various,
@@ -71,21 +81,16 @@ class BuildPostSearchResult(PostJsonSearch):
     performs a POST request and uses its result to build a single :class:`~eodag.api.search_result.SearchResult`
     object.
 
-    The available configuration parameters inherits from parent classes, with particularly
-    for this plugin:
-
-        - **api_endpoint**: (mandatory) The endpoint of the provider's search interface
+    The available configuration parameters are inherited from parent classes
+    (:class:`~eodag.plugins.search.qssearch.PostJsonSearch` and
+    :class:`~eodag.plugins.search.qssearch.QueryStringSearch`), with particularly for this plugin:
 
-        - **pagination**: The configuration of how the pagination is done
-          on the provider. It is a tree with the following nodes:
+    :param provider: provider name
+    :param config: Search plugin configuration:
 
-          - *next_page_query_obj*: (optional) The additional parameters needed to perform
-            search. These paramaters won't be included in result. This must be a json dict
-            formatted like `{{"foo":"bar"}}` because it will be passed to a `.format()`
-            method before being loaded as json.
+        * :attr:`~eodag.config.PluginConfig.remove_from_query` (``List[str]``): List of parameters
+          used to parse metadata but that must not be included to the query
 
-    :param provider: An eodag providers configuration dictionary
-    :param config: Path to the user configuration file
     """
 
     def count_hits(
@@ -110,8 +115,8 @@ class BuildPostSearchResult(PostJsonSearch):
         prep.url = prep.search_urls[0]
         prep.info_message = f"Sending search request: {prep.url}"
         prep.exception_message = (
-            f"Skipping error while searching for {self.provider} "
-            f"{self.__class__.__name__} instance:"
+            f"Skipping error while searching for {self.provider}"
+            f" {self.__class__.__name__} instance"
         )
         response = self._request(prep)
 
@@ -178,7 +183,7 @@ class BuildPostSearchResult(PostJsonSearch):
         result.update(results.product_type_def_params)
         result = dict(result, **{k: v for k, v in kwargs.items() if v is not None})
 
-        # parse porperties
+        # parse properties
         parsed_properties = properties_from_json(
             result,
             self.config.metadata_mapping,
@@ -239,19 +244,18 @@ class BuildSearchResult(BuildPostSearchResult):
     This plugin builds a single :class:`~eodag.api.search_result.SearchResult` object
     using given query parameters as product properties.
 
-    The available configuration parameters inherits from parent classes, with particularly
-    for this plugin:
+    The available configuration parameters inherits from parent classes
+    (:class:`~eodag.plugins.search.build_search_result.BuildPostSearchResult`,
+    :class:`~eodag.plugins.search.qssearch.PostJsonSearch` and
+    :class:`~eodag.plugins.search.qssearch.QueryStringSearch`), with particularly for this plugin:
 
-        - **end_date_excluded**: Set to `False` if provider does not include end date to
-          search
+    :param provider: provider name
+    :param config: Search plugin configuration:
 
-        - **remove_from_query**: List of parameters used to parse metadata but that must
-          not be included to the query
+        * :attr:`~eodag.config.PluginConfig.end_date_excluded` (``bool``): Set to ``False`` if provider
+          does not include end date in the search request; In this case, if the end date is at midnight,
+          the previous day will be used. default: ``True``
 
-        - **constraints_file_url**: url of the constraint file used to build queryables
-
-    :param provider: An eodag providers configuration dictionary
-    :param config: Path to the user configuration file
     """
 
     def __init__(self, provider: str, config: PluginConfig) -> None:
@@ -339,24 +343,6 @@ class BuildSearchResult(BuildPostSearchResult):
             self, product_type=product_type, **available_properties
         )
 
-    def get_product_type_cfg(self, key: str, default: Any = None) -> Any:
-        """
-        Get the value of a configuration option specific to the current product type.
-
-        This method retrieves the value of a configuration option from the
-        `_product_type_config` attribute. If the option is not found, the provided
-        default value is returned.
-
-        :param key: The configuration option key.
-        :param default: The default value to be returned if the option is not found (default is None).
-
-        :return: The value of the specified configuration option or the default value.
-        """
-        product_type_cfg = getattr(self.config, "product_type_config", {})
-        non_none_cfg = {k: v for k, v in product_type_cfg.items() if v}
-
-        return non_none_cfg.get(key, default)
-
     def _preprocess_search_params(self, params: Dict[str, Any]) -> None:
         """Preprocess search parameters before making a request to the CDS API.
 
@@ -397,7 +383,7 @@ class BuildSearchResult(BuildPostSearchResult):
 
         # dates
         mission_start_dt = datetime.fromisoformat(
-            self.get_product_type_cfg(
+            self.get_product_type_cfg_value(
                 "missionStartDate", DEFAULT_MISSION_START_DATE
             ).replace(
                 "Z", "+00:00"
@@ -423,11 +409,29 @@ class BuildSearchResult(BuildPostSearchResult):
             "completionTimeFromAscendingNode", default_end_str
         )
 
-        # temporary _date parameter mixing start & end
+        # adapt end date if it is midnight
         end_date_excluded = getattr(self.config, "end_date_excluded", True)
-        end_date = isoparse(params["completionTimeFromAscendingNode"])
-        if not end_date_excluded and end_date == end_date.replace(
-            hour=0, minute=0, second=0, microsecond=0
+        is_datetime = True
+        try:
+            end_date = datetime.strptime(
+                params["completionTimeFromAscendingNode"], "%Y-%m-%dT%H:%M:%SZ"
+            )
+            end_date = end_date.replace(tzinfo=tzutc())
+        except ValueError:
+            try:
+                end_date = datetime.strptime(
+                    params["completionTimeFromAscendingNode"], "%Y-%m-%dT%H:%M:%S.%fZ"
+                )
+                end_date = end_date.replace(tzinfo=tzutc())
+            except ValueError:
+                end_date = isoparse(params["completionTimeFromAscendingNode"])
+                is_datetime = False
+        start_date = isoparse(params["startTimeFromAscendingNode"])
+        if (
+            not end_date_excluded
+            and is_datetime
+            and end_date > start_date
+            and end_date == end_date.replace(hour=0, minute=0, second=0, microsecond=0)
         ):
             end_date += timedelta(days=-1)
             params["completionTimeFromAscendingNode"] = end_date.isoformat()

eodag/plugins/search/cop_marine.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 
 import copy
 import logging
+import os
 import re
 from datetime import datetime
 from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, cast
@@ -37,7 +38,7 @@ from eodag.config import PluginConfig
 from eodag.plugins.search import PreparedSearch
 from eodag.plugins.search.static_stac_search import StaticStacSearch
 from eodag.utils import get_bucket_name_and_prefix
-from eodag.utils.exceptions import UnsupportedProductType, ValidationError
+from eodag.utils.exceptions import RequestError, UnsupportedProductType, ValidationError
 
 if TYPE_CHECKING:
     from mypy_boto3_s3 import S3Client
@@ -67,6 +68,21 @@ def _get_date_from_yyyymmdd(date_str: str, item_key: str) -> Optional[datetime]:
         return date
 
 
+def _get_dates_from_dataset_data(
+    dataset_item: Dict[str, Any]
+) -> Optional[Dict[str, str]]:
+    dates = {}
+    if "start_datetime" in dataset_item["properties"]:
+        dates["start"] = dataset_item["properties"]["start_datetime"]
+        dates["end"] = dataset_item["properties"]["end_datetime"]
+    elif "datetime" in dataset_item["properties"]:
+        dates["start"] = dataset_item["properties"]["datetime"]
+        dates["end"] = dataset_item["properties"]["datetime"]
+    else:
+        return None
+    return dates
+
+
 def _get_s3_client(endpoint_url: str) -> S3Client:
     s3_session = boto3.Session()
     return s3_session.client(
@@ -94,7 +110,21 @@ def _check_int_values_properties(properties: Dict[str, Any]):
 
 
 class CopMarineSearch(StaticStacSearch):
-    """class that implements search for the Copernicus Marine provider"""
+    """class that implements search for the Copernicus Marine provider
+
+    It calls :meth:`~eodag.plugins.search.static_stac_search.StaticStacSearch.discover_product_types`
+    inherited from :class:`~eodag.plugins.search.static_stac_search.StaticStacSearch`
+    but for the actual search a special method which fetches the urls of the available products from an S3 storage and
+    filters them has been written.
+
+    The configuration parameters are inherited from the parent and grand-parent classes. The
+    :attr:`~eodag.config.PluginConfig.DiscoverMetadata.auto_discovery` parameter in the
+    :attr:`~eodag.config.PluginConfig.discover_metadata` section has to be set to ``false`` and the
+    :attr:`~eodag.config.PluginConfig.DiscoverQueryables.fetch_url` in the
+    :attr:`~eodag.config.PluginConfig.discover_queryables` queryables section has to be set to ``null`` to
+    overwrite the default config from the stac provider configuration because those functionalities
+    are not available.
+    """
 
     def __init__(self, provider: str, config: PluginConfig):
         original_metadata_mapping = copy.deepcopy(config.metadata_mapping)
@@ -107,12 +137,10 @@ class CopMarineSearch(StaticStacSearch):
     ) -> Tuple[Dict[str, Any], List[Dict[str, Any]]]:
         """Fetch product type and associated datasets info"""
 
-        fetch_url = cast(
-            str,
-            self.config.discover_product_types["fetch_url"].format(
-                **self.config.__dict__
-            ),
+        fetch_url = cast(str, self.config.discover_product_types["fetch_url"]).format(
+            **self.config.__dict__
         )
+
         logger.debug("fetch data for collection %s", product_type)
         provider_product_type = self.config.products.get(product_type, {}).get(
             "productType", None
@@ -125,9 +153,14 @@ class CopMarineSearch(StaticStacSearch):
         )
         try:
             collection_data = requests.get(collection_url).json()
-        except requests.RequestException:
+        except requests.RequestException as exc:
+            if exc.errno == 404:
+                logger.error("product %s not found", product_type)
+                raise UnsupportedProductType(product_type)
             logger.error("data for product %s could not be fetched", product_type)
-            raise UnsupportedProductType(product_type)
+            raise RequestError.from_error(
+                exc, f"data for product {product_type} could not be fetched"
+            ) from exc
 
         datasets = []
         for link in [li for li in collection_data["links"] if li["rel"] == "item"]:
@@ -170,7 +203,7 @@ class CopMarineSearch(StaticStacSearch):
         use_dataset_dates: bool = False,
     ) -> Optional[EOProduct]:
 
-        item_id = item_key.split("/")[-1].split(".")[0]
+        item_id = os.path.splitext(item_key.split("/")[-1])[0]
         download_url = s3_url + "/" + item_key
         properties = {
             "id": item_id,
@@ -180,20 +213,16 @@ class CopMarineSearch(StaticStacSearch):
             "dataset": dataset_item["id"],
         }
         if use_dataset_dates:
-            if "start_datetime" in dataset_item:
-                properties["startTimeFromAscendingNode"] = dataset_item[
-                    "start_datetime"
-                ]
-                properties["completionTimeFromAscendingNode"] = dataset_item[
-                    "end_datetime"
-                ]
-            elif "datetime" in dataset_item:
-                properties["startTimeFromAscendingNode"] = dataset_item["datetime"]
-                properties["completionTimeFromAscendingNode"] = dataset_item["datetime"]
+            dates = _get_dates_from_dataset_data(dataset_item)
+            if not dates:
+                return None
+            properties["startTimeFromAscendingNode"] = dates["start"]
+            properties["completionTimeFromAscendingNode"] = dates["end"]
         else:
-            item_dates = re.findall(r"\d{8}", item_key)
+            item_dates = re.findall(r"(\d{4})(0[1-9]|1[0-2])([0-3]\d)", item_id)
             if not item_dates:
-                item_dates = re.findall(r"\d{6}", item_key)
+                item_dates = re.findall(r"_(\d{4})(0[1-9]|1[0-2])", item_id)
+            item_dates = ["".join(row) for row in item_dates]
             item_start = _get_date_from_yyyymmdd(item_dates[0], item_key)
             if not item_start:  # identified pattern was not a valid datetime
                 return None
@@ -209,11 +238,26 @@ class CopMarineSearch(StaticStacSearch):
             ).strftime("%Y-%m-%dT%H:%M:%SZ")
 
         for key, value in collection_dict["properties"].items():
-            if key not in ["id", "title", "start_datetime", "end_datetime"]:
+            if key not in ["id", "title", "start_datetime", "end_datetime", "datetime"]:
                 properties[key] = value
         for key, value in dataset_item["properties"].items():
-            if key not in ["id", "title", "start_datetime", "end_datetime"]:
+            if key not in ["id", "title", "start_datetime", "end_datetime", "datetime"]:
                 properties[key] = value
+
+        code_mapping = self.config.products.get(product_type, {}).get(
+            "code_mapping", None
+        )
+        if code_mapping:
+            id_parts = item_id.split("_")
+            if len(id_parts) > code_mapping["index"]:
+                code = id_parts[code_mapping["index"]]
+                if "pattern" not in code_mapping:
+                    properties[code_mapping["param"]] = code
+                elif re.findall(code_mapping["pattern"], code):
+                    properties[code_mapping["param"]] = re.findall(
+                        code_mapping["pattern"], code
+                    )[0]
+
         _check_int_values_properties(properties)
 
         properties["thumbnail"] = collection_dict["assets"]["thumbnail"]["href"]
@@ -348,16 +392,54 @@ class CopMarineSearch(StaticStacSearch):
 
                 for obj in s3_objects["Contents"]:
                     item_key = obj["Key"]
+                    item_id = os.path.splitext(item_key.split("/")[-1])[0]
                     # filter according to date(s) in item id
-                    item_dates = re.findall(r"\d{8}", item_key)
+                    item_dates = re.findall(r"(\d{4})(0[1-9]|1[0-2])([0-3]\d)", item_id)
                     if not item_dates:
-                        item_dates = re.findall(r"\d{6}", item_key)
-                    item_start = _get_date_from_yyyymmdd(item_dates[0], item_key)
-                    if not item_start:  # identified pattern was not a valid datetime
+                        item_dates = re.findall(r"_(\d{4})(0[1-9]|1[0-2])", item_id)
+                    item_dates = [
+                        "".join(row) for row in item_dates
+                    ]  # join tuples returned by findall
+                    item_start = None
+                    item_end = None
+                    use_dataset_dates = False
+                    if item_dates:
+                        item_start = _get_date_from_yyyymmdd(item_dates[0], item_key)
+                        if len(item_dates) > 2:  # start, end and created_at timestamps
+                            item_end = _get_date_from_yyyymmdd(item_dates[1], item_key)
+                    if not item_start:
+                        # no valid datetime given in id
+                        use_dataset_dates = True
+                        dates = _get_dates_from_dataset_data(dataset_item)
+                        if dates:
+                            item_start_str = dates["start"].replace("Z", "+0000")
+                            item_end_str = dates["end"].replace("Z", "+0000")
+                            try:
+                                item_start = datetime.strptime(
+                                    item_start_str, "%Y-%m-%dT%H:%M:%S.%f%z"
+                                )
+                                item_end = datetime.strptime(
+                                    item_end_str, "%Y-%m-%dT%H:%M:%S.%f%z"
+                                )
+                            except ValueError:
+                                item_start = datetime.strptime(
+                                    item_start_str, "%Y-%m-%dT%H:%M:%S%z"
+                                )
+                                item_end = datetime.strptime(
+                                    item_end_str, "%Y-%m-%dT%H:%M:%S%z"
+                                )
+                    if not item_start:
+                        # no valid datetime in id and dataset data
                         continue
                     if item_start > end_date:
                         stop_search = True
-                    if not item_dates or (start_date <= item_start <= end_date):
+                    if (
+                        (start_date <= item_start <= end_date)
+                        or (item_end and start_date <= item_end <= end_date)
+                        or (
+                            item_end and item_start < start_date and item_end > end_date
+                        )
+                    ):
                         num_total += 1
                         if num_total < start_index:
                             continue
@@ -368,6 +450,7 @@ class CopMarineSearch(StaticStacSearch):
                                 endpoint_url + "/" + bucket,
                                 dataset_item,
                                 collection_dict,
+                                use_dataset_dates,
                             )
                             if product:
                                 products.append(product)

eodag/plugins/search/creodias_s3.py

@@ -29,7 +29,12 @@ from eodag.config import PluginConfig
 from eodag.plugins.authentication.aws_auth import AwsAuth
 from eodag.plugins.search.qssearch import ODataV4Search
 from eodag.utils import guess_file_type
-from eodag.utils.exceptions import AuthenticationError, MisconfiguredError, RequestError
+from eodag.utils.exceptions import (
+    AuthenticationError,
+    MisconfiguredError,
+    NotAvailableError,
+    RequestError,
+)
 
 DATA_EXTENSIONS = ["jp2", "tiff", "nc", "grib"]
 logger = logging.getLogger("eodag.search.creodiass3")
@@ -50,7 +55,7 @@ def patched_register_downloader(self, downloader, authenticator):
     try:
         _update_assets(self, downloader.config, authenticator)
     except BotoCoreError as e:
-        raise RequestError(f"could not update assets: {str(e)}") from e
+        raise RequestError.from_error(e, "could not update assets") from e
 
 
 def _update_assets(product: EOProduct, config: PluginConfig, auth: AwsAuth):
@@ -70,7 +75,7 @@ def _update_assets(product: EOProduct, config: PluginConfig, auth: AwsAuth):
             if not getattr(auth, "s3_client", None):
                 auth.s3_client = boto3.client(
                     "s3",
-                    endpoint_url=config.base_uri,
+                    endpoint_url=config.s3_endpoint,
                     aws_access_key_id=auth_dict["aws_access_key_id"],
                     aws_secret_access_key=auth_dict["aws_secret_access_key"],
                 )
@@ -105,12 +110,22 @@ def _update_assets(product: EOProduct, config: PluginConfig, auth: AwsAuth):
                 raise AuthenticationError(
                     f"Authentication failed on {config.base_uri} s3"
                 ) from e
-            raise RequestError(f"assets for product {prefix} could not be found") from e
+            raise NotAvailableError(
+                f"assets for product {prefix} could not be found"
+            ) from e
 
 
 class CreodiasS3Search(ODataV4Search):
     """
-    Search on creodias and adapt results to s3
+    ``CreodiasS3Search`` is an extension of :class:`~eodag.plugins.search.qssearch.ODataV4Search`,
+    it executes a Search on creodias and adapts results so that the assets contain links to s3.
+    It has the same configuration parameters as :class:`~eodag.plugins.search.qssearch.ODataV4Search` and
+    one additional parameter:
+
+    :param provider: provider name
+    :param config: Search plugin configuration:
+
+        * :attr:`~eodag.config.PluginConfig.s3_endpoint` (``str``) (**mandatory**): base url of the s3
     """
 
     def __init__(self, provider, config):

eodag/plugins/search/csw.py

@@ -52,7 +52,47 @@ SUPPORTED_REFERENCE_SCHEMES = ["WWW:DOWNLOAD-1.0-http--download"]
 
 
 class CSWSearch(Search):
-    """A plugin for implementing search based on OGC CSW"""
+    """A plugin for implementing search based on OGC CSW
+
+    :param provider: provider name
+    :param config: Search plugin configuration:
+
+        * :attr:`~eodag.config.PluginConfig.api_endpoint` (``str``) (**mandatory**): The endpoint of the
+          provider's search interface
+        * :attr:`~eodag.config.PluginConfig.version` (``str``): OGC Catalogue Service version; default: ``2.0.2``
+        * :attr:`~eodag.config.PluginConfig.search_definition` (``Dict[str, Any]``) (**mandatory**):
+
+          * **product_type_tags** (``List[Dict[str, Any]``): dict of product type tags
+          * **resource_location_filter** (``str``): regex string
+          * **date_tags** (``Dict[str, Any]``): tags for start and end
+
+        * :attr:`~eodag.config.PluginConfig.metadata_mapping` (``Dict[str, Any]``): The search plugins of this kind can
+          detect when a metadata mapping is "query-able", and get the semantics of how to format the query string
+          parameter that enables to make a query on the corresponding metadata. To make a metadata query-able,
+          just configure it in the metadata mapping to be a list of 2 items, the first one being the
+          specification of the query string search formatting. The later is a string following the
+          specification of Python string formatting, with a special behaviour added to it. For example,
+          an entry in the metadata mapping of this kind::
+
+                completionTimeFromAscendingNode:
+                    - 'f=acquisition.endViewingDate:lte:{completionTimeFromAscendingNode#timestamp}'
+                    - '$.properties.acquisition.endViewingDate'
+
+          means that the search url will have a query string parameter named ``f`` with a value of
+          ``acquisition.endViewingDate:lte:1543922280.0`` if the search was done with the value
+          of ``completionTimeFromAscendingNode`` being ``2018-12-04T12:18:00``. What happened is that
+          ``{completionTimeFromAscendingNode#timestamp}`` was replaced with the timestamp of the value
+          of ``completionTimeFromAscendingNode``. This example shows all there is to know about the
+          semantics of the query string formatting introduced by this plugin: any eodag search parameter
+          can be referenced in the query string with an additional optional conversion function that
+          is separated from it by a ``#`` (see :func:`~eodag.api.product.metadata_mapping.format_metadata` for further
+          details on the available converters). Note that for the values in the
+          :attr:`~eodag.config.PluginConfig.free_text_search_operations` configuration parameter follow the same rule.
+          If the metadata_mapping is not a list but only a string, this means that the parameters is not queryable but
+          it is included in the result obtained from the provider. The string indicates how the provider result should
+          be mapped to the eodag parameter.
+
+    """
 
     def __init__(self, provider: str, config: PluginConfig) -> None:
         super(CSWSearch, self).__init__(provider, config)