wolfhece._companion_plugin_manager
==================================

.. py:module:: wolfhece._companion_plugin_manager

.. autoapi-nested-parse::

   Companion plugin manager.

   Manages discovery, loading, enabling and disabling of external companion
   plugins, and integrates them into the viewer menu bar.

   Quick usage
   -----------
   ::

       from wolfhece._companion_plugin_manager import PluginManagerCompanion

       mgr = PluginManagerCompanion(viewer)
       mgr.menu_build()   # adds "Plugins" top-level menu
       mgr.discover()     # scans default directory and activates enabled plugins

       # Programmatic enable/disable:
       mgr.plugin_manager.disable('dot_picker')
       mgr.plugin_manager.enable('dot_picker')

   Persistence
   -----------
   Enabled/disabled state is stored in the viewer's
   :class:`~wolfhece.PyConfig.WolfConfiguration` under the
   ``PLUGINS_DISABLED`` key (list of disabled plugin names).

   The plugins directory is stored under ``PLUGINS_DIRECTORY``
   (empty string → built-in ``wolfhece/data/plugins``).







Module Contents
---------------

.. py:data:: _logger

.. py:class:: PluginManager(viewer: wolfhece.PyDraw.WolfMapViewer)

   Manages the runtime lifecycle of companion plugins for one viewer.

   .. attribute:: plugins

      All discovered plugins (loaded or failed).

      :type: list[PluginInfo]

   .. attribute:: active

      Mapping of plugin name → currently active companion instance.

      :type: dict[str, AbstractCompanion]


   .. py:attribute:: _viewer


   .. py:attribute:: plugins
      :type:  list[wolfhece._plugin_loader.PluginInfo]
      :value: []



   .. py:attribute:: active
      :type:  dict[str, wolfhece._menu_companion_abc.AbstractCompanion]


   .. py:method:: discover(directory: pathlib.Path | str | None = None) -> list[wolfhece._plugin_loader.PluginInfo]

      Scan *directory*, load plugins, and apply the stored enable/disable state.

      :param directory: Override the plugins directory.  ``None`` reads the
          value from the viewer configuration (falling back to the built-in
          ``wolfhece/data/plugins``).
      :return: The refreshed :attr:`plugins` list.



   .. py:method:: enable(name: str) -> bool

      Enable the plugin *name* and activate it if not already running.

      :return: ``True`` on success, ``False`` if the plugin was not found or
          could not be loaded.



   .. py:method:: disable(name: str) -> bool

      Disable the plugin *name* and destroy its active companion.

      :return: ``True`` on success, ``False`` if the plugin was not found.



   .. py:method:: is_enabled(name: str) -> bool

      Return whether the plugin *name* is currently enabled.



   .. py:method:: _activate(info: wolfhece._plugin_loader.PluginInfo) -> None

      Instantiate, wire up menu, and store the companion.



   .. py:method:: _find(name: str) -> wolfhece._plugin_loader.PluginInfo | None


   .. py:method:: _get_config()

      Return the viewer's WolfConfiguration, or ``None`` if unavailable.



   .. py:method:: _configured_directory() -> pathlib.Path | None

      Read the plugins directory from the viewer config.



   .. py:method:: _disabled_names() -> list[str]


   .. py:method:: _save_state() -> None


.. py:class:: PluginManagerCompanion(viewer: wolfhece.PyDraw.WolfMapViewer)

   Bases: :py:obj:`wolfhece._menu_companion_abc.AbstractCompanion`

   .. autoapi-inheritance-diagram:: wolfhece._companion_plugin_manager.PluginManagerCompanion
      :parts: 1
      :private-bases:


   Companion that manages external companion plugins.

   Adds a *Plugins* top-level menu to the viewer with items to discover,
   reload, and toggle individual plugins.

   Typical integration in a viewer subclass or startup script::

       from wolfhece._companion_plugin_manager import PluginManagerCompanion

       mgr = PluginManagerCompanion(viewer)
       mgr.menu_build()   # installs the "Plugins" menu
       mgr.discover()     # scans directory and activates enabled plugins


   .. py:attribute:: plugin_manager


   .. py:method:: start() -> None

      No-op — the manager operates through the menu, not interactively.



   .. py:method:: menu_build() -> None

      Build (or rebuild) the top-level *Plugins* menu.



   .. py:method:: discover(directory: pathlib.Path | str | None = None) -> list[wolfhece._plugin_loader.PluginInfo]

      Scan *directory*, activate plugins, then refresh the menu.

      :param directory: Override the plugins directory.  ``None`` reads from
          the viewer configuration.
      :return: The refreshed list of :class:`~wolfhece._plugin_loader.PluginInfo`.



   .. py:method:: _menu_items() -> list


   .. py:method:: _make_toggle(name: str)

      Return a menu-event handler that toggles plugin *name*.



   .. py:method:: _on_discover(event) -> None


   .. py:method:: _on_choose_dir(event) -> None


   .. py:method:: _persist_directory(path: pathlib.Path) -> None


   .. py:method:: _rebuild_menu() -> None