Commit #1068: new docs for PEP 3101. Also document the old string formatting...

Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification.

Doc/library/fpformat.rst

@@ -12,8 +12,8 @@ numbers representations in 100% pure Python.
 
 .. note::
 
-   This module is unnecessary: everything here can be done using the ``%`` string
-   interpolation operator described in the :ref:`string-formatting` section.
+   This module is unnecessary: everything here can be done using the string
+   formatting functions described in the :ref:`string-formatting` section.
 
 The :mod:`fpformat` module defines the following functions and an exception:
 

Doc/library/functions.rst

@@ -449,6 +449,22 @@ available.  They are listed here in alphabetical order.
 
    The float type is described in :ref:`typesnumeric`.
 
+.. function:: format(value[, format_spec])
+
+   .. index::
+      pair: str; format
+      single: __format__
+   
+   Convert a string or a number to a "formatted" representation, as controlled
+   by *format_spec*.  The interpretation of *format_spec* will depend on the
+   type of the *value* argument, however there is a standard formatting syntax
+   that is used by most built-in types: :ref:`formatspec`.
+   
+   .. note::
+
+      ``format(value, format_spec)`` merely calls ``value.__format__(format_spec)``.
+
+
 .. function:: frozenset([iterable])
    :noindex:
 
@@ -990,10 +1006,9 @@ available.  They are listed here in alphabetical order.
 
    For more information on strings see :ref:`typesseq` which describes sequence
    functionality (strings are sequences), and also the string-specific methods
-   described in the :ref:`string-methods` section. To output formatted strings
-   use template strings or the ``%`` operator described in the
-   :ref:`string-formatting` section. In addition see the :ref:`stringservices`
-   section. See also :func:`unicode`.
+   described in the :ref:`string-methods` section. To output formatted strings,
+   see the :ref:`string-formatting` section. In addition see the
+   :ref:`stringservices` section.
 
 
 .. function:: sum(iterable[, start])

Doc/library/logging.rst

@@ -611,8 +611,10 @@ This time, all messages with a severity of DEBUG or above were handled, and the
 format of the messages was also changed, and output went to the specified file
 rather than the console.
 
-Formatting uses standard Python string formatting - see section
-:ref:`string-formatting`. The format string takes the following common
+.. XXX logging should probably be updated!
+
+Formatting uses the old Python string formatting - see section
+:ref:`old-string-formatting`. The format string takes the following common
 specifiers. For a complete list of specifiers, consult the :class:`Formatter`
 documentation.
 
@@ -1483,7 +1485,7 @@ A Formatter can be initialized with a format string which makes use of knowledge
 of the :class:`LogRecord` attributes - such as the default value mentioned above
 making use of the fact that the user's message and arguments are pre-formatted
 into a :class:`LogRecord`'s *message* attribute.  This format string contains
-standard python %-style mapping keys. See section :ref:`string-formatting`
+standard python %-style mapping keys. See section :ref:`old-string-formatting`
 for more information on string formatting.
 
 Currently, the useful mapping keys in a :class:`LogRecord` are:

Doc/library/strings.rst

@@ -8,12 +8,11 @@ String Services
 The modules described in this chapter provide a wide range of string
 manipulation operations.
 
-In addition, Python's built-in string classes support the sequence type
-methods described in the :ref:`typesseq` section, and also the
-string-specific methods described in the :ref:`string-methods` section.
-To output formatted strings use template strings or the ``%`` operator
-described in the :ref:`string-formatting` section. Also, see the
-:mod:`re` module for string functions based on regular expressions.
+In addition, Python's built-in string classes support the sequence type methods
+described in the :ref:`typesseq` section, and also the string-specific methods
+described in the :ref:`string-methods` section.  To output formatted strings,
+see the :ref:`string-formatting` section. Also, see the :mod:`re` module for
+string functions based on regular expressions.
 
 
 .. toctree::

Doc/reference/datamodel.rst

@@ -1279,15 +1279,36 @@ Basic customization
 
    .. index::
       builtin: str
-      statement: print
+      builtin: print
 
-   Called by the :func:`str` built-in function and by the :keyword:`print`
-   statement to compute the "informal" string representation of an object.  This
+   Called by the :func:`str` built-in function and by the :func:`print`
+   function to compute the "informal" string representation of an object.  This
    differs from :meth:`__repr__` in that it does not have to be a valid Python
    expression: a more convenient or concise representation may be used instead.
    The return value must be a string object.
 
 
+.. method:: object.__format__(self, format_spec)
+
+   .. index::
+      pair: string; conversion
+      builtin: str
+      builtin: print
+
+   Called by the :func:`format` built-in function (and by extension, the
+   :meth:`format` method of class :class:`str`) to produce a "formatted"
+   string representation of an object. The ``format_spec`` argument is
+   a string that contains a description of the formatting options desired.
+   The interpretation of the ``format_spec`` argument is up to the type
+   implementing :meth:`__format__`, however most classes will either
+   delegate formatting to one of the built-in types, or use a similar
+   formatting option syntax.
+   
+   See :ref:`formatspec` for a description of the standard formatting syntax.
+
+   The return value must be a string object.
+
+
 .. method:: object.__lt__(self, other)
             object.__le__(self, other)
             object.__eq__(self, other)

Doc/reference/expressions.rst

@@ -5,12 +5,10 @@
 Expressions
 ***********
 
-.. index:: single: expression
+.. index:: expression, BNF
 
 This chapter explains the meaning of the elements of expressions in Python.
 
-.. index:: single: BNF
-
 **Syntax Notes:** In this and the following chapters, extended BNF notation will
 be used to describe syntax, not lexical analysis.  When (one alternative of) a
 syntax rule has the form
@@ -18,8 +16,6 @@ syntax rule has the form
 .. productionlist:: *
    name: `othername`
 
-.. index:: single: syntax
-
 and no semantics are given, the semantics of this form of ``name`` are the same
 as for ``othername``.
 
@@ -852,9 +848,9 @@ identities hold approximately where ``x/y`` is replaced by ``floor(x/y)`` or
 ``floor(x/y) - 1`` [#]_.
 
 In addition to performing the modulo operation on numbers, the ``%`` operator is
-also overloaded by string and unicode objects to perform string formatting (also
+also overloaded by string objects to perform string formatting (also
 known as interpolation). The syntax for string formatting is described in the
-Python Library Reference, section :ref:`string-formatting`.
+Python Library Reference, section :ref:`old-string-formatting`.
 
 The floor division operator, the modulo operator, and the :func:`divmod`
 function are not defined for complex numbers.  Instead, convert to a
@@ -985,9 +981,12 @@ Comparison of objects of the same type depends on the type:
 
 * Numbers are compared arithmetically.
 
+* Bytes objects are compared lexicographically using the numeric values of
+  their elements.
+
 * Strings are compared lexicographically using the numeric equivalents (the
-  result of the built-in function :func:`ord`) of their characters.  Unicode and
-  8-bit strings are fully interoperable in this behavior. [#]_
+  result of the built-in function :func:`ord`) of their characters. [#]_
+  String and bytes object can't be compared!
 
 * Tuples and lists are compared lexicographically using comparison of
   corresponding elements.  This means that to compare equal, each element must
@@ -1020,11 +1019,10 @@ particular, dictionaries support membership testing as a nicer way of spelling
 For the list and tuple types, ``x in y`` is true if and only if there exists an
 index *i* such that ``x == y[i]`` is true.
 
-For the Unicode and string types, ``x in y`` is true if and only if *x* is a
-substring of *y*.  An equivalent test is ``y.find(x) != -1``.  Note, *x* and *y*
-need not be the same type; consequently, ``u'ab' in 'abc'`` will return
-``True``. Empty strings are always considered to be a substring of any other
-string, so ``"" in "abc"`` will return ``True``.
+For the string and bytes types, ``x in y`` is true if and only if *x* is a
+substring of *y*.  An equivalent test is ``y.find(x) != -1``.  Empty strings are
+always considered to be a substring of any other string, so ``"" in "abc"`` will
+return ``True``.
 
 .. versionchanged:: 2.3
    Previously, *x* was required to be a string of length ``1``.
@@ -1272,7 +1270,7 @@ groups from right to left).
    cases, Python returns the latter result, in order to preserve that
    ``divmod(x,y)[0] * y + x % y`` be very close to ``x``.
 
-.. [#] While comparisons between unicode strings make sense at the byte
+.. [#] While comparisons between strings make sense at the byte
    level, they may be counter-intuitive to users. For example, the
    strings ``u"\u00C7"`` and ``u"\u0327\u0043"`` compare differently,
    even though they both represent the same unicode character (LATIN

Doc/tutorial/introduction.rst

@@ -399,8 +399,8 @@ The built-in function :func:`len` returns the length of a string::
       basic transformations and searching.
 
    :ref:`string-formatting`
-      The formatting operations invoked when strings are the
-      left operand of the ``%`` operator are described in more detail here.
+      The formatting operations invoked by the :meth:`format` string method are
+      described in more detail here.
 
 
 .. _tut-unicodestrings: