Automatically Import Plugins (#967)

* Automatically import Plugins
Specify plugins using CLI and config file

Signed-off-by: Naveen M K <naveen@syrusdark.website>

* Fix Doc tests

* clean manim.cfg

* Add more explanatory docs

* add info about plugins site

* use property method

Co-authored-by: friedkeenan <friedkeenan@protonmail.com>

* use types module and f-strings

* Add tests

* lint

* remove --plugins
it seems it is not possible currently to implement that

* fix doc tests

* don't define unnecessary variables

* Apply suggestions from code review

Co-authored-by: Leo Torres <dleonardotn@gmail.com>

Co-authored-by: friedkeenan <friedkeenan@protonmail.com>
Co-authored-by: Leo Torres <dleonardotn@gmail.com>

Author: 3 people

docs/source/installation/plugins.rst

@@ -20,6 +20,10 @@ install, use, and create your own plugins.
     for the best practices on installing, using, and creating plugins; as
     well as new subcommands/flags for ``manim plugins``
 
+.. tip::
+
+    See https://plugins.manim.community/ for the list of plugins available.
+
 Installing Plugins
 ******************
 Plugins can be easily installed via the ``pip``
@@ -55,27 +59,37 @@ You can list plugins as such:
 
 Using Plugins in Projects
 *************************
-Plugins specified in ``plugins/__init__.py`` are imported automatically by
-manim's ``__init__.py``. As such, writing:
+For enabling a plugin ``manim.cfg`` or command line parameters should be used.
+
+.. important::
+
+    The plugins should be module name of the plugin and not PyPi name.
 
-.. code-block:: python
+Enabling plugins through ``manim.cfg`` 
 
-    from manim import *
+.. code-block:: ini
 
-in your projects will import any of the plugins imported in
-``plugins/__init__.py``.
+    [CLI]
+    plugins = manim_rubikscube
 
-By default, ``plugins/__init__.py`` is not provided; although, there are
-plans to support subcommands that would manage this file. It is especially
-useful to create this file for projects that involve usage of the same
-plugins. Alternatively, you may manually specify the plugins in your project
-scripts.
+For specifing multiple plugins, command separated values must be used.
 
-.. code-block:: python
+.. code-block:: ini
 
-    import manim_cool_plugin
-    # or
-    from manim_cool_plugin import feature_x, feature_y, ...
+    [CLI]
+    plugins = manim_rubikscube, manim_plugintemplate
+
+Enabling Plugins through CLI
+
+.. code-block:: bash
+
+    manim basic.py --plugins=manim_plugintemplate
+
+For multiple plugins
+
+.. code-block:: bash
+
+    manim basic.py --plugins=manim_rubikscube,manim_plugintemplate
 
 Creating Plugins
 ****************
@@ -101,4 +115,33 @@ specified in poetry as:
 .. code-block:: toml
 
     [tool.poetry.plugins."manim.plugins"]
-    "name" = "object_reference"
+    "name" = "object_reference"
+
+Here ``name`` is the name of the module of the plugin.
+
+Here ``object_reference`` can point to either a function in a module or a module
+itself. For example,
+
+.. code-block:: toml
+
+    [tool.poetry.plugins."manim.plugins"]
+    "manim_plugintemplate" = "manim_plugintemplate"
+
+Here a module is used as ``object_reference``, and when this plugin is enabled,
+Manim will look for ``__all__`` keyword defined in ``manim_plugintemplate`` and
+everything as a global variable one by one.
+
+If ``object_reference`` is a function, Manim calls the function and expects the
+function returns a list of modules or functions that needs to defined globally and
+it defined it.
+
+For example,
+
+.. code-block:: toml
+
+    [tool.poetry.plugins."manim.plugins"]
+    "manim_plugintemplate" = "manim_awesomeplugin.imports:setup_things"
+
+Here, Manim will call the function ``setup_things`` defined in
+``manim_awesomeplugin.imports`` and calls that. It returns a list of function or
+modules which will be imported globally.

docs/source/tutorials/configuration.rst

@@ -353,12 +353,12 @@ A list of all config options
    'frame_y_radius', 'from_animation_number', 'images_dir', 'input_file',
    'js_renderer_path', 'leave_progress_bars', 'left_side', 'log_dir', 'log_to_file',
    'max_files_cached', 'media_dir', 'movie_file_extension', 'output_file',
-   'partial_movie_dir', 'pixel_height', 'pixel_width', 'png_mode', 'preview',
-   'progress_bar', 'quality', 'right_side', 'save_as_gif', 'save_last_frame',
+   'partial_movie_dir', 'pixel_height', 'pixel_width', 'plugins', 'png_mode',
+   'preview', 'progress_bar', 'quality', 'right_side', 'save_as_gif', 'save_last_frame',
    'save_pngs', 'scene_names', 'show_in_file_browser', 'sound', 'tex_dir',
    'tex_template', 'tex_template_file', 'text_dir', 'top', 'transparent',
-   'upto_animation_number', 'use_js_renderer', 'verbosity', 'video_dir', 'write_all',
-   'write_to_movie']
+   'upto_animation_number', 'use_js_renderer', 'verbosity', 'video_dir',
+   'write_all', 'write_to_movie']
 
 
 A list of all CLI flags

manim/_config/default.cfg

@@ -112,6 +112,9 @@ disable_caching = False
 # --tex_template
 tex_template =
 
+# specify the plugins as comma seperated values
+# manim will load that plugin if it specified here.
+plugins = 
 
 # Overrides the default output folders, NOT the output file names.  Note that
 # if the custom_folders flag is present, the Tex and text files will not be put

manim/_config/utils.py

@@ -272,6 +272,7 @@ class MyScene(Scene):
         "partial_movie_dir",
         "pixel_height",
         "pixel_width",
+        "plugins",
         "png_mode",
         "preview",
         "progress_bar",
@@ -551,7 +552,8 @@ def digest_parser(self, parser: configparser.ConfigParser) -> "ManimConfig":
             # "frame_height",
         ]:
             setattr(self, key, parser["CLI"].getfloat(key))
-
+        # plugins
+        self.plugins = parser["CLI"].get("plugins", fallback="", raw=True).split(",")
         # the next two must be set AFTER digesting pixel_width and pixel_height
         self["frame_height"] = parser["CLI"].getfloat("frame_height", 8.0)
         width = parser["CLI"].getfloat("frame_width", None)
@@ -1304,6 +1306,15 @@ def tex_template_file(self, val: str) -> None:
             self._d["tex_template_file"] = val  # actually set the falsy value
             self._tex_template = TexTemplate()  # but don't use it
 
+    @property
+    def plugins(self):
+        """List of plugins to enable."""
+        return self._d["plugins"]
+
+    @plugins.setter
+    def plugins(self, value):
+        self._d["plugins"] = value
+
 
 class ManimFrame(Mapping):
     _OPTS: typing.Set[str] = {

manim/plugins/.gitignore

@@ -0,0 +1 @@
+from .import_plugins import *

manim/plugins/__init__.py

@@ -0,0 +1,42 @@
+import types
+from importlib import import_module
+
+import pkg_resources
+
+from .. import config, logger
+
+__all__ = []
+
+
+plugins_requested: list = config["plugins"]
+if "" in plugins_requested:
+    plugins_requested.remove("")
+for plugin in pkg_resources.iter_entry_points("manim.plugins"):
+    if plugin.name not in plugins_requested:
+        continue
+    loaded_plugin = plugin.load()
+    if isinstance(loaded_plugin, types.ModuleType):
+        # it is a module so it can't be called
+        # see if __all__ is defined
+        # if it is defined use that to load all the modules necessary
+        # essentially this would be similar to `from plugin import *``
+        # if not just import the module with the plugin name
+        if hasattr(loaded_plugin, "__all__"):
+            for thing in loaded_plugin.__all__:
+                exec(f"{thing}=loaded_plugin.{thing}")
+                __all__.append(thing)
+        else:
+            exec(f"{plugin.name}=loaded_plugin")
+            __all__.append(plugin.name)
+    elif isinstance(loaded_plugin, types.FunctionType):
+        # call the function first
+        # it will return a list of modules to add globally
+        # finally add it
+        lists = loaded_plugin()
+        for l in lists:
+            exec(f"{l.__name__}=l")
+            __all__.append(l.__name__)
+    plugins_requested.remove(plugin.name)
+else:
+    if plugins_requested != []:
+        logger.warning("Missing Plugins: %s", plugins_requested)