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

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

Revision: 9762
          http://sourceforge.net/p/docutils/code/9762
Author:   milde
Date:     2024-06-14 16:19:20 +0000 (Fri, 14 Jun 2024)
Log Message:
-----------
Define/use auxiliary function `parsers.rst.roles.normalize_options()`.

Renamed from `parsers.rst.roles.normalized_role_options()` (it is now also
used for directive options).
Replaces `parsers.rst.roles.set_classes()`

The obsoleted functions will be removed in Docutils 1.0.

Modified Paths:
--------------
    trunk/docutils/HISTORY.txt
    trunk/docutils/RELEASE-NOTES.txt
    trunk/docutils/docutils/parsers/rst/directives/admonitions.py
    trunk/docutils/docutils/parsers/rst/directives/body.py
    trunk/docutils/docutils/parsers/rst/directives/images.py
    trunk/docutils/docutils/parsers/rst/roles.py

Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt	2024-06-14 15:04:19 UTC (rev 9761)
+++ trunk/docutils/HISTORY.txt	2024-06-14 16:19:20 UTC (rev 9762)
@@ -72,6 +72,11 @@
   - Removed `CSVTable.decode_from_csv()` and `CSVTable.encode_from_csv()`.
     Not required with Python 3.
 
+* docutils/parsers/rst/roles.py
+
+  - Renamed `normalized_role_options()` to `normalized_role_options()`
+    (it is now also used for directive options).
+
 * docutils/transforms/frontmatter.py
 
   - Update `DocInfo` to work with corrected element categories.
@@ -3639,11 +3644,11 @@
 * docutils/languages/sk.py: Added to project; Slovak mappings by
   Miroslav Vasko.
 
-* docutils/parser/__init__.py:
+* docutils/parsers/__init__.py:
 
   - Added ``Parser.finish_parse()`` method.
 
-* docutils/parser/rst/__init__.py:
+* docutils/parsers/rst/__init__.py:
 
   - Added options: ``--pep-references``, ``--rfc-references``,
     ``--tab-width``, ``--trim-footnote-reference-space``.

Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt	2024-06-14 15:04:19 UTC (rev 9761)
+++ trunk/docutils/RELEASE-NOTES.txt	2024-06-14 16:19:20 UTC (rev 9762)
@@ -140,6 +140,9 @@
 
 * Remove the input encoding auto-detection code in Docutils 1.0.
 
+* Remove `parsers.rst.roles.set_classes()` and
+  `parsers.rst.roles.normalized_role_options()` in Docutils 1.0.
+
 * Remove the "rawsource" argument from `nodes.Text.__init__()`
   in Docutils 2.0.
 

Modified: trunk/docutils/docutils/parsers/rst/directives/admonitions.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/directives/admonitions.py	2024-06-14 15:04:19 UTC (rev 9761)
+++ trunk/docutils/docutils/parsers/rst/directives/admonitions.py	2024-06-14 16:19:20 UTC (rev 9762)
@@ -11,7 +11,7 @@
 
 from docutils.parsers.rst import Directive
 from docutils.parsers.rst import directives
-from docutils.parsers.rst.roles import set_classes
+from docutils.parsers.rst.roles import normalize_options
 from docutils import nodes
 
 
@@ -26,10 +26,10 @@
     """Subclasses must set this to the appropriate admonition node class."""
 
     def run(self):
-        set_classes(self.options)
+        options = normalize_options(self.options)
         self.assert_has_content()
         text = '\n'.join(self.content)
-        admonition_node = self.node_class(text, **self.options)
+        admonition_node = self.node_class(text, **options)
         self.add_name(admonition_node)
         admonition_node.source, admonition_node.line = \
             self.state_machine.get_source_and_line(self.lineno)
@@ -42,7 +42,7 @@
                     self.state_machine.get_source_and_line(self.lineno))
             admonition_node += title
             admonition_node += messages
-            if 'classes' not in self.options:
+            if 'classes' not in options:
                 admonition_node['classes'] += ['admonition-'
                                                + nodes.make_id(title_text)]
         self.state.nested_parse(self.content, self.content_offset,

Modified: trunk/docutils/docutils/parsers/rst/directives/body.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/directives/body.py	2024-06-14 15:04:19 UTC (rev 9761)
+++ trunk/docutils/docutils/parsers/rst/directives/body.py	2024-06-14 16:19:20 UTC (rev 9762)
@@ -14,7 +14,7 @@
 from docutils import nodes
 from docutils.parsers.rst import Directive
 from docutils.parsers.rst import directives
-from docutils.parsers.rst.roles import set_classes
+from docutils.parsers.rst.roles import normalize_options
 from docutils.utils.code_analyzer import Lexer, LexerError, NumberLines
 
 
@@ -116,11 +116,11 @@
     has_content = True
 
     def run(self):
-        set_classes(self.options)
+        options = normalize_options(self.options)
         self.assert_has_content()
         text = '\n'.join(self.content)
         text_nodes, messages = self.state.inline_text(text, self.lineno)
-        node = nodes.literal_block(text, '', *text_nodes, **self.options)
+        node = nodes.literal_block(text, '', *text_nodes, **options)
         node.line = self.content_offset + 1
         self.add_name(node)
         return [node] + messages
@@ -147,12 +147,12 @@
             language = self.arguments[0]
         else:
             language = ''
-        set_classes(self.options)
+        options = normalize_options(self.options)
         classes = ['code']
         if language:
             classes.append(language)
-        if 'classes' in self.options:
-            classes.extend(self.options['classes'])
+        if 'classes' in options:
+            classes.extend(options['classes'])
 
         # set up lexical analyzer
         try:
@@ -165,10 +165,10 @@
             else:
                 raise self.warning(error)
 
-        if 'number-lines' in self.options:
+        if 'number-lines' in options:
             # optional argument `startline`, defaults to 1
             try:
-                startline = int(self.options['number-lines'] or 1)
+                startline = int(options['number-lines'] or 1)
             except ValueError:
                 raise self.error(':number-lines: with non-integer start value')
             endline = startline + len(self.content)
@@ -178,8 +178,8 @@
         node = nodes.literal_block('\n'.join(self.content), classes=classes)
         self.add_name(node)
         # if called from "include", set the source
-        if 'source' in self.options:
-            node.attributes['source'] = self.options['source']
+        if 'source' in options:
+            node.attributes['source'] = options['source']
         # analyze content and add nodes for every token
         for classes, value in tokens:
             if classes:
@@ -201,7 +201,7 @@
     has_content = True
 
     def run(self):
-        set_classes(self.options)
+        options = normalize_options(self.options)
         self.assert_has_content()
         # join lines, separate blocks
         content = '\n'.join(self.content).split('\n\n')
@@ -209,7 +209,7 @@
         for block in content:
             if not block:
                 continue
-            node = nodes.math_block(self.block_text, block, **self.options)
+            node = nodes.math_block(self.block_text, block, **options)
             (node.source,
              node.line) = self.state_machine.get_source_and_line(self.lineno)
             self.add_name(node)
@@ -226,10 +226,10 @@
                    'name': directives.unchanged}
 
     def run(self):
-        set_classes(self.options)
+        options = normalize_options(self.options)
         rubric_text = self.arguments[0]
         textnodes, messages = self.state.inline_text(rubric_text, self.lineno)
-        rubric = nodes.rubric(rubric_text, '', *textnodes, **self.options)
+        rubric = nodes.rubric(rubric_text, '', *textnodes, **options)
         self.add_name(rubric)
         return [rubric] + messages
 

Modified: trunk/docutils/docutils/parsers/rst/directives/images.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/directives/images.py	2024-06-14 15:04:19 UTC (rev 9761)
+++ trunk/docutils/docutils/parsers/rst/directives/images.py	2024-06-14 16:19:20 UTC (rev 9762)
@@ -24,7 +24,7 @@
 from docutils.nodes import fully_normalize_name, whitespace_normalize_name
 from docutils.parsers.rst import Directive
 from docutils.parsers.rst import directives, states
-from docutils.parsers.rst.roles import set_classes
+from docutils.parsers.rst.roles import normalize_options
 
 
 class Image(Directive):
@@ -95,8 +95,8 @@
             else:                           # malformed target
                 messages.append(data)       # data is a system message
             del self.options['target']
-        set_classes(self.options)
-        image_node = nodes.image(self.block_text, **self.options)
+        options = normalize_options(self.options)
+        image_node = nodes.image(self.block_text, **options)
         (image_node.source,
          image_node.line) = self.state_machine.get_source_and_line(self.lineno)
         self.add_name(image_node)

Modified: trunk/docutils/docutils/parsers/rst/roles.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/roles.py	2024-06-14 15:04:19 UTC (rev 9761)
+++ trunk/docutils/docutils/parsers/rst/roles.py	2024-06-14 16:19:20 UTC (rev 9762)
@@ -76,6 +76,7 @@
 
 __docformat__ = 'reStructuredText'
 
+import warnings
 
 from docutils import nodes
 from docutils.parsers.rst import directives
@@ -207,7 +208,7 @@
 
     def __call__(self, role, rawtext, text, lineno, inliner,
                  options=None, content=None):
-        options = normalized_role_options(options)
+        options = normalize_options(options)
         return [self.node_class(rawtext, text, **options)], []
 
 
@@ -224,7 +225,7 @@
 
     def __call__(self, role, rawtext, text, lineno, inliner,
                  options=None, content=None):
-        opts = normalized_role_options(self.supplied_options)
+        opts = normalize_options(self.supplied_options)
         try:
             opts.update(options)
         except TypeError:  # options may be ``None``
@@ -243,7 +244,7 @@
     """Base for custom roles if no other base role is specified."""
     # Once nested inline markup is implemented, this and other methods should
     # recursively call inliner.nested_parse().
-    options = normalized_role_options(options)
+    options = normalize_options(options)
     return [nodes.inline(rawtext, text, **options)], []
 
 
@@ -266,7 +267,7 @@
 
 def pep_reference_role(role, rawtext, text, lineno, inliner,
                        options=None, content=None):
-    options = normalized_role_options(options)
+    options = normalize_options(options)
     try:
         pepnum = int(nodes.unescape(text))
         if pepnum < 0 or pepnum > 9999:
@@ -288,7 +289,7 @@
 
 def rfc_reference_role(role, rawtext, text, lineno, inliner,
                        options=None, content=None):
-    options = normalized_role_options(options)
+    options = normalize_options(options)
     if "#" in text:
         rfcnum, section = nodes.unescape(text).split("#", 1)
     else:
@@ -315,7 +316,7 @@
 
 
 def raw_role(role, rawtext, text, lineno, inliner, options=None, content=None):
-    options = normalized_role_options(options)
+    options = normalize_options(options)
     if not inliner.document.settings.raw_enabled:
         msg = inliner.reporter.warning('raw (and derived) roles disabled')
         prb = inliner.problematic(rawtext, rawtext, msg)
@@ -340,7 +341,7 @@
 
 def code_role(role, rawtext, text, lineno, inliner,
               options=None, content=None):
-    options = normalized_role_options(options)
+    options = normalize_options(options)
     language = options.get('language', '')
     classes = ['code']
     if 'classes' in options:
@@ -375,7 +376,7 @@
 
 def math_role(role, rawtext, text, lineno, inliner,
               options=None, content=None):
-    options = normalized_role_options(options)
+    options = normalize_options(options)
     text = nodes.unescape(text, True)  # raw text without inline role markup
     node = nodes.math(rawtext, text, **options)
     return [node], []
@@ -411,11 +412,10 @@
 
 
 def set_classes(options):
-    """Deprecated. Obsoleted by ``normalized_role_options()``."""
-    # TODO: Change use in directives.py and uncomment.
-    # warnings.warn('The auxiliary function roles.set_classes() is obsoleted'
-    #     ' by roles.normalized_role_options() and will be removed'
-    #     ' in Docutils 0.21 or later', DeprecationWarning, stacklevel=2)
+    """Deprecated. Obsoleted by ``normalize_options()``."""
+    warnings.warn('The auxiliary function roles.set_classes() is obsoleted'
+                  ' by roles.normalize_options() and will be removed'
+                  ' in Docutils 1.0', DeprecationWarning, stacklevel=2)
     if options and 'class' in options:
         assert 'classes' not in options
         options['classes'] = options['class']
@@ -423,8 +423,15 @@
 
 
 def normalized_role_options(options):
+    warnings.warn('The auxiliary function roles.normalized_role_options() is '
+                  'obsoleted by roles.normalize_options() and will be removed'
+                  ' in Docutils 1.0', DeprecationWarning, stacklevel=2)
+    return normalize_options(options)
+
+
+def normalize_options(options):
     """
-    Return normalized dictionary of role options.
+    Return normalized dictionary of role/directive options.
 
     * ``None`` is replaced by an empty dictionary.
     * The key 'class' is renamed to 'classes'.
@@ -431,9 +438,9 @@
     """
     if options is None:
         return {}
-    result = options.copy()
-    if 'class' in result:
-        assert 'classes' not in result
-        result['classes'] = result['class']
-        del result['class']
-    return result
+    n_options = options.copy()
+    if 'class' in n_options:
+        assert 'classes' not in n_options
+        n_options['classes'] = n_options['class']
+        del n_options['class']
+    return n_options

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