Add docs for print_function and future_builtins. Fixes #2442.

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 5b5462257d9fa8f3ddeb5e33473ed656c36cd1e1..978b32a6b1d60b0543d4ec91441aa31e587efa95 100644 (file)
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -817,6 +817,33 @@ available.  They are listed here in alphabetical order.
    accidents.)
 
 
+.. function:: print([object, ...][, sep=' '][, end='\n'][, file=sys.stdout])
+
+   Print *object*\(s) to the stream *file*, separated by *sep* and followed by
+   *end*.  *sep*, *end* and *file*, if present, must be given as keyword
+   arguments.
+
+   All non-keyword arguments are converted to strings like :func:`str` does and
+   written to the stream, separated by *sep* and followed by *end*.  Both *sep*
+   and *end* must be strings; they can also be ``None``, which means to use the
+   default values.  If no *object* is given, :func:`print` will just write
+   *end*.
+
+   The *file* argument must be an object with a ``write(string)`` method; if it
+   is not present or ``None``, :data:`sys.stdout` will be used.
+
+   .. note::
+
+      This function is not normally available as a builtin since the name
+      ``print`` is recognized as the :keyword:`print` statement.  To disable the
+      statement and use the :func:`print` function, use this future statement at
+      the top of your module::
+
+         from __future__ import print_function
+
+   .. versionadded:: 2.6
+
+
 .. function:: property([fget[, fset[, fdel[, doc]]]])
 
    Return a property attribute for :term:`new-style class`\es (classes that

diff --git a/Doc/library/future_builtins.rst b/Doc/library/future_builtins.rst
new file mode 100644 (file)
index 0000000..e845fe4
--- /dev/null
+++ b/Doc/library/future_builtins.rst
@@ -0,0 +1,53 @@
+:mod:`future_builtins` --- Python 3 builtins
+============================================
+
+.. module:: future_builtins
+.. sectionauthor:: Georg Brandl
+.. versionadded:: 2.6
+
+This module provides functions that exist in 2.x, but have different behavior in
+Python 3, so they cannot be put into the 2.x builtin namespace.
+
+Instead, if you want to write code compatible with Python 3 builtins, import
+them from this module, like this::
+
+   from future_builtins import map, filter
+
+   ... code using Python 3-style map and filter ...
+
+The :program:`2to3` tool that ports Python 2 code to Python 3 will recognize
+this usage and leave the new builtins alone.
+
+.. note::
+
+   The Python 3 :func:`print` function is already in the builtins, but cannot be
+   accessed from Python 2 code unless you use the appropriate future statement::
+
+      from __future__ import print_function
+
+
+Available builtins are:
+
+.. function:: filter(function, iterable)
+
+   Works like :func:`itertools.ifilter`.
+
+.. function:: hex(object)
+
+   Works like the builtin :func:`hex`, but instead of :meth:`__hex__` it will
+   use the :meth:`__index__` method on its argument to get an integer that is
+   then converted to hexadecimal.
+
+.. function:: map(function, iterable, ...)
+
+   Works like :func:`itertools.imap`.
+
+.. function:: oct(object)
+
+   Works like the builtin :func:`oct`, but instead of :meth:`__oct__` it will
+   use the :meth:`__index__` method on its argument to get an integer that is
+   then converted to hexadecimal.
+
+.. function:: zip(*iterables)
+
+   Works like :func:`itertools.izip`.

diff --git a/Doc/library/python.rst b/Doc/library/python.rst
index 3b58eee98190a746936a6b76da5a102d642bc4ea..d9a37bb90cf5edad1feccc150ca27129927fd171 100644 (file)
--- a/Doc/library/python.rst
+++ b/Doc/library/python.rst
@@ -14,6 +14,7 @@ overview:
 
    sys.rst
    __builtin__.rst
+   future_builtins.rst
    __main__.rst
    warnings.rst
    contextlib.rst