Climetlab Plugin mechanism

The generic CliMetLab plugin mechanism relies on creating a Python package using the Python plugin mechanism with entry_points. Additionally, dataset plugins can be created using YAML file. A Dataset plugin template (https://github.com/ecmwf-lab/climetlab-cookiecutter-dataset) has been designed to create the boilerplate code for a plugin.

Note

Naming convention: the package name should preferably starts with climetlab- and use “-”. The Python package to import should starts with climetlab_ and use “_”.

After installation, the plugin registers itself thanks to the entry points in the 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_dataset() 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.

Todo

Move from setup.py to setup.cfg or pytoml? Add doc for conda? Link to documentation about climetlab.plugin.register().

CliMetLab plugins rely on the python plugins system using entry_points.

climetlab.core.plugins.directories(owner: bool = False) → list

Return a list of directories that are used in the project .

If owner = False, return a list of directories where to search for plugins.

If owner = True, return a list of 2-uples to include the owner in the return value.

Parameters

owner (bool, optional) –

climetlab.core.plugins.find_plugin(directories: Union[str, List[str]], name: str, loader)

Find a plugin by name .

Parameters

  • directories (list or str) – List of directories to be searched to find the plugin.

  • name (str) – Name of the plugin

  • loader (class) – Class implementing load_yaml() and load_module()

Returns

Return type

Return what the loader will returns when applied to the plugin with the right name name, found in one of the directories of the directories list.

Raises

NameError – If plugin is not found.

climetlab.core.plugins.load_plugins(kind)

Loads the plugins for a given kind. The plugin needs to have registered itself with entry_point.

Parameters

kind (str) – Plugin type such as “dataset” or “source”.

climetlab.core.plugins.register(kind, name_or_module, module_or_none=None)

Register a plugin manually.

When installing a plugin (for instance with !pip install in a notebook), the pip package with register the plugin with the entry_points mechanism, but the currently runnning kernel will need to be restarted to take the change into account. Using register() alleviates this issue.

Parameters

  • kind (str) – Type of plugind.

  • name_or_module (str or module) – Name of the installed plugin to registed.

  • module_or_none (module, optional) – Module recently installed to be registered.