Double parens in functions references

Doc/whatsnew/2.4.rst

 ****************************
   What's New in Python 2.4
 ****************************
 
 :Author: A.M. Kuchling
 
 .. |release| replace:: 1.02
 
 .. $Id: whatsnew24.tex 54632 2007-03-31 11:59:54Z georg.brandl $
 .. Don't write extensive text for new sections; I'll do that.
@@ skipping 19 matching lines @@
 implementation and design rationale.
 
 .. ======================================================================
 
 
 PEP 218: Built-In Set Objects
 =============================
 
 Python 2.3 introduced the :mod:`sets` module.  C implementations of set data
 types have now been added to the Python core as two new built-in types,
-:func:`set(iterable) <set>` and :func:`frozenset(iterable) <frozenset>`.  They provide high speed
+``set(iterable)`` and ``frozenset(iterable)``.  They provide high speed
 operations for membership testing, for eliminating duplicates from sequences,
 and for mathematical operations like unions, intersections, differences, and
 symmetric differences. ::
 
    >>> a = set('abracadabra')              # form a set from a string
    >>> 'z' in a                            # fast membership testing
    False
    >>> a                                   # unique letters in a
    set(['a', 'r', 'b', 'c', 'd'])
    >>> ''.join(a)                          # convert back into a string
@@ skipping 288 matching lines @@
 
    http://www.python.org/moin/PythonDecoratorLibrary
       This Wiki page contains several examples of decorators.
 
 .. ======================================================================
 
 
 PEP 322: Reverse Iteration
 ==========================
 
-A new built-in function, :func:`reversed(seq) <reversed>`, takes a sequence and returns an
+A new built-in function, ``reversed(seq)``, takes a sequence and returns an
 iterator that loops over the elements of the sequence  in reverse order.   ::
 
    >>> for i in reversed(xrange(1,4)):
    ...    print i
    ...
    3
    2
    1
 
 Compared to extended slicing, such as ``range(1,4)[::-1]``, :func:`reversed` is
@@ skipping 17 matching lines @@
       Written and implemented by Raymond Hettinger.
 
 .. ======================================================================
 
 
 PEP 324: New subprocess Module
 ==============================
 
 The standard library provides a number of ways to execute a subprocess, offering
 different features and different levels of complexity.
-:func:`os.system(command) <os.system>` is easy to use, but slow (it runs a shell process
+``os.system(command)`` is easy to use, but slow (it runs a shell process
 which executes the command) and dangerous (you have to be careful about escaping
 the shell's metacharacters).  The :mod:`popen2` module offers classes that can
 capture standard output and standard error from the subprocess, but the naming
 is confusing.  The :mod:`subprocess` module cleans  this up, providing a unified
 interface that offers all the features you might need.
 
 Instead of :mod:`popen2`'s collection of classes, :mod:`subprocess` contains a
 single class called :class:`Popen`  whose constructor supports a number of
 different keyword arguments. ::
 
@@ skipping 23 matching lines @@
 
 * *env* is a dictionary specifying environment variables.
 
 * *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.
 
 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
-exited without pausing,  or :meth:`communicate(data) <subprocess.Popen.communicate>` to send the string *data*
-to the subprocess's standard input.   :meth:`communicate(data) <subprocess.Popen.communicate>`  then reads any
+exited without pausing,  or ``communicate(data)`` to send the string *data*
+to the subprocess's standard input.   ``communicate(data)``  then reads any
 data that the subprocess has sent to its standard output  or standard error,
 returning a tuple ``(stdout_data, stderr_data)``.
 
 :func:`call` is a shortcut that passes its arguments along to the :class:`Popen`
 constructor, waits for the command to complete, and returns the status code of
 the subprocess.  It can serve as a safer analog to :func:`os.system`::
 
    sts = subprocess.call(['dpkg', '-i', '/tmp/new-package.deb'])
    if sts == 0:
        # Success
@@ skipping 296 matching lines @@
 library's :c:func:`atof` function.
 
 Not setting the numeric locale caused trouble for extensions that used third-
 party C libraries, however, because they wouldn't have the correct locale set.
 The motivating example was GTK+, whose user interface widgets weren't displaying
 numbers in the current locale.
 
 The solution described in the PEP is to add three new functions to the Python
 API that perform ASCII-only conversions, ignoring the locale setting:
 
-* :c:func:`PyOS_ascii_strtod(str, ptr) <PyOS_ascii_strtod>`  and :c:func:`PyOS_ascii_atof(str, ptr) <PyOS_ascii_atof>`
+* ``PyOS_ascii_strtod(str, ptr)``  and ``PyOS_ascii_atof(str, ptr)``
   both convert a string to a C :c:type:`double`.
 
-* :c:func:`PyOS_ascii_formatd(buffer, buf_len, format, d) <PyOS_ascii_formatd>` converts a
+* ``PyOS_ascii_formatd(buffer, buf_len, format, d)`` converts a
   :c:type:`double` to an ASCII string.
 
 The code for these functions came from the GLib library
 (http://library.gnome.org/devel/glib/stable/), whose developers kindly
 relicensed the relevant functions and donated them to the Python Software
 Foundation.  The :mod:`locale` module  can now change the numeric locale,
 letting extensions such as GTK+  produce the correct results.
 
 
 .. seealso::
 
    :pep:`331` - Locale-Independent Float/String Conversions
       Written by Christian R. Reis, and implemented by Gustavo Carneiro.
 
 .. ======================================================================
 
 
 Other Language Changes
 ======================
 
 Here are all of the changes that Python 2.4 makes to the core Python language.
 
 * Decorators for functions and methods were added (:pep:`318`).
 
 * Built-in :func:`set` and :func:`frozenset` types were  added (:pep:`218`).
-  Other new built-ins include the :func:`reversed(seq) <reversed>` function (:pep:`322`).
+  Other new built-ins include the ``reversed(seq)`` function (:pep:`322`).
 
 * Generator expressions were added (:pep:`289`).
 
 * Certain numeric expressions no longer return values restricted to 32 or 64
   bits (:pep:`237`).
 
 * You can now put parentheses around the list of names in a ``from module import
   names`` statement (:pep:`328`).
 
 * The :meth:`dict.update` method now accepts the same argument forms as the
@@ skipping 58 matching lines @@
   L.reverse()``, you can now write ``L.sort(reverse=True)``.
 
   The results of sorting are now guaranteed to be stable.  This means that two
   entries with equal keys will be returned in the same order as they were input.
   For example, you can sort a list of people by name, and then sort the list by
   age, resulting in a list sorted by age where people with the same age are in
   name-sorted order.
 
   (All changes to :meth:`sort` contributed by Raymond Hettinger.)
 
-* There is a new built-in function :func:`sorted(iterable) <sorted>` that works like the
+* There is a new built-in function ``sorted(iterable)`` that works like the
   in-place :meth:`list.sort` method but can be used in expressions.  The
   differences are:
 
 * the input may be any iterable;
 
 * a newly formed copy is sorted, leaving the original intact; and
 
 * the expression returns the new sorted copy
 
   ::
@@ skipping 20 matching lines @@
   (Contributed by Raymond Hettinger.)
 
 * Integer operations will no longer trigger an :exc:`OverflowWarning`. The
   :exc:`OverflowWarning` warning will disappear in Python 2.5.
 
 * The interpreter gained a new switch, :option:`-m`, that takes a name, searches
   for the corresponding  module on ``sys.path``, and runs the module as a script.
   For example,  you can now run the Python profiler with ``python -m profile``.
   (Contributed by Nick Coghlan.)
 
-* The :func:`eval(expr, globals, locals) <eval>` and :func:`execfile(filename, globals,
-  locals) <execfile>` functions and the ``exec`` statement now accept any mapping type
+* The ``eval(expr, globals, locals)`` and ``execfile(filename, globals,
+  locals)`` functions and the ``exec`` statement now accept any mapping type
   for the *locals* parameter.  Previously this had to be a regular Python
   dictionary.  (Contributed by Raymond Hettinger.)
 
 * The :func:`zip` built-in function and :func:`itertools.izip` now return an
   empty list if called with no arguments. Previously they raised a
   :exc:`TypeError` exception.  This makes them more suitable for use with variable
   length argument lists::
 
      >>> def transpose(array):
      ...    return zip(*array)
@@ skipping 170 matching lines @@
 * The :mod:`httplib` module now contains constants for HTTP status codes defined
   in various HTTP-related RFC documents.  Constants have names such as
   :const:`OK`, :const:`CREATED`, :const:`CONTINUE`, and
   :const:`MOVED_PERMANENTLY`; use pydoc to get a full list.  (Contributed by
   Andrew Eland.)
 
 * The :mod:`imaplib` module now supports IMAP's THREAD command (contributed by
   Yves Dionne) and new :meth:`deleteacl` and :meth:`myrights` methods (contributed
   by Arnaud Mazin).
 
-* The :mod:`itertools` module gained a :func:`groupby(iterable[, *func*]) <itertools.groupby>`
+* The :mod:`itertools` module gained a ``groupby(iterable[, *func*])``
   function. *iterable* is something that can be iterated over to return a stream
   of elements, and the optional *func* parameter is a function that takes an
   element and returns a key value; if omitted, the key is simply the element
   itself.  :func:`groupby` then groups the elements into subsequences which have
   matching values of the key, and returns a series of 2-tuples containing the key
   value and an iterator over the subsequence.
 
   Here's an example to make this clearer.  The *key* function simply returns
   whether a number is even or odd, so the result of :func:`groupby` is to return
   consecutive runs of odd or even numbers. ::
@@ skipping 28 matching lines @@
      r ['r', 'r']
      >>> # List unique letters
      >>> [k for k, g in groupby(letters)]
      ['a', 'b', 'c', 'd', 'r']
      >>> # Count letter occurrences
      >>> [(k, len(list(g))) for k, g in groupby(letters)]
      [('a', 5), ('b', 2), ('c', 1), ('d', 1), ('r', 2)]
 
   (Contributed by Hye-Shik Chang.)
 
-* :mod:`itertools` also gained a function named :func:`tee(iterator, N) <itertools.tee>` that
+* :mod:`itertools` also gained a function named ``tee(iterator, N)`` that
   returns *N* independent iterators that replicate *iterator*.  If *N* is omitted,
   the default is 2. ::
 
      >>> L = [1,2,3]
      >>> i1, i2 = itertools.tee(L)
      >>> i1,i2
      (<itertools.tee object at 0x402c2080>, <itertools.tee object at 0x402c2090>)
      >>> list(i1)               # Run the first iterator to exhaustion
      [1, 2, 3]
      >>> list(i2)               # Run the second iterator to exhaustion
@@ skipping 17 matching lines @@
   :func:`basicConfig` function to simplify log configuration.  The default
   behavior is to log messages to standard error, but various keyword arguments can
   be specified to log to a particular file, change the logging format, or set the
   logging level. For example::
 
      import logging
      logging.basicConfig(filename='/var/log/application.log',
          level=0,  # Log all messages
          format='%(levelname):%(process):%(thread):%(message)')
 
-  Other additions to the :mod:`logging` package include a :meth:`log(level, msg) <logging.Logger.log>`
+  Other additions to the :mod:`logging` package include a ``log(level, msg)``
   convenience method, as well as a :class:`TimedRotatingFileHandler` class that
   rotates its log files at a timed interval.  The module already had
   :class:`RotatingFileHandler`, which rotated logs once the file exceeded a
   certain size.  Both classes derive from a new :class:`BaseRotatingHandler` class
   that can be used to implement other rotating handlers.
 
   (Changes implemented by Vinay Sajip.)
 
 * The :mod:`marshal` module now shares interned strings on unpacking a  data
   structure.  This may shrink the size of certain pickle strings, but the primary
   effect is to make :file:`.pyc` files significantly smaller. (Contributed by
   Martin von Löwis.)
 
 * The :mod:`nntplib` module's :class:`NNTP` class gained :meth:`description` and
   :meth:`descriptions` methods to retrieve  newsgroup descriptions for a single
   group or for a range of groups. (Contributed by Jürgen A. Erhard.)
 
 * Two new functions were added to the :mod:`operator` module,
-  :func:`attrgetter(attr) <operator.attrgetter>` and :func:`itemgetter(index) <operator.itemgetter>`. Both functions return
+  ``attrgetter(attr)`` and ``itemgetter(index)``. Both functions return
   callables that take a single argument and return the corresponding attribute or
   item; these callables make excellent data extractors when used with :func:`map`
   or :func:`sorted`.  For example::
 
      >>> L = [('c', 2), ('d', 1), ('a', 4), ('b', 3)]
      >>> map(operator.itemgetter(0), L)
      ['c', 'd', 'a', 'b']
      >>> map(operator.itemgetter(1), L)
      [2, 1, 4, 3]
      >>> sorted(L, key=operator.itemgetter(1)) # Sort list by second tuple item
      [('d', 1), ('c', 2), ('b', 3), ('a', 4)]
 
   (Contributed by Raymond Hettinger.)
 
 * The :mod:`optparse` module was updated in various ways.  The module now passes
   its messages through :func:`gettext.gettext`, making it possible to
   internationalize Optik's help and error messages.  Help messages for options can
   now include the string ``'%default'``, which will be replaced by the option's
   default value.  (Contributed by Greg Ward.)
 
 * The long-term plan is to deprecate the :mod:`rfc822` module in some future
   Python release in favor of the :mod:`email` package. To this end, the
   :func:`email.Utils.formatdate` function has been changed to make it usable as a
   replacement for :func:`rfc822.formatdate`.  You may want to write new e-mail
   processing code with this in mind.  (Change implemented by Anthony Baxter.)
 
-* A new :func:`urandom(n) <os.urandom>` function was added to the :mod:`os` module, returning
+* A new ``urandom(n)`` function was added to the :mod:`os` module, returning
   a string containing *n* bytes of random data.  This function provides access to
   platform-specific sources of randomness such as :file:`/dev/urandom` on Linux or
   the Windows CryptoAPI.  (Contributed by Trevor Perrin.)
 
-* Another new function: :func:`os.path.lexists(path) <os.path.lexists>`  returns true if the file
+* Another new function: ``os.path.lexists(path)``  returns true if the file
   specified by *path* exists, whether or not it's a symbolic link.  This differs
-  from the existing :func:`os.path.exists(path) <os.path.exists>` function, which returns false if
+  from the existing ``os.path.exists(path)`` function, which returns false if
   *path* is a symlink that points to a destination that doesn't exist.
   (Contributed by Beni Cherniavsky.)
 
 * A new :func:`getsid` function was added to the :mod:`posix` module that
   underlies the :mod:`os` module. (Contributed by J. Raynor.)
 
 * The :mod:`poplib` module now supports POP over SSL.  (Contributed by Hector
   Urtubia.)
 
 * The :mod:`profile` module can now profile C extension functions. (Contributed
   by Nick Bastin.)
 
-* The :mod:`random` module has a new method called :meth:`getrandbits(N) <random.getrandbits>` that
+* The :mod:`random` module has a new method called ``getrandbits(N)`` that
   returns a long integer *N* bits in length.  The existing :meth:`randrange`
   method now uses :meth:`getrandbits` where appropriate, making generation of
   arbitrarily large random numbers more efficient.  (Contributed by Raymond
   Hettinger.)
 
 * The regular expression language accepted by the :mod:`re` module was extended
   with simple conditional expressions, written as ``(?(group)A|B)``.  *group* is
   either a numeric group ID or a group name defined with ``(?P<group>...)``
   earlier in the expression.  If the specified group matched, the regular
   expression pattern *A* will be tested against the string; if the group didn't
   match, the pattern *B* will be used instead. (Contributed by Gustavo Niemeyer.)
 
 * The :mod:`re` module is also no longer recursive, thanks to a massive amount
   of work by Gustavo Niemeyer.  In a recursive regular expression engine, certain
   patterns result in a large amount of C stack space being consumed, and it was
   possible to overflow the stack. For example, if you matched a 30000-byte string
   of ``a`` characters against the expression ``(a|b)+``, one stack frame was
   consumed per character.  Python 2.3 tried to check for stack overflow and raise
   a :exc:`RuntimeError` exception, but certain patterns could sidestep the
   checking and if you were unlucky Python could segfault. Python 2.4's regular
   expression engine can match this pattern without problems.
 
 * The :mod:`signal` module now performs tighter error-checking on the parameters
   to the :func:`signal.signal` function.  For example, you can't set a handler on
   the :const:`SIGKILL` signal; previous versions of Python would quietly accept
   this, but 2.4 will raise a :exc:`RuntimeError` exception.
 
 * Two new functions were added to the :mod:`socket` module. :func:`socketpair`
-  returns a pair of connected sockets and :func:`getservbyport(port) <socket.getservbyport>` looks up the
+  returns a pair of connected sockets and ``getservbyport(port)`` looks up the
   service name for a given port number. (Contributed by Dave Cole and Barry
   Warsaw.)
 
 * The :func:`sys.exitfunc` function has been deprecated.  Code should be using
   the existing :mod:`atexit` module, which correctly handles calling multiple exit
   functions.  Eventually :func:`sys.exitfunc` will become a purely internal
   interface, accessed only by :mod:`atexit`.
 
 * The :mod:`tarfile` module now generates GNU-format tar files by default.
   (Contributed by Lars Gustaebel.)
@@ skipping 161 matching lines @@
 
 Some of the changes to Python's build process and to the C API are:
 
 * Three new convenience macros were added for common return values from
   extension functions: :c:macro:`Py_RETURN_NONE`, :c:macro:`Py_RETURN_TRUE`, and
   :c:macro:`Py_RETURN_FALSE`. (Contributed by Brett Cannon.)
 
 * Another new macro, :c:macro:`Py_CLEAR(obj)`,  decreases the reference count of
   *obj* and sets *obj* to the null pointer.  (Contributed by Jim Fulton.)
 
-* A new function, :c:func:`PyTuple_Pack(N, obj1, obj2, ..., objN) <PyTuple_Pack>`, constructs
+* A new function, ``PyTuple_Pack(N, obj1, obj2, ..., objN)``, constructs
   tuples from a variable length argument list of Python objects.  (Contributed by
   Raymond Hettinger.)
 
-* A new function, :c:func:`PyDict_Contains(d, k) <PyDict_Contains>`, implements fast dictionary
+* A new function, ``PyDict_Contains(d, k)``, implements fast dictionary
   lookups without masking exceptions raised during the look-up process.
   (Contributed by Raymond Hettinger.)
 
 * The :c:macro:`Py_IS_NAN(X)` macro returns 1 if  its float or double argument
   *X* is a NaN.   (Contributed by Tim Peters.)
 
 * C code can avoid unnecessary locking by using the new
   :c:func:`PyEval_ThreadsInitialized` function to tell  if any thread operations
   have been performed.  If this function  returns false, no lock operations are
   needed. (Contributed by Nick Coghlan.)
@@ skipping 82 matching lines @@
 .. _24acks:
 
 Acknowledgements
 ================
 
 The author would like to thank the following people for offering suggestions,
 corrections and assistance with various drafts of this article: Koray Can,
 Hye-Shik Chang, Michael Dyck, Raymond Hettinger, Brian Hurt, Hamish Lawson,
 Fredrik Lundh, Sean Reifschneider, Sadruddin Rejeb.