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

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

Revision: 9366
          http://sourceforge.net/p/docutils/code/9366
Author:   milde
Date:     2023-04-26 21:00:10 +0000 (Wed, 26 Apr 2023)
Log Message:
-----------
Documentation fix/update.

The return value of `io.FileOutput` (and hence of `core.publish_cmdline()`
and `core.publish_file()`) is a `str` instance (except for
binary output document formats) and has always been under Python 3.

Modified Paths:
--------------
    trunk/docutils/docs/api/publisher.txt
    trunk/docutils/docutils/core.py

Modified: trunk/docutils/docs/api/publisher.txt
===================================================================
--- trunk/docutils/docs/api/publisher.txt	2023-04-26 12:57:44 UTC (rev 9365)
+++ trunk/docutils/docs/api/publisher.txt	2023-04-26 21:00:10 UTC (rev 9366)
@@ -42,13 +42,18 @@
 publish_cmdline()
 -----------------
 
-Function for command-line front-end tools, like ``rst2html.py`` with 
-file I/O. Also returns the output as `bytes` instance.
+Function for command-line front-end tools, like ``rst2html.py`` 
+or functions for `"console_scripts" entry points`_ like `core.rst2html()`
+with file I/O. 
+In addition to writing the output document to a file, also returns it as
+`str` instance (rsp. `bytes` for binary output document formats).
 
 There are several examples in the ``tools/`` directory of the Docutils
 repository. A detailed analysis of one such tool is in `Inside A Docutils
 Command-Line Front-End Tool`_.
 
+.. _"console_scripts" entry points:
+    https://packaging.python.org/en/latest/specifications/entry-points/
 .. _Inside A Docutils Command-Line Front-End Tool: ../howto/cmdline-tool.html
 
 
@@ -57,7 +62,7 @@
 
 For programmatic use with file-like I/O.
 In addition to writing the output document to a file, also returns it as
-a `bytes` instance.
+`str` instance (rsp. `bytes` for binary output document formats).
 
 
 publish_string()

Modified: trunk/docutils/docutils/core.py
===================================================================
--- trunk/docutils/docutils/core.py	2023-04-26 12:57:44 UTC (rev 9365)
+++ trunk/docutils/docutils/core.py	2023-04-26 21:00:10 UTC (rev 9366)
@@ -39,8 +39,9 @@
                  settings=None):
         """
         Initial setup.  If any of `reader`, `parser`, or `writer` are not
-        specified, the corresponding ``set_...`` method should be called with
-        a component name (`set_reader` sets the parser as well).
+        specified, ``set_components()`` or the corresponding ``set_...()``
+        method should be called with component names
+        (`set_reader` sets the parser as well).
         """
 
         self.document = None
@@ -385,7 +386,8 @@
     """
     Set up & run a `Publisher` for command-line-based file I/O (input and
     output file paths taken automatically from the command line).
-    Also return the encoded output as `bytes`.
+    Also return the output as `str` or `bytes` (for binary output document
+    formats).
 
     Parameters: see `publish_programmatically()` for the remainder.
 
@@ -412,7 +414,8 @@
                  config_section=None, enable_exit_status=False):
     """
     Set up & run a `Publisher` for programmatic use with file-like I/O.
-    Also return the encoded output as `bytes`.
+    Also return the output as `str` or `bytes` (for binary output document
+    formats).
 
     Parameters: see `publish_programmatically()`.
     """
@@ -591,7 +594,7 @@
     """
     Set up & run a `Publisher` for command-line-based file I/O (input and
     output file paths taken automatically from the command line).
-    Also return the encoded output as `bytes`.
+    Also return the output as `bytes`.
 
     This is just like publish_cmdline, except that it uses
     io.BinaryFileOutput instead of io.FileOutput.

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