📚 review docs and 🔖 prepare release 1.0

CHANGES.rst

@@ -11,6 +11,14 @@ Changes
 =======
 
 
+Version 1.0.0 (2023-09-22)
+--------------------------
+
+- Review module dependencies
+- Add driver for Copernicus DataSpace EcoSystem.
+- Improve docs for command line and downloading.
+
+
 Version 0.9.0 (2023-01-26)
 --------------------------
 

USAGE.rst

@@ -156,6 +156,12 @@ To download Landsat-8 Digital Number from `USGS Earth Explorer <https://earthexp
 SciHub
 ~~~~~~
 
+
+.. warning::
+
+    The official Copernicus SciHub is being deprecated. Use ``Dataspace`` instead.
+
+
 To download Sentinel-2 from `SciHub <https://scihub.copernicus.eu/dhus/>`_::
 
     bdc-collector download --provider=SciHub \
@@ -173,6 +179,20 @@ To download L2A::
                            --password=password
 
 
+Dataspace
+~~~~~~~~~
+
+
+To download Sentinel-2 from `Dataspace EcoSystem <https://dataspace.copernicus.eu/>`_::
+
+    bdc-collector download --provider=Dataspace \
+                           --scene-id=S2B_MSIL2A_20200930T135119_N0214_R024_T21KXA_20200930T175714 \
+                           --output=. \
+                           --dataset SENTINEL-2 \
+                           --username=user \
+                           --password=password
+
+
 Google Public Data Sets
 ~~~~~~~~~~~~~~~~~~~~~~~
 

bdc_collectors/dataspace/__init__.py

@@ -24,13 +24,14 @@
 import logging
 import os
 import shutil
+import time
 import typing as t
 from urllib.parse import ParseResult, urlparse
 
 import requests
 
 from ..base import BaseProvider, BulkDownloadResult, SceneResult, SceneResults
-from ..exceptions import DataOfflineError
+from ..exceptions import DataOfflineError, DownloadError
 from ..scihub.sentinel2 import Sentinel1, Sentinel2
 from ..utils import download_stream, import_entry
 from ._token import TokenManager
@@ -60,7 +61,7 @@ class DataspaceProvider(BaseProvider):
     `Access Token <https://documentation.dataspace.copernicus.eu/APIs/Token.html>`_,
     an ``access_token`` is required to download data. By default, this module stores these tokens in
     :class:`bdc_collectors.dataspace._token.TokenManager`. Whenever a download is initiated by 
-    :method:`bdc_collectors.dataspace.DataspaceProvider.download`, the bdc-collectors creates two (2) access tokens
+    :meth:`bdc_collectors.dataspace.DataspaceProvider.download`, the bdc-collectors creates two (2) access tokens
     in memory and then use it to download as many scenes as can. When the token expires, it automatically refresh
     a new token.
 
@@ -75,6 +76,7 @@ class DataspaceProvider(BaseProvider):
 
 
         You may change the API backend with command:
+
         >>> from bdc_collectors.dataspace.stac import StacStrategy
         >>> stac = StacStrategy()
         >>> provider = DataspaceProvider(username='[email protected]', password='passwd', strategy=stac)
@@ -151,14 +153,25 @@ def download(self, query: t.Union[SceneResult, str], output: str, *args, **kwarg
 
         download_url = parsed_changed.geturl()
 
-        token = self._token_manager.get_token()
+        # Retry 3 times before reject
+        for i in range(3):
+            token = self._token_manager.get_token()
+
+            headers = {"Authorization": f"Bearer {token.token}"}
+            self.session.headers = headers
+            try:
+                response = self.session.get(download_url, stream=True, timeout=600, allow_redirects=True)
+
+                # TODO: Validate Offline/Exception to retry later Checksum
+                download_stream(tmp_file, response, progress=self._kwargs.get("progress", False))
 
-        headers = {"Authorization": f"Bearer {token.token}"}
-        self.session.headers = headers
-        response = self.session.get(download_url, stream=True, timeout=600, allow_redirects=True)
+                break
+            except Exception:
+                logging.debug(f"Error in download {query.scene_id}")
+                time.sleep(3)
 
-        # TODO: Validate Offline/Exception to retry later Checksum
-        download_stream(tmp_file, response, progress=self._kwargs.get("progress", False))
+            if i == 2:
+                raise DownloadError(f"Could not download {query.scene_id}")
 
         shutil.move(tmp_file, target_file)
 

bdc_collectors/dataspace/_cache.py

@@ -19,8 +19,8 @@
 """Define a minimal cache strategy for Dataspace metadata.
 
 This file contains the following strategies:
-- RedisStrategy
-- RawDictStrategy
+- :class:`bdc_collectors.dataspace._cache.RedisStrategy`
+- :class:`bdc_collectors.dataspace._cache.RawDictStrategy`
 """
 
 import os

bdc_collectors/dataspace/_token.py

@@ -37,13 +37,15 @@ class TokenManager:
     
     Examples:
         Use the TokenManager as following to generate a new token:    
+
         >>> from bdc_collectors.dataspace._token import TokenManager
         >>> manager = TokenManager("username", "password")
         >>> token = manager.get_token()
         >>> # Use the token to download anything during the next 10 minutes
         >>> another = manager.get_token()
 
         You can also use Redis Backend for token management. (Make sure you have the library 'redis' installed and server up and running.)
+
         >>> from bdc_collectors.dataspace._cache import RedisStrategy
         >>> from bdc_collectors.dataspace._token import TokenManager
         >>> manager = TokenManager("username", "password", token_cache=RedisStrategy())

bdc_collectors/utils.py

@@ -27,8 +27,8 @@
 
 import dateutil
 import requests
-from shapely import from_wkt
 from shapely.geometry import base, shape
+from shapely.wkt import loads as from_wkt
 from tqdm import tqdm
 
 from .exceptions import DownloadError

bdc_collectors/version.py

@@ -18,4 +18,4 @@
 
 """Version information for BDC-Collectors."""
 
-__version__ = '0.9.0'
+__version__ = '1.0.0'

docs/sphinx/api.rst

@@ -40,6 +40,10 @@ Providers
 SciHub Copernicus
 +++++++++++++++++
 
+.. deprecated: 1.0
+
+    Use `Dataspace`_ instead.
+
 .. automodule:: bdc_collectors.scihub
     :members:
 
@@ -79,6 +83,32 @@ MODIS
     :members:
 
 
+.. _Dataspace:
+
+Copernicus Dataspace EcoSystem
+++++++++++++++++++++++++++++++
+
+.. automodule:: bdc_collectors.dataspace
+    :members:
+
+
+Dataspace API Implementations
+
+.. automodule:: bdc_collectors.dataspace.odata
+    :members:
+
+
+.. automodule:: bdc_collectors.dataspace.stac
+    :members:
+
+
+.. automodule:: bdc_collectors.dataspace._token
+    :members:
+
+
+.. automodule:: bdc_collectors.dataspace._cache
+    :members:
+
 Exceptions
 ----------