From f5b4015e976685972c823c4d992ab685b39d9b3a Mon Sep 17 00:00:00 2001 From: Sylvain Brunato <61419125+sbrunato@users.noreply.github.com> Date: Wed, 5 Feb 2025 16:44:07 +0100 Subject: [PATCH] docs: eodag-cube api ref (#1511) --- docs/api_reference/assets.rst | 32 ++++++++++++ docs/api_reference/eoproduct.rst | 52 +++++++++++-------- docs/api_reference/exceptions.rst | 7 +++ docs/api_reference/index.rst | 1 + docs/api_reference/types.rst | 3 ++ docs/api_reference/utils.rst | 10 ++++ docs/conf.py | 8 +-- .../api_user_guide/9_post_process.ipynb | 10 ++-- eodag/api/product/_assets.py | 37 +++++++++++-- eodag/api/product/_product.py | 32 +++++------- pytest.ini | 1 + setup.cfg | 2 +- 12 files changed, 144 insertions(+), 51 deletions(-) create mode 100644 docs/api_reference/assets.rst diff --git a/docs/api_reference/assets.rst b/docs/api_reference/assets.rst new file mode 100644 index 000000000..eef08ef57 --- /dev/null +++ b/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 `__ 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 diff --git a/docs/api_reference/eoproduct.rst b/docs/api_reference/eoproduct.rst index fe0174db4..8bf2fccbb 100644 --- a/docs/api_reference/eoproduct.rst +++ b/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 `__ 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 diff --git a/docs/api_reference/exceptions.rst b/docs/api_reference/exceptions.rst index 3be33fc5c..8d606a736 100644 --- a/docs/api_reference/exceptions.rst +++ b/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 `__ installed. + +.. automodule:: eodag_cube.utils.exceptions + :members: diff --git a/docs/api_reference/index.rst b/docs/api_reference/index.rst index 945d91346..e575fd1fd 100644 --- a/docs/api_reference/index.rst +++ b/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 diff --git a/docs/api_reference/types.rst b/docs/api_reference/types.rst index 7a36ce048..5711f6e3c 100644 --- a/docs/api_reference/types.rst +++ b/docs/api_reference/types.rst @@ -7,3 +7,6 @@ Types .. automodule:: eodag.types.download_args :members: + +.. autoclass:: eodag_cube.types.XarrayDict + :members: diff --git a/docs/api_reference/utils.rst b/docs/api_reference/utils.rst index 475a2a157..66ec971e0 100644 --- a/docs/api_reference/utils.rst +++ b/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 `__ installed. + +.. automodule:: eodag_cube.utils.xarray + :members: + Misc ---- diff --git a/docs/conf.py b/docs/conf.py index c8e6320cb..69e1a3969 100644 --- a/docs/conf.py +++ b/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"] diff --git a/docs/notebooks/api_user_guide/9_post_process.ipynb b/docs/notebooks/api_user_guide/9_post_process.ipynb index 32f9fade6..2e5b330c4 100644 --- a/docs/notebooks/api_user_guide/9_post_process.ipynb +++ b/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*." ] }, { diff --git a/eodag/api/product/_assets.py b/eodag/api/product/_assets.py index 60f5d5191..d1ac5c56e 100644 --- a/eodag/api/product/_assets.py +++ b/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) + + >>> 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"]) + + >>> product.assets["foo"] + {'href': 'http://somewhere/something'} """ product: EOProduct diff --git a/eodag/api/product/_product.py b/eodag/api/product/_product.py index c3934c91c..ba96d8869 100644 --- a/eodag/api/product/_product.py +++ b/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 `_ @@ -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 diff --git a/pytest.ini b/pytest.ini index 56283ece4..765b443fd 100644 --- a/pytest.ini +++ b/pytest.ini @@ -1,5 +1,6 @@ [pytest] testpaths = + eodag/api/product eodag/types eodag/utils tests diff --git a/setup.cfg b/setup.cfg index f0d01d3fe..5f4f7df63 100644 --- a/setup.cfg +++ b/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