cellmap_flow.plugins
====================

.. py:module:: cellmap_flow.plugins

.. autoapi-nested-parse::

   Plugin manager for cellmap_flow.

   Handles registration, loading, and management of user plugins
   (ModelConfig, InputNormalizer, PostProcessor subclasses).

   Plugins are stored in ~/.cellmap_flow/plugins/. ``load_plugins`` runs them,
   so that their subclasses appear in __subclasses__() calls; the commands,
   the dashboard and the finetune job call it when they start, and importing
   cellmap_flow does not. A script that uses a plugin's classes calls it.

   ``analyze_script`` is the safety check a plugin passes to be registered;
   a script model's script passes it too, each time it is loaded
   (``models.configs.script.load_safe_config``).



Attributes
----------

.. autoapisummary::

   cellmap_flow.plugins.logger
   cellmap_flow.plugins.PLUGINS_DIR
   cellmap_flow.plugins.DISALLOWED_IMPORTS
   cellmap_flow.plugins.DISALLOWED_FUNCTIONS


Functions
---------

.. autoapisummary::

   cellmap_flow.plugins.analyze_script
   cellmap_flow.plugins.get_plugins_dir
   cellmap_flow.plugins.register_plugin
   cellmap_flow.plugins.unregister_plugin
   cellmap_flow.plugins.list_plugins
   cellmap_flow.plugins.load_plugins


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

.. py:data:: logger

.. py:data:: PLUGINS_DIR

.. py:data:: DISALLOWED_IMPORTS

.. py:data:: DISALLOWED_FUNCTIONS

.. py:function:: analyze_script(filepath)

   Analyzes the script at `filepath` using `ast` for potentially unsafe imports and function calls.
   Returns a boolean indicating whether the script is safe and a list of detected issues.


.. py:function:: get_plugins_dir() -> pathlib.Path

   Return the plugins directory, creating it if necessary.


.. py:function:: register_plugin(filepath: str, force: bool = False) -> pathlib.Path

   Register a plugin by copying a Python file to ~/.cellmap_flow/plugins/.

   :param filepath: Path to the Python file to register.
   :param force: Overwrite existing plugin with the same name.

   :returns: Path to the installed plugin file.

   :raises FileNotFoundError: If the source file does not exist.
   :raises FileExistsError: If a plugin with the same name already exists and force is False.
   :raises ValueError: If the file is not a .py file or fails safety analysis.


.. py:function:: unregister_plugin(name: str) -> None

   Remove a registered plugin by filename.

   :param name: Filename of the plugin (e.g. 'my_normalizer.py').
                The .py extension is added automatically if missing.


.. py:function:: list_plugins() -> List[pathlib.Path]

   Return a sorted list of all registered plugin file paths.

   Does not create the plugins directory: this runs on every package import,
   including inside each LSF job, and only registering a plugin needs it.


.. py:function:: load_plugins() -> int

   Load all registered plugins from ~/.cellmap_flow/plugins/.

   Each plugin file is executed so that any subclasses defined in it
   (ModelConfig, InputNormalizer, PostProcessor) become available
   through __subclasses__().

   Safe to call multiple times — plugins are only loaded once.

   :returns: Number of plugins successfully loaded.