diff --git a/docs/examples/demo_sources_plugin.ipynb b/docs/examples/demo_sources_plugin.ipynb index 6a01ae1a..1cc3457f 100644 --- a/docs/examples/demo_sources_plugin.ipynb +++ b/docs/examples/demo_sources_plugin.ipynb @@ -44,7 +44,7 @@ }, "outputs": [], "source": [ - "# !pip install --quiet git+https://github.com/ecmwf/earthkit-data-demo-source" + "# !pip install --quiet earthkit-data-demo-source" ] }, { diff --git a/docs/plugins/plugins.rst b/docs/plugins/plugins.rst index a137c1ff..90421305 100644 --- a/docs/plugins/plugins.rst +++ b/docs/plugins/plugins.rst @@ -11,21 +11,19 @@ Plugin as python packages using ``entry_points`` A plugin can be added to earthkit-data by using the standard `Python plugin `_ mechanism based on ``entry_points``. -This requires the plugin package to have a special section in its ``setup.cfg`` file. During the installation of the package, the plugin registers itself thanks to the entry points in it configuration, making earthkit-data aware of the new capabilities. -Then, the user can take advantage of the shared code through the enhanced :py:func:`from_source` etc. methods. +This requires the plugin package to have a special section in its ``pyproject.toml`` file. During the installation of the package, the plugin registers itself thanks to the entry points in it configuration, making earthkit-data aware of the new capabilities. Users can then take advantage of the shared code through the enhanced :py:func:`from_source` etc. methods. The following example shows how it can be done. :Example: - Let us suppose our package is called **earthkit-data-package-name** and implements a ``"sources"`` (note the plural form) plugin type . If it is a ``pip`` package using ``setuptools`` we need to add an ``entry_points`` block to ``setup.cfg``: + Let us suppose our package is called **earthkit-data-package-name** and implements a ``"sources"`` (note the plural form) plugin type . If it is a ``pip`` package using ``setuptools`` we need to add an ``entry_points`` block to ``pyproject.toml``: - .. code-block:: ini + .. code-block:: toml + + entry-points."earthkit.data.sources".foo = "earthkit_data_package_name:FooClass" + entry-points."earthkit.data.sources".bar = "earthkit_data_package_name:BarClass" - [options.entry_points] - earthkit.data.sources = - foo = earthkit_data_package_name:FooClass - bar = earthkit_data_package_name:BarClass This block specifies that in the package the :py:class:`FooClass` class implements the ``"foo"`` source, while the :py:class:`BarClass` class implements the ``"bar"`` source. In earthkit-data we will be able to use them as: diff --git a/docs/plugins/sources_plugin.rst b/docs/plugins/sources_plugin.rst index 7a9d7a7a..83d38e1e 100644 --- a/docs/plugins/sources_plugin.rst +++ b/docs/plugins/sources_plugin.rst @@ -26,16 +26,14 @@ This package must contain a Python class inherited from :class:`earthkit.data.So from earthkit_data_my_source import MyClass -Please note that in this line the package name to import form has to contain "_" characters. +Please note that in the line above the package name has to contain "_" characters. -In the ``setup.cfg`` file of the package the ``entry_points`` +In the ``pyproject.toml`` file of the package the ``entry_points`` integration must be set as follow: -.. code-block:: ini +.. code-block:: toml - [options.entry_points] - earthkit.data.sources = - my-source = earthkit_data_my_source:MyClass + entry-points."earthkit.data.sources".my-source = "earthkit_data_my_source:MyClass" With this we could use the new source in :func:`from_source` as: @@ -49,7 +47,7 @@ With this we could use the new source in :func:`from_source` as: .. note:: - The source name used in :func:`from_source` is only defined in the ``entry_points`` block in ``setup.cfg``, so it is not deduced from the package name. + The source name used in :func:`from_source` is only defined in the ``entry_points`` block in ``pyproject.toml``, so it is not deduced from the package name. Example @@ -57,11 +55,11 @@ Example The ``earthkit-data-demo-source`` package demonstrates how to implement a ``sources plugin``. Its source code is located at https://github.com/ecmwf/earthkit-data-demo-source. This plugin enables earthkit-data to access data from an SQL database. -This demo package is not hosted on PyPI but we need to install it from github: +This demo package can be installed as: .. code-block:: shell - pip install git+https://github.com/ecmwf/earthkit-data-demo-source + pip install earthkit-data-demo-source Having finished the installation, tabular data can be read in earthkit-data as follows: @@ -78,13 +76,11 @@ Having finished the installation, tabular data can be read in earthkit-data as f ) df = ds.to_pandas() -The integration is performed by ``entry_points`` is defined in ``setup.cfg``. +The integration is performed by ``entry_points`` defined in ``pyproject.toml``. -.. code-block:: ini +.. code-block:: toml - [options.entry_points] - earthkit.data.sources = - demo-source = earthkit_data_demo_source:DemoSource + entry-points."earthkit.data.sources".demo-source = "earthkit_data_demo_source:DemoSource" See the :ref:`/examples/demo_sources_plugin.ipynb` notebook for the full example.