eodag 2.12.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

eodag/types/__init__.py

@@ -18,8 +18,9 @@
 """EODAG types"""
 from __future__ import annotations
 
-from typing import Any, Dict, List, Literal, Optional, Union
+from typing import Any, Dict, List, Literal, Optional, Tuple, TypedDict, Union
 
+from annotated_types import Gt, Lt
 from pydantic import Field
 from pydantic.fields import FieldInfo
 
@@ -56,13 +57,51 @@ def json_type_to_python(json_type: Union[str, List[str]]) -> type:
         return type(None)
 
 
-def python_type_to_json(python_type: type) -> Optional[Union[str, List[str]]]:
+def _get_min_or_max(type_info: Union[Lt, Gt, Any]) -> Tuple[str, Any]:
+    """
+    checks if the value from an Annotated object is a minimum or maximum
+    :param type_info: info from Annotated
+    :return: "min" or "max"
+    """
+    if isinstance(type_info, Gt):
+        return "min", type_info.gt
+    if isinstance(type_info, Lt):
+        return "max", type_info.lt
+    return "", None
+
+
+def _get_type_info_from_annotated(
+    annotated_type: Annotated[type, Any]
+) -> Dict[str, Any]:
+    """
+    retrieves type information from an annotated object
+    :param annotated_type: annotated object
+    :return: dict containing type and min/max if available
+    """
+    type_args = get_args(annotated_type)
+    type_data = {
+        "type": list(JSON_TYPES_MAPPING.keys())[
+            list(JSON_TYPES_MAPPING.values()).index(type_args[0])
+        ]
+    }
+    if len(type_args) >= 2:
+        min_or_max, value = _get_min_or_max(type_args[1])
+        type_data[min_or_max] = value
+    if len(type_args) > 2:
+        min_or_max, value = _get_min_or_max(type_args[2])
+        type_data[min_or_max] = value
+    return type_data
+
+
+def python_type_to_json(
+    python_type: type,
+) -> Optional[Union[str, List[Dict[str, Any]]]]:
     """Get json type from python https://spec.openapis.org/oas/v3.1.0#data-types
 
     >>> python_type_to_json(int)
     'integer'
     >>> python_type_to_json(Union[float, str])
-    ['number', 'string']
+    [{'type': 'number'}, {'type': 'string'}]
 
     :param python_type: the python type
     :returns: the json type
@@ -70,18 +109,25 @@ def python_type_to_json(python_type: type) -> Optional[Union[str, List[str]]]:
     if get_origin(python_type) is Union:
         json_type = list()
         for single_python_type in get_args(python_type):
+            type_data = {}
             if single_python_type in JSON_TYPES_MAPPING.values():
                 # JSON_TYPES_MAPPING key from given value
                 single_json_type = list(JSON_TYPES_MAPPING.keys())[
                     list(JSON_TYPES_MAPPING.values()).index(single_python_type)
                 ]
-                json_type.append(single_json_type)
+                type_data["type"] = single_json_type
+                json_type.append(type_data)
+            elif get_origin(single_python_type) == Annotated:
+                type_data = _get_type_info_from_annotated(single_python_type)
+                json_type.append(type_data)
         return json_type
     elif python_type in JSON_TYPES_MAPPING.values():
         # JSON_TYPES_MAPPING key from given value
         return list(JSON_TYPES_MAPPING.keys())[
             list(JSON_TYPES_MAPPING.values()).index(python_type)
         ]
+    elif get_origin(python_type) == Annotated:
+        return [_get_type_info_from_annotated(python_type)]
     else:
         return None
 
@@ -99,7 +145,9 @@ def json_field_definition_to_python(
     ...         'title': 'Foo parameter'
     ...     }
     ... )
-    >>> str(result).replace('_extensions', '') # python3.8 compatibility
+    >>> res_repr = str(result).replace('_extensions', '') # python3.8 compatibility
+    >>> res_repr = res_repr.replace(', default=None', '') # pydantic >= 2.7.0 compatibility
+    >>> res_repr
     "typing.Annotated[bool, FieldInfo(annotation=NoneType, required=False, title='Foo parameter')]"
 
     :param json_field_definition: the json field definition
@@ -152,20 +200,54 @@ def python_field_definition_to_json(
             "%s must be an instance of Annotated" % python_field_definition
         )
 
-    json_field_definition = dict()
+    json_field_definition: Dict[str, Any] = dict()
 
     python_field_args = get_args(python_field_definition)
 
     # enum & type
     if get_origin(python_field_args[0]) is Literal:
         enum_args = get_args(python_field_args[0])
-        json_field_definition["type"] = python_type_to_json(type(enum_args[0]))
+        type_data = python_type_to_json(type(enum_args[0]))
+        if isinstance(type_data, str):
+            json_field_definition["type"] = type_data
+        elif type_data is None:
+            json_field_definition["type"] = json_field_definition[
+                "min"
+            ] = json_field_definition["max"] = None
+        else:
+            json_field_definition["type"] = [row["type"] for row in type_data]
+            json_field_definition["min"] = [
+                row["min"] if "min" in row else None for row in type_data
+            ]
+            json_field_definition["max"] = [
+                row["max"] if "max" in row else None for row in type_data
+            ]
         json_field_definition["enum"] = list(enum_args)
     # type
     else:
         field_type = python_type_to_json(python_field_args[0])
-        if field_type is not None:
-            json_field_definition["type"] = python_type_to_json(python_field_args[0])
+        if isinstance(field_type, str):
+            json_field_definition["type"] = field_type
+        elif field_type is None:
+            json_field_definition["type"] = json_field_definition[
+                "min"
+            ] = json_field_definition["max"] = None
+        else:
+            json_field_definition["type"] = [row["type"] for row in field_type]
+            json_field_definition["min"] = [
+                row["min"] if "min" in row else None for row in field_type
+            ]
+            json_field_definition["max"] = [
+                row["max"] if "max" in row else None for row in field_type
+            ]
+    if "min" in json_field_definition and json_field_definition["min"].count(
+        None
+    ) == len(json_field_definition["min"]):
+        json_field_definition.pop("min")
+    if "max" in json_field_definition and json_field_definition["max"].count(
+        None
+    ) == len(json_field_definition["max"]):
+        json_field_definition.pop("max")
 
     if len(python_field_args) < 2:
         return json_field_definition
@@ -204,7 +286,9 @@ def model_fields_to_annotated(
     >>> from pydantic import create_model
     >>> some_model = create_model("some_model", foo=(str, None))
     >>> fields_definitions = model_fields_to_annotated(some_model.model_fields)
-    >>> str(fields_definitions).replace('_extensions', '') # python3.8 compatibility
+    >>> fd_repr = str(fields_definitions).replace('_extensions', '') # python3.8 compatibility
+    >>> fd_repr = fd_repr.replace(', default=None', '') # pydantic >= 2.7.0 compatibility
+    >>> fd_repr
     "{'foo': typing.Annotated[str, FieldInfo(annotation=NoneType, required=False)]}"
 
     :param model_fields: BaseModel.model_fields to convert
@@ -217,3 +301,15 @@ def model_fields_to_annotated(
         new_field_info.annotation = None
         annotated_model_fields[param] = Annotated[field_type, new_field_info]
     return annotated_model_fields
+
+
+class ProviderSortables(TypedDict):
+    """A class representing sortable parameter(s) of a provider and the allowed
+    maximum number of used sortable(s) in a search request with the provider
+
+    :param sortables: The list of sortable parameter(s) of a provider
+    :param max_sort_params: (optional) The allowed maximum number of sortable(s) in a search request with the provider
+    """
+
+    sortables: List[str]
+    max_sort_params: Annotated[Optional[int], Gt(0)]

eodag/types/bbox.py

@@ -15,9 +15,9 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-from typing import Any, Dict, List, Tuple, Union
+from typing import Dict, List, Tuple, Union
 
-from pydantic import BaseModel, validator
+from pydantic import BaseModel, ValidationInfo, field_validator
 from shapely.geometry.polygon import Polygon
 
 NumType = Union[float, int]
@@ -36,7 +36,7 @@ class BBox(BaseModel):
     lonmax: NumType
     latmax: NumType
 
-    def __init__(__pydantic_self__, bboxArgs: BBoxArgs) -> None:  # type: ignore
+    def __init__(__pydantic_self__, bboxArgs: BBoxArgs) -> None:  # type: ignore  # pylint: disable=no-self-argument
         """
         Constructs all the necessary attributes for the BBox object.
 
@@ -55,11 +55,12 @@ class BBox(BaseModel):
             values = bboxArgs
         else:
             raise ValueError(
-                "Expected a dictionary, list or tuple with 4 values for lonmin, latmin, lonmax, latmax"
+                "Expected a dictionary,",
+                " list or tuple with 4 values for lonmin, latmin, lonmax, latmax",
             )
         super().__init__(**values)
 
-    @validator("lonmin", "lonmax")
+    @field_validator("lonmin", "lonmax")
     @classmethod
     def validate_longitude(cls, v: NumType) -> NumType:
         """
@@ -72,7 +73,7 @@ class BBox(BaseModel):
             raise ValueError("Longitude values must be between -180 and 180")
         return v
 
-    @validator("latmin", "latmax")
+    @field_validator("latmin", "latmax")
     @classmethod
     def validate_latitude(cls, v: NumType) -> NumType:
         """
@@ -85,31 +86,31 @@ class BBox(BaseModel):
             raise ValueError("Latitude values must be between -90 and 90")
         return v
 
-    @validator("lonmax")
+    @field_validator("lonmax")
     @classmethod
-    def validate_lonmax(cls, v: NumType, values: Dict[str, Any]) -> NumType:
+    def validate_lonmax(cls, v: NumType, info: ValidationInfo) -> NumType:
         """
         Validates that lonmax is greater than lonmin.
 
         :param v: The lonmax value to be validated.
-        :param values: A dictionary containing the current attribute values.
+        :param info: Additional validation informations.
         :return: The validated lonmax value.
         """
-        if "lonmin" in values and v < values["lonmin"]:
+        if "lonmin" in info.data and v < info.data["lonmin"]:
             raise ValueError("lonmax must be greater than lonmin")
         return v
 
-    @validator("latmax")
+    @field_validator("latmax")
     @classmethod
-    def validate_latmax(cls, v: NumType, values: Dict[str, Any]) -> NumType:
+    def validate_latmax(cls, v: NumType, info: ValidationInfo) -> NumType:
         """
         Validates that latmax is greater than latmin.
 
         :param v: The latmax value to be validated.
-        :param values: A dictionary containing the current attribute values.
+        :param info: Additional validation informations.
         :return: The validated latmax value.
         """
-        if "latmin" in values and v < values["latmin"]:
+        if "latmin" in info.data and v < info.data["latmin"]:
             raise ValueError("latmax must be greater than latmin")
         return v
 

eodag/types/download_args.py

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+# Copyright 2024, CS GROUP - France, https://www.csgroup.eu/
+#
+# This file is part of EODAG project
+#     https://www.github.com/CS-SI/EODAG
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+from typing import Dict, Optional, TypedDict
+
+
+class DownloadConf(TypedDict, total=False):
+    """Download configuration
+
+    :cvar output_prefix: where to store downloaded products, as an absolute file path
+                         (Default: local temporary directory)
+    :cvar output_extension: downloaded file extension
+    :cvar extract: whether to extract the downloaded products, only applies to archived products
+    :cvar dl_url_params: additional parameters to pass over to the download url as an url parameter
+    :cvar delete_archive: whether to delete the downloaded archives
+    :cvar asset: regex filter to identify assets to download
+    """
+
+    output_dir: str
+    output_extension: str
+    extract: bool
+    dl_url_params: Dict[str, str]
+    delete_archive: bool
+    asset: Optional[str]

eodag/types/search_args.py

@@ -15,9 +15,11 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+import re
 from datetime import datetime
-from typing import Dict, List, Optional, Tuple, Union, cast
+from typing import Any, Dict, List, Optional, Tuple, Union, cast
 
+from annotated_types import MinLen
 from pydantic import BaseModel, ConfigDict, Field, conint, field_validator
 from shapely import wkt
 from shapely.errors import GEOSException
@@ -25,12 +27,14 @@ from shapely.geometry import Polygon, shape
 from shapely.geometry.base import GEOMETRY_TYPES, BaseGeometry
 
 from eodag.types.bbox import BBox
-from eodag.utils import DEFAULT_ITEMS_PER_PAGE, DEFAULT_PAGE
+from eodag.utils import DEFAULT_ITEMS_PER_PAGE, DEFAULT_PAGE, Annotated
+from eodag.utils.exceptions import ValidationError
 
 NumType = Union[float, int]
 GeomArgs = Union[List[NumType], Tuple[NumType], Dict[str, NumType], str, BaseGeometry]
 
 PositiveInt = conint(gt=0)
+SortByList = Annotated[List[Tuple[str, str]], MinLen(1)]
 
 
 class SearchArgs(BaseModel):
@@ -47,6 +51,7 @@ class SearchArgs(BaseModel):
     locations: Optional[Dict[str, str]] = Field(None)
     page: Optional[int] = Field(DEFAULT_PAGE, gt=0)  # type: ignore
     items_per_page: Optional[PositiveInt] = Field(DEFAULT_ITEMS_PER_PAGE)  # type: ignore
+    sort_by: Optional[SortByList] = Field(None)  # type: ignore
 
     @field_validator("start", "end", mode="before")
     @classmethod
@@ -60,24 +65,69 @@ class SearchArgs(BaseModel):
 
     @field_validator("geom", mode="before")
     @classmethod
-    def check_geom(cls, v: GeomArgs) -> BaseGeometry:
+    def check_geom(cls, v: Any) -> BaseGeometry:
         """Validate geom"""
         # GeoJSON geometry
-        if isinstance(v, dict) and v.get("type") in GEOMETRY_TYPES:
+        if isinstance(v, dict) and v.get("type") in GEOMETRY_TYPES:  # type: ignore
             return cast(BaseGeometry, shape(v))
 
         # Bounding Box
         if isinstance(v, (list, tuple, dict)):
-            return BBox(v).to_polygon()
+            return BBox(v).to_polygon()  # type: ignore
 
         if isinstance(v, str):
             # WKT geometry
             try:
-                return cast(Polygon, wkt.loads(v))
-            except GEOSException as e:
+                return cast(Polygon, wkt.loads(v))  # type: ignore
+            except GEOSException as e:  # type: ignore
                 raise ValueError(f"Invalid geometry WKT string: {v}") from e
 
         if isinstance(v, BaseGeometry):
             return v
 
         raise TypeError(f"Invalid geometry type: {type(v)}")
+
+    @field_validator("sort_by", mode="before")
+    @classmethod
+    def check_sort_by_arg(
+        cls,
+        sort_by_arg: Optional[SortByList],  # type: ignore
+    ) -> Optional[SortByList]:  # type: ignore
+        """Check if the sort_by argument is correct
+
+        :param sort_by_arg: The sort_by argument
+        :returns: The sort_by argument with sorting order parsed (whitespace(s) are
+                  removed and only the 3 first letters in uppercase are kept)
+        """
+        if sort_by_arg is None:
+            return None
+
+        assert isinstance(
+            sort_by_arg, list
+        ), f"Sort argument must be a list of tuple(s), got a '{type(sort_by_arg)}' instead"
+        sort_order_pattern = r"^(ASC|DES)[a-zA-Z]*$"
+        for i, sort_by_tuple in enumerate(sort_by_arg):
+            assert isinstance(
+                sort_by_tuple, tuple
+            ), f"Sort argument must be a list of tuple(s), got a list of '{type(sort_by_tuple)}' instead"
+            # get sorting elements by removing leading and trailing whitespace(s) if exist
+            sort_param = sort_by_tuple[0].strip()
+            sort_order = sort_by_tuple[1].strip().upper()
+            assert re.match(sort_order_pattern, sort_order) is not None, (
+                "Sorting order must be set to 'ASC' (ASCENDING) or 'DESC' (DESCENDING), "
+                f"got '{sort_order}' with '{sort_param}' instead"
+            )
+            sort_by_arg[i] = (sort_param, sort_order[:3])
+        # remove duplicates
+        pruned_sort_by_arg: SortByList = list(dict.fromkeys(sort_by_arg))  # type: ignore
+        for i, sort_by_tuple in enumerate(pruned_sort_by_arg):
+            for j, sort_by_tuple_tmp in enumerate(pruned_sort_by_arg):
+                # since duplicated tuples or dictionnaries have been removed, if two sorting parameters are equal,
+                # then their sorting order is different and there is a contradiction that would raise an error
+                if i != j and sort_by_tuple[0] == sort_by_tuple_tmp[0]:
+                    raise ValidationError(
+                        f"'{sort_by_tuple[0]}' parameter is called several times to sort results with different "
+                        "sorting orders. Please set it to only one ('ASC' (ASCENDING) or 'DESC' (DESCENDING))",
+                        set([sort_by_tuple[0]]),
+                    )
+        return pruned_sort_by_arg

eodag/types/whoosh.py

@@ -0,0 +1,79 @@
+# -*- coding: utf-8 -*-
+# Copyright 2024, CS Systemes d'Information, https://www.csgroup.eu/
+#
+# This file is part of EODAG project
+#     https://www.github.com/CS-SI/EODAG
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from typing import List
+
+from whoosh.fields import Schema
+from whoosh.matching import NullMatcher
+from whoosh.qparser import OrGroup, QueryParser, plugins
+from whoosh.query.positional import Phrase
+from whoosh.query.qcore import QueryError
+
+
+class RobustPhrase(Phrase):
+    """
+    Matches documents containing a given phrase.
+    """
+
+    def matcher(self, searcher, context=None):
+        """
+        Override the default to not raise error on match exception but simply return not found
+        Needed to handle phrase search in whoosh.fields.IDLIST
+        """
+        try:
+            return super().matcher(searcher, context)
+        except QueryError:
+            return NullMatcher()
+
+
+class EODAGQueryParser(QueryParser):
+    """
+    A hand-written query parser built on modular plug-ins.
+
+    Override the default to include specific EODAG configuration
+    """
+
+    def __init__(
+        self,
+        filters: List[str],
+        schema: Schema,
+    ):
+        """
+        EODAG QueryParser initialization
+
+        :param filters: list of fieldnames to filter on
+        :param schema: Whoosh Schema
+        """
+        super().__init__(
+            None,
+            schema=schema,
+            plugins=[
+                plugins.SingleQuotePlugin(),
+                plugins.FieldsPlugin(),
+                plugins.WildcardPlugin(),
+                plugins.PhrasePlugin(),
+                plugins.GroupPlugin(),
+                plugins.OperatorsPlugin(),
+                plugins.BoostPlugin(),
+                plugins.EveryPlugin(),
+                plugins.RangePlugin(),
+                plugins.PlusMinusPlugin(),
+                plugins.MultifieldPlugin(filters, fieldboosts=None),
+            ],
+            phraseclass=RobustPhrase,
+            group=OrGroup,
+        )