Mirrors
/
cpython
mirror of https://github.com/python/cpython
3
0
Fork 0
Code Releases Activity
Browse Source

#15543: glossary entry for and 'universal newlines', and links to it. 

Patch by Chris Jerdonek.
pull/2332/head
R David Murray 14 years ago
parent
2d44ceeada
commit
5618aaaafe
13 changed files with 78 additions and 26 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 7
      Doc/glossary.rst
  2. 5
      Doc/library/bz2.rst
  3. 8
      Doc/library/functions.rst
  4. 25
      Doc/library/io.rst
  5. 12
      Doc/library/stdtypes.rst
  6. 12
      Doc/library/subprocess.rst
  7. 2
      Doc/library/urllib.rst
  8. 8
      Doc/library/zipfile.rst
  9. 4
      Doc/reference/simple_stmts.rst
  10. 6
      Doc/whatsnew/2.3.rst
  11. 5
      Doc/whatsnew/2.4.rst
  12. 5
      Doc/whatsnew/2.5.rst
  13. 5
      Doc/whatsnew/2.6.rst

7
Doc/glossary.rst
View File

@ -630,6 +630,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.viewkeys`, :meth:`dict.viewvalues`,
and :meth:`dict.viewitems` are called dictionary views. They are lazy

5
Doc/library/bz2.rst
View File

@ -42,6 +42,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[, buffering[, compresslevel]]])
Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading (default)
@ -50,7 +53,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

8
Doc/library/functions.rst
View File

@ -859,13 +859,17 @@ available. They are listed here in alphabetical order.
binary mode, on systems that differentiate between binary and text files; on
systems that don't have this distinction, adding the ``'b'`` has no effect.
.. index::
single: universal newlines; open() built-in function
In addition to the standard :c:func:`fopen` values *mode* may be ``'U'`` or
``'rU'``. Python is usually built with universal newline support; supplying
``'rU'``. Python is usually built with :term:`universal newlines` support;
supplying
``'U'`` opens the file as a text file, but lines may be terminated by any of the
following: the Unix end-of-line convention ``'\n'``, the Macintosh convention
``'\r'``, or the Windows convention ``'\r\n'``. All of these external
representations are seen as ``'\n'`` by the Python program. If Python is built
without universal newline support a *mode* with ``'U'`` is the same as normal
without universal newlines support a *mode* with ``'U'`` is the same as normal
text mode. Note that file objects so opened also have an attribute called
:attr:`newlines` which has a value of ``None`` (if no newlines have yet been
seen), ``'\n'``, ``'\r'``, ``'\r\n'``, or a tuple containing all the newline

25
Doc/library/io.rst
View File

@ -92,7 +92,7 @@ Module Interface
``'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)
========= ===============================================================
@ -141,14 +141,18 @@ Module Interface
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
.. index::
single: universal newlines; open() (in module io)
*newline* controls how :term:`universal newlines` 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.
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
``''``, 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.
@ -754,13 +758,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:
* On input, if *newline* is ``None``, universal newlines mode is enabled.
* On input, 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 enabled, but line endings are returned to
``''``, 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.
@ -817,10 +825,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`.
Advanced topics

12
Doc/library/stdtypes.rst
View File

@ -1181,10 +1181,13 @@ string 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.
@ -2558,16 +2561,19 @@ the particular object.
form ``<...>``. This is a read-only attribute and may not be present on all
file-like objects.
.. index::
single: universal newlines; file.newlines attribute
.. attribute:: file.newlines
If Python was built with universal newlines enabled (the default) this
If Python was built with :term:`universal newlines` enabled (the default) this
read-only attribute exists, and for files opened in universal newline read
mode it keeps track of the types of newlines encountered while reading the
file. The values it can take are ``'\r'``, ``'\n'``, ``'\r\n'``, ``None``
(unknown, no newlines read yet) or a tuple containing all the newline types
seen, to indicate that multiple newline conventions were encountered. For
files not opened in universal newline read mode the value of this attribute
files not opened in universal newlines read mode the value of this attribute
will be ``None``.

12
Doc/library/subprocess.rst
View File

@ -220,9 +220,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
When *stdout* or *stderr* are pipes and *universal_newlines* is
:const:`True` then all line endings will be converted to ``'\n'`` as
described for the universal newlines `'U'`` mode argument to :func:`open`.
``True`` then all line endings will be converted to ``'\n'`` as described
for the :term:`universal newlines` `'U'`` mode argument to :func:`open`.
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
@ -382,8 +385,9 @@ functions.
.. _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
If *universal_newlines* is ``True``, the file objects *stdout* and *stderr* are
opened as text files in :term:`universal newlines` mode. 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.

2
Doc/library/urllib.rst
View File

@ -34,7 +34,7 @@ High-level interface
Open a network object denoted by a URL for reading. If the URL does not have a
scheme identifier, or if it has :file:`file:` as its scheme identifier, this
opens a local file (without universal newlines); otherwise it opens a socket to
opens a local file (without :term:`universal newlines`); otherwise it opens a socket to
a server somewhere on the network. If the connection cannot be made the
:exc:`IOError` exception is raised. If all went well, a file-like object is
returned. This supports the following methods: :meth:`read`, :meth:`readline`,

8
Doc/library/zipfile.rst
View File

@ -163,13 +163,17 @@ ZipFile Objects
Return a list of archive members by name.
.. index::
single: universal newlines; zipfile.ZipFile.open method
.. method:: ZipFile.open(name[, mode[, pwd]])
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
parameter, if included, must be one of the following: ``'r'`` (the default),
``'U'``, or ``'rU'``. Choosing ``'U'`` or ``'rU'`` will enable
:term:`universal newline <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`.

4
Doc/reference/simple_stmts.rst
View File

@ -1024,5 +1024,5 @@ which may be useful to pass around for use by :keyword:`exec`.
.. rubric:: Footnotes
.. [#] Note that the parser only accepts the Unix-style end of line convention.
If you are reading the code from a file, make sure to use universal
newline mode to convert Windows or Mac-style newlines.
If you are reading the code from a file, make sure to use
:term:`universal newlines` mode to convert Windows or Mac-style newlines.

6
Doc/whatsnew/2.3.rst
View File

@ -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`.

5
Doc/whatsnew/2.4.rst
View File

@ -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

5
Doc/whatsnew/2.5.rst
View File

@ -1338,9 +1338,12 @@ 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
: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

5
Doc/whatsnew/2.6.rst
View File

@ -1067,9 +1067,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.

Write Preview
Loading…
Cancel
Save