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 files 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 @@ -873,11 +873,15 @@ 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: - * On input, if *newline* is ``None``, universal newlines mode is enabled. + * On input, if *newline* is ``None``, 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 returned to diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -256,10 +256,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 + a text string with :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 @@ -767,10 +767,14 @@ 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: - * On input, if *newline* is ``None``, universal newlines mode is enabled. + * On input, if *newline* is ``None``, + :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 returned to @@ -842,10 +846,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 for + :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 @@ -156,7 +156,7 @@ decoding to text will often need to be handled at the application level. This behaviour may be overridden by setting *universal_newlines* to - :const:`True` as described below in :ref:`frequently-used-arguments`. + ``True`` as described below in :ref:`frequently-used-arguments`. To also capture standard error in the result, use ``stderr=subprocess.STDOUT``:: @@ -237,11 +237,24 @@ :data:`STDOUT`, which indicates that the stderr data from the child process should be captured into the same file handle as for *stdout*. - When *stdout* or *stderr* are pipes and *universal_newlines* is - :const:`True` then the output data is assumed to be encoded as UTF-8 and - will automatically be decoded to text. All line endings will be converted - to ``'\n'`` as described for the universal newlines ``'U'`` mode argument - to :func:`open`. + .. index:: + single: universal newlines; subprocess module + + If *universal_newlines* is ``True``, the file objects *stdout* and *stderr* + are automatically decoded to text using + :term:`universal newline ` mode. All line breaks + are seen as ``'\n'`` by the Python program as described for the universal + newlines ``'U'`` mode argument to :func:`open`. + + When *stdout* or *stderr* are pipes and *universal_newlines* is ``True`` + then the output data is assumed to be encoded as UTF-8. + + .. note:: + + The *universal_newlines* feature is only available if Python is built + with universal newline support (the default). Also, the newlines + attribute of the file objects :attr:`stdout`, :attr:`stdin` and + :attr:`stderr` are not updated by the :meth:`communicate` method. If *shell* is :const:`True`, the specified command will be executed through the shell. This can be useful if you are using Python primarily for the @@ -442,18 +455,9 @@ .. _side-by-side assembly: http://en.wikipedia.org/wiki/Side-by-Side_Assembly - If *universal_newlines* is :const:`True`, the file objects stdout and stderr are - opened as text files, but lines may be terminated by any of ``'\n'``, the Unix - end-of-line convention, ``'\r'``, the old Macintosh convention or ``'\r\n'``, the - Windows convention. All of these external representations are seen as ``'\n'`` - by the Python program. - - .. note:: - - This feature is only available if Python is built with universal newline - support (the default). Also, the newlines attribute of the file objects - :attr:`stdout`, :attr:`stdin` and :attr:`stderr` are not updated by the - :meth:`communicate` method. + If *universal_newlines* is ``True``, the file objects *stdout* and *stderr* + are opened as text files using universal newline mode, as described above + in :ref:`frequently-used-arguments`. If given, *startupinfo* will be a :class:`STARTUPINFO` object, which is passed to the underlying ``CreateProcess`` function. 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::