diff -r aaa68dce117e Doc/library/os.rst --- a/Doc/library/os.rst Thu Aug 09 21:38:23 2012 +0200 +++ b/Doc/library/os.rst Sat Aug 11 00:00:33 2012 +0300 @@ -450,7 +450,7 @@ .. function:: setpgrp() - Call the system call :c:func:`setpgrp` or :c:func:`setpgrp(0, 0)` depending on + Call the system call :c:func:`setpgrp` or ``setpgrp(0, 0)`` depending on which version is implemented (if any). See the Unix manual for the semantics. Availability: Unix. diff -r aaa68dce117e Doc/library/platform.rst --- a/Doc/library/platform.rst Thu Aug 09 21:38:23 2012 +0200 +++ b/Doc/library/platform.rst Sat Aug 11 00:00:33 2012 +0300 @@ -30,8 +30,8 @@ returned as strings. Values that cannot be determined are returned as given by the parameter presets. - If bits is given as ``''``, the :c:func:`sizeof(pointer)` (or - :c:func:`sizeof(long)` on Python version < 1.5.2) is used as indicator for the + If bits is given as ``''``, the ``sizeof(pointer)`` (or + ``sizeof(long)`` on Python version < 1.5.2) is used as indicator for the supported pointer size. The function relies on the system's :file:`file` command to do the actual work. diff -r aaa68dce117e Doc/whatsnew/2.0.rst --- a/Doc/whatsnew/2.0.rst Thu Aug 09 21:38:23 2012 +0200 +++ b/Doc/whatsnew/2.0.rst Sat Aug 11 00:00:33 2012 +0300 @@ -166,7 +166,7 @@ registering new encodings that are then available throughout a Python program. If an encoding isn't specified, the default encoding is usually 7-bit ASCII, though it can be changed for your Python installation by calling the -:func:`sys.setdefaultencoding(encoding)` function in a customised version of +:func:`sys.setdefaultencoding(encoding) ` function in a customised version of :file:`site.py`. Combining 8-bit and Unicode strings always coerces to Unicode, using the default @@ -203,7 +203,7 @@ The :mod:`codecs` module contains functions to look up existing encodings and register new ones. Unless you want to implement a new encoding, you'll most -often use the :func:`codecs.lookup(encoding)` function, which returns a +often use the :func:`codecs.lookup(encoding) ` function, which returns a 4-element tuple: ``(encode_func, decode_func, stream_reader, stream_writer)``. * *encode_func* is a function that takes a Unicode string, and returns a 2-tuple @@ -600,7 +600,7 @@ Changes to Built-in Functions ----------------------------- -A new built-in, :func:`zip(seq1, seq2, ...)`, has been added. :func:`zip` +A new built-in, ``zip(seq1, seq2, ...)``, has been added. :func:`zip` returns a list of tuples where each tuple contains the i-th element from each of the argument sequences. The difference between :func:`zip` and ``map(None, seq1, seq2)`` is that :func:`map` pads the sequences with ``None`` if the @@ -619,7 +619,7 @@ would be ``(2, 0, 1, 'beta', 1)``. *level* is a string such as ``"alpha"``, ``"beta"``, or ``"final"`` for a final release. -Dictionaries have an odd new method, :meth:`setdefault(key, default)`, which +Dictionaries have an odd new method, :meth:`setdefault(key, default) `, which behaves similarly to the existing :meth:`get` method. However, if the key is missing, :meth:`setdefault` both returns the value of *default* as :meth:`get` would do, and also inserts it into the dictionary as the value for *key*. Thus, @@ -671,7 +671,7 @@ ``NO_STRICT_LIST_APPEND`` to preserve the old behaviour; this isn't recommended. Some of the functions in the :mod:`socket` module are still forgiving in this -way. For example, :func:`socket.connect( ('hostname', 25) )` is the correct +way. For example, :func:`socket.connect( ('hostname', 25) ) ` is the correct form, passing a tuple representing an IP address, but :func:`socket.connect( 'hostname', 25 )` also works. :func:`socket.connect_ex` and :func:`socket.bind` are similarly easy-going. 2.0alpha1 tightened these functions up, but because @@ -1038,7 +1038,7 @@ is an implementation of the Secure Socket Layer, which encrypts the data being sent over a socket. When compiling Python, you can edit :file:`Modules/Setup` to include SSL support, which adds an additional function to the :mod:`socket` -module: :func:`socket.ssl(socket, keyfile, certfile)`, which takes a socket +module: :func:`socket.ssl(socket, keyfile, certfile) `, which takes a socket object and returns an SSL socket. The :mod:`httplib` and :mod:`urllib` modules were also changed to support ``https://`` URLs, though no one has implemented FTP or SMTP over SSL. diff -r aaa68dce117e Doc/whatsnew/2.1.rst --- a/Doc/whatsnew/2.1.rst Thu Aug 09 21:38:23 2012 +0200 +++ b/Doc/whatsnew/2.1.rst Sat Aug 11 00:00:33 2012 +0300 @@ -204,7 +204,7 @@ list, or any other Python object. Alternatively they can raise an exception if the comparison is impossible, inconsistent, or otherwise meaningless. -The built-in :func:`cmp(A,B)` function can use the rich comparison machinery, +The built-in ``cmp(A,B)`` function can use the rich comparison machinery, and now accepts an optional argument specifying which comparison operation to use; this is given as one of the strings ``"<"``, ``"<="``, ``">"``, ``">="``, ``"=="``, or ``"!="``. If called without the optional third argument, @@ -350,7 +350,7 @@ and another being circular references in data structures such as trees. For example, consider a memoizing function that caches the results of another -function :func:`f(x)` by storing the function's argument and its result in a +function ``f(x)`` by storing the function's argument and its result in a dictionary:: _cache = {} @@ -656,7 +656,7 @@ use :mod:`ftplib` to retrieve files and then don't work from behind a firewall. It's deemed unlikely that this will cause problems for anyone, because Netscape defaults to passive mode and few people complain, but if passive mode is - unsuitable for your application or network setup, call :meth:`set_pasv(0)` on + unsuitable for your application or network setup, call :meth:`set_pasv(0) ` on FTP objects to disable passive mode. * Support for raw socket access has been added to the :mod:`socket` module, @@ -666,7 +666,7 @@ for displaying timing profiles for Python programs, invoked when the module is run as a script. Contributed by Eric S. Raymond. -* A new implementation-dependent function, :func:`sys._getframe([depth])`, has +* A new implementation-dependent function, :func:`sys._getframe([depth]) `, has been added to return a given frame object from the current call stack. :func:`sys._getframe` returns the frame at the top of the call stack; if the optional integer argument *depth* is supplied, the function returns the frame diff -r aaa68dce117e Doc/whatsnew/2.2.rst --- a/Doc/whatsnew/2.2.rst Thu Aug 09 21:38:23 2012 +0200 +++ b/Doc/whatsnew/2.2.rst Sat Aug 11 00:00:33 2012 +0300 @@ -173,12 +173,12 @@ * :attr:`__doc__` is the attribute's docstring. -* :meth:`__get__(object)` is a method that retrieves the attribute value from +* :meth:`__get__(object) <__get__>` is a method that retrieves the attribute value from *object*. -* :meth:`__set__(object, value)` sets the attribute on *object* to *value*. +* :meth:`__set__(object, value) <__set__>` sets the attribute on *object* to *value*. -* :meth:`__delete__(object, value)` deletes the *value* attribute of *object*. +* :meth:`__delete__(object, value) <__delete__>` deletes the *value* attribute of *object*. For example, when you write ``obj.x``, the steps that Python actually performs are:: @@ -288,7 +288,7 @@ which is the behaviour we're after. This lookup rule is the same as the one followed by Common Lisp. A new built-in function, :func:`super`, provides a way to get at a class's superclasses without having to reimplement Python's -algorithm. The most commonly used form will be :func:`super(class, obj)`, which +algorithm. The most commonly used form will be ``super(class, obj)``, which returns a bound superclass object (not the actual class object). This form will be used in methods to call a method in the superclass; for example, :class:`D`'s :meth:`save` method would look like this:: @@ -301,7 +301,7 @@ ... :func:`super` can also return unbound superclass objects when called as -:func:`super(class)` or :func:`super(class1, class2)`, but this probably won't +``super(class)`` or ``super(class1, class2)``, but this probably won't often be useful. @@ -314,13 +314,13 @@ ``obj.parent`` into a method call such as ``obj.get_parent``. Python 2.2 adds some new ways of controlling attribute access. -First, :meth:`__getattr__(attr_name)` is still supported by new-style classes, +First, :meth:`__getattr__(attr_name) <__getattr__>` is still supported by new-style classes, and nothing about it has changed. As before, it will be called when an attempt is made to access ``obj.foo`` and no attribute named ``foo`` is found in the instance's dictionary. New-style classes also support a new method, -:meth:`__getattribute__(attr_name)`. The difference between the two methods is +:meth:`__getattribute__(attr_name) <__getattribute__>`. The difference between the two methods is that :meth:`__getattribute__` is *always* called whenever any attribute is accessed, while the old :meth:`__getattr__` is only called if ``foo`` isn't found in the instance's dictionary. @@ -441,8 +441,8 @@ In Python 2.2, iteration can be implemented separately, and :meth:`__getitem__` methods can be limited to classes that really do support random access. The -basic idea of iterators is simple. A new built-in function, :func:`iter(obj)` -or ``iter(C, sentinel)``, is used to get an iterator. :func:`iter(obj)` returns +basic idea of iterators is simple. A new built-in function, :func:`iter(obj) ` +or :func:`iter(C, sentinel) `, is used to get an iterator. ``iter(obj)`` returns an iterator for the object *obj*, while ``iter(C, sentinel)`` returns an iterator that will invoke the callable object *C* until it returns *sentinel* to signal that the iterator is done. @@ -793,7 +793,7 @@ Another change is simpler to explain. Since their introduction, Unicode strings have supported an :meth:`encode` method to convert the string to a selected -encoding such as UTF-8 or Latin-1. A symmetric :meth:`decode([*encoding*])` +encoding such as UTF-8 or Latin-1. A symmetric :meth:`decode([*encoding*]) ` method has been added to 8-bit strings (though not to Unicode strings) in 2.2. :meth:`decode` assumes that the string is in the specified encoding and decodes it, returning whatever is returned by the codec. @@ -1203,7 +1203,7 @@ to an MBCS encoded string, as used by the Microsoft file APIs. As MBCS is explicitly used by the file APIs, Python's choice of ASCII as the default encoding turns out to be an annoyance. On Unix, the locale's character set is - used if :func:`locale.nl_langinfo(CODESET)` is available. (Windows support was + used if :func:`locale.nl_langinfo(CODESET) ` is available. (Windows support was contributed by Mark Hammond with assistance from Marc-André Lemburg. Unix support was added by Martin von Löwis.) diff -r aaa68dce117e Doc/whatsnew/2.3.rst --- a/Doc/whatsnew/2.3.rst Thu Aug 09 21:38:23 2012 +0200 +++ b/Doc/whatsnew/2.3.rst Sat Aug 11 00:00:33 2012 +0300 @@ -501,8 +501,8 @@ ZeroDivisionError: integer division or modulo by zero Slightly more advanced programs will use a logger other than the root logger. -The :func:`getLogger(name)` function is used to get a particular log, creating -it if it doesn't exist yet. :func:`getLogger(None)` returns the root logger. :: +The :func:`getLogger(name) ` function is used to get a particular log, creating +it if it doesn't exist yet. ``getLogger(None)`` returns the root logger. :: log = logging.getLogger('server') ... @@ -721,10 +721,10 @@ objects to it. Additional built-in and frozen modules can be imported by an object added to this list. -Importer objects must have a single method, :meth:`find_module(fullname, -path=None)`. *fullname* will be a module or package name, e.g. ``string`` or +Importer objects must have a single method, ``find_module(fullname, +path=None)``. *fullname* will be a module or package name, e.g. ``string`` or ``distutils.core``. :meth:`find_module` must return a loader object that has a -single method, :meth:`load_module(fullname)`, that creates and returns the +single method, ``load_module(fullname)``, that creates and returns the corresponding module object. Pseudo-code for Python's new import logic, therefore, looks something like this @@ -932,7 +932,7 @@ [0, 2, 4] To simplify implementing sequences that support extended slicing, slice objects -now have a method :meth:`indices(length)` which, given the length of a sequence, +now have a method :meth:`indices(length) ` which, given the length of a sequence, returns a ``(start, stop, step)`` tuple that can be passed directly to :func:`range`. :meth:`indices` handles omitted and out-of-bounds indices in a manner consistent with regular slices (and this innocuous phrase hides a welter @@ -981,7 +981,7 @@ * Built-in types now support the extended slicing syntax, as described in section :ref:`section-slices` of this document. -* A new built-in function, :func:`sum(iterable, start=0)`, adds up the numeric +* A new built-in function, :func:`sum(iterable, start=0) `, adds up the numeric items in the iterable object and returns their sum. :func:`sum` only accepts numbers, meaning that you can't use it to concatenate a bunch of strings. (Contributed by Alex Martelli.) @@ -995,7 +995,7 @@ its index, now takes optional *start* and *stop* arguments to limit the search to only part of the list. -* Dictionaries have a new method, :meth:`pop(key[, *default*])`, that returns +* Dictionaries have a new method, :meth:`pop(key[, *default*]) `, that returns the value corresponding to *key* and removes that key/value pair from the dictionary. If the requested key isn't present in the dictionary, *default* is returned if it's specified and :exc:`KeyError` raised if it isn't. :: @@ -1017,7 +1017,7 @@ {} >>> - There's also a new class method, :meth:`dict.fromkeys(iterable, value)`, that + There's also a new class method, :meth:`dict.fromkeys(iterable, value) `, that creates a dictionary with keys taken from the supplied iterator *iterable* and all values set to *value*, defaulting to ``None``. @@ -1090,7 +1090,7 @@ 100 bytecodes, speeding up single-threaded applications by reducing the switching overhead. Some multithreaded applications may suffer slower response time, but that's easily fixed by setting the limit back to a lower number using - :func:`sys.setcheckinterval(N)`. The limit can be retrieved with the new + :func:`sys.setcheckinterval(N) `. The limit can be retrieved with the new :func:`sys.getcheckinterval` function. * One minor but far-reaching change is that the names of extension types defined @@ -1269,10 +1269,10 @@ * Previously the :mod:`doctest` module would only search the docstrings of public methods and functions for test cases, but it now also examines private - ones as well. The :func:`DocTestSuite(` function creates a + ones as well. The :func:`DocTestSuite() ` function creates a :class:`unittest.TestSuite` object from a set of :mod:`doctest` tests. -* The new :func:`gc.get_referents(object)` function returns a list of all the +* The new :func:`gc.get_referents(object) ` function returns a list of all the objects referenced by *object*. * The :mod:`getopt` module gained a new function, :func:`gnu_getopt`, that @@ -1344,8 +1344,8 @@ documentation for details. (Contributed by Raymond Hettinger.) -* Two new functions in the :mod:`math` module, :func:`degrees(rads)` and - :func:`radians(degs)`, convert between radians and degrees. Other functions in +* Two new functions in the :mod:`math` module, :func:`degrees(rads) ` and + :func:`radians(degs) `, convert between radians and degrees. Other functions in the :mod:`math` module such as :func:`math.sin` and :func:`math.cos` have always required input values measured in radians. Also, an optional *base* argument was added to :func:`math.log` to make it easier to compute logarithms for bases @@ -1402,7 +1402,7 @@ and therefore faster performance. Setting the parser object's :attr:`buffer_text` attribute to :const:`True` will enable buffering. -* The :func:`sample(population, k)` function was added to the :mod:`random` +* The :func:`sample(population, k) ` function was added to the :mod:`random` module. *population* is a sequence or :class:`xrange` object containing the elements of a population, and :func:`sample` chooses *k* elements from the population without replacing chosen elements. *k* can be any value up to @@ -1448,7 +1448,7 @@ encryption is not believed to be secure. If you need encryption, use one of the several AES Python modules that are available separately. -* The :mod:`shutil` module gained a :func:`move(src, dest)` function that +* The :mod:`shutil` module gained a :func:`move(src, dest) ` function that recursively moves a file or directory to a new location. * Support for more advanced POSIX signal handling was added to the :mod:`signal` @@ -1456,7 +1456,7 @@ platforms. * The :mod:`socket` module now supports timeouts. You can call the - :meth:`settimeout(t)` method on a socket object to set a timeout of *t* seconds. + :meth:`settimeout(t) ` method on a socket object to set a timeout of *t* seconds. Subsequent socket operations that take longer than *t* seconds to complete will abort and raise a :exc:`socket.timeout` exception. @@ -1477,9 +1477,9 @@ :program:`tar`\ -format archive files. (Contributed by Lars Gustäbel.) * The new :mod:`textwrap` module contains functions for wrapping strings - containing paragraphs of text. The :func:`wrap(text, width)` function takes a + containing paragraphs of text. The :func:`wrap(text, width) ` function takes a string and returns a list containing the text split into lines of no more than - the chosen width. The :func:`fill(text, width)` function returns a single + the chosen width. The :func:`fill(text, width) ` function returns a single string, reformatted to fit into lines no longer than the chosen width. (As you can guess, :func:`fill` is built on top of :func:`wrap`. For example:: @@ -1900,7 +1900,7 @@ short int`, ``I`` for :c:type:`unsigned int`, and ``K`` for :c:type:`unsigned long long`. -* A new function, :c:func:`PyObject_DelItemString(mapping, char \*key)` was added +* A new function, :c:func:`PyObject_DelItemString(mapping, char \*key) ` was added as shorthand for ``PyObject_DelItem(mapping, PyString_New(key))``. * File objects now manage their internal string buffer differently, increasing diff -r aaa68dce117e Doc/whatsnew/2.4.rst --- a/Doc/whatsnew/2.4.rst Thu Aug 09 21:38:23 2012 +0200 +++ b/Doc/whatsnew/2.4.rst Sat Aug 11 00:00:33 2012 +0300 @@ -37,7 +37,7 @@ 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)` and :func:`frozenset(iterable)`. They provide high speed +:func:`set(iterable) ` and :func:`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. :: @@ -346,7 +346,7 @@ PEP 322: Reverse Iteration ========================== -A new built-in function, :func:`reversed(seq)`, takes a sequence and returns an +A new built-in function, :func:`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)): @@ -384,7 +384,7 @@ The standard library provides a number of ways to execute a subprocess, offering different features and different levels of complexity. -:func:`os.system(command)` is easy to use, but slow (it runs a shell process +:func:`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 @@ -428,8 +428,8 @@ 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)` to send the string *data* -to the subprocess's standard input. :meth:`communicate(data)` then reads any +exited without pausing, or :meth:`communicate(data) ` to send the string *data* +to the subprocess's standard input. :meth:`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)``. @@ -746,10 +746,10 @@ 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)` and :c:func:`PyOS_ascii_atof(str, ptr)` +* :c:func:`PyOS_ascii_strtod(str, ptr) ` and :c:func:`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)` converts a +* :c:func:`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 @@ -775,7 +775,7 @@ * 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)` function (:pep:`322`). + Other new built-ins include the :func:`reversed(seq) ` function (:pep:`322`). * Generator expressions were added (:pep:`289`). @@ -854,7 +854,7 @@ (All changes to :meth:`sort` contributed by Raymond Hettinger.) -* There is a new built-in function :func:`sorted(iterable)` that works like the +* There is a new built-in function :func:`sorted(iterable) ` that works like the in-place :meth:`list.sort` method but can be used in expressions. The differences are: @@ -895,8 +895,8 @@ For example, you can now run the Python profiler with ``python -m profile``. (Contributed by Nick Coghlan.) -* The :func:`eval(expr, globals, locals)` and :func:`execfile(filename, globals, - locals)` functions and the ``exec`` statement now accept any mapping type +* The :func:`eval(expr, globals, locals) ` and :func:`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.) @@ -1087,7 +1087,7 @@ Yves Dionne) and new :meth:`deleteacl` and :meth:`myrights` methods (contributed by Arnaud Mazin). -* The :mod:`itertools` module gained a :func:`groupby(iterable[, *func*])` +* The :mod:`itertools` module gained a :func:`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 @@ -1136,7 +1136,7 @@ (Contributed by Hye-Shik Chang.) -* :mod:`itertools` also gained a function named :func:`tee(iterator, N)` that +* :mod:`itertools` also gained a function named :func:`tee(iterator, N) ` that returns *N* independent iterators that replicate *iterator*. If *N* is omitted, the default is 2. :: @@ -1174,7 +1174,7 @@ level=0, # Log all messages format='%(levelname):%(process):%(thread):%(message)') - Other additions to the :mod:`logging` package include a :meth:`log(level, msg)` + Other additions to the :mod:`logging` package include a :meth:`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 @@ -1193,7 +1193,7 @@ 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)` and :func:`itemgetter(index)`. Both functions return + :func:`attrgetter(attr) ` and :func:`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:: @@ -1220,14 +1220,14 @@ 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)` function was added to the :mod:`os` module, returning +* A new :func:`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)` returns true if the file +* Another new function: :func:`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)` function, which returns false if + from the existing :func:`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.) @@ -1240,7 +1240,7 @@ * 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)` that +* The :mod:`random` module has a new method called :meth:`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 @@ -1269,7 +1269,7 @@ 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)` looks up the + returns a pair of connected sockets and :func:`getservbyport(port) ` looks up the service name for a given port number. (Contributed by Dave Cole and Barry Warsaw.) @@ -1451,11 +1451,11 @@ * 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)`, constructs +* A new function, :c:func:`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)`, implements fast dictionary +* A new function, :c:func:`PyDict_Contains(d, k) `, implements fast dictionary lookups without masking exceptions raised during the look-up process. (Contributed by Raymond Hettinger.) diff -r aaa68dce117e Doc/whatsnew/2.5.rst --- a/Doc/whatsnew/2.5.rst Thu Aug 09 21:38:23 2012 +0200 +++ b/Doc/whatsnew/2.5.rst Sat Aug 11 00:00:33 2012 +0300 @@ -171,7 +171,7 @@ popup_menu.append( ("Open", open_func, 1) ) Another function in the :mod:`functools` module is the -:func:`update_wrapper(wrapper, wrapped)` function that helps you write well- +:func:`update_wrapper(wrapper, wrapped) ` function that helps you write well- behaved decorators. :func:`update_wrapper` copies the name, module, and docstring attribute to a wrapper function so that tracebacks inside the wrapped function are easier to understand. For example, you might write:: @@ -454,7 +454,7 @@ ``val = yield i`` but have to use parentheses when there's an operation, as in ``val = (yield i) + 12``.) -Values are sent into a generator by calling its :meth:`send(value)` method. The +Values are sent into a generator by calling its :meth:`send(value) ` method. The generator's code is then resumed and the :keyword:`yield` expression returns the specified *value*. If the regular :meth:`next` method is called, the :keyword:`yield` returns :const:`None`. @@ -496,7 +496,7 @@ In addition to :meth:`send`, there are two other new methods on generators: -* :meth:`throw(type, value=None, traceback=None)` is used to raise an exception +* :meth:`throw(type, value=None, traceback=None) ` is used to raise an exception inside the generator; the exception is raised by the :keyword:`yield` expression where the generator's execution is paused. @@ -660,7 +660,7 @@ * The code in *BLOCK* is executed. -* If *BLOCK* raises an exception, the :meth:`__exit__(type, value, traceback)` +* If *BLOCK* raises an exception, the :meth:`__exit__(type, value, traceback) <__exit__>` is called with the exception details, the same values returned by :func:`sys.exc_info`. The method's return value controls whether the exception is re-raised: any false value re-raises the exception, and ``True`` will result @@ -773,7 +773,7 @@ with db_transaction(db) as cursor: ... -The :mod:`contextlib` module also has a :func:`nested(mgr1, mgr2, ...)` function +The :mod:`contextlib` module also has a :func:`nested(mgr1, mgr2, ...) ` function that combines a number of context managers so you don't need to write nested ':keyword:`with`' statements. In this example, the single ':keyword:`with`' statement both starts a database transaction and acquires a thread lock:: @@ -782,7 +782,7 @@ with nested (db_transaction(db), lock) as (cursor, locked): ... -Finally, the :func:`closing(object)` function returns *object* so that it can be +Finally, the :func:`closing(object) ` function returns *object* so that it can be bound to a variable, and calls ``object.close`` at the end of the block. :: import urllib, sys @@ -955,7 +955,7 @@ A corresponding :attr:`nb_index` slot was added to the C-level :c:type:`PyNumberMethods` structure to let C extensions implement this protocol. -:c:func:`PyNumber_Index(obj)` can be used in extension code to call the +:c:func:`PyNumber_Index(obj) ` can be used in extension code to call the :meth:`__index__` function and retrieve its result. @@ -976,7 +976,7 @@ * The :class:`dict` type has a new hook for letting subclasses provide a default value when a key isn't contained in the dictionary. When a key isn't found, the - dictionary's :meth:`__missing__(key)` method will be called. This hook is used + dictionary's :meth:`__missing__(key) ` method will be called. This hook is used to implement the new :class:`defaultdict` class in the :mod:`collections` module. The following example defines a dictionary that returns zero for any missing key:: @@ -989,16 +989,16 @@ print d[1], d[2] # Prints 1, 2 print d[3], d[4] # Prints 0, 0 -* Both 8-bit and Unicode strings have new :meth:`partition(sep)` and - :meth:`rpartition(sep)` methods that simplify a common use case. - - The :meth:`find(S)` method is often used to get an index which is then used to +* Both 8-bit and Unicode strings have new :meth:`partition(sep) ` and + :meth:`rpartition(sep) ` methods that simplify a common use case. + + The :meth:`find(S) ` method is often used to get an index which is then used to slice the string and obtain the pieces that are before and after the separator. - :meth:`partition(sep)` condenses this pattern into a single method call that + :meth:`partition(sep) ` condenses this pattern into a single method call that returns a 3-tuple containing the substring before the separator, the separator itself, and the substring after the separator. If the separator isn't found, the first element of the tuple is the entire string and the other two elements - are empty. :meth:`rpartition(sep)` also returns a 3-tuple but starts searching + are empty. :meth:`rpartition(sep) ` also returns a 3-tuple but starts searching from the end of the string; the ``r`` stands for 'reverse'. Some examples:: @@ -1157,7 +1157,7 @@ .. Patch 1313939, 1359618 -* The :func:`long(str, base)` function is now faster on long digit strings +* The :func:`long(str, base) ` function is now faster on long digit strings because fewer intermediate results are calculated. The peak is for strings of around 800--1000 digits where the function is 6 times faster. (Contributed by Alan McIntyre and committed at the NeedForSpeed sprint.) @@ -1268,7 +1268,7 @@ (Contributed by Guido van Rossum.) * The :class:`deque` double-ended queue type supplied by the :mod:`collections` - module now has a :meth:`remove(value)` method that removes the first occurrence + module now has a :meth:`remove(value) ` method that removes the first occurrence of *value* in the queue, raising :exc:`ValueError` if the value isn't found. (Contributed by Raymond Hettinger.) @@ -1291,7 +1291,7 @@ * The :mod:`csv` module, which parses files in comma-separated value format, received several enhancements and a number of bugfixes. You can now set the maximum size in bytes of a field by calling the - :meth:`csv.field_size_limit(new_limit)` function; omitting the *new_limit* + :meth:`csv.field_size_limit(new_limit) ` function; omitting the *new_limit* argument will return the currently-set limit. The :class:`reader` class now has a :attr:`line_num` attribute that counts the number of physical lines read from the source; records can span multiple physical lines, so :attr:`line_num` is not @@ -1308,7 +1308,7 @@ (Contributed by Skip Montanaro and Andrew McNamara.) * The :class:`datetime` class in the :mod:`datetime` module now has a - :meth:`strptime(string, format)` method for parsing date strings, contributed + :meth:`strptime(string, format) ` method for parsing date strings, contributed by Josh Spoerri. It uses the same format characters as :func:`time.strptime` and :func:`time.strftime`:: @@ -1399,7 +1399,7 @@ * The :mod:`mailbox` module underwent a massive rewrite to add the capability to modify mailboxes in addition to reading them. A new set of classes that include :class:`mbox`, :class:`MH`, and :class:`Maildir` are used to read mailboxes, and - have an :meth:`add(message)` method to add messages, :meth:`remove(key)` to + have an :meth:`add(message) ` method to add messages, :meth:`remove(key) ` to remove messages, and :meth:`lock`/:meth:`unlock` to lock/unlock the mailbox. The following example converts a maildir-format mailbox into an mbox-format one:: @@ -1454,7 +1454,7 @@ :func:`wait4` return additional information. :func:`wait3` doesn't take a process ID as input, so it waits for any child process to exit and returns a 3-tuple of *process-id*, *exit-status*, *resource-usage* as returned from the - :func:`resource.getrusage` function. :func:`wait4(pid)` does take a process ID. + :func:`resource.getrusage` function. :func:`wait4(pid) ` does take a process ID. (Contributed by Chad J. Schroeder.) On FreeBSD, the :func:`os.stat` function now returns times with nanosecond @@ -1528,8 +1528,8 @@ In Python code, netlink addresses are represented as a tuple of 2 integers, ``(pid, group_mask)``. - Two new methods on socket objects, :meth:`recv_into(buffer)` and - :meth:`recvfrom_into(buffer)`, store the received data in an object that + Two new methods on socket objects, :meth:`recv_into(buffer) ` and + :meth:`recvfrom_into(buffer) `, store the received data in an object that supports the buffer protocol instead of returning the data as a string. This means you can put the data directly into an array or a memory-mapped file. @@ -1553,8 +1553,8 @@ year, number, name = s.unpack(data) You can also pack and unpack data to and from buffer objects directly using the - :meth:`pack_into(buffer, offset, v1, v2, ...)` and :meth:`unpack_from(buffer, - offset)` methods. This lets you store data directly into an array or a memory- + :meth:`pack_into(buffer, offset, v1, v2, ...) ` and :meth:`unpack_from(buffer, + offset) ` methods. This lets you store data directly into an array or a memory- mapped file. (:class:`Struct` objects were implemented by Bob Ippolito at the NeedForSpeed @@ -1588,7 +1588,7 @@ .. patch 918101 * The :mod:`threading` module now lets you set the stack size used when new - threads are created. The :func:`stack_size([*size*])` function returns the + threads are created. The :func:`stack_size([*size*]) ` function returns the currently configured stack size, and supplying the optional *size* parameter sets a new value. Not all platforms support changing the stack size, but Windows, POSIX threading, and OS/2 all do. (Contributed by Andrew MacIntyre.) @@ -1907,7 +1907,7 @@ h = hashlib.new('md5') # Provide algorithm as a string Once a hash object has been created, its methods are the same as before: -:meth:`update(string)` hashes the specified string into the current digest +:meth:`update(string) ` hashes the specified string into the current digest state, :meth:`digest` and :meth:`hexdigest` return the digest value as a binary string or a string of hex digits, and :meth:`copy` returns a new hashing object with the same digest state. @@ -2164,20 +2164,20 @@ * Two new macros can be used to indicate C functions that are local to the current file so that a faster calling convention can be used. - :c:func:`Py_LOCAL(type)` declares the function as returning a value of the + :c:func:`Py_LOCAL(type) ` declares the function as returning a value of the specified *type* and uses a fast-calling qualifier. - :c:func:`Py_LOCAL_INLINE(type)` does the same thing and also requests the + :c:func:`Py_LOCAL_INLINE(type) ` does the same thing and also requests the function be inlined. If :c:func:`PY_LOCAL_AGGRESSIVE` is defined before :file:`python.h` is included, a set of more aggressive optimizations are enabled for the module; you should benchmark the results to find out if these optimizations actually make the code faster. (Contributed by Fredrik Lundh at the NeedForSpeed sprint.) -* :c:func:`PyErr_NewException(name, base, dict)` can now accept a tuple of base +* :c:func:`PyErr_NewException(name, base, dict) ` can now accept a tuple of base classes as its *base* argument. (Contributed by Georg Brandl.) * The :c:func:`PyErr_Warn` function for issuing warnings is now deprecated in - favour of :c:func:`PyErr_WarnEx(category, message, stacklevel)` which lets you + favour of :c:func:`PyErr_WarnEx(category, message, stacklevel) ` which lets you specify the number of stack frames separating this function and the caller. A *stacklevel* of 1 is the function calling :c:func:`PyErr_WarnEx`, 2 is the function above that, and so forth. (Added by Neal Norwitz.) diff -r aaa68dce117e Doc/whatsnew/3.0.rst --- a/Doc/whatsnew/3.0.rst Thu Aug 09 21:38:23 2012 +0200 +++ b/Doc/whatsnew/3.0.rst Sat Aug 11 00:00:33 2012 +0300 @@ -812,7 +812,7 @@ * The :func:`round` function rounding strategy and return type have changed. Exact halfway cases are now rounded to the nearest even result instead of away from zero. (For example, ``round(2.5)`` now - returns ``2`` rather than ``3``.) :func:`round(x[, n])` now + returns ``2`` rather than ``3``.) :func:`round(x[, n]) ` now delegates to ``x.__round__([n])`` instead of always returning a float. It generally returns an integer when called with a single argument and a value of the same type as ``x`` when called with two