Revert FutureWarnings.

Wait with warnings until a consensus is found about the future
"string/bytes" export API and stable usage patterns can be recommended.

git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk@9256 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

2 files changed, 14 insertions, 15 deletions

diff --git a/docutils/docutils/core.py b/docutils/docutils/core.py
index 58e9d087d..0d3d044bf 100644
--- a/docutils/docutils/core.py
+++ b/docutils/docutils/core.py
@@ -452,8 +452,6 @@ def publish_string(source, source_path=None, destination_path=None,
     .. _output_encoding:
         https://docutils.sourceforge.io/docs/user/config.html#output-encoding
     """
-    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..b8673d17e 100644
--- a/docutils/docutils/io.py
+++ b/docutils/docutils/io.py
@@ -247,6 +247,13 @@ 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 `data` is a `bytes` instance, it 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 '
@@ -589,26 +596,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):