Climetlab Plugin mechanism

This document discuss how plugins are integrated into CliMetLab. There are two ways to add a plugin into CliMetLab:

• A Python package using the standard Python plugin mechanism based on entry_points. This is the generic CliMetLab plugin mechanism.

• A YAML file can be also be used to create plugins, when the plugin is simple enough and used only generic predefined code. (currently only for dataset plugins).

Plugin as python packages using entry_points

During the installation of the pip package, the plugin registers itself thanks to the entry points in its setup.py file, making CliMetLab aware of the new capabilities. Then, the user can take advantage of the shared code though the enhanced climetlab.load_dataset(), climetlab.load_source() and climetlab.plot_map(), etc.

For pip packages using setuptools, creating a plugin consists in adding an entry in setup.py:

  setuptools.setup(
      name = 'climetlab-package-name',
      ...
      entry_points={"climetlab.<plugintype>":
              ["foo = climetlab_package_name:FooClass",
               "bar = climetlab_package_name:BarClass"]
      },
  )

In this package called climetlab-package-name, the class climetlab_package_name.FooClass provides Python code related to "foo". Additional code related to "bar" is located in the class climetlab_package_name.BarClass. The <plugintype> is one of the plugin type in the table above: dataset, sources, readers, etc. See the individual documentation for each plugin type for detailed examples and the standard `Python plugin documentation<https://packaging.python.org/guides/creating-and-discovering-plugins>`_.

Plugin as YAML files

Todo

This is still a work-in-progress.

Additionally, for dataset plugins only, CliMetLab search for known locations to find a YAML file with a name matching the requested dataset. The YAML files are used to create an appropriate class.