manim 0.18.0.post0__py3-none-any.whl → 0.19.0__py3-none-any.whl

manim/cli/default_group.py

@@ -1,65 +1,197 @@
-"""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 typing import TYPE_CHECKING, Any, Callable
+
 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,
@@ -30,16 +32,18 @@ CFG_DEFAULTS = {
     "resolution": (854, 480),
 }
 
+__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
 
 

manim/cli/plugins/commands.py

@@ -5,12 +5,15 @@ plugin``. Here you can specify options, subcommands, and subgroups for the plugi
 group.
 
 """
+
 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"]
 
 
 @cloup.command(
@@ -26,6 +29,16 @@ from ...plugins.plugins_flags import list_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

@@ -5,24 +5,56 @@ Manim's render subcommand is accessed in the command-line interface via
 can specify options, and arguments for the render command.
 
 """
+
 from __future__ import annotations
 
+import http.client
 import json
 import sys
+import urllib.error
+import urllib.request
+from argparse import Namespace
 from pathlib import Path
+from typing import Any, cast
 
-import click
 import cloup
-import requests
 
-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(
@@ -30,56 +62,34 @@ from .render_options import render_options
     no_args_is_help=True,
     epilog=EPILOG,
 )
-@click.argument("file", type=Path, required=True)
-@click.argument("scene_names", required=False, nargs=-1)
+@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)
@@ -120,13 +130,26 @@ def render(
     if config.notify_outdated_version:
         manim_info_url = "https://pypi.org/pypi/manim/json"
         warn_prompt = "Cannot check if latest release of manim is installed"
-        req_info = {}
 
         try:
-            req_info = requests.get(manim_info_url, timeout=10)
-            req_info.raise_for_status()
-
-            stable = req_info.json()["info"]["version"]
+            with urllib.request.urlopen(
+                urllib.request.Request(manim_info_url),
+                timeout=10,
+            ) as response:
+                response = cast(http.client.HTTPResponse, response)
+                json_data = json.loads(response.read())
+        except urllib.error.HTTPError:
+            logger.debug("HTTP Error: %s", warn_prompt)
+        except urllib.error.URLError:
+            logger.debug("URL Error: %s", warn_prompt)
+        except json.JSONDecodeError:
+            logger.debug(
+                "Error while decoding JSON from %r: %s", manim_info_url, warn_prompt
+            )
+        except Exception:
+            logger.debug("Something went wrong: %s", warn_prompt)
+        else:
+            stable = json_data["info"]["version"]
             if stable != __version__:
                 console.print(
                     f"You are using manim version [red]v{__version__}[/red], but version [green]v{stable}[/green] is available.",
@@ -134,16 +157,5 @@ def render(
                 console.print(
                     "You should consider upgrading via [yellow]pip install -U manim[/yellow]",
                 )
-        except requests.exceptions.HTTPError:
-            logger.debug(f"HTTP Error: {warn_prompt}")
-        except requests.exceptions.ConnectionError:
-            logger.debug(f"Connection Error: {warn_prompt}")
-        except requests.exceptions.Timeout:
-            logger.debug(f"Timed Out: {warn_prompt}")
-        except json.JSONDecodeError:
-            logger.debug(warn_prompt)
-            logger.debug(f"Error decoding JSON from {manim_info_url}")
-        except Exception:
-            logger.debug(f"Something went wrong: {warn_prompt}")
 
-    return args
+    return kwargs

manim/cli/render/ease_of_access_options.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
-import click
-from cloup import option, option_group
+from cloup import Choice, option, option_group
+
+__all__ = ["ease_of_access_options"]
 
 ease_of_access_options = option_group(
     "Ease of access options",
@@ -9,7 +10,7 @@ ease_of_access_options = option_group(
         "--progress_bar",
         default=None,
         show_default=False,
-        type=click.Choice(
+        type=Choice(
             ["display", "leave", "none"],
             case_sensitive=False,
         ),