Merge branch 'master' into cleanup/util-2a-mock-part

Author: picnixz

.ruff.toml

@@ -15,17 +15,23 @@ exclude = [
     "doc/usage/extensions/example*.py",
 ]
 ignore = [
+    # flake8-annotations
     "ANN401",  # Dynamically typed expressions (typing.Any) are disallowed in `{name}`
+    # pycodestyle
     "E741",  # Ambiguous variable name: `{name}`
+    # pyflakes
     "F841",  # Local variable `{name}` is assigned to but never used
+    # refurb
     "FURB101",  # `open` and `read` should be replaced by `Path(...).read_text(...)`
     "FURB103",  # `open` and `write` should be replaced by `Path(...).write_text(...)`
+    # pylint
     "PLC1901",  # simplify truthy/falsey string comparisons
+    # flake8-simplify
     "SIM102",  # Use a single `if` statement instead of nested `if` statements
     "SIM108",  # Use ternary operator `{contents}` instead of `if`-`else`-block
+    # pyupgrade
     "UP031",   # Use format specifiers instead of percent format
     "UP032",   # Use f-string instead of `format` call
-
 ]
 external = [  # Whitelist for RUF100 unknown code warnings
     "E704",
@@ -36,7 +42,8 @@ select = [
       # NOT YET USED
     # airflow ('AIR')
       # Airflow is not used in Sphinx
-    "ANN",  # flake8-annotations ('ANN')
+    # flake8-annotations ('ANN')
+    "ANN",
     # flake8-unused-arguments ('ARG')
     "ARG004",  # Unused static method argument: `{name}`
     # flake8-async ('ASYNC')
@@ -124,7 +131,8 @@ select = [
       # NOT YET USED
     # flynt ('FLY')
       # NOT YET USED
-    "FURB",     # refurb
+    # refurb ('FURB')
+    "FURB",
     # flake8-logging-format ('G')
     "G001",  # Logging statement uses `str.format`
 #    "G002",  # Logging statement uses `%`
@@ -136,6 +144,7 @@ select = [
     "G202",  # Logging statement has redundant `exc_info`
     # isort ('I')
     "I",
+    # flake8-import-conventions ('ICN')
     "ICN",  # flake8-import-conventions
     # flake8-no-pep420 ('INP')
     "INP",
@@ -327,16 +336,19 @@ select = [
     "S612",  # Use of insecure `logging.config.listen` detected
 #    "S701",  # Using jinja2 templates with `autoescape=False` is dangerous and can lead to XSS. Ensure `autoescape=True` or use the `select_autoescape` function.
 #    "S702",  # Mako templates allow HTML and JavaScript rendering by default and are inherently open to XSS attacks
+    # flake8-simplify ('SIM')
     "SIM",  # flake8-simplify
     # flake8-self ('SLF')
       # NOT YET USED
-    "SLOT",  # flake8-slots
+    # flake8-slots ('SLOT')
+    "SLOT",
     # flake8-debugger ('T10')
     "T100",  # Trace found: `{name}` used
     # flake8-print ('T20')
     "T201",  # `print` found
     "T203",  # `pprint` found
-    "TCH",  # flake8-type-checking
+    # flake8-type-checking ('TCH')
+    "TCH",
     # flake8-todos ('TD')
 #    "TD001",  # Invalid TODO tag: `{tag}`
 #    "TD003",  # Missing issue link on the line following this TODO
@@ -352,7 +364,8 @@ select = [
       # Trio is not used in Sphinx
     # tryceratops ('TRY')
       # NOT YET USED
-    "UP001",  # pyupgrade
+    # pyupgrade ('UP')
+    "UP",
     # pycodestyle ('W')
     "W191",  # Indentation contains tabs
 #    "W291",  # Trailing whitespace

sphinx/util/inspect.py

@@ -219,9 +219,10 @@ def isclassmethod(obj: Any, cls: Any = None, name: str | None = None) -> bool:
         return True
     if cls and name:
         # trace __mro__ if the method is defined in parent class
+        sentinel = object()
         for basecls in getmro(cls):
-            meth = basecls.__dict__.get(name)
-            if meth is not None:
+            meth = basecls.__dict__.get(name, sentinel)
+            if meth is not sentinel:
                 return isclassmethod(meth)
     return False
 
@@ -232,9 +233,10 @@ def isstaticmethod(obj: Any, cls: Any = None, name: str | None = None) -> bool:
         return True
     if cls and name:
         # trace __mro__ if the method is defined in parent class
+        sentinel = object()
         for basecls in getattr(cls, '__mro__', [cls]):
-            meth = basecls.__dict__.get(name)
-            if meth is not None:
+            meth = basecls.__dict__.get(name, sentinel)
+            if meth is not sentinel:
                 return isinstance(meth, staticmethod)
     return False
 

sphinx/util/typing.py

@@ -184,13 +184,9 @@ def restify(cls: type | None, mode: str = 'fully-qualified-except-typing') -> st
                 # newtypes have correct module info since Python 3.10+
                 return f':py:class:`{modprefix}{cls.__module__}.{cls.__name__}`'
             else:
-                return ':py:class:`%s`' % cls.__name__
+                return f':py:class:`{cls.__name__}`'
         elif UnionType and isinstance(cls, UnionType):
-            if len(cls.__args__) > 1 and None in cls.__args__:
-                args = ' | '.join(restify(a, mode) for a in cls.__args__ if a)
-                return 'Optional[%s]' % args
-            else:
-                return ' | '.join(restify(a, mode) for a in cls.__args__)
+            return ' | '.join(restify(a, mode) for a in cls.__args__)
         elif cls.__module__ in ('__builtin__', 'builtins'):
             if hasattr(cls, '__args__'):
                 if not cls.__args__:  # Empty tuple, list, ...
@@ -199,23 +195,11 @@ def restify(cls: type | None, mode: str = 'fully-qualified-except-typing') -> st
                 concatenated_args = ', '.join(restify(arg, mode) for arg in cls.__args__)
                 return fr':py:class:`{cls.__name__}`\ [{concatenated_args}]'
             else:
-                return ':py:class:`%s`' % cls.__name__
+                return f':py:class:`{cls.__name__}`'
         elif (inspect.isgenericalias(cls)
               and cls.__module__ == 'typing'
               and cls.__origin__ is Union):  # type: ignore[attr-defined]
-            if (len(cls.__args__) > 1  # type: ignore[attr-defined]
-                    and cls.__args__[-1] is NoneType):  # type: ignore[attr-defined]
-                if len(cls.__args__) > 2:  # type: ignore[attr-defined]
-                    args = ', '.join(restify(a, mode)
-                                     for a in cls.__args__[:-1])  # type: ignore[attr-defined]
-                    return ':py:obj:`~typing.Optional`\\ [:obj:`~typing.Union`\\ [%s]]' % args
-                else:
-                    return ':py:obj:`~typing.Optional`\\ [%s]' % restify(
-                        cls.__args__[0], mode)  # type: ignore[attr-defined]
-            else:
-                args = ', '.join(restify(a, mode)
-                                 for a in cls.__args__)  # type: ignore[attr-defined]
-                return ':py:obj:`~typing.Union`\\ [%s]' % args
+            return ' | '.join(restify(a, mode) for a in cls.__args__)  # type: ignore[attr-defined]
         elif inspect.isgenericalias(cls):
             if isinstance(cls.__origin__, typing._SpecialForm):  # type: ignore[attr-defined]
                 text = restify(cls.__origin__, mode)  # type: ignore[attr-defined,arg-type]
@@ -245,10 +229,10 @@ def restify(cls: type | None, mode: str = 'fully-qualified-except-typing') -> st
                         literal_args.append(_format_literal_enum_arg(a, mode=mode))
                     else:
                         literal_args.append(repr(a))
-                text += r"\ [%s]" % ', '.join(literal_args)
+                text += fr"\ [{', '.join(literal_args)}]"
                 del literal_args
             elif cls.__args__:
-                text += r"\ [%s]" % ", ".join(restify(a, mode) for a in cls.__args__)
+                text += fr"\ [{', '.join(restify(a, mode) for a in cls.__args__)}]"
 
             return text
         elif isinstance(cls, typing._SpecialForm):
@@ -262,7 +246,7 @@ def restify(cls: type | None, mode: str = 'fully-qualified-except-typing') -> st
             else:
                 return f':py:class:`{modprefix}{cls.__module__}.{cls.__qualname__}`'
         elif isinstance(cls, ForwardRef):
-            return ':py:class:`%s`' % cls.__forward_arg__
+            return f':py:class:`{cls.__forward_arg__}`'
         else:
             # not a class (ex. TypeVar)
             if cls.__module__ == 'typing':

tests/test_extensions/test_ext_autodoc_autoclass.py

@@ -276,8 +276,7 @@ def test_show_inheritance_for_subclass_of_generic_type(app):
         '.. py:class:: Quux(iterable=(), /)',
         '   :module: target.classes',
         '',
-        '   Bases: :py:class:`~typing.List`\\ '
-        '[:py:obj:`~typing.Union`\\ [:py:class:`int`, :py:class:`float`]]',
+        '   Bases: :py:class:`~typing.List`\\ [:py:class:`int` | :py:class:`float`]',
         '',
         '   A subclass of List[Union[int, float]]',
         '',

tests/test_util/test_util_typing.py

@@ -190,24 +190,44 @@ def test_restify_type_hints_Callable():
 
 
 def test_restify_type_hints_Union():
-    assert restify(Optional[int]) == ":py:obj:`~typing.Optional`\\ [:py:class:`int`]"
-    assert restify(Union[str, None]) == ":py:obj:`~typing.Optional`\\ [:py:class:`str`]"
-    assert restify(Union[int, str]) == (":py:obj:`~typing.Union`\\ "
-                                        "[:py:class:`int`, :py:class:`str`]")
-    assert restify(Union[int, Integral]) == (":py:obj:`~typing.Union`\\ "
-                                             "[:py:class:`int`, :py:class:`numbers.Integral`]")
-    assert restify(Union[int, Integral], "smart") == (":py:obj:`~typing.Union`\\ "
-                                                      "[:py:class:`int`,"
-                                                      " :py:class:`~numbers.Integral`]")
+    assert restify(Union[int]) == ":py:class:`int`"
+    assert restify(Union[int, str]) == ":py:class:`int` | :py:class:`str`"
+    assert restify(Optional[int]) == ":py:class:`int` | :py:obj:`None`"
+
+    assert restify(Union[str, None]) == ":py:class:`str` | :py:obj:`None`"
+    assert restify(Union[None, str]) == ":py:obj:`None` | :py:class:`str`"
+    assert restify(Optional[str]) == ":py:class:`str` | :py:obj:`None`"
+
+    assert restify(Union[int, str, None]) == (
+        ":py:class:`int` | :py:class:`str` | :py:obj:`None`"
+    )
+    assert restify(Optional[Union[int, str]]) in {
+        ":py:class:`str` | :py:class:`int` | :py:obj:`None`",
+        ":py:class:`int` | :py:class:`str` | :py:obj:`None`",
+    }
+
+    assert restify(Union[int, Integral]) == (
+        ":py:class:`int` | :py:class:`numbers.Integral`"
+    )
+    assert restify(Union[int, Integral], "smart") == (
+        ":py:class:`int` | :py:class:`~numbers.Integral`"
+    )
 
     assert (restify(Union[MyClass1, MyClass2]) ==
-            (":py:obj:`~typing.Union`\\ "
-             "[:py:class:`tests.test_util.test_util_typing.MyClass1`, "
-             ":py:class:`tests.test_util.test_util_typing.<MyClass2>`]"))
+            (":py:class:`tests.test_util.test_util_typing.MyClass1`"
+             " | :py:class:`tests.test_util.test_util_typing.<MyClass2>`"))
     assert (restify(Union[MyClass1, MyClass2], "smart") ==
-            (":py:obj:`~typing.Union`\\ "
-             "[:py:class:`~tests.test_util.test_util_typing.MyClass1`,"
-             " :py:class:`~tests.test_util.test_util_typing.<MyClass2>`]"))
+            (":py:class:`~tests.test_util.test_util_typing.MyClass1`"
+             " | :py:class:`~tests.test_util.test_util_typing.<MyClass2>`"))
+
+    assert (restify(Optional[Union[MyClass1, MyClass2]]) ==
+            (":py:class:`tests.test_util.test_util_typing.MyClass1`"
+             " | :py:class:`tests.test_util.test_util_typing.<MyClass2>`"
+             " | :py:obj:`None`"))
+    assert (restify(Optional[Union[MyClass1, MyClass2]], "smart") ==
+            (":py:class:`~tests.test_util.test_util_typing.MyClass1`"
+             " | :py:class:`~tests.test_util.test_util_typing.<MyClass2>`"
+             " | :py:obj:`None`"))
 
 
 def test_restify_type_hints_typevars():
@@ -300,6 +320,7 @@ def test_restify_pep_585():
 @pytest.mark.skipif(sys.version_info[:2] <= (3, 9), reason='python 3.10+ is required.')
 def test_restify_type_union_operator():
     assert restify(int | None) == ":py:class:`int` | :py:obj:`None`"  # type: ignore[attr-defined]
+    assert restify(None | int) == ":py:obj:`None` | :py:class:`int`"  # type: ignore[attr-defined]
     assert restify(int | str) == ":py:class:`int` | :py:class:`str`"  # type: ignore[attr-defined]
     assert restify(int | str | None) == (":py:class:`int` | :py:class:`str` | "  # type: ignore[attr-defined]
                                          ":py:obj:`None`")
@@ -486,9 +507,12 @@ def test_stringify_type_hints_Union():
     assert stringify_annotation(Optional[int], "fully-qualified") == "int | None"
     assert stringify_annotation(Optional[int], "smart") == "int | None"
 
-    assert stringify_annotation(Union[str, None], 'fully-qualified-except-typing') == "str | None"
-    assert stringify_annotation(Union[str, None], "fully-qualified") == "str | None"
-    assert stringify_annotation(Union[str, None], "smart") == "str | None"
+    assert stringify_annotation(Union[int, None], 'fully-qualified-except-typing') == "int | None"
+    assert stringify_annotation(Union[None, int], 'fully-qualified-except-typing') == "None | int"
+    assert stringify_annotation(Union[int, None], "fully-qualified") == "int | None"
+    assert stringify_annotation(Union[None, int], "fully-qualified") == "None | int"
+    assert stringify_annotation(Union[int, None], "smart") == "int | None"
+    assert stringify_annotation(Union[None, int], "smart") == "None | int"
 
     assert stringify_annotation(Union[int, str], 'fully-qualified-except-typing') == "int | str"
     assert stringify_annotation(Union[int, str], "fully-qualified") == "int | str"