Skip to content

Plugin Installation Guide

How to install the SitePack reference plugin (or any MineProductivity plugin) and confirm it is discovered.

1. Prerequisites

  • A Python 3.12 environment with MineProductivity >=2.0.0,<4 installed.
  • For the PDF renderer, the plugin's [pdf] extra (pulls in reportlab).

2. Install

From the repository root:

pip install -e examples/plugins/sitepack          # core backends
pip install -e "examples/plugins/sitepack[pdf]"   # + PDF renderer

The plugin declares its extension points as entry points in pyproject.toml, so installation is all that is required - there is no manual registration step and no configuration file to edit.

3. Verify discovery

Discovery is performed by the framework, through entry points only:

from mineproductivity.registry import EntryPointDiscovery, EntryPointSpec
from mineproductivity.visualization import RENDERERS
from mineproductivity.optimization import REGISTRY

# Import the plugin's target modules (registration is the import side effect).
EntryPointDiscovery().discover(
    EntryPointSpec(group="mineproductivity.visualization.renderers",
                   target_registry="visualization.renderers")
)
EntryPointDiscovery().discover(
    EntryPointSpec(group="mineproductivity.optimization", target_registry="optimization")
)

assert "HTML.SitePack" in RENDERERS
assert "MIP.SitePackDispatchAllocation" in REGISTRY

discover() returns Result.ok((...)) naming the entry-points that loaded. A plugin that fails to import (e.g. incompatible framework) is skipped, not fatal - the return value simply omits it.

4. Version compatibility

The plugin targets mineproductivity >=2.0.0,<4.0.0 (the v2.x and v3.x public API is identical for the surfaces it uses). If installed against an unsupported framework, importing it raises registry.VersionIncompatibleError; EntryPointDiscovery catches that and skips the plugin, leaving the host stable.

5. Uninstall

pip uninstall mineproductivity-sitepack

After uninstall the entry points disappear, so discover() no longer finds the backends and any consuming solution transparently falls back to its plugin-free behaviour.