[Python-checkins] r61709 - python/trunk/Doc/library/functions.rst python/trunk/Doc/library/future_builtins.rst python/trunk/Doc/library/python.rst

[georg.brandl]

Author: georg.brandl
Date: Fri Mar 21 20:37:57 2008
New Revision: 61709

Added:
   python/trunk/Doc/library/future_builtins.rst
Modified:
   python/trunk/Doc/library/functions.rst
   python/trunk/Doc/library/python.rst
Log:
Add docs for print_function and future_builtins. Fixes #2442.


Modified: python/trunk/Doc/library/functions.rst
==============================================================================
--- python/trunk/Doc/library/functions.rst	(original)
+++ python/trunk/Doc/library/functions.rst	Fri Mar 21 20:37:57 2008
@@ -817,6 +817,33 @@
    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

Added: python/trunk/Doc/library/future_builtins.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/library/future_builtins.rst	Fri Mar 21 20:37:57 2008
@@ -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`.

Modified: python/trunk/Doc/library/python.rst
==============================================================================
--- python/trunk/Doc/library/python.rst	(original)
+++ python/trunk/Doc/library/python.rst	Fri Mar 21 20:37:57 2008
@@ -14,6 +14,7 @@
 
    sys.rst
    __builtin__.rst
+   future_builtins.rst
    __main__.rst
    warnings.rst
    contextlib.rst