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 @@ -874,12 +874,16 @@ 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 newline ` 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 + universal newline 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 enabled, but line endings are 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,11 +768,15 @@ 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 + :term:`universal newline ` 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 enabled, but line endings are @@ -846,10 +850,14 @@ 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 using + :term:`universal newline ` 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,14 @@ ``' 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 newline ` + 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,14 @@ :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 newline ` 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 +513,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 newline 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 newline ` 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 newline ` 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 newline ` 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.