Merge branch 'main' into fix-syntaxwarning

.github/workflows/ci.yml

@@ -23,15 +23,15 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-22.04, macos-13, windows-latest]
-        python: ["3.9", "3.10", "3.11", "3.12"]
+        python: ["3.9", "3.10", "3.11", "3.12", "3.13"]
 
     steps:
       - name: Checkout the repository
         uses: actions/checkout@v4
 
       - name: Install Poetry
         run: |
-          pipx install "poetry==1.7.*"
+          pipx install "poetry==1.8.*"
           poetry config virtualenvs.prefer-active-python true
 
       - name: Setup Python ${{ matrix.python }}
@@ -142,10 +142,7 @@ jobs:
           Expand-Archive -LiteralPath "$($env:TMP)\TinyTex.zip" -DestinationPath "$($PWD)\ManimCache\LatexWindows"
           $env:Path = "$($PWD)\ManimCache\LatexWindows\TinyTeX\bin\windows;$($env:PATH)"
           tlmgr update --self
-          foreach ($c in $tinyTexPackages){
-            $c=$c.Trim()
-            tlmgr install $c
-          }
+          tlmgr install $tinyTexPackages
           $env:PATH=$OriPath
           echo "Completed Latex"
 
@@ -156,10 +153,9 @@ jobs:
           $env:Path = "$env:USERPROFILE\.poetry\bin;$($env:PATH)"
           echo "$env:Path" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
 
-      - name: Install manim
+      - name: Install dependencies and manim
         run: |
-          poetry config installer.modern-installation false
-          poetry install
+          poetry install --all-extras
 
       - name: Run tests
         run: |

.pre-commit-config.yaml

@@ -1,9 +1,9 @@
-default_stages: [commit, push]
+default_stages: [pre-commit, pre-push]
 fail_fast: false
 exclude: ^(manim/grpc/gen/|docs/i18n/)
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: check-ast
         name: Validate Python
@@ -13,7 +13,7 @@ repos:
       - id: check-toml
         name: Validate Poetry
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.2
+    rev: v0.8.0
     hooks:
       - id: ruff
         name: ruff lint
@@ -22,7 +22,7 @@ repos:
       - id: ruff-format
         types: [python]
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.11.2
+    rev: v1.13.0
     hooks:
       - id: mypy
         additional_dependencies:

docs/source/contributing/docs/types.rst

@@ -57,7 +57,8 @@ consider this slightly contrived function:
 
 .. code-block:: python
 
-   def shift_mobject(mob: Mobject, direction: Vector3D, scale_factor: float = 1) -> mob:
+   M = TypeVar("M", bound=Mobject)  # allow any mobject
+   def shift_mobject(mob: M, direction: Vector3D, scale_factor: float = 1) -> M:
        return mob.shift(direction * scale_factor)
 
 Here we see an important example of the difference. ``direction`` can not, and
@@ -129,6 +130,6 @@ There are several representations of images in Manim. The most common is
 the representation as a NumPy array of floats representing the pixels of an image.
 This is especially common when it comes to the OpenGL renderer.
 
-This is the use case of the :class:`~.typing.Image` type hint. Sometimes, Manim may use ``PIL.Image``,
-in which case one should use that type hint instead.
+This is the use case of the :class:`~.typing.PixelArray` type hint. Sometimes, Manim may use ``PIL.Image.Image``,
+which is not the same as :class:`~.typing.PixelArray`. In this case, use the ``PIL.Image.Image`` typehint.
 Of course, if a more specific type of image is needed, it can be annotated as such.

docs/source/examples.rst

@@ -90,7 +90,7 @@ Basic Concepts
                 [[i * 256 / n for i in range(0, n)] for _ in range(0, n)]
             )
             image = ImageMobject(imageArray).scale(2)
-            image.background_rectangle = SurroundingRectangle(image, GREEN)
+            image.background_rectangle = SurroundingRectangle(image, color=GREEN)
             self.add(image, image.background_rectangle)
 
 .. manim:: BooleanOperations

docs/source/reference_index/utilities_misc.rst

@@ -10,6 +10,7 @@ Module Index
    :toctree: ../reference
 
    ~utils.bezier
+   cli
    ~utils.color
    ~utils.commands
    ~utils.config_ops

manim/__main__.py

@@ -3,22 +3,49 @@
 import click
 import cloup
 
-from . import __version__, cli_ctx_settings, console
-from .cli.cfg.group import cfg
-from .cli.checkhealth.commands import checkhealth
-from .cli.default_group import DefaultGroup
-from .cli.init.commands import init
-from .cli.plugins.commands import plugins
-from .cli.render.commands import render
-from .constants import EPILOG
+from manim import __version__
+from manim._config import cli_ctx_settings, console
+from manim.cli.cfg.group import cfg
+from manim.cli.checkhealth.commands import checkhealth
+from manim.cli.default_group import DefaultGroup
+from manim.cli.init.commands import init
+from manim.cli.plugins.commands import plugins
+from manim.cli.render.commands import render
+from manim.constants import EPILOG
 
 
-def show_splash(ctx, param, value):
+def show_splash(ctx: click.Context, param: click.Option, value: str | None) -> None:
+    """When giving a value by console, show an initial message with the Manim
+    version before executing any other command: ``Manim Community vA.B.C``.
+
+    Parameters
+    ----------
+    ctx
+        The Click context.
+    param
+        A Click option.
+    value
+        A string value given by console, or None.
+    """
     if value:
         console.print(f"Manim Community [green]v{__version__}[/green]\n")
 
 
-def print_version_and_exit(ctx, param, value):
+def print_version_and_exit(
+    ctx: click.Context, param: click.Option, value: str | None
+) -> None:
+    """Same as :func:`show_splash`, but also exit when giving a value by
+    console.
+
+    Parameters
+    ----------
+    ctx
+        The Click context.
+    param
+        A Click option.
+    value
+        A string value given by console, or None.
+    """
     show_splash(ctx, param, value)
     if value:
         ctx.exit()
@@ -53,8 +80,14 @@ def print_version_and_exit(ctx, param, value):
     expose_value=False,
 )
 @cloup.pass_context
-def main(ctx):
-    """The entry point for manim."""
+def main(ctx: click.Context) -> None:
+    """The entry point for Manim.
+
+    Parameters
+    ----------
+    ctx
+        The Click context.
+    """
     pass
 
 

manim/_config/cli_colors.py

@@ -1,13 +1,14 @@
 from __future__ import annotations
 
 import configparser
+from typing import Any
 
 from cloup import Context, HelpFormatter, HelpTheme, Style
 
 __all__ = ["parse_cli_ctx"]
 
 
-def parse_cli_ctx(parser: configparser.SectionProxy) -> Context:
+def parse_cli_ctx(parser: configparser.SectionProxy) -> dict[str, Any]:
     formatter_settings: dict[str, str | int] = {
         "indent_increment": int(parser["indent_increment"]),
         "width": int(parser["width"]),

manim/animation/animation.py

@@ -7,17 +7,17 @@
 from .. import config, logger
 from ..constants import RendererType
 from ..mobject import mobject
-from ..mobject.mobject import Mobject
+from ..mobject.mobject import Group, Mobject
 from ..mobject.opengl import opengl_mobject
 from ..utils.rate_functions import linear, smooth
 
-__all__ = ["Animation", "Wait", "override_animation"]
+__all__ = ["Animation", "Wait", "Add", "override_animation"]
 
 
 from collections.abc import Iterable, Sequence
 from copy import deepcopy
 from functools import partialmethod
-from typing import TYPE_CHECKING, Callable
+from typing import TYPE_CHECKING, Any, Callable
 
 from typing_extensions import Self
 
@@ -172,6 +172,19 @@ def __init__(
                 ),
             )
 
+    @property
+    def run_time(self) -> float:
+        return self._run_time
+
+    @run_time.setter
+    def run_time(self, value: float) -> None:
+        if value < 0:
+            raise ValueError(
+                f"The run_time of {self.__class__.__name__} cannot be "
+                f"negative. The given value was {value}."
+            )
+        self._run_time = value
+
     def _typecheck_input(self, mobject: Mobject | None) -> None:
         if mobject is None:
             logger.debug("Animation with empty mobject")
@@ -625,6 +638,90 @@ def interpolate(self, alpha: float) -> None:
         pass
 
 
+class Add(Animation):
+    """Add Mobjects to a scene, without animating them in any other way. This
+    is similar to the :meth:`.Scene.add` method, but :class:`Add` is an
+    animation which can be grouped into other animations.
+
+    Parameters
+    ----------
+    mobjects
+        One :class:`~.Mobject` or more to add to a scene.
+    run_time
+        The duration of the animation after adding the ``mobjects``. Defaults
+        to 0, which means this is an instant animation without extra wait time
+        after adding them.
+    **kwargs
+        Additional arguments to pass to the parent :class:`Animation` class.
+
+    Examples
+    --------
+
+    .. manim:: DefaultAddScene
+
+        class DefaultAddScene(Scene):
+            def construct(self):
+                text_1 = Text("I was added with Add!")
+                text_2 = Text("Me too!")
+                text_3 = Text("And me!")
+                texts = VGroup(text_1, text_2, text_3).arrange(DOWN)
+                rect = SurroundingRectangle(texts, buff=0.5)
+
+                self.play(
+                    Create(rect, run_time=3.0),
+                    Succession(
+                        Wait(1.0),
+                        # You can Add a Mobject in the middle of an animation...
+                        Add(text_1),
+                        Wait(1.0),
+                        # ...or multiple Mobjects at once!
+                        Add(text_2, text_3),
+                    ),
+                )
+                self.wait()
+
+    .. manim:: AddWithRunTimeScene
+
+        class AddWithRunTimeScene(Scene):
+            def construct(self):
+                # A 5x5 grid of circles
+                circles = VGroup(
+                    *[Circle(radius=0.5) for _ in range(25)]
+                ).arrange_in_grid(5, 5)
+
+                self.play(
+                    Succession(
+                        # Add a run_time of 0.2 to wait for 0.2 seconds after
+                        # adding the circle, instead of using Wait(0.2) after Add!
+                        *[Add(circle, run_time=0.2) for circle in circles],
+                        rate_func=smooth,
+                    )
+                )
+                self.wait()
+    """
+
+    def __init__(
+        self, *mobjects: Mobject, run_time: float = 0.0, **kwargs: Any
+    ) -> None:
+        mobject = mobjects[0] if len(mobjects) == 1 else Group(*mobjects)
+        super().__init__(mobject, run_time=run_time, introducer=True, **kwargs)
+
+    def begin(self) -> None:
+        pass
+
+    def finish(self) -> None:
+        pass
+
+    def clean_up_from_scene(self, scene: Scene) -> None:
+        pass
+
+    def update_mobjects(self, dt: float) -> None:
+        pass
+
+    def interpolate(self, alpha: float) -> None:
+        pass
+
+
 def override_animation(
     animation_class: type[Animation],
 ) -> Callable[[Callable], Callable]: