docs: eodag-cube api ref (#1511)

docs/api_reference/assets.rst

@@ -0,0 +1,32 @@
+.. module:: eodag.api.product._assets
+
+======
+Assets
+======
+
+.. autoclass:: AssetsDict
+   :members:
+
+.. autoclass:: Asset
+   :members:
+
+Pixel access
+------------
+
+.. warning::
+
+   The following methods will only be available with `eodag-cube <https://github.com/CS-SI/eodag-cube>`__ installed.
+
+.. class:: eodag_cube.api.product._assets.AssetsDict
+   :canonical: eodag_cube.api.product._assets.AssetsDict
+
+   Inherits from :class:`eodag.api.product._assets.AssetsDict` and implements pixel access related methods.
+
+.. class:: eodag_cube.api.product._assets.Asset
+
+   Inherits from :class:`eodag.api.product._assets.Asset` and implements pixel access related methods.
+
+.. automethod:: eodag_cube.api.product._assets.Asset.to_xarray
+.. automethod:: eodag_cube.api.product._assets.Asset.get_file_obj
+.. automethod:: eodag_cube.api.product._assets.Asset.rio_env
+.. automethod:: eodag_cube.api.product._assets.Asset.get_data

docs/api_reference/eoproduct.rst

@@ -7,40 +7,50 @@ EOProduct
 Constructor
 -----------
 
-.. autosummary::
+.. autoclass:: EOProduct
 
-   EOProduct
+   :Attributes:
 
-Download
---------
-
-.. autosummary::
+      .. autoattribute:: provider
+      .. autoattribute:: properties
+      .. autoattribute:: product_type
+      .. autoattribute:: geometry
+      .. autoattribute:: search_intersection
+      .. autoattribute:: location
+      .. autoattribute:: remote_location
+      .. autoattribute:: assets
+      .. autoattribute:: driver
 
-   EOProduct.download
-   EOProduct.get_quicklook
-
-Driver
+Download
 --------
 
-.. autosummary::
-
-   EOProduct.driver
+.. automethod:: EOProduct.download
+.. automethod:: EOProduct.get_quicklook
 
 Conversion
 ----------
 
-.. autosummary::
-
-   EOProduct.as_dict
-   EOProduct.from_geojson
+.. automethod:: EOProduct.as_dict
+.. automethod:: EOProduct.from_geojson
 
 Interface
 ---------
 
-.. autosummary::
+.. autoproperty:: EOProduct.__geo_interface__
+
+Pixel access
+------------
+
+.. warning::
+
+   The following methods will only be available with `eodag-cube <https://github.com/CS-SI/eodag-cube>`__ installed.
 
-   EOProduct.__geo_interface__
+.. class:: eodag_cube.api.product._product.EOProduct
+   :canonical: eodag_cube.api.product._product.EOProduct
 
+   Inherits from :class:`eodag.api.product._product.EOProduct` and implements pixel access related methods.
 
-.. autoclass:: eodag.api.product._product.EOProduct
-   :members: driver, download, get_quicklook, as_dict, from_geojson, __geo_interface__
+.. automethod:: eodag_cube.api.product._product.EOProduct.to_xarray
+.. automethod:: eodag_cube.api.product._product.EOProduct.get_file_obj
+.. automethod:: eodag_cube.api.product._product.EOProduct.rio_env
+.. automethod:: eodag_cube.api.product._product.EOProduct.get_data

docs/api_reference/exceptions.rst

@@ -4,3 +4,10 @@ Exceptions
 
 .. automodule:: eodag.utils.exceptions
    :members:
+
+.. warning::
+
+   The following classes will only be available with `eodag-cube <https://github.com/CS-SI/eodag-cube>`__ installed.
+
+.. automodule:: eodag_cube.utils.exceptions
+   :members:

docs/api_reference/index.rst

@@ -12,6 +12,7 @@ The Python API Reference provides an overview of all public objects, functions a
    core
    searchresult
    eoproduct
+   assets
    utils
    exceptions
    types

docs/api_reference/types.rst

@@ -7,3 +7,6 @@ Types
 
 .. automodule:: eodag.types.download_args
    :members:
+
+.. autoclass:: eodag_cube.types.XarrayDict
+   :members:

docs/api_reference/utils.rst

@@ -30,6 +30,16 @@ S3
 .. automodule:: eodag.utils.s3
    :members:
 
+xarray
+------
+
+.. warning::
+
+   These functions will only be available with `eodag-cube <https://github.com/CS-SI/eodag-cube>`__ installed.
+
+.. automodule:: eodag_cube.utils.xarray
+   :members:
+
 Misc
 ----
 

docs/conf.py

@@ -242,15 +242,17 @@
     "pull": ("https://github.com/CS-SI/eodag/pull/%s", "#%s"),
 }
 
-# Example configuration for intersphinx: refer to the Python standard library.
+# configuration for intersphinx
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
-    # python-requests url temporary changed
-    # https://github.com/psf/requests/issues/6140#issuecomment-1135071992
     "python-requests": ("https://requests.readthedocs.io/en/stable/", None),
     "shapely": ("https://shapely.readthedocs.io/en/stable/", None),
     "click": ("https://click.palletsprojects.com/en/stable/", None),
     "urllib3": ("https://urllib3.readthedocs.io/en/stable/", None),
+    "xarray": ("https://docs.xarray.dev/en/stable/", None),
+    "rasterio": ("https://rasterio.readthedocs.io/en/stable/", None),
+    "rioxarray": ("https://corteva.github.io/rioxarray/stable/", None),
+    "fsspec": ("https://filesystem-spec.readthedocs.io/en/stable/", None),
 }
 
 suppress_warnings = ["misc.copy_overwrite"]

docs/notebooks/api_user_guide/9_post_process.ipynb

@@ -47,7 +47,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Sentinel products are generally distributed in the [SAFE format](https://sentinel.esa.int/web/sentinel/user-guides/sentinel-2-msi/data-formats). AWS-based providers however offers Sentinel products in a \"scattered\" way, each file being able to be downloaded individually. `eodag` downloads these multiple files and automatically builds a SAFE product out of them. Image processing softwares such as [SNAP](https://step.esa.int/main/toolboxes/snap/) work well with products in the SAFE format."
+    "Sentinel products are generally distributed in the [SAFE format](https://sentiwiki.copernicus.eu/web/safe-format). AWS-based providers however offers Sentinel products in a \"scattered\" way, each file being able to be downloaded individually. `eodag` downloads these multiple files and automatically builds a SAFE product out of them. Image processing softwares such as [SNAP](https://step.esa.int/main/toolboxes/snap/) work well with products in the SAFE format."
    ]
   },
   {
@@ -63,21 +63,23 @@
    "source": [
     "At some point `eodag` had some capabilities to directly post-process a product, i.e. to access its data. These capabilities, which relied on [xarray](https://docs.xarray.dev/en/stable/) and [rasterio](https://rasterio.readthedocs.io/en/latest/), have been ported to the Python package [eodag-cube](https://github.com/CS-SI/eodag-cube) to avoid the heavy dependencies associated with `rasterio` and `GDAL` in particular. Installing this package is enough to benefit from its capabilities.\n",
     "\n",
-    "[eodag-cube](https://github.com/CS-SI/eodag-cube) extends the [EOProduct](../../api_reference/eoproduct.rst#eodag.api.product._product.EOProduct) class with a `to_xarray()` method which returns product readable content in a `XarrayDict` (dictionary of `xarray.Dataset`)."
+    "[eodag-cube](https://github.com/CS-SI/eodag-cube) extends the [EOProduct](../../api_reference/eoproduct.rst#eodag.api.product._product.EOProduct) class with a [to_xarray()](../../api_reference/eoproduct.rst#eodag_cube.api.product._product.EOProduct.to_xarray) method which returns product readable content in a `XarrayDict` (dictionary of `xarray.Dataset`).",
+    "\n",
+    "A [ffspec](https://filesystem-spec.readthedocs.io) file refering to the data can also be obtained using the [get_file_obj()](../../api_reference/eoproduct.rst#eodag_cube.api.product._product.EOProduct.get_file_obj) method."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Setup"
+    "### Usage"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "A search is made to get *Sentinel 2 Level-1C* products from *Creodias S3*."
+    "In this example, a search is made to get *Sentinel 2 Level-1C* products from *Creodias S3*."
    ]
   },
   {

eodag/api/product/_assets.py

@@ -31,12 +31,27 @@
 
 
 class AssetsDict(UserDict):
-    """A UserDict object listing assets contained in a
-    :class:`~eodag.api.product._product.EOProduct` resulting from a search.
+    """A UserDict object which values are :class:`~eodag.api.product._assets.Asset`
+    contained in a :class:`~eodag.api.product._product.EOProduct` resulting from a
+    search.
 
     :param product: Product resulting from a search
     :param args: (optional) Arguments used to init the dictionary
     :param kwargs: (optional) Additional named-arguments used to init the dictionary
+
+    Example
+    -------
+
+    >>> from eodag.api.product import EOProduct
+    >>> product = EOProduct(
+    ...     provider="foo",
+    ...     properties={"id": "bar", "geometry": "POINT (0 0)"}
+    ... )
+    >>> type(product.assets)
+    <class 'eodag.api.product._assets.AssetsDict'>
+    >>> product.assets.update({"foo": {"href": "http://somewhere/something"}})
+    >>> product.assets
+    {'foo': {'href': 'http://somewhere/something'}}
     """
 
     product: EOProduct
@@ -119,13 +134,27 @@ def _repr_html_(self, embeded=False):
 
 
 class Asset(UserDict):
-    """A UserDict object containg one of the assets of a
-    :class:`~eodag.api.product._product.EOProduct` resulting from a search.
+    """A UserDict object containg one of the
+    :attr:`~eodag.api.product._product.EOProduct.assets` resulting from a search.
 
     :param product: Product resulting from a search
     :param key: asset key
     :param args: (optional) Arguments used to init the dictionary
     :param kwargs: (optional) Additional named-arguments used to init the dictionary
+
+    Example
+    -------
+
+    >>> from eodag.api.product import EOProduct
+    >>> product = EOProduct(
+    ...     provider="foo",
+    ...     properties={"id": "bar", "geometry": "POINT (0 0)"}
+    ... )
+    >>> product.assets.update({"foo": {"href": "http://somewhere/something"}})
+    >>> type(product.assets["foo"])
+    <class 'eodag.api.product._assets.Asset'>
+    >>> product.assets["foo"]
+    {'href': 'http://somewhere/something'}
     """
 
     product: EOProduct

eodag/api/product/_product.py

@@ -89,20 +89,6 @@ class EOProduct:
 
     :param provider: The provider from which the product originates
     :param properties: The metadata of the product
-    :ivar product_type: The product type
-    :vartype product_type: str
-    :ivar location: The path to the product, either remote or local if downloaded
-    :vartype location: str
-    :ivar remote_location: The remote path to the product
-    :vartype remote_location: str
-    :ivar search_kwargs: The search kwargs used by eodag to search for the product
-    :vartype search_kwargs: Any
-    :ivar geometry: The geometry of the product
-    :vartype geometry: :class:`shapely.geometry.base.BaseGeometry`
-    :ivar search_intersection: The intersection between the product's geometry
-                               and the search area.
-    :vartype search_intersection: :class:`shapely.geometry.base.BaseGeometry` or None
-
 
     .. note::
         The geojson spec `enforces <https://github.com/geojson/draft-geojson/pull/6>`_
@@ -112,18 +98,28 @@ class EOProduct:
         mentioned CRS.
     """
 
+    #: The provider from which the product originates
     provider: str
+    #: The metadata of the product
     properties: dict[str, Any]
+    #: The product type
     product_type: Optional[str]
-    location: str
-    filename: str
-    remote_location: str
-    search_kwargs: Any
+    #: The geometry of the product
     geometry: BaseGeometry
+    #: The intersection between the product's geometry and the search area.
     search_intersection: Optional[BaseGeometry]
+    #: The path to the product, either remote or local if downloaded
+    location: str
+    #: The remote path to the product
+    remote_location: str
+    #: Assets of the product
     assets: AssetsDict
     #: Driver enables additional methods to be called on the EOProduct
     driver: DatasetDriver
+    #: Product data filename, stored during download
+    filename: str
+    #: Product search keyword arguments, stored during search
+    search_kwargs: Any
 
     def __init__(
         self, provider: str, properties: dict[str, Any], **kwargs: Any

pytest.ini

@@ -1,5 +1,6 @@
 [pytest]
 testpaths =
+    eodag/api/product
     eodag/types
     eodag/utils
     tests

setup.cfg

@@ -86,7 +86,7 @@ server =
 notebook = tqdm[notebook]
 tutorials =
     eodag[ecmwf,notebook]
-    eodag-cube >= 0.6.0b1
+    eodag-cube @ git+https://github.com/CS-SI/eodag-cube@develop
     jupyter
     ipyleaflet >= 0.10.0
     ipywidgets