SF.net SVN: docutils:[10146] trunk/docutils
milde--- via Docutils-checkins <[email protected]> Tue, 27 May 2025 06:14:27 +0000
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 10146
http://sourceforge.net/p/docutils/code/10146
Author: milde
Date: 2025-05-27 06:14:22 +0000 (Tue, 27 May 2025)
Log Message:
-----------
Deprecate the `TransformSpec.unknown_reference_resolvers` hook chain.
`unknown_reference_resolvers` were introduced to support component-specific
resolving of unknown references. Ian Bicking's "Wiki.py" module in the sandbox
shows that a simple transform can be used for that task.
Removing the hook and its complex specification will simplify both,
API and code base without loss of functionality.
The only known use case is the MoinMoin wiki.1
Versions <= 1.9 register a "resolver" function for "Wiki references".
MoinMoin 2.0 does not use the "unknown_reference_resolvers" hook;
MoinMoin 1.9 requires Python 2, so a removal will not affect
existing installations.
1 The LaTeX writer uses a "resolver function" for BibTeX citation_references
in Docutils 0.22 development and pre-release versions.
It will be changed to use a transform in the next commit.
Modified Paths:
--------------
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docutils/__init__.py
trunk/docutils/docutils/io.py
trunk/docutils/docutils/transforms/__init__.py
trunk/docutils/test/test_transforms/test__init__.py
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2025-05-25 21:05:14 UTC (rev 10145)
+++ trunk/docutils/RELEASE-NOTES.rst 2025-05-27 06:14:22 UTC (rev 10146)
@@ -163,6 +163,9 @@
* Remove the input_encoding_ auto-detection code in Docutils 1.0.
+* Remove the "TransformSpec.unknown_reference_resolvers" hook chain
+ in Docutils 1.0. Use a transform.
+
* Remove `parsers.rst.roles.set_classes()` and
`parsers.rst.roles.normalized_role_options()`
(obsoleted by `parsers.rst.roles.normalize_options()`) in Docutils 2.0.
Modified: trunk/docutils/docutils/__init__.py
===================================================================
--- trunk/docutils/docutils/__init__.py 2025-05-25 21:05:14 UTC (rev 10145)
+++ trunk/docutils/docutils/__init__.py 2025-05-27 06:14:22 UTC (rev 10146)
@@ -75,7 +75,8 @@
]
class _UnknownReferenceResolver(Protocol):
- """See `TransformSpec.unknown_reference_resolvers`."""
+ """Deprecated. Will be removed in Docutils 1.0."""
+ # See `TransformSpec.unknown_reference_resolvers`.
priority: int
@@ -284,41 +285,39 @@
unknown_reference_resolvers: Sequence[_UnknownReferenceResolver] = ()
"""List of hook functions which assist in resolving references.
- Override in subclasses to implement component-specific resolving of
- unknown references.
-
- Unknown references have a 'refname' attribute which doesn't correspond
- to any target in the document. Called when the transforms in
- `docutils.transforms.references` are unable to find a correct target.
-
- The list should contain functions which will try to resolve unknown
- references, with the following signature::
-
- def reference_resolver(node: nodes.Element) -> bool:
- '''Returns boolean: true if resolved, false if not.'''
-
- If the function is able to resolve the reference, it should also remove
- the 'refname' attribute and mark the node as resolved::
-
- del node['refname']
- node.resolved = True
-
- Each function must have a "priority" attribute which will affect the order
- the unknown_reference_resolvers are run
- cf. ../docs/api/transforms.html#transform-priority-range-categories ::
-
- reference_resolver.priority = 500
-
- Examples:
- `writers.latex2e.Writer` defines a resolver to mark citation references
- as resolved by BibTeX if the "use_bibtex" configuration setting is set.
-
- The `MoinMoin ReStructured Text Parser`__ provides a resolver for
- "WikiWiki links" (currently only in the outdated 1.9 version).
-
- __ https://github.com/moinwiki/moin-1.9/blob/1.9.11/MoinMoin/parser/
- text_rst.py
+ Deprecated. Will be removed in Docutils 1.0
"""
+ # Override in subclasses to implement component-specific resolving of
+ # unknown references.
+ #
+ # Unknown references have a 'refname' attribute which doesn't correspond
+ # to any target in the document. Called when the transforms in
+ # `docutils.transforms.references` are unable to find a correct target.
+ #
+ # The list should contain functions which will try to resolve unknown
+ # references, with the following signature::
+ #
+ # def reference_resolver(node: nodes.Element) -> bool:
+ # '''Returns boolean: true if resolved, false if not.'''
+ #
+ # If the function is able to resolve the reference, it should also remove
+ # the 'refname' attribute and mark the node as resolved::
+ #
+ # del node['refname']
+ # node.resolved = True
+ #
+ # Each function must have a "priority" attribute which will affect the
+ # order the unknown_reference_resolvers are run
+ # cf. ../docs/api/transforms.html#transform-priority-range-categories ::
+ #
+ # reference_resolver.priority = 500
+ #
+ # Examples:
+ # The `MoinMoin ReStructured Text Parser`__ provided a resolver for
+ # "WikiWiki links" in the 1.9 version.
+ #
+ # __ https://github.com/moinwiki/moin-1.9/blob/1.9.11/MoinMoin/parser/
+ # text_rst.py
class Component(SettingsSpec, TransformSpec):
Modified: trunk/docutils/docutils/io.py
===================================================================
--- trunk/docutils/docutils/io.py 2025-05-25 21:05:14 UTC (rev 10145)
+++ trunk/docutils/docutils/io.py 2025-05-27 06:14:22 UTC (rev 10146)
@@ -82,9 +82,9 @@
Docutils input objects must provide a `read()` method that
returns the source, typically as `str` instance.
- Inheriting `TransformSpec` allows input objects to add
- "transforms" and "unknown_reference_resolvers" to the "Transformer".
- (Optional for custom input objects since Docutils 0.19.)
+ Inheriting `TransformSpec` allows input objects to add "transforms" to
+ the "Transformer". (Since Docutils 0.19, input objects are no longer
+ required to be `TransformSpec` instances.)
"""
component_type: Final = 'input'
@@ -242,9 +242,9 @@
Docutils output objects must provide a `write()` method that
expects and handles one argument (the output).
- Inheriting `TransformSpec` allows output objects to add
- "transforms" and "unknown_reference_resolvers" to the "Transformer".
- (Optional for custom output objects since Docutils 0.19.)
+ Inheriting `TransformSpec` allows output objects to add "transforms" to
+ the "Transformer". (Since Docutils 0.19, output objects are no longer
+ required to be `TransformSpec` instances.)
"""
component_type: Final = 'output'
Modified: trunk/docutils/docutils/transforms/__init__.py
===================================================================
--- trunk/docutils/docutils/transforms/__init__.py 2025-05-25 21:05:14 UTC (rev 10145)
+++ trunk/docutils/docutils/transforms/__init__.py 2025-05-27 06:14:22 UTC (rev 10146)
@@ -25,6 +25,8 @@
__docformat__ = 'reStructuredText'
+import warnings
+
from docutils import languages, ApplicationError, TransformSpec
@@ -64,8 +66,8 @@
"""
Store "transforms" and apply them to the document tree.
- Collect lists of `Transform` instances and "unknown_reference_resolvers"
- from Docutils components (`TransformSpec` instances).
+ Collect lists of `Transform` instances from Docutils
+ components (`TransformSpec` instances).
Apply collected "transforms" to the document tree.
Also keeps track of components by component type name.
@@ -80,8 +82,11 @@
"""
self.unknown_reference_resolvers = []
- """List of hook functions which assist in resolving references."""
+ """List of hook functions which assist in resolving references.
+ Deprecated. Will be removed in Docutils 1.0.
+ """
+
self.document = document
"""The `nodes.document` object this Transformer is attached to."""
@@ -167,6 +172,11 @@
return f.priority
resolvers.sort(key=keyfun)
self.unknown_reference_resolvers += resolvers
+ if self.unknown_reference_resolvers:
+ warnings.warn('The `unknown_reference_resolvers` hook chain '
+ 'will be removed in Docutils 1.0.\n'
+ 'Use a transform to resolve references.',
+ DeprecationWarning, stacklevel=2)
def apply_transforms(self) -> None:
"""Apply all of the stored transforms, in priority order."""
Modified: trunk/docutils/test/test_transforms/test__init__.py
===================================================================
--- trunk/docutils/test/test_transforms/test__init__.py 2025-05-25 21:05:14 UTC (rev 10145)
+++ trunk/docutils/test/test_transforms/test__init__.py 2025-05-27 06:14:22 UTC (rev 10146)
@@ -17,6 +17,7 @@
# so we import the local `docutils` package.
sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
+import docutils
from docutils import transforms, utils
@@ -47,5 +48,21 @@
self.assertEqual(transform_record[3], {'foo': 42})
+class TransformerWarningsTestCase(unittest.TestCase):
+
+ @staticmethod
+ def dummy_resolver(node):
+ # Cf. `TransformSpec.unknown_reference_resolvers`.
+ return node.resolved
+
+ def test_deprecation_warnings(self):
+ transformer = transforms.Transformer(utils.new_document('test data'))
+ component = docutils.Component()
+ component.unknown_reference_resolvers = [self.dummy_resolver]
+ self.dummy_resolver.priority = 50
+ with self.assertWarnsRegex(DeprecationWarning, 'will be removed'):
+ transformer.populate_from_components([component])
+
+
if __name__ == '__main__':
unittest.main()
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins