bpo-43712 : fileinput: Add encoding parameter (GH-25272)

1 files changed, 26 insertions, 9 deletions

diff --git a/Doc/library/fileinput.rst b/Doc/library/fileinput.rst
index cc4039a..8196400 100644
--- a/Doc/library/fileinput.rst
+++ b/Doc/library/fileinput.rst
@@ -18,7 +18,7 @@ write one file see :func:`open`.
 The typical use is::
 
    import fileinput
-   for line in fileinput.input():
+   for line in fileinput.input(encoding="utf-8"):
        process(line)
 
 This iterates over the lines of all files listed in ``sys.argv[1:]``, defaulting
@@ -49,13 +49,14 @@ a file may not have one.
 You can control how files are opened by providing an opening hook via the
 *openhook* parameter to :func:`fileinput.input` or :class:`FileInput()`. The
 hook must be a function that takes two arguments, *filename* and *mode*, and
-returns an accordingly opened file-like object. Two useful hooks are already
-provided by this module.
+returns an accordingly opened file-like object. If *encoding* and/or *errors*
+are specified, they will be passed to the hook as aditional keyword arguments.
+This module provides a :func:`hook_encoded` to support compressed files.
 
 The following function is the primary interface of this module:
 
 
-.. function:: input(files=None, inplace=False, backup='', *, mode='r', openhook=None)
+.. function:: input(files=None, inplace=False, backup='', *, mode='r', openhook=None, encoding=None, errors=None)
 
    Create an instance of the :class:`FileInput` class.  The instance will be used
    as global state for the functions of this module, and is also returned to use
@@ -66,7 +67,7 @@ The following function is the primary interface of this module:
    :keyword:`with` statement.  In this example, *input* is closed after the
    :keyword:`!with` statement is exited, even if an exception occurs::
 
-      with fileinput.input(files=('spam.txt', 'eggs.txt')) as f:
+      with fileinput.input(files=('spam.txt', 'eggs.txt'), encoding="utf-8") as f:
           for line in f:
               process(line)
 
@@ -76,6 +77,9 @@ The following function is the primary interface of this module:
    .. versionchanged:: 3.8
       The keyword parameters *mode* and *openhook* are now keyword-only.
 
+   .. versionchanged:: 3.10
+      The keyword-only parameter *encoding* and *errors* are added.
+
 
 The following functions use the global state created by :func:`fileinput.input`;
 if there is no active state, :exc:`RuntimeError` is raised.
@@ -137,7 +141,7 @@ The class which implements the sequence behavior provided by the module is
 available for subclassing as well:
 
 
-.. class:: FileInput(files=None, inplace=False, backup='', *, mode='r', openhook=None)
+.. class:: FileInput(files=None, inplace=False, backup='', *, mode='r', openhook=None, encoding=None, errors=None)
 
    Class :class:`FileInput` is the implementation; its methods :meth:`filename`,
    :meth:`fileno`, :meth:`lineno`, :meth:`filelineno`, :meth:`isfirstline`,
@@ -155,6 +159,8 @@ available for subclassing as well:
    *filename* and *mode*, and returns an accordingly opened file-like object. You
    cannot use *inplace* and *openhook* together.
 
+   You can specify *encoding* and *errors* that is passed to :func:`open` or *openhook*.
+
    A :class:`FileInput` instance can be used as a context manager in the
    :keyword:`with` statement.  In this example, *input* is closed after the
    :keyword:`!with` statement is exited, even if an exception occurs::
@@ -162,7 +168,6 @@ available for subclassing as well:
       with FileInput(files=('spam.txt', 'eggs.txt')) as input:
           process(input)
 
-
    .. versionchanged:: 3.2
       Can be used as a context manager.
 
@@ -175,6 +180,8 @@ available for subclassing as well:
    .. versionchanged:: 3.8
       The keyword parameter *mode* and *openhook* are now keyword-only.
 
+   .. versionchanged:: 3.10
+      The keyword-only parameter *encoding* and *errors* are added.
 
 
 **Optional in-place filtering:** if the keyword argument ``inplace=True`` is
@@ -191,14 +198,20 @@ when standard input is read.
 
 The two following opening hooks are provided by this module:
 
-.. function:: hook_compressed(filename, mode)
+.. function:: hook_compressed(filename, mode, *, encoding=None, errors=None)
 
    Transparently opens files compressed with gzip and bzip2 (recognized by the
    extensions ``'.gz'`` and ``'.bz2'``) using the :mod:`gzip` and :mod:`bz2`
    modules.  If the filename extension is not ``'.gz'`` or ``'.bz2'``, the file is
    opened normally (ie, using :func:`open` without any decompression).
 
-   Usage example:  ``fi = fileinput.FileInput(openhook=fileinput.hook_compressed)``
+   The *encoding* and *errors* values are passed to to :class:`io.TextIOWrapper`
+   for compressed files and open for normal files.
+
+   Usage example:  ``fi = fileinput.FileInput(openhook=fileinput.hook_compressed, encoding="utf-8")``
+
+   .. versionchanged:: 3.10
+      The keyword-only parameter *encoding* and *errors* are added.
 
 
 .. function:: hook_encoded(encoding, errors=None)
@@ -212,3 +225,7 @@ The two following opening hooks are provided by this module:
 
    .. versionchanged:: 3.6
       Added the optional *errors* parameter.
+
+   .. deprecated:: 3.10
+      This function is deprecated since :func:`input` and :class:`FileInput`
+      now have *encoding* and *errors* parameters.