Deprecate Parser.{config,env} (#13644)

Author: AA-Turner

CHANGES.rst

@@ -20,7 +20,8 @@ Deprecated
   Patch by Adam Turner.
 * #13637: Deprecate the :py:meth:`!set_application` method
   of :py:class:`~sphinx.parsers.Parser` objects.
-  Sphinx now directly sets the :py:attr:`!config` and :py:attr:`!env` attributes.
+  Patch by Adam Turner.
+* #13644: Deprecate the :py:attr:`!Parser.config` and :py:attr:`!env` attributes.
   Patch by Adam Turner.
 
 Features added

sphinx/parsers.py

@@ -24,21 +24,31 @@
 
 
 class Parser(docutils.parsers.Parser):
-    """A base class of source parsers.
+    """A base class for source parsers.
 
-    The additional parsers should inherit this class
-    instead of ``docutils.parsers.Parser``.
-    Compared with ``docutils.parsers.Parser``,
-    this class improves accessibility to Sphinx APIs.
-
-    The subclasses can access sphinx core runtime objects (app, config and env).
+    Additional parsers should inherit from this class instead of
+    ``docutils.parsers.Parser``.
+    This class provides access to core Sphinx objects; *config* and *env*.
     """
 
-    #: The config object
-    config: Config
+    _config: Config
+    _env: BuildEnvironment
+
+    @property
+    def config(self) -> Config:
+        """The config object."""
+        cls_module = self.__class__.__module__
+        cls_name = self.__class__.__qualname__
+        _deprecation_warning(cls_module, f'{cls_name}.config', remove=(9, 0))
+        return self._config
 
-    #: The environment object
-    env: BuildEnvironment
+    @property
+    def env(self) -> BuildEnvironment:
+        """The environment object."""
+        cls_module = self.__class__.__module__
+        cls_name = self.__class__.__qualname__
+        _deprecation_warning(cls_module, f'{cls_name}.env', remove=(9, 0))
+        return self._env
 
     def set_application(self, app: Sphinx) -> None:
         """set_application will be called from Sphinx to set app and other instance variables
@@ -47,9 +57,9 @@ def set_application(self, app: Sphinx) -> None:
         """
         cls_module = self.__class__.__module__
         cls_name = self.__class__.__qualname__
-        _deprecation_warning(cls_module, f'{cls_name}.set_application', remove=(10, 0))
-        self.config = app.config
-        self.env = app.env
+        _deprecation_warning(cls_module, f'{cls_name}.set_application', remove=(9, 0))
+        self._config = app.config
+        self._env = app.env
 
 
 class RSTParser(docutils.parsers.rst.Parser, Parser):

sphinx/registry.py

@@ -381,8 +381,8 @@ def create_source_parser(
         parser_class = self.get_source_parser(filename)
         parser = parser_class()
         if isinstance(parser, SphinxParser):
-            parser.config = config
-            parser.env = env
+            parser._config = config
+            parser._env = env
         return parser
 
     def add_translator(

sphinx/testing/restructuredtext.py

@@ -22,8 +22,8 @@ def parse(app: Sphinx, text: str, docname: str = 'index') -> nodes.document:
         reader = SphinxStandaloneReader()
         reader._setup_transforms(app.registry.get_transforms())
         parser = RSTParser()
-        parser.config = app.config
-        parser.env = app.env
+        parser._config = app.config
+        parser._env = app.env
         with sphinx_domains(env):
             return publish_doctree(
                 text,

tests/test_markup/test_parser.py

@@ -16,8 +16,8 @@ def test_RSTParser_prolog_epilog(RSTStateMachine, app):
     document = new_document('dummy.rst')
     document.settings = Mock(tab_width=8, language_code='')
     parser = RSTParser()
-    parser.config = app.config
-    parser.env = app.env
+    parser._config = app.config
+    parser._env = app.env
 
     # normal case
     text = 'hello Sphinx world\nSphinx is a document generator'