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 </contributing/datasets>
).
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 :pyclimetlab.load_dataset()
, :pyclimetlab.load_source()
and :pyclimetlab.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 :pyclimetlab_package_name.FooClass
provides Python code related to "foo"
. Additional code related to "bar"
is located in the class :pyclimetlab_package_name.BarClass
. The <plugintype> is one of the plugin type in the table above: dataset <datasets>
, sources <sources>
, readers <readers>
, etc. See the individual documentation for each plugin type for detailed examples and the standard Python plugin documentation.
This is still a work-in-progress.
Additionally, for dataset plugins </contributing/datasets>
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.