Distribution Statement
# # # This source code is subject to the license referenced at
# # # NRLMMD-GEOIPS.

Setting up for Plugin Development#

  1. To develop a new GeoIPS plugin, first install GeoIPS and ensure that you have your environment enabled and all environment variables set as described in the installation instructions.

  2. Then, choose a name for your package. By contention the package name should:

    • be all lower case

    • start with a letter

    • contain only letters, numbers, and underscores

    From here on, anywhere @package@ is used should be replaced with your chosen package name.

  3. Clone the template_basic_plugin repository, rename it, and remove the link to github.

    cd $GEOIPS_PACKAGES_DIR
git clone --no-tags --single-branch https://github.com/NRLMMD-GEOIPS/template_basic_plugin.git

# Replace @package@ with your package name, removing the @s
mv template_basic_plugin @package@
cd $MY_PKG_NAME
git remote remove origin template_basic_plugin.git

  4. Update readme.md

    The readme.md file describes your plugin package and should be updated to match your package. To do this, edit README.md to:

    • Replace all instances of @package@ with your package name.

    • Search for all remaining @ within the file and follow the included instructions to update the readme appropriately.

    • Remove all lines containing @.

  5. Update pyproject.toml

    Installing a Python package requires metadata that describes the package and how to install it. GeoIPS uses pyproject.toml to define this information. We, additionally, make GeoIPS aware of plugin packages using entry-points.

    To update pyproject.toml for your package, edit the file to:

    • Update @package@ to your package name.

    • Update my_package to your package name.

    • Add any python package depenencies to the install_requires section.

  6. Add and commit your changes.

    git add README.md pyproject.toml
git commit -m "Updated name of template plugin package to mine"

  7. Install your package using the changes you just made.

    Note: Any time you edit pyproject.toml, you must reinstall your package. Without doing this, GeoIPS will not be aware of your new changes, since it will be in the previous install state, which doesn’t include any new updates to this file.

    pip install -e $MY_PKG_DIR

    The -e portion of the command above means ‘editable’, so we can edit the package after it is installed and changes will be reflected in the installed package. Again, the only time you must reinstall is when you edit pyproject.toml, which generally only occurs when you create new module based plugins, and must add them as entry-points to pyproject.toml. This is further discussed in the Algorithms Section.

Defining pyproject.toml#

Installing Python packages requires metadata that describes the package and how to install it.

pyproject.toml defines this information for pip, including:

  • Package name, version, description, license, etc.

  • Which files should be contained in the package when installed

  • How to build the package

We make GeoIPS aware of our package using the “geoips.plugin_packages” namespace (allows GeoIPS to find YAML-based plugins)

And makes it aware of our module-based plugins using one namespace per interface (e.g. “geoips.algorithms”).

On this page

This Page