[Docutils-develop] [PATCH] Revert FutureWarnings.

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

Only add warnigns to core functions, if users can avoid this
warnings following a recommended practice.

For core API functions and classes: don't change the behaviour
but replace with new function(s) showing new behaviour.
This way users can switch to the new behaviour at some stage during the
transition period.
Add a deprecation warning once the new functions are in place.

# Suggestion for the next step to solve the "string I/O" problem.
# OK to commit?
---
 docutils/docutils/core.py |  2 --
 docutils/docutils/io.py   | 27 +++++++++++++--------------
 2 files changed, 13 insertions(+), 16 deletions(-)

diff --git a/docutils/docutils/core.py b/docutils/docutils/core.py
index a54ed7a90..edbcfc3df 100644
--- a/docutils/docutils/core.py
+++ b/docutils/docutils/core.py
@@ -443,8 +443,6 @@ def publish_string(source, source_path=None, destination_path=None,
 
     Parameters: see `publish_programmatically`.
     """
-    warnings.warn('The return type of publish_string will change to '
-                  '"str" from Docutils 0.21.', FutureWarning, stacklevel=2)
     output, pub = publish_programmatically(
         source_class=io.StringInput, source=source, source_path=source_path,
         destination_class=io.StringOutput,
diff --git a/docutils/docutils/io.py b/docutils/docutils/io.py
index 53e93886a..12342025d 100644
--- a/docutils/docutils/io.py
+++ b/docutils/docutils/io.py
@@ -247,6 +247,11 @@ class Output(TransformSpec):
         raise NotImplementedError
 
     def encode(self, data):
+        """Encode `data` with `self.encoding` (unless it is already encoded).
+
+        If `self.encoding` is set to the pseudo encoding name "unicode",
+        `data` must be a `str` instance and is returned unchanged.
+        """
         if self.encoding and self.encoding.lower() == 'unicode':
             assert isinstance(data, str), (
                 'the encoding given is "unicode" but the output is not '
@@ -581,7 +586,7 @@ class StringInput(Input):
     default_source_path = '<string>'
 
     def read(self):
-        """Return the source as `str` instance.
+        """Return the source as `str` object.
 
         Decode, if required (see `Input.decode`).
         """
@@ -589,26 +594,20 @@ class StringInput(Input):
 
 
 class StringOutput(Output):
-
-    """
-    Direct string output.
-    """
+    """Output to a `bytes` or `str` instance."""
 
     default_destination_path = '<string>'
 
     def write(self, data):
-        """Encode `data`, store it in `self.destination`, and return it."""
+        """Encode `data`, store it in `self.destination`, and return it.
+
+        If `self.encoding` is set to the pseudo encoding name "unicode",
+        `data` must be a `str` instance and is returned unchanged.
+        (cf. `Output.encode`)
+        """
         self.destination = self.encode(data)
         return self.destination
 
-    def encode(self, data):
-        data = super().encode(data)
-        if not isinstance(data, str):
-            warnings.warn("StringOutput.encode()'s return type will change to "
-                          f'``str`` from Docutils 0.21, got type {type(data)}',
-                          FutureWarning, stacklevel=2)
-        return data
-
 
 class NullInput(Input):
 
-- 
2.30.2