From 1b00f25bf99d9b7a5f307984f6467258de636d23 Mon Sep 17 00:00:00 2001 From: R David Murray Date: Wed, 15 Aug 2012 10:43:58 -0400 Subject: #15543: glossary entry for and 'universal newlines', and links to it. Patch by Chris Jerdonek. --- Doc/glossary.rst | 7 +++++++ Doc/library/bz2.rst | 5 ++++- Doc/library/csv.rst | 6 +++++- Doc/library/functions.rst | 12 ++++++++---- Doc/library/importlib.rst | 7 ++++++- Doc/library/io.rst | 17 ++++++++++++----- Doc/library/stdtypes.rst | 5 ++++- Doc/library/subprocess.rst | 9 ++++++--- Doc/library/zipfile.rst | 8 ++++++-- Doc/whatsnew/2.3.rst | 6 +++++- Doc/whatsnew/2.4.rst | 5 ++++- Doc/whatsnew/2.5.rst | 8 ++++++-- Doc/whatsnew/2.6.rst | 5 ++++- 13 files changed, 77 insertions(+), 23 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index bf1234d..7cd9905 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -600,6 +600,13 @@ Glossary 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/bz2.rst b/Doc/library/bz2.rst index d13f6e0..93144b6 100644 --- a/Doc/library/bz2.rst +++ b/Doc/library/bz2.rst @@ -40,6 +40,9 @@ Here is a summary of the features offered by the bz2 module: Handling of compressed files is offered by the :class:`BZ2File` class. +.. index:: + single: universal newlines; bz2.BZ2File class + .. class:: BZ2File(filename, mode='r', buffering=0, compresslevel=9) Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading (default) @@ -48,7 +51,7 @@ Handling of compressed files is offered by the :class:`BZ2File` class. unbuffered, and larger numbers specify the buffer size; the default is ``0``. If *compresslevel* is given, it must be a number between ``1`` and ``9``; the default is ``9``. Add a ``'U'`` to mode to open the file for input - with universal newline support. Any line ending in the input file will be + in :term:`universal newlines` mode. Any line ending in the input file will be seen as a ``'\n'`` in Python. Also, a file so opened gains the attribute :attr:`newlines`; the value for this attribute is one of ``None`` (no newline read yet), ``'\r'``, ``'\n'``, ``'\r\n'`` or a tuple containing all the diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst index edbe726..e84e218 100644 --- a/Doc/library/csv.rst +++ b/Doc/library/csv.rst @@ -46,6 +46,9 @@ Module Contents The :mod:`csv` module defines the following functions: +.. index:: + single: universal newlines; csv.reader function + .. function:: reader(csvfile, dialect='excel', **fmtparams) Return a reader object which will iterate over lines in the given *csvfile*. @@ -486,4 +489,5 @@ done:: .. [1] If ``newline=''`` is not specified, newlines embedded inside quoted fields will not be interpreted correctly, and on platforms that use ``\r\n`` linendings on write an extra ``\r`` will be added. It should always be safe to specify - ``newline=''``, since the csv module does its own (universal) newline handling. + ``newline=''``, since the csv module does its own + (:term:`universal `) newline handling. diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 3b94495..6b80bd9 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -819,7 +819,7 @@ are always available. They are listed here in alphabetical order. ``'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 @@ are always available. They are listed here in alphabetical order. 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 index c9f742a..158e7b4 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -189,10 +189,15 @@ are also provided to help in implementing the core ABCs. (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 using :term:`universal newlines`, translating all + recognized line separators into ``'\n'`` characters. + 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 index b302c64..8e6e601 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -757,13 +757,17 @@ Text I/O 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. @@ -819,10 +823,13 @@ Text I/O 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 index f46787e..9688393 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1325,10 +1325,13 @@ functions based on regular expressions. ``' 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 index b963983..899bd7c 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -224,9 +224,12 @@ default values. The arguments that are most commonly needed are: 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`. 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'``. @@ -440,7 +443,7 @@ functions. .. _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 index bcec134..4035a14 100644 --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -169,13 +169,17 @@ ZipFile Objects 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 index 0cc29f6..f71422f 100644 --- a/Doc/whatsnew/2.3.rst +++ b/Doc/whatsnew/2.3.rst @@ -366,6 +366,9 @@ Under MacOS, :func:`os.listdir` may now return Unicode filenames. .. ====================================================================== +.. index:: + single: universal newlines; What's new + PEP 278: Universal Newline Support ================================== @@ -378,7 +381,8 @@ two-character sequence of a carriage return plus a newline. 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 index 09ff600..9d339a5 100644 --- a/Doc/whatsnew/2.4.rst +++ b/Doc/whatsnew/2.4.rst @@ -411,6 +411,9 @@ error streams will be. You can provide a file object or a file descriptor, or 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 @@ The constructor has a number of handy options: * *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.5.rst b/Doc/whatsnew/2.5.rst index ff599c8..afe0f5e 100644 --- a/Doc/whatsnew/2.5.rst +++ b/Doc/whatsnew/2.5.rst @@ -1338,10 +1338,14 @@ complete list of changes, or look through the SVN logs for all the details. .. XXX need to provide some more detail here + .. index:: + single: universal newlines; What's new + * The :mod:`fileinput` module was made more flexible. Unicode filenames are now supported, and a *mode* parameter that defaults to ``"r"`` was added to the - :func:`input` function to allow opening files in binary or universal-newline - mode. Another new parameter, *openhook*, lets you use a function other than + :func:`input` function to allow opening files in binary or + :term:`universal newlines` mode. + Another new parameter, *openhook*, lets you use a function other than :func:`open` to open the input files. Once you're iterating over the set of files, the :class:`FileInput` object's new :meth:`fileno` returns the file descriptor for the currently opened file. (Contributed by Georg Brandl.) diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst index 6c5d630..a84bc19 100644 --- a/Doc/whatsnew/2.6.rst +++ b/Doc/whatsnew/2.6.rst @@ -1071,9 +1071,12 @@ the :mod:`io` module: 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. -- cgit v0.12 From ee0a945ae4077d9e4ffdb77e247ed13265316897 Mon Sep 17 00:00:00 2001 From: R David Murray Date: Wed, 15 Aug 2012 11:05:36 -0400 Subject: #15543: reflow paragraphs. --- Doc/library/functions.rst | 5 ++--- Doc/library/importlib.rst | 7 +++---- Doc/library/io.rst | 14 +++++++------- Doc/library/zipfile.rst | 14 +++++++------- Doc/whatsnew/2.3.rst | 13 ++++++------- Doc/whatsnew/2.5.rst | 12 ++++++------ 6 files changed, 31 insertions(+), 34 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 6b80bd9..da07762 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -878,9 +878,8 @@ are always available. They are listed here in alphabetical order. 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: + 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'``, diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 158e7b4..1649063 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -196,10 +196,9 @@ are also provided to help in implementing the core ABCs. An abstract method to return the source of a module. It is returned as a text string using :term:`universal newlines`, translating all - recognized line separators into ``'\n'`` characters. - Returns ``None`` if no - source is available (e.g. a built-in module). Raises :exc:`ImportError` - if the loader cannot find the module specified. + recognized line separators into ``'\n'`` characters. Returns ``None`` + if no source is available (e.g. a built-in module). Raises + :exc:`ImportError` if the loader cannot find the module specified. .. method:: is_package(fullname) diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 8e6e601..b71bfd4 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -764,13 +764,13 @@ Text I/O ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``. It works as follows: * 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 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. + :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 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. * When writing output to the stream, if *newline* is ``None``, any ``'\n'`` characters written are translated to the system default line separator, diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst index 4035a14..48edf1f 100644 --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -174,13 +174,13 @@ ZipFile Objects .. 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 - :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`. + 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 + :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 index f71422f..f4c79e4 100644 --- a/Doc/whatsnew/2.3.rst +++ b/Doc/whatsnew/2.3.rst @@ -379,13 +379,12 @@ mark the ends of lines in text files. Unix uses the linefeed (ASCII character 10), MacOS uses the carriage return (ASCII character 13), and Windows uses a two-character sequence of a carriage return plus a newline. -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 -: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`. +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 :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`. Universal newline support is also used when importing modules and when executing a file with the :func:`execfile` function. This means that Python modules can diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst index afe0f5e..e059cd5 100644 --- a/Doc/whatsnew/2.5.rst +++ b/Doc/whatsnew/2.5.rst @@ -1343,12 +1343,12 @@ complete list of changes, or look through the SVN logs for all the details. * The :mod:`fileinput` module was made more flexible. Unicode filenames are now supported, and a *mode* parameter that defaults to ``"r"`` was added to the - :func:`input` function to allow opening files in binary or - :term:`universal newlines` mode. - Another new parameter, *openhook*, lets you use a function other than - :func:`open` to open the input files. Once you're iterating over the set of - files, the :class:`FileInput` object's new :meth:`fileno` returns the file - descriptor for the currently opened file. (Contributed by Georg Brandl.) + :func:`input` function to allow opening files in binary or :term:`universal + newlines` mode. Another new parameter, *openhook*, lets you use a function + other than :func:`open` to open the input files. Once you're iterating over + the set of files, the :class:`FileInput` object's new :meth:`fileno` returns + the file descriptor for the currently opened file. (Contributed by Georg + Brandl.) * In the :mod:`gc` module, the new :func:`get_count` function returns a 3-tuple containing the current collection counts for the three GC generations. This is -- cgit v0.12