feat(core)!: search optional count and return only SearchResult (#1200)

Co-authored-by: Sylvain Brunato <[email protected]>

README.rst

@@ -105,7 +105,7 @@ Example usage for interacting with the api in your Python code:
 
     dag = EODataAccessGateway()
 
-    search_results, total_count = dag.search(
+    search_results = dag.search(
         productType='S2_MSI_L1C',
         geom={'lonmin': 1, 'latmin': 43.5, 'lonmax': 2, 'latmax': 44}, # accepts WKT polygons, shapely.geometry, ...
         start='2021-01-01',

docs/conf.py

@@ -137,6 +137,7 @@
         "image_light": "_static/eodag_logo_160.png",
         "image_dark": "_static/eodag_logo_160r.png",
     },
+    "show_toc_level": 2,
 }
 
 html_logo = "_static/eodag_logo_160.png"

docs/getting_started_guide/configure.rst

@@ -255,7 +255,7 @@ This file can be used to download products with the API:
 
    from eodag import EODataAccessGateway
    dag = EODataAccessGateway()
-   products, total_count = dag.search(
+   products = dag.search(
       productType="S2_MSI_L1C",
       start="2018-01-01",
       end="2018-01-31",

docs/index.rst

@@ -71,7 +71,7 @@ downloading *Sentinel 2 Level-1C* products from any provider's catalog is as sim
 
    dag = EODataAccessGateway()
 
-   search_results, total_count = dag.search(
+   search_results = dag.search(
        productType="S2_MSI_L1C",
        start="2021-03-01",
        end="2021-03-31",

docs/notebooks/api_user_guide/1_overview.ipynb

@@ -223,10 +223,7 @@
    "source": [
     "The [EODataAccessGateway](../../api_reference/core.rst#eodag.api.core.EODataAccessGateway) class provides three search methods which have a similar signature but behave in different ways:\n",
     "\n",
-    "[search()](../../api_reference/core.rst#eodag.api.core.EODataAccessGateway.search) returns a tuple with:\n",
-    "\n",
-    "* a [SearchResult](../../api_reference/searchresult.rst#eodag.api.search_result.SearchResult) that stores the products obtained from a given **page** (default: `page=1`) and a given maximum **number of items per page** (default: `items_per_page=20`)\n",
-    "* an integer that is the **estimated** total number of products matching the search criteria\n",
+    "[search()](../../api_reference/core.rst#eodag.api.core.EODataAccessGateway.search) returns a [SearchResult](../../api_reference/searchresult.rst#eodag.api.search_result.SearchResult) that stores the products obtained from a given **page** (default: `page=1`) and a given maximum **number of items per page** (default: `items_per_page=20`). The attribute [SearchResult.number_matched](../../api_reference/searchresult.rst#eodag.api.search_result.SearchResult) optionally stores the **estimated** total number of products matching the search criteria.\n",
     "\n",
     "<div class=\"alert alert-info\">\n",
     "\n",
@@ -248,7 +245,7 @@
     "\n",
     "Warning\n",
     "\n",
-    "The second element returned by [search()](../../api_reference/core.rst#eodag.api.core.EODataAccessGateway.search) is the **estimated** total number of products matching the search criteria, since, unfortunately, all the providers do not return the **exact** total number.\n",
+    "The [SearchResult.number_matched](../../api_reference/searchresult.rst#eodag.api.search_result.SearchResult) property is the **estimated** total number of products matching the search criteria, since, unfortunately, all the providers do not return the **exact** total number.\n",
     "\n",
     "</div>"
    ]
@@ -279,7 +276,8 @@
     "    \"productType\": \"S2_MSI_L1C\",\n",
     "    \"start\": \"2021-03-01\",\n",
     "    \"end\": \"2021-03-31\",\n",
-    "    \"geom\": {\"lonmin\": 1, \"latmin\": 43, \"lonmax\": 2, \"latmax\": 44}\n",
+    "    \"geom\": {\"lonmin\": 1, \"latmin\": 43, \"lonmax\": 2, \"latmax\": 44},\n",
+    "    \"count\": True\n",
     "}"
    ]
   },
@@ -291,7 +289,8 @@
     "\n",
     "* `productType`: `eodag`'s product type\n",
     "* `start` and `end`: the start and end sensing datetimes (UTC)\n",
-    "* `geom`: the region of interest, which can be defined in different ways (`list`, `dict`, WKT string, `shapely.geometry`)."
+    "* `geom`: the region of interest, which can be defined in different ways (`list`, `dict`, WKT string, `shapely.geometry`).\n",
+    "* `count`: whether to retrieve the estimated total number of results or not (default is `False`)"
    ]
   },
   {
@@ -310,7 +309,14 @@
     }
    ],
    "source": [
-    "products_first_page, estimated_total_number = dag.search(**search_criteria)"
+    "products_first_page = dag.search(**search_criteria)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The estimated total number of products matching the search criteria is stored in the `number_matched` attribute (set to `None` if `count` is disabled or not available)."
    ]
   },
   {
@@ -327,14 +333,14 @@
     }
    ],
    "source": [
-    "print(f\"Got {len(products_first_page)} products and an estimated total number of {estimated_total_number} products.\")"
+    "print(f\"Got {len(products_first_page)} products and an estimated total number of {products_first_page.number_matched} products.\")"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "A [SearchResult](../../api_reference/searchresult.rst#eodag.api.search_result.SearchResult) contains a number of [EOProduct](../../api_reference/eoproduct.rst#eodag.api.product._product.EOProduct). Each one of them has a `properties` attribute that is a dictionnary storing the product's metadata."
+    "A [SearchResult](../../api_reference/searchresult.rst#eodag.api.search_result.SearchResult) contains a number of [EOProduct](../../api_reference/eoproduct.rst#eodag.api.product._product.EOProduct). Each one of them has a `properties` attribute that is a dictionary storing the product's metadata."
    ]
   },
   {