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

manim/utils/deprecation.py

@@ -6,15 +6,17 @@ __all__ = ["deprecated", "deprecated_params"]
 
 
 import inspect
+import logging
 import re
-from typing import Any, Callable, Iterable
+from collections.abc import Callable, Iterable
+from typing import Any, TypeVar, overload
 
 from decorator import decorate, decorator
 
-from .. import logger
+logger = logging.getLogger("manim")
 
 
-def _get_callable_info(callable: Callable) -> tuple[str, str]:
+def _get_callable_info(callable_: Callable[..., Any], /) -> tuple[str, str]:
     """Returns type and name of a callable.
 
     Parameters
@@ -28,8 +30,8 @@ def _get_callable_info(callable: Callable) -> tuple[str, str]:
         The type and name of the callable. Type can can be one of "class", "method" (for
         functions defined in classes) or "function"). For methods, name is Class.method.
     """
-    what = type(callable).__name__
-    name = callable.__qualname__
+    what = type(callable_).__name__
+    name = callable_.__qualname__
     if what == "function" and "." in name:
         what = "method"
     elif what != "function":
@@ -38,9 +40,9 @@ def _get_callable_info(callable: Callable) -> tuple[str, str]:
 
 
 def _deprecation_text_component(
-    since: str | None,
-    until: str | None,
-    message: str,
+    since: str | None = None,
+    until: str | None = None,
+    message: str | None = None,
 ) -> str:
     """Generates a text component used in deprecation messages.
 
@@ -68,13 +70,37 @@ def _deprecation_text_component(
     return f"deprecated {since}and {until}.{msg}"
 
 
+# TODO: Use ParamSpec to type decorated functions when Python 3.9 is out of life
+T = TypeVar("T")
+
+
+@overload
+def deprecated(
+    func: Callable[..., T],
+    since: str | None = None,
+    until: str | None = None,
+    replacement: str | None = None,
+    message: str | None = "",
+) -> Callable[..., T]: ...
+
+
+@overload
+def deprecated(
+    func: None = None,
+    since: str | None = None,
+    until: str | None = None,
+    replacement: str | None = None,
+    message: str | None = "",
+) -> Callable[[Callable[..., T]], Callable[..., T]]: ...
+
+
 def deprecated(
-    func: Callable = None,
+    func: Callable[..., T] | None = None,
     since: str | None = None,
     until: str | None = None,
     replacement: str | None = None,
     message: str | None = "",
-) -> Callable:
+) -> Callable[..., T] | Callable[[Callable[..., T]], Callable[..., T]]:
     """Decorator to mark a callable as deprecated.
 
     The decorated callable will cause a warning when used. The docstring of the
@@ -104,10 +130,12 @@ def deprecated(
 
         from manim.utils.deprecation import deprecated
 
+
         @deprecated
         def foo(**kwargs):
             pass
 
+
         @deprecated
         class Bar:
             def __init__(self):
@@ -117,6 +145,7 @@ def deprecated(
             def baz(self):
                 pass
 
+
         foo()
         # WARNING  The function foo has been deprecated and may be removed in a later version.
 
@@ -130,15 +159,14 @@ def deprecated(
 
         from manim.utils.deprecation import deprecated
 
+
         @deprecated(
-            since="v0.2",
-            until="v0.4",
-            replacement="bar",
-            message="It is cooler."
+            since="v0.2", until="v0.4", replacement="bar", message="It is cooler."
         )
         def foo():
             pass
 
+
         foo()
         # WARNING  The function foo has been deprecated since v0.2 and is expected to be removed after v0.4. Use bar instead. It is cooler.
 
@@ -146,10 +174,12 @@ def deprecated(
 
         from manim.utils.deprecation import deprecated
 
+
         @deprecated(since="05/01/2021", until="06/01/2021")
         def foo():
             pass
 
+
         foo()
         # WARNING  The function foo has been deprecated since 05/01/2021 and is expected to be removed after 06/01/2021.
 
@@ -183,7 +213,7 @@ def deprecated(
         deprecated = _deprecation_text_component(since, until, msg)
         return f"The {what} {name} has been {deprecated}"
 
-    def deprecate_docs(func: Callable):
+    def deprecate_docs(func: Callable) -> None:
         """Adjust docstring to indicate the deprecation.
 
         Parameters
@@ -195,7 +225,7 @@ def deprecated(
         doc_string = func.__doc__ or ""
         func.__doc__ = f"{doc_string}\n\n.. attention:: Deprecated\n  {warning}"
 
-    def deprecate(func: Callable, *args, **kwargs):
+    def deprecate(func: Callable[..., T], *args: Any, **kwargs: Any) -> T:
         """The actual decorator used to extend the callables behavior.
 
         Logs a warning message.
@@ -232,10 +262,10 @@ def deprecated_params(
     params: str | Iterable[str] | None = None,
     since: str | None = None,
     until: str | None = None,
-    message: str | None = "",
+    message: str = "",
     redirections: None
     | (Iterable[tuple[str, str] | Callable[..., dict[str, Any]]]) = None,
-) -> Callable:
+) -> Callable[..., T]:
     """Decorator to mark parameters of a callable as deprecated.
 
     It can also be used to automatically redirect deprecated parameter values to their
@@ -285,10 +315,12 @@ def deprecated_params(
 
         from manim.utils.deprecation import deprecated_params
 
+
         @deprecated_params(params="a, b, c")
         def foo(**kwargs):
             pass
 
+
         foo(x=2, y=3, z=4)
         # No warning
 
@@ -299,15 +331,17 @@ def deprecated_params(
 
         from manim.utils.deprecation import deprecated_params
 
+
         @deprecated_params(
             params="a, b, c",
             since="v0.2",
             until="v0.4",
-            message="The letters x, y, z are cooler."
+            message="The letters x, y, z are cooler.",
         )
         def foo(**kwargs):
             pass
 
+
         foo(a=2)
         # WARNING  The parameter a of method foo has been deprecated since v0.2 and is expected to be removed after v0.4. The letters x, y, z are cooler.
 
@@ -315,14 +349,18 @@ def deprecated_params(
 
         from manim.utils.deprecation import deprecated_params
 
-        @deprecated_params(redirections=[
-            # Two ways to redirect one parameter to another:
-            ("old_param", "new_param"),
-            lambda old_param2: {"new_param22": old_param2}
-        ])
+
+        @deprecated_params(
+            redirections=[
+                # Two ways to redirect one parameter to another:
+                ("old_param", "new_param"),
+                lambda old_param2: {"new_param22": old_param2},
+            ]
+        )
         def foo(**kwargs):
             return kwargs
 
+
         foo(x=1, old_param=2)
         # WARNING  The parameter old_param of method foo has been deprecated and may be removed in a later version.
         # returns {"x": 1, "new_param": 2}
@@ -331,12 +369,14 @@ def deprecated_params(
 
         from manim.utils.deprecation import deprecated_params
 
-        @deprecated_params(redirections=[
-            lambda runtime_in_ms: {"run_time": runtime_in_ms / 1000}
-        ])
+
+        @deprecated_params(
+            redirections=[lambda runtime_in_ms: {"run_time": runtime_in_ms / 1000}]
+        )
         def foo(**kwargs):
             return kwargs
 
+
         foo(runtime_in_ms=500)
         # WARNING  The parameter runtime_in_ms of method foo has been deprecated and may be removed in a later version.
         # returns {"run_time": 0.5}
@@ -345,12 +385,14 @@ def deprecated_params(
 
         from manim.utils.deprecation import deprecated_params
 
-        @deprecated_params(redirections=[
-            lambda buff_x=1, buff_y=1: {"buff": (buff_x, buff_y)}
-        ])
+
+        @deprecated_params(
+            redirections=[lambda buff_x=1, buff_y=1: {"buff": (buff_x, buff_y)}]
+        )
         def foo(**kwargs):
             return kwargs
 
+
         foo(buff_x=2)
         # WARNING  The parameter buff_x of method foo has been deprecated and may be removed in a later version.
         # returns {"buff": (2, 1)}
@@ -359,18 +401,23 @@ def deprecated_params(
 
         from manim.utils.deprecation import deprecated_params
 
-        @deprecated_params(redirections=[
-            lambda buff=1: {"buff_x": buff[0], "buff_y": buff[1]} if isinstance(buff, tuple)
-                    else {"buff_x": buff,    "buff_y": buff}
-        ])
+
+        @deprecated_params(
+            redirections=[
+                lambda buff=1: {"buff_x": buff[0], "buff_y": buff[1]}
+                if isinstance(buff, tuple)
+                else {"buff_x": buff, "buff_y": buff}
+            ]
+        )
         def foo(**kwargs):
             return kwargs
 
+
         foo(buff=0)
         # WARNING  The parameter buff of method foo has been deprecated and may be removed in a later version.
         # returns {"buff_x": 0, buff_y: 0}
 
-        foo(buff=(1,2))
+        foo(buff=(1, 2))
         # WARNING  The parameter buff of method foo has been deprecated and may be removed in a later version.
         # returns {"buff_x": 1, buff_y: 2}
 
@@ -405,7 +452,7 @@ def deprecated_params(
 
     redirections = list(redirections)
 
-    def warning_msg(func: Callable, used: list[str]):
+    def warning_msg(func: Callable[..., T], used: list[str]) -> str:
         """Generate the deprecation warning message.
 
         Parameters
@@ -428,7 +475,7 @@ def deprecated_params(
         deprecated = _deprecation_text_component(since, until, message)
         return f"The parameter{parameter_s} {used_} of {what} {name} {has_have_been} {deprecated}"
 
-    def redirect_params(kwargs: dict, used: list[str]):
+    def redirect_params(kwargs: dict[str, Any], used: list[str]) -> None:
         """Adjust the keyword arguments as defined by the redirections.
 
         Parameters
@@ -452,7 +499,7 @@ def deprecated_params(
                 if len(redirector_args) > 0:
                     kwargs.update(redirector(**redirector_args))
 
-    def deprecate_params(func, *args, **kwargs):
+    def deprecate_params(func: Callable[..., T], *args: Any, **kwargs: Any) -> T:
         """The actual decorator function used to extend the callables behavior.
 
         Logs a warning message when a deprecated parameter is used and redirects it if
@@ -484,4 +531,4 @@ def deprecated_params(
             redirect_params(kwargs, used)
         return func(*args, **kwargs)
 
-    return decorator(deprecate_params)
+    return decorator(deprecate_params)  # type: ignore[return-value]

manim/utils/docbuild/__init__.py

@@ -0,0 +1,17 @@
+"""Utilities for building the Manim documentation.
+
+For more information about the Manim documentation building, see:
+
+-   :doc:`/contributing/development`, specifically the ``Documentation``
+    bullet point under :ref:`polishing-changes-and-submitting-a-pull-request`
+-   :doc:`/contributing/docs`
+
+.. autosummary::
+   :toctree: ../reference
+
+   autoaliasattr_directive
+   autocolor_directive
+   manim_directive
+   module_parsing
+
+"""

manim/utils/docbuild/autoaliasattr_directive.py

@@ -0,0 +1,236 @@
+"""A directive for documenting type aliases and other module-level attributes."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from docutils.statemachine import StringList
+
+from manim.utils.docbuild.module_parsing import parse_module_attributes
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+__all__ = ["AliasAttrDocumenter"]
+
+
+ALIAS_DOCS_DICT, DATA_DICT, TYPEVAR_DICT = parse_module_attributes()
+ALIAS_LIST = [
+    alias_name
+    for module_dict in ALIAS_DOCS_DICT.values()
+    for category_dict in module_dict.values()
+    for alias_name in category_dict
+]
+
+
+def smart_replace(base: str, alias: str, substitution: str) -> str:
+    """Auxiliary function for substituting type aliases into a base
+    string, when there are overlaps between the aliases themselves.
+
+    Parameters
+    ----------
+    base
+        The string in which the type aliases will be located and
+        replaced.
+    alias
+        The substring to be substituted.
+    substitution
+        The string which will replace every occurrence of ``alias``.
+
+    Returns
+    -------
+    str
+        The new string after the alias substitution.
+    """
+    occurrences = []
+    len_alias = len(alias)
+    len_base = len(base)
+
+    def condition(char: str) -> bool:
+        return not char.isalnum() and char != "_"
+
+    start = 0
+    i = 0
+    while True:
+        i = base.find(alias, start)
+        if i == -1:
+            break
+        if (i == 0 or condition(base[i - 1])) and (
+            i + len_alias == len_base or condition(base[i + len_alias])
+        ):
+            occurrences.append(i)
+        start = i + len_alias
+
+    for o in occurrences[::-1]:
+        base = base[:o] + substitution + base[o + len_alias :]
+
+    return base
+
+
+def setup(app: Sphinx) -> None:
+    app.add_directive("autoaliasattr", AliasAttrDocumenter)
+
+
+class AliasAttrDocumenter(Directive):
+    """Directive which replaces Sphinx's Autosummary for module-level
+    attributes: instead, it manually crafts a new "Type Aliases"
+    section, where all the module-level attributes which are explicitly
+    annotated as :class:`TypeAlias` are considered as such, for their
+    use all around the Manim docs.
+
+    These type aliases are separated from the "regular" module-level
+    attributes, which get their traditional "Module Attributes"
+    section autogenerated with Sphinx's Autosummary under "Type
+    Aliases".
+
+    See ``docs/source/_templates/autosummary/module.rst`` to watch
+    this directive in action.
+
+    See :func:`~.parse_module_attributes` for more information on how
+    the modules are parsed to obtain the :class:`TypeAlias` information
+    and separate it from the other attributes.
+    """
+
+    objtype = "autoaliasattr"
+    required_arguments = 1
+    has_content = True
+
+    def run(self) -> list[nodes.Element]:
+        module_name = self.arguments[0]
+        # not present in the keys of the DICTs
+        module_name = module_name.removeprefix("manim.")
+        module_alias_dict = ALIAS_DOCS_DICT.get(module_name, None)
+        module_attrs_list = DATA_DICT.get(module_name, None)
+        module_typevars = TYPEVAR_DICT.get(module_name, None)
+
+        content = nodes.container()
+
+        # Add "Type Aliases" section
+        if module_alias_dict is not None:
+            module_alias_section = nodes.section(ids=[f"{module_name}.alias"])
+            content += module_alias_section
+
+            # Use a rubric (title-like), just like in `module.rst`
+            module_alias_section += nodes.rubric(text="Type Aliases")
+
+            # category_name: str
+            # category_dict: AliasCategoryDict = dict[str, AliasInfo]
+            for category_name, category_dict in module_alias_dict.items():
+                category_section = nodes.section(
+                    ids=[category_name.lower().replace(" ", "_")]
+                )
+                module_alias_section += category_section
+                # category_name can be possibly "" for uncategorized aliases
+                if category_name:
+                    category_section += nodes.title(text=category_name)
+
+                category_alias_container = nodes.container()
+                category_section += category_alias_container
+
+                # alias_name: str
+                # alias_info: AliasInfo = dict[str, str]
+                #   Contains "definition": str
+                #   Can possibly contain "doc": str
+                for alias_name, alias_info in category_dict.items():
+                    # Replace all occurrences of type aliases in the
+                    # definition for automatic cross-referencing!
+                    alias_def = alias_info["definition"]
+                    for A in ALIAS_LIST:
+                        alias_def = smart_replace(alias_def, A, f":class:`~.{A}`")
+
+                    # Using the `.. class::` directive is CRUCIAL, since
+                    # function/method parameters are always annotated via
+                    # classes - therefore Sphinx expects a class
+                    unparsed = StringList(
+                        [
+                            f".. class:: {alias_name}",
+                            "",
+                            "    .. parsed-literal::",
+                            "",
+                            f"        {alias_def}",
+                            "",
+                        ]
+                    )
+
+                    if "doc" in alias_info:
+                        # Replace all occurrences of type aliases in
+                        # the docs for automatic cross-referencing!
+                        alias_doc = alias_info["doc"]
+                        for A in ALIAS_LIST:
+                            alias_doc = alias_doc.replace(f"`{A}`", f":class:`~.{A}`")
+
+                        # also hyperlink the TypeVars from that module
+                        if module_typevars is not None:
+                            for T in module_typevars:
+                                alias_doc = alias_doc.replace(f"`{T}`", f":class:`{T}`")
+
+                        # Add all the lines with 4 spaces behind, to consider all the
+                        # documentation as a paragraph INSIDE the `.. class::` block
+                        doc_lines = alias_doc.split("\n")
+                        unparsed.extend(
+                            StringList([f"    {line}" for line in doc_lines])
+                        )
+
+                    # Parse the reST text into a fresh container
+                    # https://www.sphinx-doc.org/en/master/extdev/markupapi.html#parsing-directive-content-as-rest
+                    alias_container = nodes.container()
+                    self.state.nested_parse(unparsed, 0, alias_container)
+                    category_alias_container += alias_container
+
+        # then add the module TypeVars section
+        if module_typevars is not None:
+            module_typevars_section = nodes.section(ids=[f"{module_name}.typevars"])
+            content += module_typevars_section
+
+            # Use a rubric (title-like), just like in `module.rst`
+            module_typevars_section += nodes.rubric(text="TypeVar's")
+
+            # name: str
+            # definition: TypeVarDict = dict[str, str]
+            for name, definition in module_typevars.items():
+                # Using the `.. class::` directive is CRUCIAL, since
+                # function/method parameters are always annotated via
+                # classes - therefore Sphinx expects a class
+                unparsed = StringList(
+                    [
+                        f".. class:: {name}",
+                        "",
+                        "    .. parsed-literal::",
+                        "",
+                        f"        {definition}",
+                        "",
+                    ]
+                )
+
+                # Parse the reST text into a fresh container
+                # https://www.sphinx-doc.org/en/master/extdev/markupapi.html#parsing-directive-content-as-rest
+                typevar_container = nodes.container()
+                self.state.nested_parse(unparsed, 0, typevar_container)
+                module_typevars_section += typevar_container
+
+        # Then, add the traditional "Module Attributes" section
+        if module_attrs_list is not None:
+            module_attrs_section = nodes.section(ids=[f"{module_name}.data"])
+            content += module_attrs_section
+
+            # Use the same rubric (title-like) as in `module.rst`
+            module_attrs_section += nodes.rubric(text="Module Attributes")
+            # Let Sphinx Autosummary do its thing as always
+            # Add all the attribute names with 4 spaces behind, so that
+            # they're considered as INSIDE the `.. autosummary::` block
+            unparsed = StringList(
+                [
+                    ".. autosummary::",
+                    *(f"    {attr}" for attr in module_attrs_list),
+                ]
+            )
+
+            # Parse the reST text into a fresh container
+            # https://www.sphinx-doc.org/en/master/extdev/markupapi.html#parsing-directive-content-as-rest
+            data_container = nodes.container()
+            self.state.nested_parse(unparsed, 0, data_container)
+            module_attrs_section += data_container
+
+        return [content]

manim/utils/docbuild/autocolor_directive.py

@@ -0,0 +1,99 @@
+"""A directive for documenting colors in Manim."""
+
+from __future__ import annotations
+
+import inspect
+from typing import TYPE_CHECKING
+
+from docutils import nodes
+from docutils.parsers.rst import Directive
+
+from manim import ManimColor
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+__all__ = ["ManimColorModuleDocumenter"]
+
+
+def setup(app: Sphinx) -> None:
+    app.add_directive("automanimcolormodule", ManimColorModuleDocumenter)
+
+
+class ManimColorModuleDocumenter(Directive):
+    objtype = "automanimcolormodule"
+    required_arguments = 1
+    has_content = True
+
+    def add_directive_header(self, sig: str) -> None:
+        # TODO: The Directive class has no method named
+        # add_directive_header.
+        super().add_directive_header(sig)  # type: ignore[misc]
+
+    def run(self) -> list[nodes.Element]:
+        module_name = self.arguments[0]
+        try:
+            import importlib
+
+            module = importlib.import_module(module_name)
+        except ImportError:
+            return [
+                nodes.error(
+                    None,  # type: ignore[arg-type]
+                    nodes.paragraph(text=f"Failed to import module '{module_name}'"),
+                )
+            ]
+
+        # Number of Colors displayed in one row
+        num_color_cols = 2
+        table = nodes.table(align="center")
+
+        tgroup = nodes.tgroup(cols=num_color_cols * 2)
+        table += tgroup
+        for _ in range(num_color_cols * 2):
+            tgroup += nodes.colspec(colwidth=1)
+
+        # Create header rows for the table
+        thead = nodes.thead()
+        header_row = nodes.row()
+        for _ in range(num_color_cols):
+            header_col1 = nodes.paragraph(text="Color Name")
+            header_col2 = nodes.paragraph(text="RGB Hex Code")
+            header_row += nodes.entry("", header_col1)
+            header_row += nodes.entry("", header_col2)
+        thead += header_row
+        tgroup += thead
+
+        color_elements = []
+        for member_name, member_obj in inspect.getmembers(module):
+            if isinstance(member_obj, ManimColor):
+                r, g, b = member_obj.to_rgb()
+                luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b
+
+                # Choose the font color based on the background luminance
+                font_color = "black" if luminance > 0.5 else "white"
+
+                color_elements.append((member_name, member_obj.to_hex(), font_color))
+
+        tbody = nodes.tbody()
+
+        for base_i in range(0, len(color_elements), num_color_cols):
+            row = nodes.row()
+            for idx in range(base_i, base_i + num_color_cols):
+                if idx < len(color_elements):
+                    member_name, hex_code, font_color = color_elements[idx]
+                    col1 = nodes.literal(text=member_name)
+                    col2 = nodes.raw(
+                        "",
+                        f'<div style="background-color:{hex_code};padding: 0.25rem 0;border-radius:8px;margin: 0.5rem 0.2rem"><code style="color:{font_color};">{hex_code}</code></div>',
+                        format="html",
+                    )
+                else:
+                    col1 = nodes.literal(text="")
+                    col2 = nodes.raw("", "", format="html")
+                row += nodes.entry("", col1)
+                row += nodes.entry("", col2)
+            tbody += row
+        tgroup += tbody
+
+        return [table]