manim 0.18.1__py3-none-any.whl → 0.19.0__py3-none-any.whl

manim/cli/default_group.py

@@ -6,68 +6,192 @@ In particular, this class is what allows ``manim`` to act as ``manim render``.
     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 ``cloup.Group`` instead
-    of ``click.Group``.
+    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 typing import TYPE_CHECKING, Any, Callable
 
 import cloup
 
+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)
-
-    def get_command(self, ctx, cmd_name):
-        if cmd_name not in self.commands:
+        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.
+
+        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
         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

@@ -10,13 +10,14 @@ 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,
@@ -34,15 +35,15 @@ CFG_DEFAULTS = {
 __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"]),
@@ -54,18 +55,21 @@ def select_resolution():
         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)
@@ -85,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",
@@ -94,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)
 
@@ -117,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:
@@ -145,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")
@@ -190,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
 
 

manim/cli/plugins/commands.py

@@ -10,8 +10,8 @@ from __future__ import annotations
 
 import cloup
 
-from ...constants import CONTEXT_SETTINGS, EPILOG
-from ...plugins.plugins_flags import list_plugins
+from manim.constants import CONTEXT_SETTINGS, EPILOG
+from manim.plugins.plugins_flags import list_plugins
 
 __all__ = ["plugins"]
 
@@ -29,6 +29,16 @@ __all__ = ["plugins"]
     is_flag=True,
     help="List available plugins.",
 )
-def plugins(list_available):
+def plugins(list_available: bool) -> None:
+    """Print a list of all available plugins when calling ``manim plugins -l``
+    or ``manim plugins --list``.
+
+    Parameters
+    ----------
+    list_available
+        If the ``-l`` or ``-list`` option is passed to ``manim plugins``, this
+        parameter will be set to ``True``, which will print a list of all
+        available plugins.
+    """
     if list_available:
         list_plugins()

manim/cli/render/commands.py

@@ -13,78 +13,83 @@ import json
 import sys
 import urllib.error
 import urllib.request
+from argparse import Namespace
 from pathlib import Path
-from typing import cast
+from typing import Any, cast
 
 import cloup
 
-from ... import __version__, config, console, error_console, logger
-from ..._config import tempconfig
-from ...constants import EPILOG, RendererType
-from ...utils.module_ops import scene_classes_from_file
-from .ease_of_access_options import ease_of_access_options
-from .global_options import global_options
-from .output_options import output_options
-from .render_options import render_options
+from manim import __version__
+from manim._config import (
+    config,
+    console,
+    error_console,
+    logger,
+    tempconfig,
+)
+from manim.cli.render.ease_of_access_options import ease_of_access_options
+from manim.cli.render.global_options import global_options
+from manim.cli.render.output_options import output_options
+from manim.cli.render.render_options import render_options
+from manim.constants import EPILOG, RendererType
+from manim.utils.module_ops import scene_classes_from_file
 
 __all__ = ["render"]
 
 
+class ClickArgs(Namespace):
+    def __init__(self, args: dict[str, Any]) -> None:
+        for name in args:
+            setattr(self, name, args[name])
+
+    def _get_kwargs(self) -> list[tuple[str, Any]]:
+        return list(self.__dict__.items())
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, ClickArgs):
+            return NotImplemented
+        return vars(self) == vars(other)
+
+    def __contains__(self, key: str) -> bool:
+        return key in self.__dict__
+
+    def __repr__(self) -> str:
+        return str(self.__dict__)
+
+
 @cloup.command(
     context_settings=None,
     no_args_is_help=True,
     epilog=EPILOG,
 )
-@cloup.argument("file", type=Path, required=True)
+@cloup.argument("file", type=cloup.Path(path_type=Path), required=True)
 @cloup.argument("scene_names", required=False, nargs=-1)
 @global_options
 @output_options
-@render_options  # type: ignore
+@render_options
 @ease_of_access_options
-def render(
-    **args,
-):
+def render(**kwargs: Any) -> ClickArgs | dict[str, Any]:
     """Render SCENE(S) from the input FILE.
 
     FILE is the file path of the script or a config file.
 
     SCENES is an optional list of scenes in the file.
     """
-
-    if args["save_as_gif"]:
+    if kwargs["save_as_gif"]:
         logger.warning("--save_as_gif is deprecated, please use --format=gif instead!")
-        args["format"] = "gif"
+        kwargs["format"] = "gif"
 
-    if args["save_pngs"]:
+    if kwargs["save_pngs"]:
         logger.warning("--save_pngs is deprecated, please use --format=png instead!")
-        args["format"] = "png"
+        kwargs["format"] = "png"
 
-    if args["show_in_file_browser"]:
+    if kwargs["show_in_file_browser"]:
         logger.warning(
             "The short form of show_in_file_browser is deprecated and will be moved to support --format.",
         )
 
-    class ClickArgs:
-        def __init__(self, args):
-            for name in args:
-                setattr(self, name, args[name])
-
-        def _get_kwargs(self):
-            return list(self.__dict__.items())
-
-        def __eq__(self, other):
-            if not isinstance(other, ClickArgs):
-                return NotImplemented
-            return vars(self) == vars(other)
-
-        def __contains__(self, key):
-            return key in self.__dict__
-
-        def __repr__(self):
-            return str(self.__dict__)
-
-    click_args = ClickArgs(args)
-    if args["jupyter"]:
+    click_args = ClickArgs(kwargs)
+    if kwargs["jupyter"]:
         return click_args
 
     config.digest_args(click_args)
@@ -153,4 +158,4 @@ def render(
                     "You should consider upgrading via [yellow]pip install -U manim[/yellow]",
                 )
 
-    return args
+    return kwargs

manim/cli/render/global_options.py

@@ -1,22 +1,56 @@
 from __future__ import annotations
 
+import logging
 import re
+import sys
+from typing import TYPE_CHECKING
 
 from cloup import Choice, option, option_group
 
-from ... import logger
+if TYPE_CHECKING:
+    from click import Context, Option
 
 __all__ = ["global_options"]
 
+logger = logging.getLogger("manim")
 
-def validate_gui_location(ctx, param, value):
-    if value:
-        try:
-            x_offset, y_offset = map(int, re.split(r"[;,\-]", value))
-            return (x_offset, y_offset)
-        except Exception:
-            logger.error("GUI location option is invalid.")
-            exit()
+
+def validate_gui_location(
+    ctx: Context, param: Option, value: str | None
+) -> tuple[int, int] | None:
+    """If the ``value`` string is given, extract from it the GUI location,
+    which should be in any of these formats: 'x;y', 'x,y' or 'x-y'.
+
+    Parameters
+    ----------
+    ctx
+        The Click context.
+    param
+        A Click option.
+    value
+        The optional string which will be parsed.
+
+    Returns
+    -------
+    tuple[int, int] | None
+        If ``value`` is ``None``, the return value is ``None``. Otherwise, it's
+        the ``(x, y)`` location for the GUI.
+
+    Raises
+    ------
+    ValueError
+        If ``value`` has an invalid format.
+    """
+    if value is None:
+        return None
+
+    try:
+        x_offset, y_offset = map(int, re.split(r"[;,\-]", value))
+    except Exception:
+        logger.error("GUI location option is invalid.")
+        sys.exit()
+
+    return (x_offset, y_offset)
 
 
 global_options = option_group(