diff --git a/Doc/glossary.rst b/Doc/glossary.rst --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -706,6 +706,13 @@ object has a type. An object's type is accessible as its :attr:`__class__` attribute or can be retrieved with ``type(obj)``. + universal newlines + A manner of interpreting text streams in which all of the following are + recognized as ending a line: the Unix end-of-line convention ``'\n'``, + the Windows convention ``'\r\n'``, and the old Macintosh convention + ``'\r'``. See :pep:`278` and :pep:`3116`, as well as + :func:`str.splitlines` for an additional use. + view The objects returned from :meth:`dict.keys`, :meth:`dict.values`, and :meth:`dict.items` are called dictionary views. They are lazy sequences diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -819,7 +819,7 @@ ``'b'`` binary mode ``'t'`` text mode (default) ``'+'`` open a disk file for updating (reading and writing) - ``'U'`` universal newline mode (for backwards compatibility; should + ``'U'`` universal newlines mode (for backwards compatibility; should not be used in new code) ========= =============================================================== @@ -874,14 +874,18 @@ used. Any other error handling name that has been registered with :func:`codecs.register_error` is also valid. - *newline* controls how universal newlines works (it only applies to text - mode). It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``. It + .. index:: + single: universal newlines; open() built-in function + + *newline* controls how :term:`universal newlines` mode works (it only + applies to text mode). + It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``. It works as follows: * When reading input from the stream, if *newline* is ``None``, universal newlines mode is enabled. Lines in the input can end in ``'\n'``, ``'\r'``, or ``'\r\n'``, and these are translated into ``'\n'`` before - being returned to the caller. If it is ``''``, universal newline mode is + being returned to the caller. If it is ``''``, universal newlines mode is enabled, but line endings are returned to the caller untranslated. If it has any of the other legal values, input lines are only terminated by the given string, and the line ending is returned to the caller untranslated. diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -290,10 +290,13 @@ (e.g. built-in module). :exc:`ImportError` is raised if loader cannot find the requested module. + .. index:: + single: universal newlines; importlib.abc.InspectLoader.get_source method + .. method:: get_source(fullname) - An abstract method to return the source of a module. It is returned as - a text string with universal newlines. Returns ``None`` if no + An abstract method to return the source of a module. It is obtained as + a text string using :term:`universal newlines`. Returns ``None`` if no source is available (e.g. a built-in module). Raises :exc:`ImportError` if the loader cannot find the module specified. diff --git a/Doc/library/io.rst b/Doc/library/io.rst --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -768,13 +768,17 @@ sequences) can be used. Any other error handling name that has been registered with :func:`codecs.register_error` is also valid. + .. index:: + single: universal newlines; io.TextIOWrapper class + *newline* controls how line endings are handled. It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``. It works as follows: - * When reading input from the stream, if *newline* is ``None``, universal - newlines mode is enabled. Lines in the input can end in ``'\n'``, + * When reading input from the stream, if *newline* is ``None``, + :term:`universal newlines` mode is enabled. Lines in the input can end + in ``'\n'``, ``'\r'``, or ``'\r\n'``, and these are translated into ``'\n'`` before - being returned to the caller. If it is ``''``, universal newline mode is + being returned to the caller. If it is ``''``, universal newlines mode is enabled, but line endings are returned to the caller untranslated. If it has any of the other legal values, input lines are only terminated by the given string, and the line ending is returned to the caller untranslated. @@ -843,10 +847,13 @@ output.close() +.. index:: + single: universal newlines; io.IncrementalNewlineDecoder class + .. class:: IncrementalNewlineDecoder - A helper codec that decodes newlines for universal newlines mode. It - inherits :class:`codecs.IncrementalDecoder`. + A helper codec that decodes newlines for :term:`universal newlines` mode. + It inherits :class:`codecs.IncrementalDecoder`. Performance diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1349,10 +1349,13 @@ ``' 1 2 3 '.split(None, 1)`` returns ``['1', '2 3 ']``. +.. index:: + single: universal newlines; str.splitlines method + .. method:: str.splitlines([keepends]) Return a list of the lines in the string, breaking at line boundaries. - This method uses the universal newlines approach to splitting lines. + This method uses the :term:`universal newlines` approach to splitting lines. Line breaks are not included in the resulting list unless *keepends* is given and true. diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -285,9 +285,13 @@ :data:`STDOUT`, which indicates that the stderr data from the child process should be captured into the same file handle as for *stdout*. + .. index:: + single: universal newlines; subprocess module + If *universal_newlines* is ``True``, the file objects *stdin*, *stdout* - and *stderr* will be opened as text streams with universal newlines support, - using the encoding returned by :func:`locale.getpreferredencoding`. + and *stderr* will be opened as text streams in :term:`universal newlines` + mode using the encoding returned by + :func:`locale.getpreferredencoding(False) `. For *stdin*, line ending characters ``'\n'`` in the input will be converted to the default line separator :data:`os.linesep`. For *stdout* and *stderr*, all line endings in the output will be converted to ``'\n'``. @@ -508,7 +512,7 @@ .. _side-by-side assembly: http://en.wikipedia.org/wiki/Side-by-Side_Assembly If *universal_newlines* is ``True``, the file objects *stdin*, *stdout* - and *stderr* are opened as text files with universal newlines support, as + and *stderr* are opened as text streams in universal newlines mode, as described above in :ref:`frequently-used-arguments`. If given, *startupinfo* will be a :class:`STARTUPINFO` object, which is diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -197,13 +197,17 @@ Return a list of archive members by name. +.. index:: + single: universal newlines; zipfile.ZipFile.open method + .. method:: ZipFile.open(name, mode='r', pwd=None) Extract a member from the archive as a file-like object (ZipExtFile). *name* is the name of the file in the archive, or a :class:`ZipInfo` object. The *mode* parameter, if included, must be one of the following: ``'r'`` (the default), - ``'U'``, or ``'rU'``. Choosing ``'U'`` or ``'rU'`` will enable universal newline - support in the read-only object. *pwd* is the password used for encrypted files. + ``'U'``, or ``'rU'``. Choosing ``'U'`` or ``'rU'`` will enable + :term:`universal newlines` support in the read-only object. + *pwd* is the password used for encrypted files. Calling :meth:`open` on a closed ZipFile will raise a :exc:`RuntimeError`. .. note:: diff --git a/Doc/whatsnew/2.3.rst b/Doc/whatsnew/2.3.rst --- a/Doc/whatsnew/2.3.rst +++ b/Doc/whatsnew/2.3.rst @@ -366,6 +366,9 @@ .. ====================================================================== +.. index:: + single: universal newlines; What's new + PEP 278: Universal Newline Support ================================== @@ -378,7 +381,8 @@ Python's file objects can now support end of line conventions other than the one followed by the platform on which Python is running. Opening a file with the -mode ``'U'`` or ``'rU'`` will open a file for reading in universal newline mode. +mode ``'U'`` or ``'rU'`` will open a file for reading in +:term:`universal newlines` mode. All three line ending conventions will be translated to a ``'\n'`` in the strings returned by the various file methods such as :meth:`read` and :meth:`readline`. diff --git a/Doc/whatsnew/2.4.rst b/Doc/whatsnew/2.4.rst --- a/Doc/whatsnew/2.4.rst +++ b/Doc/whatsnew/2.4.rst @@ -411,6 +411,9 @@ you can use the constant ``subprocess.PIPE`` to create a pipe between the subprocess and the parent. +.. index:: + single: universal newlines; What's new + The constructor has a number of handy options: * *close_fds* requests that all file descriptors be closed before running the @@ -424,7 +427,7 @@ * *preexec_fn* is a function that gets called before the child is started. * *universal_newlines* opens the child's input and output using Python's - universal newline feature. + :term:`universal newlines` feature. Once you've created the :class:`Popen` instance, you can call its :meth:`wait` method to pause until the subprocess has exited, :meth:`poll` to check if it's diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst --- a/Doc/whatsnew/2.6.rst +++ b/Doc/whatsnew/2.6.rst @@ -1071,9 +1071,12 @@ The :class:`BytesIO` class supports reading, writing, and seeking over an in-memory buffer. + .. index:: + single: universal newlines; What's new + * :class:`TextIOBase`: Provides functions for reading and writing strings (remember, strings will be Unicode in Python 3.0), - and supporting universal newlines. :class:`TextIOBase` defines + and supporting :term:`universal newlines`. :class:`TextIOBase` defines the :meth:`readline` method and supports iteration upon objects.