Require the PEP 563 'annotations' future import

.ruff.toml

@@ -295,7 +295,7 @@ select = [
     "TC001",  # documentation doesn't need type-checking blocks
 ]
 "doc/conf.py" = ["INP001", "W605"]
-"doc/development/tutorials/examples/*" = ["INP001"]
+"doc/development/tutorials/examples/*" = ["I002", "INP001"]
 # allow print() in the tutorial
 "doc/development/tutorials/examples/recipe.py" = [
     "FURB118",
@@ -360,7 +360,7 @@ select = [
 
 # these tests need old ``typing`` generic aliases
 "tests/test_util/test_util_typing.py" = ["UP006", "UP007", "UP035"]
-"tests/test_util/typing_test_data.py" = ["FA100", "PYI030", "UP006", "UP007", "UP035"]
+"tests/test_util/typing_test_data.py" = ["FA100", "I002", "PYI030", "UP006", "UP007", "UP035"]
 
 "utils/*" = [
     "T201",  # whitelist ``print`` for stdout messages
@@ -377,6 +377,9 @@ inline-quotes = "single"
 forced-separate = [
     "tests",
 ]
+required-imports = [
+    "from __future__ import annotations",
+]
 
 [format]
 preview = true

sphinx/__init__.py

@@ -1,4 +1,5 @@
 """The Sphinx documentation toolchain."""
+from __future__ import annotations
 
 __version__ = '8.2.0'
 __display_version__ = __version__  # used for command line version

sphinx/__main__.py

@@ -1,4 +1,5 @@
 """The Sphinx documentation toolchain."""
+from __future__ import annotations
 
 import sys
 

sphinx/builders/latex/nodes.py

@@ -1,4 +1,5 @@
 """Additional nodes for LaTeX writer."""
+from __future__ import annotations
 
 from docutils import nodes
 

sphinx/environment/adapters/asset.py

@@ -1,8 +1,13 @@
 """Assets adapter for sphinx.environment."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
 
-from sphinx.environment import BuildEnvironment
 from sphinx.util._pathlib import _StrPath
 
+if TYPE_CHECKING:
+    from sphinx.environment import BuildEnvironment
+
 
 class ImageAdapter:
     def __init__(self, env: BuildEnvironment) -> None:

sphinx/ext/intersphinx/__main__.py

@@ -1,4 +1,5 @@
 """Command line interface for the intersphinx extension."""
+from __future__ import annotations
 
 import logging as _logging
 import sys

sphinx/pygments_styles.py

@@ -1,4 +1,5 @@
 """Sphinx theme specific highlighting styles."""
+from __future__ import annotations
 
 from pygments.style import Style
 from pygments.styles.friendly import FriendlyStyle

sphinx/testing/restructuredtext.py

@@ -1,11 +1,18 @@
-from docutils import nodes
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
 from docutils.core import publish_doctree
 
-from sphinx.application import Sphinx
 from sphinx.io import SphinxStandaloneReader
 from sphinx.parsers import RSTParser
 from sphinx.util.docutils import sphinx_domains
 
+if TYPE_CHECKING:
+    from docutils import nodes
+
+    from sphinx.application import Sphinx
+
 
 def parse(app: Sphinx, text: str, docname: str = 'index') -> nodes.document:
     """Parse a string as reStructuredText with Sphinx application."""

sphinx/util/_lines.py

@@ -1,3 +1,6 @@
+from __future__ import annotations
+
+
 def parse_line_num_spec(spec: str, total: int) -> list[int]:
     """Parse a line number spec (such as "1,2,4-6") and return a list of
     wanted line numbers.

sphinx/util/build_phase.py

@@ -1,4 +1,5 @@
 """Build phase of Sphinx application."""
+from __future__ import annotations
 
 from enum import IntEnum
 

sphinx/util/http_date.py

@@ -2,6 +2,7 @@
 
 Reference: https://www.rfc-editor.org/rfc/rfc7231#section-7.1.1.1
 """
+from __future__ import annotations
 
 import time
 import warnings

tests/test_builders/test_build.py

@@ -1,4 +1,5 @@
 """Test all builders."""
+from __future__ import annotations
 
 import os
 import shutil

tests/test_builders/test_build_changes.py

@@ -1,4 +1,5 @@
 """Test the ChangesBuilder class."""
+from __future__ import annotations
 
 import pytest
 

tests/test_builders/test_build_dirhtml.py

@@ -1,4 +1,5 @@
 """Test dirhtml builder."""
+from __future__ import annotations
 
 import posixpath
 

tests/test_builders/test_build_epub.py

@@ -1,4 +1,5 @@
 """Test the HTML builder and check output against XPath."""
+from __future__ import annotations
 
 import os
 import subprocess

tests/test_builders/test_build_gettext.py

@@ -1,4 +1,5 @@
 """Test the build process with gettext builder with the test root."""
+from __future__ import annotations
 
 import gettext
 import re

tests/test_builders/test_build_html_assets.py

@@ -1,4 +1,5 @@
 """Test the HTML builder and check output against XPath."""
+from __future__ import annotations
 
 import re
 from pathlib import Path

tests/test_builders/test_build_html_code.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import pytest
 
 

tests/test_builders/test_build_html_copyright.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import time
 
 import pytest

tests/test_builders/test_build_html_download.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import hashlib
 import re
 

tests/test_builders/test_build_html_highlight.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from unittest.mock import ANY, call, patch
 
 import pytest

tests/test_builders/test_build_html_image.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import re
 from pathlib import Path
 

tests/test_builders/test_build_html_maths.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import pytest
 
 from sphinx.errors import ConfigError

tests/test_builders/test_build_html_numfig.py

@@ -1,4 +1,5 @@
 """Test the HTML builder and check output against XPath."""
+from __future__ import annotations
 
 import os
 import re

tests/test_builders/test_build_html_tocdepth.py

@@ -1,4 +1,5 @@
 """Test the HTML builder and check output against XPath."""
+from __future__ import annotations
 
 import pytest
 

tests/test_builders/test_build_html_toctree.py

@@ -1,4 +1,5 @@
 """Test the HTML builder and check output against XPath."""
+from __future__ import annotations
 
 import re
 from unittest.mock import patch

tests/test_builders/test_build_latex.py

@@ -1,4 +1,5 @@
 """Test the build process with LaTeX builder with the test root."""
+from __future__ import annotations
 
 import http.server
 import os

tests/test_builders/test_build_manpage.py

@@ -1,4 +1,5 @@
 """Test the build process with manpage builder with the test root."""
+from __future__ import annotations
 
 import docutils
 import pytest

tests/test_builders/test_build_texinfo.py

@@ -1,4 +1,5 @@
 """Test the build process with Texinfo builder with the test root."""
+from __future__ import annotations
 
 import re
 import subprocess

tests/test_builders/test_build_warnings.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import os
 import re
 import sys

tests/test_builders/test_incremental_reading.py

@@ -1,4 +1,5 @@
 """Test the Builder class."""
+from __future__ import annotations
 
 import sys
 

tests/test_config/test_copyright.py

@@ -1,4 +1,5 @@
 """Test copyright year adjustment"""
+from __future__ import annotations
 
 import time
 

tests/test_directives/test_directive_code.py

@@ -1,4 +1,5 @@
 """Test the code-block directive."""
+from __future__ import annotations
 
 import pytest
 from docutils import nodes

tests/test_directives/test_directive_only.py

@@ -1,4 +1,5 @@
 """Test the only directive with the test root."""
+from __future__ import annotations
 
 import re
 

tests/test_directives/test_directive_option.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import pytest
 
 

tests/test_directives/test_directive_other.py

@@ -1,4 +1,5 @@
 """Test the other directives."""
+from __future__ import annotations
 
 from pathlib import Path
 

tests/test_directives/test_directive_patch.py

@@ -1,4 +1,5 @@
 """Test the patched directives."""
+from __future__ import annotations
 
 import pytest
 from docutils import nodes

tests/test_directives/test_directives_no_typesetting.py

@@ -1,4 +1,5 @@
 """Tests the directives"""
+from __future__ import annotations
 
 import pytest
 from docutils import nodes

tests/test_domains/test_domain_c.py

@@ -1,9 +1,10 @@
 """Tests the C Domain"""
+from __future__ import annotations
 
 import itertools
 import xml.etree.ElementTree as ET
 import zlib
-from io import StringIO
+from typing import TYPE_CHECKING
 
 import pytest
 
@@ -29,6 +30,9 @@
 from sphinx.util.cfamily import DefinitionError
 from sphinx.writers.text import STDINDENT
 
+if TYPE_CHECKING:
+    from io import StringIO
+
 
 class Config:
     c_id_attributes = ['id_attr', 'LIGHTGBM_C_EXPORT']

tests/test_domains/test_domain_cpp.py

@@ -1,9 +1,10 @@
 """Tests the C++ Domain"""
+from __future__ import annotations
 
 import itertools
 import re
 import zlib
-from io import StringIO
+from typing import TYPE_CHECKING
 
 import pytest
 
@@ -30,6 +31,9 @@
 from sphinx.util.cfamily import DefinitionError, NoOldIdError
 from sphinx.writers.text import STDINDENT
 
+if TYPE_CHECKING:
+    from io import StringIO
+
 
 def parse(name, string):
     class Config:

tests/test_domains/test_domain_js.py

@@ -1,4 +1,5 @@
 """Tests the JavaScript Domain"""
+from __future__ import annotations
 
 from unittest.mock import Mock
 

tests/test_domains/test_domain_rst.py

@@ -1,4 +1,5 @@
 """Tests the reStructuredText domain."""
+from __future__ import annotations
 
 import pytest
 

tests/test_domains/test_domain_std.py

@@ -1,4 +1,5 @@
 """Tests the std domain"""
+from __future__ import annotations
 
 from unittest import mock
 

tests/test_environment/test_environment.py

@@ -1,4 +1,5 @@
 """Test the BuildEnvironment class."""
+from __future__ import annotations
 
 import shutil
 from pathlib import Path

tests/test_environment/test_environment_indexentries.py

@@ -1,4 +1,5 @@
 """Test the sphinx.environment.adapters.indexentries."""
+from __future__ import annotations
 
 import pytest
 

tests/test_environment/test_environment_record_dependencies.py

@@ -1,4 +1,5 @@
 """Tests for ``record_dependencies``."""
+from __future__ import annotations
 
 import pytest
 

tests/test_environment/test_environment_toctree.py

@@ -1,4 +1,5 @@
 """Test the sphinx.environment.adapters.toctree."""
+from __future__ import annotations
 
 import pytest
 from docutils import nodes

tests/test_errors.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from sphinx.errors import ExtensionError
 
 

tests/test_events.py

@@ -1,4 +1,5 @@
 """Test the EventManager class."""
+from __future__ import annotations
 
 import pytest
 

tests/test_extensions/ext_napoleon_pep526_data_google.py

@@ -1,4 +1,5 @@
 """Test module for napoleon PEP 526 compatibility with google style"""
+from __future__ import annotations
 
 module_level_var: int = 99
 """This is an example module level variable"""

tests/test_extensions/ext_napoleon_pep526_data_numpy.py

@@ -1,4 +1,5 @@
 """Test module for napoleon PEP 526 compatibility with numpy style"""
+from __future__ import annotations
 
 module_level_var: int = 99
 """This is an example module level variable"""