mirror of https://github.com/python/cpython
#15543: glossary entry for and 'universal newlines', and links to it.
Patch by Chris Jerdonek.
This commit is contained in:
parent
f748a3773f
commit
1b00f25bf9
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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 <universal newlines>`) newline handling.
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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::
|
||||
|
|
|
@ -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`.
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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.)
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
Loading…
Reference in New Issue