[Docutils-checkins] SF.net SVN: docutils:[9769] trunk/docutils

[<mi...@us...>]

Revision: 9769
          http://sourceforge.net/p/docutils/code/9769
Author:   milde
Date:     2024-06-18 07:44:41 +0000 (Tue, 18 Jun 2024)
Log Message:
-----------
Deprecate "parser_name" argument of `readers.Reader.__init__()`.

Instead, the "parser" argument accepts now a parser name as well as
a `parsers.Parser` instance.

Also change some boolean values from `1` to `True`.

Modified Paths:
--------------
    trunk/docutils/HISTORY.txt
    trunk/docutils/docutils/readers/__init__.py
    trunk/docutils/docutils/readers/pep.py
    trunk/docutils/test/functional/tests/pep_html.py

Added Paths:
-----------
    trunk/docutils/test/test_readers/test__init__.py

Removed Paths:
-------------
    trunk/docutils/test/test_readers/test_get_reader_class.py

Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt	2024-06-15 12:08:27 UTC (rev 9768)
+++ trunk/docutils/HISTORY.txt	2024-06-18 07:44:41 UTC (rev 9769)
@@ -77,6 +77,10 @@
   - Renamed `normalized_role_options()` to `normalized_role_options()`
     (it is now also used for directive options).
 
+* docutils/readers/__init__.py:
+
+  - Deprecate "parser_name" argument of `Reader.__init__()`.
+
 * docutils/transforms/frontmatter.py
 
   - Update `DocInfo` to work with corrected element categories.

Modified: trunk/docutils/docutils/readers/__init__.py
===================================================================
--- trunk/docutils/docutils/readers/__init__.py	2024-06-15 12:08:27 UTC (rev 9768)
+++ trunk/docutils/docutils/readers/__init__.py	2024-06-18 07:44:41 UTC (rev 9769)
@@ -9,6 +9,7 @@
 __docformat__ = 'reStructuredText'
 
 from importlib import import_module
+import warnings
 
 from docutils import utils, parsers, Component
 from docutils.transforms import universal
@@ -38,6 +39,9 @@
         """
         Initialize the Reader instance.
 
+        :parser: A parser instance or name (an instance will be created).
+        :parser_name: deprecated, use "parser".
+
         Several instance attributes are defined with dummy initial values.
         Subclasses may use these attributes as they wish.
         """
@@ -46,8 +50,15 @@
         """A `parsers.Parser` instance shared by all doctrees.  May be left
         unspecified if the document source determines the parser."""
 
-        if parser is None and parser_name:
-            self.set_parser(parser_name)
+        if isinstance(parser, str):
+            self.set_parser(parser)
+        if parser_name is not None:
+            warnings.warn('Argument "parser_name" will be removed '
+                          'in Docutils 2.0.\n'
+                          '  Specify parser name in the "parser" argument.',
+                          DeprecationWarning, stacklevel=2)
+            if self.parser is None:
+                self.set_parser(parser_name)
 
         self.source = None
         """`docutils.io` IO object, source of input data."""

Modified: trunk/docutils/docutils/readers/pep.py
===================================================================
--- trunk/docutils/docutils/readers/pep.py	2024-06-15 12:08:27 UTC (rev 9768)
+++ trunk/docutils/docutils/readers/pep.py	2024-06-18 07:44:41 UTC (rev 9769)
@@ -8,7 +8,6 @@
 
 __docformat__ = 'reStructuredText'
 
-
 from docutils.readers import standalone
 from docutils.transforms import peps, frontmatter
 from docutils.parsers import rst
@@ -37,12 +36,18 @@
         transforms.extend([peps.Headers, peps.Contents, peps.TargetNotes])
         return transforms
 
-    settings_default_overrides = {'pep_references': 1, 'rfc_references': 1}
+    settings_default_overrides = {'pep_references': True,
+                                  'rfc_references': True}
 
     inliner_class = rst.states.Inliner
 
     def __init__(self, parser=None, parser_name=None):
-        """`parser` should be ``None``."""
-        if parser is None:
+        """`parser` should be ``None``, `parser_name` is ignored.
+
+        The default parser is "rst" with PEP-specific settings
+        (since Docutils 0.3). Since Docutils 0.22, `parser` is ignored,
+        if it is a `str` instance.
+        """
+        if parser is None or isinstance(parser, str):
             parser = rst.Parser(rfc2822=True, inliner=self.inliner_class())
-        standalone.Reader.__init__(self, parser, '')
+        super().__init__(parser)

Modified: trunk/docutils/test/functional/tests/pep_html.py
===================================================================
--- trunk/docutils/test/functional/tests/pep_html.py	2024-06-15 12:08:27 UTC (rev 9768)
+++ trunk/docutils/test/functional/tests/pep_html.py	2024-06-18 07:44:41 UTC (rev 9769)
@@ -8,8 +8,8 @@
 settings_overrides = {
     'python_home': "http://www.python.org",
     'pep_home': "http://www.python.org/peps",
-    'no_random': 1,
-    'cloak_email_addresses': 1,
+    'no_random': True,
+    'cloak_email_addresses': True,
     # local copy of default stylesheet:
     'stylesheet_path': 'functional/input/data/html4css1.css',
     }

Added: trunk/docutils/test/test_readers/test__init__.py
===================================================================
--- trunk/docutils/test/test_readers/test__init__.py	                        (rev 0)
+++ trunk/docutils/test/test_readers/test__init__.py	2024-06-18 07:44:41 UTC (rev 9769)
@@ -0,0 +1,78 @@
+#! /usr/bin/env python3
+
+# $Id$
+# Author: grubert abadger1999
+# Maintainer: doc...@li...
+# Copyright: This module has been placed in the public domain.
+
+"""Test the "docutils.readers" module."""
+
+from pathlib import Path
+import sys
+import unittest
+
+# Prepend the "docutils root" to the Python library path
+# so we import the local `docutils` and `test` packages.
+# ensure `test` package can be loaded also if not running as __main__
+# (required by ``python -m unittest``
+DOCUTILS_ROOT = Path(__file__).resolve().parents[2]
+if str(DOCUTILS_ROOT) not in sys.path:
+    sys.path.insert(0, str(DOCUTILS_ROOT))
+
+from docutils import parsers, readers  # noqa: E402
+
+
+class ReaderTests(unittest.TestCase):
+
+    def test__init__(self):
+        # Initialization also instantiates a parser, if one is specified.
+        reader = readers.Reader()
+        self.assertEqual(reader.parser, None)
+        # The parser can be specified via its name
+        reader = readers.Reader('rst')
+        self.assertTrue(isinstance(reader.parser, parsers.rst.Parser),
+                        f'should be Parser instance, not {reader.parser!r}')
+        # or passed as instance
+        parser = parsers.rst.Parser()
+        reader = readers.Reader(parser)
+        self.assertEqual(reader.parser, parser)
+        # # the second argument `parser_name` is deprecated
+        with self.assertWarnsRegex(
+            DeprecationWarning,
+            'Specify parser name in the "parser" argument.'):
+            reader = readers.Reader(parser_name='rst')
+        self.assertTrue(isinstance(reader.parser, parsers.rst.Parser))
+        # if both arguments are specified, `parser` has precedence:
+        with self.assertWarns(DeprecationWarning):
+            reader = readers.Reader(parser, parser_name='null')
+        self.assertEqual(reader.parser, parser)
+
+        # __init__() is inherited or called by the standard readers:
+        reader = readers.get_reader_class('standalone')('null')
+        self.assertTrue(isinstance(reader, readers.standalone.Reader))
+        self.assertTrue(isinstance(reader.parser, parsers.null.Parser))
+
+        reader = readers.get_reader_class('pep')()
+        self.assertTrue(isinstance(reader, readers.pep.Reader))
+        # the "pep" reader uses the "rst" parser with special settings
+        self.assertTrue(isinstance(reader.parser, parsers.rst.Parser))
+
+
+class GetReaderClassTestCase(unittest.TestCase):
+
+    def test_registered_reader(self):
+        reader_class = readers.get_reader_class('pep')
+        self.assertEqual(reader_class, readers.pep.Reader)
+
+    def test_bogus_reader(self):
+        with self.assertRaises(ImportError):
+            readers.get_reader_class('nope')
+
+    def test_local_reader(self):
+        # requires local-reader.py in `test` package
+        reader_class = readers.get_reader_class('test.local-reader')
+        self.assertEqual(reader_class.supported, ('dummy', ))
+
+
+if __name__ == '__main__':
+    unittest.main()


Property changes on: trunk/docutils/test/test_readers/test__init__.py
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: svn:keywords
## -0,0 +1 ##
+Author Date Id Revision
\ No newline at end of property
Deleted: trunk/docutils/test/test_readers/test_get_reader_class.py
===================================================================
--- trunk/docutils/test/test_readers/test_get_reader_class.py	2024-06-15 12:08:27 UTC (rev 9768)
+++ trunk/docutils/test/test_readers/test_get_reader_class.py	2024-06-18 07:44:41 UTC (rev 9769)
@@ -1,44 +0,0 @@
-#! /usr/bin/env python3
-
-# $Id$
-# Author: grubert abadger1999
-# Maintainer: doc...@li...
-# Copyright: This module has been placed in the public domain.
-
-"""
-test get_reader_class
-"""
-
-from pathlib import Path
-import sys
-import unittest
-
-# Prepend the "docutils root" to the Python library path
-# so we import the local `docutils` and `test` packages.
-# ensure `test` package can be loaded also if not running as __main__
-# (required by ``python -m unittest``
-DOCUTILS_ROOT = Path(__file__).resolve().parents[2]
-if str(DOCUTILS_ROOT) not in sys.path:
-    sys.path.insert(0, str(DOCUTILS_ROOT))
-
-from docutils.readers import get_reader_class  # noqa: E402
-
-
-class GetReaderClassTestCase(unittest.TestCase):
-
-    def test_registered_reader(self):
-        get_reader_class('pep')
-        # raises ImportError on failure
-
-    def test_bogus_reader(self):
-        with self.assertRaises(ImportError):
-            get_reader_class('nope')
-
-    def test_local_reader(self):
-        # requires local-reader.py in `test` package
-        get_reader_class('test.local-reader')
-        # raises ImportError on failure
-
-
-if __name__ == '__main__':
-    unittest.main()

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.