.. _plugins: Plugins ======= EODAG uses a two-level plugin system. *Plugin topics* are abstract interfaces for a specific functionality of EODAG like *Search* or *Download*. EODAG providers are implementations of at least one plugin topic. The more plugin topics are implemented by a provider, the more functionality of eodag are available for this provider. .. image:: _static/plugins_architecture.png :width: 800 :alt: EODAG plugins architecture :class: no-scaled-link Plugin Management ^^^^^^^^^^^^^^^^^ The plugin machinery is managed by one instance of :class:`~eodag.plugins.manager.PluginManager`. The instance manager knows how to discover plugins at runtime, using `setuptools entry points mechanism `_. Plugins Available ^^^^^^^^^^^^^^^^^ EODAG currently advertises 5 types of plugins: *Search*, *Download*, *Crunch*, *Authentication* and *Api*. .. toctree:: :maxdepth: 1 plugins_reference/search plugins_reference/crunch plugins_reference/auth plugins_reference/download plugins_reference/api The providers are implemented with a triplet of *Search/Authentication/Download* plugins or with an *Api* plugin: +------------------------+------------------------------------+---------------------------------+------------------+ | Provider | Search | Authentication | Download | +========================+====================================+=================================+==================+ | ``aws_eos`` | |PostJsonSearch| | |AwsAuth| | |AwsDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``cop_ads`` | |ECMWFSearch| | |HTTPHeaderAuth| | |HTTPDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``cop_cds`` | |ECMWFSearch| | |HTTPHeaderAuth| | |HTTPDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``cop_ewds`` | |ECMWFSearch| | |HTTPHeaderAuth| | |HTTPDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``cop_dataspace`` | |QueryStringSearch| | |KeycloakOIDCPasswordAuth| | |HTTPDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``cop_dataspace_s3`` | |CreodiasS3Search| | |AwsAuth| | |AwsDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``cop_ghsl`` | |CopGhslSearch| | ``None`` | |HTTPDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``cop_marine`` | |CopMarineSearch| | |AwsAuth| | |AwsDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``creodias`` | |QueryStringSearch| | |KeycloakOIDCPasswordAuth| | |HTTPDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``creodias_s3`` | |QueryStringSearch| | |AwsAuth| | |AwsDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``dedl`` | |StacSearch| | |OIDCTokenExchangeAuth| | |HTTPDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``dedt_lumi`` | |ECMWFSearch| | |OIDCAuthorizationCodeFlowAuth| | |HTTPDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``dedt_mn5`` | |ECMWFSearch| | |OIDCAuthorizationCodeFlowAuth| | |HTTPDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``earth_search`` | |StacSearch| | |AwsAuth| | |AwsDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``earth_search_gcs`` | |StacSearch| | |AwsAuth| | |AwsDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``ecmwf`` | |EcmwfApi| | |EcmwfApi| | |EcmwfApi| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``eumetsat_ds`` | |QueryStringSearch| | |TokenAuth| | |HTTPDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``fedeo-ceda`` | |StacSearch| | ``None`` | |HTTPDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``geodes`` | |StacSearch| | |HTTPHeaderAuth| | |HTTPDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``geodes_s3`` | |StacListAssets| | |AwsAuth| | |AwsDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``hydroweb_next`` | |StacSearch| | |HTTPHeaderAuth| | |HTTPDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``meteoblue`` | |MeteoblueSearch| | |HttpQueryStringAuth| | |HTTPDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``planetary_computer`` | |StacSearch| | |SASAuth| | |HTTPDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``usgs`` | |UsgsApi| | |UsgsApi| | |UsgsApi| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``usgs_satapi_aws`` | |StacSearch| | |AwsAuth| | |AwsDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``wekeo_ecmwf`` | |PostJsonSearch| | |TokenAuth| | |HTTPDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``wekeo_cmems`` | |PostJsonSearch| | |TokenAuth| | |HTTPDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ | ``wekeo_main`` | |WekeoSearch| | |TokenAuth| | |HTTPDownload| | +------------------------+------------------------------------+---------------------------------+------------------+ .. |UsgsApi| replace:: :class:`~eodag.plugins.apis.usgs.UsgsApi` .. |EcmwfApi| replace:: :class:`~eodag.plugins.apis.ecmwf.EcmwfApi` .. |GenericAuth| replace:: :class:`~eodag.plugins.authentication.generic.GenericAuth` .. |HTTPHeaderAuth| replace:: :class:`~eodag.plugins.authentication.header.HTTPHeaderAuth` .. |AwsAuth| replace:: :class:`~eodag.plugins.authentication.aws_auth.AwsAuth` .. |TokenAuth| replace:: :class:`~eodag.plugins.authentication.token.TokenAuth` .. |OIDCAuthorizationCodeFlowAuth| replace:: :class:`~eodag.plugins.authentication.openid_connect.OIDCAuthorizationCodeFlowAuth` .. |OIDCTokenExchangeAuth| replace:: :class:`~eodag.plugins.authentication.token_exchange.OIDCTokenExchangeAuth` .. |KeycloakOIDCPasswordAuth| replace:: :class:`~eodag.plugins.authentication.keycloak.KeycloakOIDCPasswordAuth` .. |HttpQueryStringAuth| replace:: :class:`~eodag.plugins.authentication.qsauth.HttpQueryStringAuth` .. |SASAuth| replace:: :class:`~eodag.plugins.authentication.sas_auth.SASAuth` .. |EOIAMAuth| replace:: :class:`~eodag.plugins.authentication.eoiam.EOIAMAuth` .. |AwsDownload| replace:: :class:`~eodag.plugins.download.aws.AwsDownload` .. |HTTPDownload| replace:: :class:`~eodag.plugins.download.http.HTTPDownload` .. |QueryStringSearch| replace:: :class:`~eodag.plugins.search.qssearch.QueryStringSearch` .. |ODataV4Search| replace:: :class:`~eodag.plugins.search.qssearch.ODataV4Search` .. |PostJsonSearch| replace:: :class:`~eodag.plugins.search.qssearch.PostJsonSearch` .. |StacSearch| replace:: :class:`~eodag.plugins.search.qssearch.StacSearch` .. |WekeoSearch| replace:: :class:`~eodag.plugins.search.qssearch.WekeoSearch` .. |ECMWFSearch| replace:: :class:`~eodag.plugins.search.build_search_result.ECMWFSearch` .. |MeteoblueSearch| replace:: :class:`~eodag.plugins.search.build_search_result.MeteoblueSearch` .. |WekeoECMWFSearch| replace:: :class:`~eodag.plugins.search.build_search_result.WekeoECMWFSearch` .. |CreodiasS3Search| replace:: :class:`~eodag.plugins.search.creodias_s3.CreodiasS3Search` .. |CopGhslSearch| replace:: :class:`~eodag.plugins.search.cop_ghsl.CopGhslSearch` .. |CopMarineSearch| replace:: :class:`~eodag.plugins.search.cop_marine.CopMarineSearch` .. |StacListAssets| replace:: :class:`~eodag.plugins.search.stac_list_assets.StacListAssets` .. _creating_plugins: Creating Plugins ^^^^^^^^^^^^^^^^ EODAG plugins can be separated from the core eodag package. They live in your Python site-packages as standalone Python packages or modules, with eodag's specific entry points that will be looked at by the plugin manager to load plugins at runtime. These entry points are: ``eodag.plugins.{topic}``, with possible values for ``topic`` being ``api``, ``search``, ``crunch``, ``auth`` and ``download``. All you have to do to create eodag plugins is start a new Python project, add eodag as a dependancy to your project, and then create the plugin type you want in Python module(s) by importing its base class from ``eodag.plugins.{topic}.base`` and subclassing it. Here is an example for an :class:`~eodag.plugins.apis.base.Api` plugin class located in a module named ``your_package.your_module``: .. code-block:: python from eodag.plugins.apis.base import Api class SampleApiPlugin(Api): def query(self): pass def download(self): pass Then, in the `configuration file `_ of your Python project, add this: .. tabs:: .. tab:: pyproject.toml .. code-block:: toml [project.entry-points."eodag.plugins.api"] SampleApiPlugin = "your_package.your_module:SampleApiPlugin" .. tab:: setup.py .. code-block:: python setup( # ... entry_points={ 'eodag.plugins.api': [ 'SampleApiPlugin = your_package.your_module:SampleApiPlugin' ] } ) See `what the PyPa explains `_ to better understand this concept. In EODAG, the name you give to your plugin in the entry point doesn't matter, but we prefer it to be the same as the class name of the plugin. What matters is that the entry point must be a class deriving from one of the 5 plugin topics supported. Be particularly careful with consistency between the entry point name and the super class of you plugin class. Here is a list of entry point names and the plugin topic to which they map: * `eodag.plugins.api` : :class:`~eodag.plugins.apis.base.Api` * `eodag.plugins.authentication` : :class:`~eodag.plugins.authentication.base.Authentication` * `eodag.plugins.crunch` : :class:`~eodag.plugins.crunch.base.Crunch` * `eodag.plugins.download` : :class:`~eodag.plugins.download.base.Download` * `eodag.plugins.search` : :class:`~eodag.plugins.search.base.Search` Read the :ref:`mock search plugin` section to get an example of how to build a search plugin. As an example of external plugin, you can have a look to `eodag-sentinelsat (archived) `_. .. _mock search plugin: A sample mock search plugin """"""""""""""""""""""""""" In this section, we demonstrate the creation of custom search plugin. This plugin will return a list of mocked EOProducts on search requests. 1. Create a folder called `eodag_search_mock`. It will be the name of our package. 2. Make an empty `__init.py__` file in the package folder. 3. Make a `mock_search.py` file and paste in it the following class definition. It is our search plugin. The `query()` function is the one called by EODAG when searching for products. .. code-block:: python # mock_search.py from typing import Any, List, Optional, Tuple from eodag.plugins.search import PreparedSearch from eodag.plugins.search.base import Search from eodag.api.product import EOProduct class MockSearch(Search): """Implement a Mock search plugin""" def query( self, prep: PreparedSearch = PreparedSearch(), **kwargs: Any, ) -> Tuple[List[EOProduct], Optional[int]]: """Generate EOProduct from the request""" return ([EOProduct( provider=self.provider, properties={ **{ "id": f"mock_{kwargs.get('collection')}_{i}" }, **kwargs } ) for i in range(0, prep.limit)], prep.limit if prep.count else None ) 4. Create a `pyproject.toml` file in the package folder and paste in it the following content. The `projects.entry-points` is crucial for EODAG to detect this new plugin. .. code-block:: toml [project] name = "eodag-search-mock" version = "0.0.1" description = "Mock Search plugin for EODAG" requires-python = ">=3.8" dependencies = [ "eodag" ] [project.entry-points."eodag.plugins.search"] MockSearch = "mock_search:MockSearch" 5. Your plugin is now ready. You need to install it for EODAG to be able to use it. .. code-block:: shell pip install eodag_search_mock Plugin configuration ^^^^^^^^^^^^^^^^^^^^ .. autoclass:: eodag.config.PluginConfig :members: :member-order: bysource :undoc-members: :exclude-members: priority, collection_config, yaml_loader, from_mapping, from_yaml, update, validate, yaml_dumper, yaml_tag