manim 0.17.0__py3-none-any.whl → 0.19.1__py3-none-any.whl

manim/cli/checkhealth/checks.py

@@ -0,0 +1,192 @@
+"""Auxiliary module for the checkhealth subcommand, contains
+the actual check implementations.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from collections.abc import Callable
+from typing import Protocol, cast
+
+__all__ = ["HEALTH_CHECKS"]
+
+
+class HealthCheckFunction(Protocol):
+    description: str
+    recommendation: str
+    skip_on_failed: list[str]
+    post_fail_fix_hook: Callable[..., object] | None
+    __name__: str
+
+    def __call__(self) -> bool: ...
+
+
+HEALTH_CHECKS: list[HealthCheckFunction] = []
+
+
+def healthcheck(
+    description: str,
+    recommendation: str,
+    skip_on_failed: list[HealthCheckFunction | str] | None = None,
+    post_fail_fix_hook: Callable[..., object] | None = None,
+) -> Callable[[Callable[[], bool]], HealthCheckFunction]:
+    """Decorator used for declaring health checks.
+
+    This decorator attaches some data to a function, which is then added to a
+    a list containing all checks.
+
+    Parameters
+    ----------
+    description
+        A brief description of this check, displayed when the ``checkhealth``
+        subcommand is run.
+    recommendation
+        Help text which is displayed in case the check fails.
+    skip_on_failed
+        A list of check functions which, if they fail, cause the current check
+        to be skipped.
+    post_fail_fix_hook
+        A function that is meant to (interactively) help to fix the detected
+        problem, if possible. This is only called upon explicit confirmation of
+        the user.
+
+    Returns
+    -------
+    Callable[Callable[[], bool], :class:`HealthCheckFunction`]
+        A decorator which converts a function into a health check function, as
+        required by the ``checkhealth`` subcommand.
+    """
+    new_skip_on_failed: list[str]
+    if skip_on_failed is None:
+        new_skip_on_failed = []
+    else:
+        new_skip_on_failed = [
+            skip.__name__ if callable(skip) else skip for skip in skip_on_failed
+        ]
+
+    def wrapper(func: Callable[[], bool]) -> HealthCheckFunction:
+        health_func = cast(HealthCheckFunction, func)
+        health_func.description = description
+        health_func.recommendation = recommendation
+        health_func.skip_on_failed = new_skip_on_failed
+        health_func.post_fail_fix_hook = post_fail_fix_hook
+        HEALTH_CHECKS.append(health_func)
+        return health_func
+
+    return wrapper
+
+
+@healthcheck(
+    description="Checking whether manim is on your PATH",
+    recommendation=(
+        "The command <manim> is currently not on your system's PATH.\n\n"
+        "You can work around this by calling the manim module directly "
+        "via <python -m manim> instead of just <manim>.\n\n"
+        "To fix the PATH issue properly: "
+        "Usually, the Python package installer pip issues a warning "
+        "during the installation which contains more information. "
+        "Consider reinstalling manim via <pip uninstall manim> "
+        "followed by <pip install manim> to see the warning again, "
+        "then consult the internet on how to modify your system's "
+        "PATH variable."
+    ),
+)
+def is_manim_on_path() -> bool:
+    """Check whether ``manim`` is in ``PATH``.
+
+    Returns
+    -------
+    :class:`bool`
+        Whether ``manim`` is in ``PATH`` or not.
+    """
+    path_to_manim = shutil.which("manim")
+    return path_to_manim is not None
+
+
+@healthcheck(
+    description="Checking whether the executable belongs to manim",
+    recommendation=(
+        "The command <manim> does not belong to your installed version "
+        "of this library, it likely belongs to manimgl / manimlib.\n\n"
+        "Run manim via <python -m manim> or via <manimce>, or uninstall "
+        "and reinstall manim via <pip install --upgrade "
+        "--force-reinstall manim> to fix this."
+    ),
+    skip_on_failed=[is_manim_on_path],
+)
+def is_manim_executable_associated_to_this_library() -> bool:
+    """Check whether the ``manim`` executable in ``PATH`` is associated to this
+    library. To verify this, the executable should look like this:
+
+    .. code-block:: python
+
+        #!<MANIM_PATH>/.../python
+        import sys
+        from manim.__main__ import main
+
+        if __name__ == "__main__":
+            sys.exit(main())
+
+
+    Returns
+    -------
+    :class:`bool`
+        Whether the ``manim`` executable in ``PATH`` is associated to this
+        library or not.
+    """
+    path_to_manim = shutil.which("manim")
+    assert path_to_manim is not None
+    with open(path_to_manim, "rb") as manim_binary:
+        manim_exec = manim_binary.read()
+
+    # first condition below corresponds to the executable being
+    # some sort of python script. second condition happens when
+    # the executable is actually a Windows batch file.
+    return b"manim.__main__" in manim_exec or b'"%~dp0\\manim"' in manim_exec
+
+
+@healthcheck(
+    description="Checking whether latex is available",
+    recommendation=(
+        "Manim cannot find <latex> on your system's PATH. "
+        "You will not be able to use Tex and MathTex mobjects "
+        "in your scenes.\n\n"
+        "Consult our installation instructions "
+        "at https://docs.manim.community/en/stable/installation.html "
+        "or search the web for instructions on how to install a "
+        "LaTeX distribution on your operating system."
+    ),
+)
+def is_latex_available() -> bool:
+    """Check whether ``latex`` is in ``PATH`` and can be executed.
+
+    Returns
+    -------
+    :class:`bool`
+        Whether ``latex`` is in ``PATH`` and can be executed or not.
+    """
+    path_to_latex = shutil.which("latex")
+    return path_to_latex is not None and os.access(path_to_latex, os.X_OK)
+
+
+@healthcheck(
+    description="Checking whether dvisvgm is available",
+    recommendation=(
+        "Manim could find <latex>, but not <dvisvgm> on your system's "
+        "PATH. Make sure your installed LaTeX distribution comes with "
+        "dvisvgm and consider installing a larger distribution if it "
+        "does not."
+    ),
+    skip_on_failed=[is_latex_available],
+)
+def is_dvisvgm_available() -> bool:
+    """Check whether ``dvisvgm`` is in ``PATH`` and can be executed.
+
+    Returns
+    -------
+    :class:`bool`
+        Whether ``dvisvgm`` is in ``PATH`` and can be executed or not.
+    """
+    path_to_dvisvgm = shutil.which("dvisvgm")
+    return path_to_dvisvgm is not None and os.access(path_to_dvisvgm, os.X_OK)

manim/cli/checkhealth/commands.py

@@ -0,0 +1,90 @@
+"""A CLI utility helping to diagnose problems with
+your Manim installation.
+
+"""
+
+from __future__ import annotations
+
+import sys
+import timeit
+
+import click
+import cloup
+
+from manim.cli.checkhealth.checks import HEALTH_CHECKS, HealthCheckFunction
+
+__all__ = ["checkhealth"]
+
+
+@cloup.command(
+    context_settings=None,
+)
+def checkhealth() -> None:
+    """This subcommand checks whether Manim is installed correctly
+    and has access to its required (and optional) system dependencies.
+    """
+    click.echo(f"Python executable: {sys.executable}\n")
+    click.echo("Checking whether your installation of Manim Community is healthy...")
+    failed_checks: list[HealthCheckFunction] = []
+
+    for check in HEALTH_CHECKS:
+        click.echo(f"- {check.description} ... ", nl=False)
+        if any(
+            failed_check.__name__ in check.skip_on_failed
+            for failed_check in failed_checks
+        ):
+            click.secho("SKIPPED", fg="blue")
+            continue
+        check_result = check()
+        if check_result:
+            click.secho("PASSED", fg="green")
+        else:
+            click.secho("FAILED", fg="red")
+            failed_checks.append(check)
+
+    click.echo()
+
+    if failed_checks:
+        click.echo(
+            "There are problems with your installation, "
+            "here are some recommendations to fix them:"
+        )
+        for ind, failed_check in enumerate(failed_checks):
+            click.echo(failed_check.recommendation)
+            if ind + 1 < len(failed_checks):
+                click.confirm("Continue with next recommendation?")
+
+    else:  # no problems detected!
+        click.echo("No problems detected, your installation seems healthy!")
+        render_test_scene = click.confirm(
+            "Would you like to render and preview a test scene?"
+        )
+        if render_test_scene:
+            import manim as mn
+
+            class CheckHealthDemo(mn.Scene):
+                def _inner_construct(self) -> None:
+                    banner = mn.ManimBanner().shift(mn.UP * 0.5)
+                    self.play(banner.create())
+                    self.wait(0.5)
+                    self.play(banner.expand())
+                    self.wait(0.5)
+                    text_left = mn.Text("All systems operational!")
+                    formula_right = mn.MathTex(r"\oint_{\gamma} f(z)~dz = 0")
+                    text_tex_group = mn.VGroup(text_left, formula_right)
+                    text_tex_group.arrange(mn.RIGHT, buff=1).next_to(banner, mn.DOWN)
+                    self.play(mn.Write(text_tex_group))
+                    self.wait(0.5)
+                    self.play(
+                        mn.FadeOut(banner, shift=mn.UP),
+                        mn.FadeOut(text_tex_group, shift=mn.DOWN),
+                    )
+
+                def construct(self) -> None:
+                    self.execution_time = timeit.timeit(self._inner_construct, number=1)
+
+            with mn.tempconfig({"preview": True, "disable_caching": True}):
+                scene = CheckHealthDemo()
+                scene.render()
+
+                click.echo(f"Scene rendered in {scene.execution_time:.2f} seconds.")

manim/cli/default_group.py

@@ -1,65 +1,198 @@
-"""DefaultGroup allows a subcommand to act as the main command
+"""``DefaultGroup`` allows a subcommand to act as the main command.
 
 In particular, this class is what allows ``manim`` to act as ``manim render``.
+
+.. note::
+    This is a vendored version of https://github.com/click-contrib/click-default-group/
+    under the BSD 3-Clause "New" or "Revised" License.
+
+    This library isn't used as a dependency, as we need to inherit from
+    :class:`cloup.Group` instead of :class:`click.Group`.
 """
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
 import cloup
 
-from .. import logger
+from manim.utils.deprecation import deprecated
 
 __all__ = ["DefaultGroup"]
 
+if TYPE_CHECKING:
+    from click import Command, Context
+
 
 class DefaultGroup(cloup.Group):
-    """Invokes a subcommand marked with ``default=True`` if any subcommand not
+    """Invokes a subcommand marked with ``default=True`` if any subcommand is not
     chosen.
+
+    Parameters
+    ----------
+    *args
+        Positional arguments to forward to :class:`cloup.Group`.
+    **kwargs
+        Keyword arguments to forward to :class:`cloup.Group`. The keyword
+        ``ignore_unknown_options`` must be set to ``False``.
+
+    Attributes
+    ----------
+    default_cmd_name : str | None
+        The name of the default command, if specified through the ``default``
+        keyword argument. Otherwise, this is set to ``None``.
+    default_if_no_args : bool
+        Whether to include or not the default command, if no command arguments
+        are supplied. This can be specified through the ``default_if_no_args``
+        keyword argument. Default is ``False``.
     """
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args: Any, **kwargs: Any):
         # To resolve as the default command.
         if not kwargs.get("ignore_unknown_options", True):
             raise ValueError("Default group accepts unknown options")
         self.ignore_unknown_options = True
-        self.default_cmd_name = kwargs.pop("default", None)
-        self.default_if_no_args = kwargs.pop("default_if_no_args", False)
+        self.default_cmd_name: str | None = kwargs.pop("default", None)
+        self.default_if_no_args: bool = kwargs.pop("default_if_no_args", False)
         super().__init__(*args, **kwargs)
 
-    def set_default_command(self, command):
-        """Sets a command function as the default command."""
+    def set_default_command(self, command: Command) -> None:
+        """Sets a command function as the default command.
+
+        Parameters
+        ----------
+        command
+            The command to set as default.
+        """
         cmd_name = command.name
         self.add_command(command)
         self.default_cmd_name = cmd_name
 
-    def parse_args(self, ctx, args):
-        if not args and self.default_if_no_args:
+    def parse_args(self, ctx: Context, args: list[str]) -> list[str]:
+        """Parses the list of ``args`` by forwarding it to
+        :meth:`cloup.Group.parse_args`. Before doing so, if
+        :attr:`default_if_no_args` is set to ``True`` and ``args`` is empty,
+        this function appends to it the name of the default command specified
+        by :attr:`default_cmd_name`.
+
+        Parameters
+        ----------
+        ctx
+            The Click context.
+        args
+            A list of arguments. If it's empty and :attr:`default_if_no_args`
+            is ``True``, append the name of the default command to it.
+
+        Returns
+        -------
+        list[str]
+            The parsed arguments.
+        """
+        if not args and self.default_if_no_args and self.default_cmd_name:
             args.insert(0, self.default_cmd_name)
-        return super().parse_args(ctx, args)
+        parsed_args: list[str] = super().parse_args(ctx, args)
+        return parsed_args
+
+    def get_command(self, ctx: Context, cmd_name: str) -> Command | None:
+        """Get a command function by its name, by forwarding the arguments to
+        :meth:`cloup.Group.get_command`. If ``cmd_name`` does not match any of
+        the command names in :attr:`commands`, attempt to get the default command
+        instead.
+
+        Parameters
+        ----------
+        ctx
+            The Click context.
+        cmd_name
+            The name of the command to get.
 
-    def get_command(self, ctx, cmd_name):
-        if cmd_name not in self.commands:
+        Returns
+        -------
+        :class:`click.Command` | None
+            The command, if found. Otherwise, ``None``.
+        """
+        if cmd_name not in self.commands and self.default_cmd_name:
             # No command name matched.
-            ctx.arg0 = cmd_name
+            ctx.meta["arg0"] = cmd_name
             cmd_name = self.default_cmd_name
         return super().get_command(ctx, cmd_name)
 
-    def resolve_command(self, ctx, args):
-        base = super()
-        cmd_name, cmd, args = base.resolve_command(ctx, args)
-        if hasattr(ctx, "arg0"):
-            args.insert(0, ctx.arg0)
-            cmd_name = cmd.name
+    def resolve_command(
+        self, ctx: Context, args: list[str]
+    ) -> tuple[str | None, Command | None, list[str]]:
+        """Given a list of ``args`` given by a CLI, find a command which
+        matches the first element, and return its name (``cmd_name``), the
+        command function itself (``cmd``) and the rest of the arguments which
+        shall be passed to the function (``cmd_args``). If not found, return
+        ``None``, ``None`` and the rest of the arguments.
+
+        After resolving the command, if the Click context given by ``ctx``
+        contains an ``arg0`` attribute in its :attr:`click.Context.meta`
+        dictionary, insert it as the first element of the returned
+        ``cmd_args``.
+
+        Parameters
+        ----------
+        ctx
+            The Click context.
+        cmd_name
+            The name of the command to get.
+
+        Returns
+        -------
+        cmd_name : str | None
+            The command name, if found. Otherwise, ``None``.
+        cmd : :class:`click.Command` | None
+            The command, if found. Otherwise, ``None``.
+        cmd_args : list[str]
+            The rest of the arguments to be passed to ``cmd``.
+        """
+        cmd_name, cmd, args = super().resolve_command(ctx, args)
+        if "arg0" in ctx.meta:
+            args.insert(0, ctx.meta["arg0"])
+            if cmd is not None:
+                cmd_name = cmd.name
         return cmd_name, cmd, args
 
-    def command(self, *args, **kwargs):
+    @deprecated
+    def command(
+        self, *args: Any, **kwargs: Any
+    ) -> Callable[[Callable[..., object]], Command]:
+        """Return a decorator which converts any function into the default
+        subcommand for this :class:`DefaultGroup`.
+
+        .. warning::
+            This method is deprecated. Use the ``default`` parameter of
+            :class:`DefaultGroup` or :meth:`set_default_command` instead.
+
+        Parameters
+        ----------
+        *args
+            Positional arguments to pass to :meth:`cloup.Group.command`.
+        **kwargs
+            Keyword arguments to pass to :meth:`cloup.Group.command`.
+
+        Returns
+        -------
+        Callable[[Callable[..., object]], click.Command]
+            A decorator which transforms its input into this
+            :class:`DefaultGroup`'s default subcommand.
+        """
         default = kwargs.pop("default", False)
-        decorator = super().command(*args, **kwargs)
+        decorator: Callable[[Callable[..., object]], Command] = super().command(
+            *args, **kwargs
+        )
         if not default:
             return decorator
-        logger.log(
-            "Use default param of DefaultGroup or " "set_default_command() instead",
+        warnings.warn(
+            "Use default param of DefaultGroup or set_default_command() instead",
             DeprecationWarning,
+            stacklevel=1,
         )
 
-        def _decorator(f):
+        def _decorator(f: Callable) -> Command:
             cmd = decorator(f)
             self.set_default_command(cmd)
             return cmd

manim/cli/init/commands.py

@@ -5,17 +5,19 @@ init``. Here you can specify options, subcommands, and subgroups for the init
 group.
 
 """
+
 from __future__ import annotations
 
 import configparser
 from pathlib import Path
+from typing import Any
 
 import click
 import cloup
 
-from ... import console
-from ...constants import CONTEXT_SETTINGS, EPILOG, QUALITIES
-from ...utils.file_ops import (
+from manim._config import console
+from manim.constants import CONTEXT_SETTINGS, EPILOG, QUALITIES
+from manim.utils.file_ops import (
     add_import_statement,
     copy_template_files,
     get_template_names,
@@ -27,19 +29,21 @@ CFG_DEFAULTS = {
     "background_color": "BLACK",
     "background_opacity": 1,
     "scene_names": "Default",
-    "resolution": (854, 480),
+    "resolution": (1920, 1080),
 }
 
+__all__ = ["select_resolution", "update_cfg", "project", "scene"]
+
 
-def select_resolution():
+def select_resolution() -> tuple[int, int]:
     """Prompts input of type click.Choice from user. Presents options from QUALITIES constant.
 
     Returns
     -------
-        :class:`tuple`
-            Tuple containing height and width.
+    tuple[int, int]
+        Tuple containing height and width.
     """
-    resolution_options = []
+    resolution_options: list[tuple[int, int]] = []
     for quality in QUALITIES.items():
         resolution_options.append(
             (quality[1]["pixel_height"], quality[1]["pixel_width"]),
@@ -47,22 +51,25 @@ def select_resolution():
     resolution_options.pop()
     choice = click.prompt(
         "\nSelect resolution:\n",
-        type=click.Choice([f"{i[0]}p" for i in resolution_options]),
+        type=cloup.Choice([f"{i[0]}p" for i in resolution_options]),
         show_default=False,
         default="480p",
     )
-    return [res for res in resolution_options if f"{res[0]}p" == choice][0]
+    matches = [res for res in resolution_options if f"{res[0]}p" == choice]
+    return matches[0]
 
 
-def update_cfg(cfg_dict: dict, project_cfg_path: Path):
-    """Updates the manim.cfg file after reading it from the project_cfg_path.
+def update_cfg(cfg_dict: dict[str, Any], project_cfg_path: Path) -> None:
+    """Update the ``manim.cfg`` file after reading it from the specified
+    ``project_cfg_path``.
 
     Parameters
     ----------
     cfg_dict
-        values used to update manim.cfg found project_cfg_path.
+        Values used to update ``manim.cfg`` which is found in
+        ``project_cfg_path``.
     project_cfg_path
-        Path of manim.cfg file.
+        Path of the ``manim.cfg`` file.
     """
     config = configparser.ConfigParser()
     config.read(project_cfg_path)
@@ -82,7 +89,7 @@ def update_cfg(cfg_dict: dict, project_cfg_path: Path):
     context_settings=CONTEXT_SETTINGS,
     epilog=EPILOG,
 )
-@cloup.argument("project_name", type=Path, required=False)
+@cloup.argument("project_name", type=cloup.Path(path_type=Path), required=False)
 @cloup.option(
     "-d",
     "--default",
@@ -91,13 +98,14 @@ def update_cfg(cfg_dict: dict, project_cfg_path: Path):
     help="Default settings for project creation.",
     nargs=1,
 )
-def project(default_settings, **args):
+def project(default_settings: bool, **kwargs: Any) -> None:
     """Creates a new project.
 
     PROJECT_NAME is the name of the folder in which the new project will be initialized.
     """
-    if args["project_name"]:
-        project_name = args["project_name"]
+    project_name: Path
+    if kwargs["project_name"]:
+        project_name = kwargs["project_name"]
     else:
         project_name = click.prompt("Project Name", type=Path)
 
@@ -114,7 +122,7 @@ def project(default_settings, **args):
         )
     else:
         project_name.mkdir()
-        new_cfg = {}
+        new_cfg: dict[str, Any] = {}
         new_cfg_path = Path.resolve(project_name / "manim.cfg")
 
         if not default_settings:
@@ -142,23 +150,23 @@ def project(default_settings, **args):
 )
 @cloup.argument("scene_name", type=str, required=True)
 @cloup.argument("file_name", type=str, required=False)
-def scene(**args):
+def scene(**kwargs: Any) -> None:
     """Inserts a SCENE to an existing FILE or creates a new FILE.
 
     SCENE is the name of the scene that will be inserted.
 
     FILE is the name of file in which the SCENE will be inserted.
     """
-    template_name = click.prompt(
+    template_name: str = click.prompt(
         "template",
         type=click.Choice(get_template_names(), False),
         default="Default",
     )
     scene = (get_template_path() / f"{template_name}.mtp").resolve().read_text()
-    scene = scene.replace(template_name + "Template", args["scene_name"], 1)
+    scene = scene.replace(template_name + "Template", kwargs["scene_name"], 1)
 
-    if args["file_name"]:
-        file_name = Path(args["file_name"])
+    if kwargs["file_name"]:
+        file_name = Path(kwargs["file_name"])
 
         if file_name.suffix != ".py":
             file_name = file_name.with_suffix(file_name.suffix + ".py")
@@ -187,7 +195,7 @@ def scene(**args):
     help="Create a new project or insert a new scene.",
 )
 @cloup.pass_context
-def init(ctx):
+def init(ctx: cloup.Context) -> None:
     pass