Update whatsnew document to use specific markup for identifiers, thus enabling cross-linking.
diff --git a/Doc/whatsnew/3.0.rst b/Doc/whatsnew/3.0.rst
index 859c64b..c9416db 100644
--- a/Doc/whatsnew/3.0.rst
+++ b/Doc/whatsnew/3.0.rst
@@ -79,7 +79,7 @@
remains syntactically valid that trips people up. I'm also omitting
changes to rarely used features.)
-* The ``print`` statement has been replaced with a ``print()`` function,
+* The ``print`` statement has been replaced with a :func:`print` function,
with keyword arguments to replace most of the special syntax of the
old ``print`` statement (PEP 3105). Examples::
@@ -106,9 +106,9 @@
There are <4294967296> possibilities!
- Notes about the ``print()`` function:
+ Notes about the :func:`print` function:
- * The ``print()`` function doesn't support the "softspace" feature of
+ * The :func:`print` function doesn't support the "softspace" feature of
the old ``print`` statement. For example, in Python 2.x,
``print "A\n", "B"`` would write ``"A\nB\n"``; but in Python 3.0,
``print("A\n", "B")`` writes ``"A\n B\n"``.
@@ -118,7 +118,7 @@
``print(x)`` instead!
* When using the ``2to3`` source-to-source conversion tool, all
- ``print`` statements are autmatically converted to ``print()``
+ ``print`` statements are autmatically converted to :func:`print`
function calls, so this is mostly a non-issue for larger projects.
* Python 3.0 uses strings and bytes instead of the Unicode strings and
@@ -131,19 +131,19 @@
that if a file is opened using an incorrect mode or encoding, I/O
will likely fail.
-* ``map()`` and ``filter()`` return iterators. A quick fix is e.g.
+* :func:`map` and :func:`filter` return iterators. A quick fix is e.g.
``list(map(...))``, but a better fix is often to use a list
- comprehension (especially when the original code uses ``lambda``).
- Particularly tricky is ``map()`` invoked for the side effects of the
+ comprehension (especially when the original code uses :keyword:`lambda`).
+ Particularly tricky is :func:`map` invoked for the side effects of the
function; the correct transformation is to use a for-loop.
-* ``dict`` methods ``.keys()``, ``.items()`` and ``.values()`` return
- views instead of lists. For example, this no longer works:
- ``k = d.keys(); k.sort()``. Use ``k = sorted(d)`` instead.
+* :class:`dict` methods :meth:`dict.keys`, :meth:`dict.items` and
+ :meth:`dict.values` return views instead of lists. For example, this no
+ longer works: ``k = d.keys(); k.sort()``. Use ``k = sorted(d)`` instead.
* ``1/2`` returns a float. Use ``1//2`` to get the truncating behavior.
-* The ``repr()`` of a long integer doesn't include the trailing ``L``
+* The :func:`repr` of a long integer doesn't include the trailing ``L``
anymore, so code that unconditionally strips that character will
chop off the last digit instead.
@@ -151,32 +151,33 @@
Strings and Bytes
=================
-* There is only one string type; its name is ``str`` but its behavior
- and implementation are more like ``unicode`` in 2.x.
+* There is only one string type; its name is :class:`str` but its behavior and
+ implementation are like :class:`unicode` in 2.x.
-* The ``basestring`` superclass has been removed. The ``2to3`` tool
- replaces every occurence of ``basestring`` with ``str``.
+* The :class:`basestring` superclass has been removed. The ``2to3`` tool
+ replaces every occurence of :class:`basestring` with :class:`str`.
-* PEP 3137: There is a new type, ``bytes``, to represent binary data
- (and encoded text, which is treated as binary data until you decide
- to decode it). The ``str`` and ``bytes`` types cannot be mixed; you
- must always explicitly convert between them, using the ``.encode()``
- (str -> bytes) or ``.decode()`` (bytes -> str) methods.
+* PEP 3137: There is a new type, :class:`bytes`, to represent binary data (and
+ encoded text, which is treated as binary data until you decide to decode it).
+ The :class:`str` and :class:`bytes` types cannot be mixed; you must always
+ explicitly convert between them, using the :meth:`str.encode` (str -> bytes)
+ or :meth:`bytes.decode` (bytes -> str) methods.
-* PEP 3112: Bytes literals. E.g. b"abc".
+.. XXX add bytearray
+
+* PEP 3112: Bytes literals, e.g. ``b"abc"``, create :class:`bytes` instances.
* PEP 3120: UTF-8 default source encoding.
-* PEP 3131: Non-ASCII identifiers. (However, the standard library
- remains ASCII-only with the exception of contributor names in
- comments.)
+* PEP 3131: Non-ASCII identifiers. (However, the standard library remains
+ ASCII-only with the exception of contributor names in comments.)
* PEP 3116: New I/O Implementation. The API is nearly 100% backwards
- compatible, but completely reimplemented (currently mostly in
- Python). Also, binary files use bytes instead of strings.
+ compatible, but completely reimplemented (currently mostly in Python). Also,
+ binary files use bytes instead of strings.
-* The ``StringIO`` and ``cStringIO`` modules are gone. Instead,
- import ``StringIO`` or ``BytesIO`` from the ``io`` module.
+* The :mod:`StringIO` and :mod:`cStringIO` modules are gone. Instead, import
+ :class:`io.StringIO` or :class:`io.BytesIO`.
PEP 3101: A New Approach to String Formatting
@@ -184,20 +185,20 @@
.. XXX expand this
-* A new system for built-in string formatting operations replaces
- the ``%`` string formatting operator.
+* A new system for built-in string formatting operations replaces the ``%``
+ string formatting operator.
-PEP 3106: Revamping dict ``.keys()``, ``.items()`` and ``.values()``
-====================================================================
+PEP 3106: Revamping dict :meth:`dict.keys`, :meth:`dict.items` and :meth:`dict.values`
+======================================================================================
.. XXX expand this
-* The ``.iterkeys()``, ``.itervalues()`` and ``.iteritems()`` methods
- have been removed.
+* The :meth:`dict.iterkeys`, :meth:`dict.itervalues` and :meth:`dict.iteritems`
+ methods have been removed.
-* ``.keys()``, ``.values()`` and ``.items()`` return objects with set
- behavior that reference the underlying dict.
+* :meth:`dict.keys`, :meth:`dict.values` and :meth:`dict.items` return objects
+ with set behavior that reference the underlying dict.
PEP 3107: Function Annotations
@@ -205,33 +206,31 @@
.. XXX expand this
-* A standardized way of annotating a function's parameters and return
- values.
+* A standardized way of annotating a function's parameters and return values.
Exception Stuff
===============
-* PEP 352: Exceptions must derive from BaseException. This is the
- root of the exception hierarchy.
+* PEP 352: Exceptions must derive from :exc:`BaseException`. This is the root
+ of the exception hierarchy.
-* StandardException was removed (already in 2.6).
+* :exc:`StandardError` was removed (already in 2.6).
-* Dropping sequence behavior (slicing!) and ``.message`` attribute of
+* Dropping sequence behavior (slicing!) and :attr:`message` attribute of
exception instances.
-* PEP 3109: Raising exceptions. You must now use ``raise
- Exception(args)`` instead of ``raise Exception, args``.
+* PEP 3109: Raising exceptions. You must now use ``raise Exception(args)``
+ instead of ``raise Exception, args``.
* PEP 3110: Catching exceptions.
-* PEP 3134: Exception chaining. (The ``__context__`` feature from the
- PEP hasn't been implemented yet in 3.0a1.)
+* PEP 3134: Exception chaining. (The :attr:`__context__` feature from the PEP
+ hasn't been implemented yet in 3.0a2.)
-* A few exception messages are improved when Windows fails to load an
- extension module. For example, ``error code 193`` is now ``%1 is not
- a valid Win32 application``. Strings now deal with non-English
- locales.
+* A few exception messages are improved when Windows fails to load an extension
+ module. For example, ``error code 193`` is now ``%1 is not a valid Win32
+ application``. Strings now deal with non-English locales.
New Class and Metaclass Stuff
@@ -255,101 +254,97 @@
Here are most of the changes that Python 3.0 makes to the core Python
language and built-in functions.
-* Removed backticks (use ``repr()`` instead).
+* Removed backticks (use :func:`repr` instead).
* Removed ``<>`` (use ``!=`` instead).
* ``!=`` now returns the opposite of ``==``, unless ``==`` returns
``NotImplemented``.
-* ``as`` and ``with`` are keywords.
+* :keyword:`as` and :keyword:`with` are keywords.
* ``True``, ``False``, and ``None`` are keywords.
-* PEP 237: ``long`` renamed to ``int``. That is, there is only one
- built-in integral type, named ``int``; but it behaves like the old
- ``long`` type, with the exception that the literal suffix ``L`` is
- neither supported by the parser nor produced by ``repr()`` anymore.
- ``sys.maxint`` was also removed since the int type has no maximum
- value anymore.
+* PEP 237: :class:`long` renamed to :class:`int`. That is, there is only one
+ built-in integral type, named :class:`int`; but it behaves like the old
+ :class:`long` type, with the exception that the literal suffix ``L`` is
+ neither supported by the parser nor produced by :func:`repr` anymore.
+ :data:`sys.maxint` was also removed since the int type has no maximum value
+ anymore.
* PEP 238: int division returns a float.
-* The ordering operators behave differently: for example, ``x < y``
- where ``x`` and ``y`` have incompatible types raises ``TypeError``
- instead of returning a pseudo-random boolean.
+* The ordering operators behave differently: for example, ``x < y`` where ``x``
+ and ``y`` have incompatible types raises :exc:`TypeError` instead of returning
+ a pseudo-random boolean.
-* ``__getslice__()`` and friends killed. The syntax ``a[i:j]`` now
- translates to ``a.__getitem__(slice(i, j))`` (or ``__setitem__``
- or ``__delitem__``, depending on context).
+* :meth:`__getslice__` and friends killed. The syntax ``a[i:j]`` now translates
+ to ``a.__getitem__(slice(i, j))`` (or :meth:`__setitem__` or
+ :meth:`__delitem__`, depending on context).
-* PEP 3102: Keyword-only arguments. Named parameters occurring after
- ``*args`` in the parameter list *must* be specified using keyword
- syntax in the call. You can also use a bare ``*`` in the parameter
- list to indicate that you don't accept a variable-length argument
- list, but you do have keyword-only arguments.
+* PEP 3102: Keyword-only arguments. Named parameters occurring after ``*args``
+ in the parameter list *must* be specified using keyword syntax in the call.
+ You can also use a bare ``*`` in the parameter list to indicate that you don't
+ accept a variable-length argument list, but you do have keyword-only
+ arguments.
-* PEP 3104: ``nonlocal`` statement. Using ``nonlocal x`` you can now
+* PEP 3104: :keyword:`nonlocal` statement. Using ``nonlocal x`` you can now
assign directly to a variable in an outer (but non-global) scope.
-* PEP 3111: ``raw_input()`` renamed to ``input()``. That is, the new
- ``input()`` function reads a line from ``sys.stdin`` and returns it
- with the trailing newline stripped. It raises ``EOFError`` if the
- input is terminated prematurely. To get the old behavior of
- ``input()``, use ``eval(input())``.
+* PEP 3111: :func:`raw_input` renamed to :func:`input`. That is, the new
+ :func:`input` function reads a line from :data:`sys.stdin` and returns it with
+ the trailing newline stripped. It raises :exc:`EOFError` if the input is
+ terminated prematurely. To get the old behavior of :func:`input`, use
+ ``eval(input())``.
-* ``xrange()`` renamed to ``range()``.
+* :func:`xrange` renamed to :func:`range`.
-* PEP 3113: Tuple parameter unpacking removed. You can no longer write
- ``def foo(a, (b, c)): ...``. Use ``def foo(a, b_c): b, c = b_c``
- instead.
+* PEP 3113: Tuple parameter unpacking removed. You can no longer write ``def
+ foo(a, (b, c)): ...``. Use ``def foo(a, b_c): b, c = b_c`` instead.
-* PEP 3114: ``.next()`` renamed to ``.__next__()``, new builtin
- ``next()`` to call the ``__next__()`` method on an object.
+* PEP 3114: ``.next()`` renamed to :meth:`__next__`, new builtin :func:`next` to
+ call the :meth:`__next__` method on an object.
-* PEP 3127: New octal literals; binary literals and ``bin()``.
- Instead of ``0666``, you write ``0o666``. The oct() function is
- modified accordingly. Also, ``0b1010`` equals 10, and ``bin(10)``
- returns ``"0b1010"``. ``0666`` is now a ``SyntaxError``.
+* PEP 3127: New octal literals; binary literals and :func:`bin`. Instead of
+ ``0666``, you write ``0o666``. The :func:`oct` function is modified
+ accordingly. Also, ``0b1010`` equals 10, and ``bin(10)`` returns
+ ``"0b1010"``. ``0666`` is now a :exc:`SyntaxError`.
-* PEP 3132: Extended Iterable Unpacking. You can now write things
- like ``a, b, *rest = some_sequence``. And even ``*rest, a =
- stuff``. The ``rest`` object is always a list; the right-hand
- side may be any iterable.
+* PEP 3132: Extended Iterable Unpacking. You can now write things like ``a, b,
+ *rest = some_sequence``. And even ``*rest, a = stuff``. The ``rest`` object
+ is always a list; the right-hand side may be any iterable.
-* PEP 3135: New ``super()``. You can now invoke ``super()`` without
- arguments and the right class and instance will automatically be
- chosen. With arguments, its behavior is unchanged.
+* PEP 3135: New :func:`super`. You can now invoke :func:`super` without
+ arguments and the right class and instance will automatically be chosen. With
+ arguments, its behavior is unchanged.
-* ``zip()``, ``map()`` and ``filter()`` return iterators.
+* :func:`zip`, :func:`map` and :func:`filter` return iterators.
-* ``string.letters`` and its friends (``.lowercase`` and
- ``.uppercase``) are gone. Use ``string.ascii_letters``
+* :data:`string.letters` and its friends (:data:`string.lowercase` and
+ :data:`string.uppercase`) are gone. Use :data:`string.ascii_letters`
etc. instead.
-* Removed: ``apply()``, ``callable()``, ``coerce()``, ``execfile()``,
- ``file()``, ``reduce()``, ``reload()``.
+* Removed: :func:`apply`, :func:`callable`, :func:`coerce`, :func:`execfile`,
+ :func:`file`, :func:`reduce`, :func:`reload`.
-* Removed: ``dict.has_key()``.
+* Removed: :meth:`dict.has_key`.
-* ``exec`` is now a function.
+* :func:`exec` is now a function.
-* There is a new free format floating point representation, which is
- based on "Floating-Point Printer Sample Code", by Robert G. Burger.
- ``repr(11./5)`` now returns ``2.2`` instead of ``2.2000000000000002``.
+* There is a new free format floating point representation, which is based on
+ "Floating-Point Printer Sample Code", by Robert G. Burger. ``repr(11./5)``
+ now returns ``2.2`` instead of ``2.2000000000000002``.
-* The ``__oct__()`` and ``__hex__()`` special methods are removed --
- ``oct()`` and ``hex()`` use ``__index__()`` now to convert the
- argument to an integer.
+* The :meth:`__oct__` and :meth:`__hex__` special methods are removed --
+ :func:`oct` and :func:`hex` use :meth:`__index__` now to convert the argument
+ to an integer.
-* There is now a ``bin()`` builtin function.
+* Support is removed for :attr:`__members__` and :attr:`__methods__`.
-* Support is removed for ``__members__`` and ``__methods__``.
+* Renamed the boolean conversion C-level slot and method: ``nb_nonzero`` is now
+ ``nb_bool`` and :meth:`__nonzero__` is now :meth:`__bool__`.
-* ``nb_nonzero`` is now ``nb_bool`` and ``__nonzero__`` is now
- ``__bool__``.
-
-* Removed ``sys.maxint``. Use ``sys.maxsize``.
+* Removed :data:`sys.maxint`. Use :data:`sys.maxsize`.
.. ======================================================================
@@ -360,10 +355,10 @@
* Detailed changes are listed here.
-The net result of the 3.0 generalizations is that Python 3.0 runs the
-pystone benchmark around 33% slower than Python 2.5. There's room for
-improvement; we expect to be optimizing string and integer operations
-significantly before the final 3.0 release!
+The net result of the 3.0 generalizations is that Python 3.0 runs the pystone
+benchmark around 33% slower than Python 2.5. There's room for improvement; we
+expect to be optimizing string and integer operations significantly before the
+final 3.0 release!
.. ======================================================================
@@ -371,26 +366,27 @@
New, Improved, and Deprecated Modules
=====================================
-As usual, Python's standard library received a number of enhancements
-and bug fixes. Here's a partial list of the most notable changes,
-sorted alphabetically by module name. Consult the :file:`Misc/NEWS`
-file in the source tree for a more complete list of changes, or look
-through the Subversion logs for all the details.
+As usual, Python's standard library received a number of enhancements and bug
+fixes. Here's a partial list of the most notable changes, sorted alphabetically
+by module name. Consult the :file:`Misc/NEWS` file in the source tree for a more
+complete list of changes, or look through the Subversion logs for all the
+details.
-* The ``cPickle`` module is gone. Use ``pickle`` instead. Eventually
+* The :mod:`cPickle` module is gone. Use :mod:`pickle` instead. Eventually
we'll have a transparent accelerator module.
-* The ``imageop`` module is gone.
+* The :mod:`imageop` module is gone.
-* The ``audiodev``, ``Bastion``, ``bsddb185``, ``exceptions``,
- ``linuxaudiodev``, ``md5``, ``MimeWriter``, ``mimify``, ``popen2``,
- ``rexec``, ``sets``, ``sha``, ``stringold``, ``strop``, ``sunaudiodev``,
- ``timing``, and ``xmllib`` modules are gone.
+* The :mod:`audiodev`, :mod:`Bastion`, :mod:`bsddb185`, :mod:`exceptions`,
+ :mod:`linuxaudiodev`, :mod:`md5`, :mod:`MimeWriter`, :mod:`mimify`,
+ :mod:`popen2`, :mod:`rexec`, :mod:`sets`, :mod:`sha`, :mod:`stringold`,
+ :mod:`strop`, :mod:`sunaudiodev`, :mod:`timing`, and :mod:`xmllib` modules are
+ gone.
-* The ``new`` module is gone.
+* The :mod:`new` module is gone.
-* The methods ``os.tmpnam()``, ``os.tempnam()`` and ``os.tmpfile()`` have
- been removed in favor of the ``tempfile`` module.
+* The functions :func:`os.tmpnam`, :func:`os.tempnam` and :func:`os.tmpfile`
+ have been removed in favor of the :mod:`tempfile` module.
.. ======================================================================
.. whole new modules get described in subsections here
@@ -407,15 +403,15 @@
* PEP 3121: Extension Module Initialization & Finalization.
-* PEP 3123: Making ``PyObject_HEAD`` conform to standard C.
+* PEP 3123: Making :cmacro:`PyObject_HEAD` conform to standard C.
* No more C API support for restricted execution.
-* ``PyNumber_Coerce()``, ``PyNumber_CoerceEx()``, ``PyMember_Get``,
- and ``PyMember_Set`` C APIs are removed.
+* :cfunc:`PyNumber_Coerce`, :cfunc:`PyNumber_CoerceEx`, :cfunc:`PyMember_Get`,
+ and :cfunc:`PyMember_Set` C APIs are removed.
-* New C API ``PyImport_ImportModuleNoBlock()``, works like
- ``PyImport_ImportModule()`` but won't block on the import lock (returning
+* New C API :cfunc:`PyImport_ImportModuleNoBlock`, works like
+ :cfunc:`PyImport_ImportModule` but won't block on the import lock (returning
an error instead).
.. ======================================================================