Deprecate the sphinx.io module (#13682)

Author: AA-Turner

CHANGES.rst

@@ -29,6 +29,11 @@ Deprecated
 * #13679: Non-decodable characters in source files will raise an error in Sphinx 9.
   Currently, such bytes are replaced with '?' along with logging a warning.
   Patch by Adam Turner.
+* #13682: Deprecate :py:mod:`!sphinx.io`.
+  Sphinx no longer uses the :py:mod:`!sphinx.io` classes,
+  having replaced them with standard Python I/O.
+  The entire :py:mod:`!sphinx.io` module will be removed in Sphinx 10.
+  Patch by Adam Turner.
 
 Features added
 --------------

doc/extdev/deprecated.rst

@@ -22,6 +22,11 @@ The following is a list of deprecated interfaces.
      - Removed
      - Alternatives
 
+   * - ``sphinx.io`` (entire module)
+     - 8.3
+     - 10.0
+     - ``docutils.io`` or standard Python I/O
+
    * - ``sphinx.builders.Builder.app``
      - 8.3
      - 10.0

sphinx/io.py

@@ -2,13 +2,15 @@
 
 from __future__ import annotations
 
+import warnings
 from typing import TYPE_CHECKING
 
 from docutils.io import FileInput
 from docutils.readers import standalone
 from docutils.transforms.references import DanglingReferences
 from docutils.writers import UnfilteredWriter
 
+from sphinx.deprecation import RemovedInSphinx10Warning
 from sphinx.transforms import SphinxTransformer
 from sphinx.util import logging
 from sphinx.util.docutils import LoggingReporter
@@ -27,13 +29,23 @@
 
 logger = logging.getLogger(__name__)
 
+warnings.warn('sphinx.io is deprecated', RemovedInSphinx10Warning, stacklevel=2)
+
 
 class SphinxBaseReader(standalone.Reader):  # type: ignore[misc]
     """A base class of readers for Sphinx.
 
     This replaces reporter by Sphinx's on generating document.
     """
 
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        warnings.warn(
+            'sphinx.io.SphinxBaseReader is deprecated',
+            RemovedInSphinx10Warning,
+            stacklevel=2,
+        )
+
     transforms: list[type[Transform]] = []
 
     def get_transforms(self) -> list[type[Transform]]:
@@ -67,6 +79,14 @@ def new_document(self) -> nodes.document:
 class SphinxStandaloneReader(SphinxBaseReader):
     """A basic document reader for Sphinx."""
 
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        warnings.warn(
+            'sphinx.io.SphinxStandaloneReader is deprecated',
+            RemovedInSphinx10Warning,
+            stacklevel=2,
+        )
+
     def _setup_transforms(self, transforms: list[type[Transform]], /) -> None:
         self.transforms = self.transforms + transforms
 
@@ -92,6 +112,14 @@ def read_source(self, env: BuildEnvironment) -> str:
 class SphinxDummyWriter(UnfilteredWriter):  # type: ignore[type-arg]
     """Dummy writer module used for generating doctree."""
 
+    def __init__(self) -> None:
+        super().__init__()
+        warnings.warn(
+            'sphinx.io.SphinxDummyWriter is deprecated',
+            RemovedInSphinx10Warning,
+            stacklevel=2,
+        )
+
     supported = ('html',)  # needed to keep "meta" nodes
 
     def translate(self) -> None:
@@ -100,6 +128,11 @@ def translate(self) -> None:
 
 def SphinxDummySourceClass(source: Any, *args: Any, **kwargs: Any) -> Any:
     """Bypass source object as is to cheat Publisher."""
+    warnings.warn(
+        'sphinx.io.SphinxDummySourceClass is deprecated',
+        RemovedInSphinx10Warning,
+        stacklevel=2,
+    )
     return source
 
 
@@ -109,3 +142,8 @@ class SphinxFileInput(FileInput):
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         kwargs['error_handler'] = 'sphinx'
         super().__init__(*args, **kwargs)
+        warnings.warn(
+            'sphinx.io.SphinxFileInput is deprecated',
+            RemovedInSphinx10Warning,
+            stacklevel=2,
+        )