diff options
Diffstat (limited to 'Doc')
47 files changed, 449 insertions, 162 deletions
diff --git a/Doc/bugs.rst b/Doc/bugs.rst index 8b8df81..9abe50c 100644 --- a/Doc/bugs.rst +++ b/Doc/bugs.rst @@ -53,7 +53,7 @@ taken on the bug. Article which goes into some detail about how to create a useful bug report. This describes what kind of information is useful and why it is useful. - `Bug Writing Guidelines <http://www.mozilla.org/quality/bug-writing-guidelines.html>`_ + `Bug Writing Guidelines <http://developer.mozilla.org/en/docs/Bug_writing_guidelines>`_ Information about writing a good bug report. Some of this is specific to the Mozilla project, but describes general good practices. diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 2742a53..d165f16 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -137,7 +137,7 @@ reference counts for other objects contained in the object if this is a compound object type, such as a list, as well as performing any additional finalization that's needed. There's no chance that the reference count can overflow; at least as many bits are used to hold the reference count as there are distinct -memory locations in virtual memory (assuming ``sizeof(long) >= sizeof(char*)``). +memory locations in virtual memory (assuming ``sizeof(Py_ssize_t) >= sizeof(void*)``). Thus, the reference count increment is a simple operation. It is not necessary to increment an object's reference count for every local diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst index 6c2be3e..36684e2 100644 --- a/Doc/distutils/apiref.rst +++ b/Doc/distutils/apiref.rst @@ -73,7 +73,7 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and +--------------------+--------------------------------+-------------------------------------------------------------+ | *classifiers* | A list of categories for the | The list of available | | | package | categorizations is at | - | | | http://cheeseshop.python.org/pypi?:action=list_classifiers. | + | | | http://pypi.python.org/pypi?:action=list_classifiers. | +--------------------+--------------------------------+-------------------------------------------------------------+ | *distclass* | the :class:`Distribution` | A subclass of | | | class to use | :class:`distutils.core.Distribution` | diff --git a/Doc/distutils/examples.rst b/Doc/distutils/examples.rst index 4e4adc5..d937b83 100644 --- a/Doc/distutils/examples.rst +++ b/Doc/distutils/examples.rst @@ -11,7 +11,7 @@ Distutils Cookbook. .. seealso:: - `Distutils Cookbook <http://www.python.org/cgi-bin/moinmoin/DistutilsCookbook>`_ + `Distutils Cookbook <http://wiki.python.org/moin/DistutilsCookbook>`_ Collection of recipes showing how to achieve more control over distutils. diff --git a/Doc/distutils/setupscript.rst b/Doc/distutils/setupscript.rst index 7c65821..3cc1da9 100644 --- a/Doc/distutils/setupscript.rst +++ b/Doc/distutils/setupscript.rst @@ -578,7 +578,7 @@ Notes: (4) These fields should not be used if your package is to be compatible with Python versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website - <http://www.python.org/pypi>`_. + <http://pypi.python.org/pypi>`_. 'short string' A single line of text, not more than 200 characters. diff --git a/Doc/distutils/sourcedist.rst b/Doc/distutils/sourcedist.rst index 9f15870..960cc0a 100644 --- a/Doc/distutils/sourcedist.rst +++ b/Doc/distutils/sourcedist.rst @@ -122,7 +122,8 @@ distribution: * all files in the Distutils "build" tree (default :file:`build/`) -* all files in directories named :file:`RCS`, :file:`CVS` or :file:`.svn` +* all files in directories named :file:`RCS`, :file:`CVS`, :file:`.svn`, + :file:`.hg`, :file:`.git`, :file:`.bzr` or :file:`_darcs` Now we have our complete list of files, which is written to the manifest for future reference, and then used to build the source distribution archive(s). @@ -156,8 +157,9 @@ source distribution: previous two steps, so it's important that the ``prune`` command in the manifest template comes after the ``recursive-include`` command -#. exclude the entire :file:`build` tree, and any :file:`RCS`, :file:`CVS` and - :file:`.svn` directories +#. exclude the entire :file:`build` tree, and any :file:`RCS`, :file:`CVS`, + :file:`.svn`, :file:`.hg`, :file:`.git`, :file:`.bzr` and :file:`_darcs` + directories Just like in the setup script, file and directory names in the manifest template should always be slash-separated; the Distutils will take care of converting diff --git a/Doc/documenting/style.rst b/Doc/documenting/style.rst index 5d0ccb7..5821bd8 100644 --- a/Doc/documenting/style.rst +++ b/Doc/documenting/style.rst @@ -66,5 +66,5 @@ Unix 1970s. -.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2003.pdf +.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2006.pdf diff --git a/Doc/howto/advocacy.rst b/Doc/howto/advocacy.rst index 8b5b11c..d71e1ec 100644 --- a/Doc/howto/advocacy.rst +++ b/Doc/howto/advocacy.rst @@ -346,7 +346,7 @@ http://www.opensource.org wasn't written commercially. This site presents arguments that show how open source software can have considerable advantages over closed-source software. -http://sunsite.unc.edu/LDP/HOWTO/mini/Advocacy.html +http://www.faqs.org/docs/Linux-mini/Advocacy.html The Linux Advocacy mini-HOWTO was the inspiration for this document, and is also well worth reading for general suggestions on winning acceptance for a new technology, such as Linux or Python. In general, you won't make much progress diff --git a/Doc/howto/curses.rst b/Doc/howto/curses.rst index 841a030..b56b2c8 100644 --- a/Doc/howto/curses.rst +++ b/Doc/howto/curses.rst @@ -52,7 +52,7 @@ everything, though. No one has made a Windows port of the curses module. On a Windows platform, try the Console module written by Fredrik Lundh. The Console module provides cursor-addressable text output, plus full support for mouse and keyboard input, -and is available from http://effbot.org/efflib/console. +and is available from http://effbot.org/zone/console-index.htm. The Python curses module @@ -432,5 +432,5 @@ ncurses; feel free to add that. If you write an interesting little program, feel free to contribute it as another demo. We can always use more of them! -The ncurses FAQ: http://dickey.his.com/ncurses/ncurses.faq.html +The ncurses FAQ: http://invisible-island.net/ncurses/ncurses.faq.html diff --git a/Doc/howto/regex.rst b/Doc/howto/regex.rst index 40f5fdb..d83665f 100644 --- a/Doc/howto/regex.rst +++ b/Doc/howto/regex.rst @@ -367,8 +367,8 @@ module. If you have Tkinter available, you may also want to look at Python distribution. It allows you to enter REs and strings, and displays whether the RE matches or fails. :file:`redemo.py` can be quite useful when trying to debug a complicated RE. Phil Schwartz's `Kodos -<http://www.phil-schwartz.com/kodos.spy>`_ is also an interactive tool for -developing and testing RE patterns. +<http://kodos.sourceforge.net/>`_ is also an interactive tool for developing and +testing RE patterns. This HOWTO uses the standard Python interpreter for its examples. First, run the Python interpreter, import the :mod:`re` module, and compile a RE:: diff --git a/Doc/howto/unicode.rst b/Doc/howto/unicode.rst index 67aa2b2..454d25e 100644 --- a/Doc/howto/unicode.rst +++ b/Doc/howto/unicode.rst @@ -216,10 +216,6 @@ To help understand the standard, Jukka Korpela has written an introductory guide to reading the Unicode character tables, available at <http://www.cs.tut.fi/~jkorpela/unicode/guide.html>. -Roman Czyborra wrote another explanation of Unicode's basic principles; it's at -<http://czyborra.com/unicode/characters.html>. Czyborra has written a number of -other Unicode-related documentation, available from <http://www.cyzborra.com>. - Two other good introductory articles were written by Joel Spolsky <http://www.joelonsoftware.com/articles/Unicode.html> and Jason Orendorff <http://www.jorendorff.com/articles/unicode/>. If this introduction didn't make @@ -429,7 +425,7 @@ The documentation for the :mod:`codecs` module. Marc-André Lemburg gave a presentation at EuroPython 2002 titled "Python and Unicode". A PDF version of his slides is available at -<http://www.egenix.com/files/python/Unicode-EPC2002-Talk.pdf>, and is an +<http://downloads.egenix.com/python/Unicode-EPC2002-Talk.pdf>, and is an excellent overview of the design of Python's Unicode features. @@ -616,7 +612,7 @@ References The PDF slides for Marc-André Lemburg's presentation "Writing Unicode-aware Applications in Python" are available at -<http://www.egenix.com/files/python/LSM2005-Developing-Unicode-aware-applications-in-Python.pdf> +<http://downloads.egenix.com/python/LSM2005-Developing-Unicode-aware-applications-in-Python.pdf> and discuss questions of character encodings as well as how to internationalize and localize an application. diff --git a/Doc/howto/urllib2.rst b/Doc/howto/urllib2.rst index 05588b9..4ba3932 100644 --- a/Doc/howto/urllib2.rst +++ b/Doc/howto/urllib2.rst @@ -8,7 +8,7 @@ There is an French translation of an earlier revision of this HOWTO, available at `urllib2 - Le Manuel manquant - <http://www.voidspace/python/articles/urllib2_francais.shtml>`_. + <http://www.voidspace.org.uk/python/articles/urllib2_francais.shtml>`_. diff --git a/Doc/install/index.rst b/Doc/install/index.rst index c830c8d..d83e3f2 100644 --- a/Doc/install/index.rst +++ b/Doc/install/index.rst @@ -869,10 +869,10 @@ Using non-Microsoft compilers on Windows -Borland C++ -^^^^^^^^^^^ +Borland/CodeGear C++ +^^^^^^^^^^^^^^^^^^^^ -This subsection describes the necessary steps to use Distutils with the Borland +This subsection describes the necessary steps to use Distutils with the Borland C++ compiler version 5.5. First you have to know that Borland's object file format (OMF) is different from the format used by the Python version you can download from the Python or ActiveState Web site. (Python is built with @@ -912,7 +912,7 @@ section :ref:`inst-config-files`.) .. seealso:: - `C++Builder Compiler <http://www.borland.com/bcppbuilder/freecompiler/>`_ + `C++Builder Compiler <http://www.codegear.com/downloads/free/cppbuilder>`_ Information about the free C++ compiler from Borland, including links to the download pages. @@ -935,9 +935,7 @@ following steps. These compilers require some special libraries. This task is more complex than for Borland's C++, because there is no program to convert the library. First you have to create a list of symbols which the Python DLL exports. (You can find -a good program for this task at -http://starship.python.net/crew/kernr/mingw32/Notes.html, see at PExports 0.42h -there.) +a good program for this task at http://www.emmestech.com/software/cygwin/pexports-0.43/download_pexports.html) .. I don't understand what the next line means. --amk .. (inclusive the references on data structures.) @@ -981,9 +979,6 @@ Distutils (see section :ref:`inst-config-files`.) `Building Python modules on MS Windows platform with MinGW <http://www.zope.org/Members/als/tips/win32_mingw_modules>`_ Information about building the required libraries for the MinGW environment. - http://pyopengl.sourceforge.net/ftp/win32-stuff/ - Converted import libraries in Cygwin/MinGW and Borland format, and a script to - create the registry entries needed for Distutils to locate the built Python. .. rubric:: Footnotes diff --git a/Doc/library/aepack.rst b/Doc/library/aepack.rst index daaa9b2..d8aef6b 100644 --- a/Doc/library/aepack.rst +++ b/Doc/library/aepack.rst @@ -84,7 +84,3 @@ The :mod:`aepack` module defines the following functions: Module :mod:`aetypes` Python definitions of codes for Apple Event descriptor types. - - `Inside Macintosh: Interapplication Communication <http://developer.apple.com/techpubs/mac/IAC/IAC-2.html>`_ - Information about inter-process communications on the Macintosh. - diff --git a/Doc/library/cookielib.rst b/Doc/library/cookielib.rst index bc14051..f6008f1 100644 --- a/Doc/library/cookielib.rst +++ b/Doc/library/cookielib.rst @@ -117,7 +117,7 @@ The following classes are provided: Extensions to this module, including a class for reading Microsoft Internet Explorer cookies on Windows. - http://www.netscape.com/newsref/std/cookie_spec.html + http://wp.netscape.com/newsref/std/cookie_spec.html The specification of the original Netscape cookie protocol. Though this is still the dominant protocol, the 'Netscape cookie protocol' implemented by all the major browsers (and :mod:`cookielib`) only bears a passing resemblance to diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index 3fad2fb..8db1cb5 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -1486,9 +1486,31 @@ For :class:`time` objects, the format codes for year, month, and day should not be used, as time objects have no such values. If they're used anyway, ``1900`` is substituted for the year, and ``0`` for the month and day. -For :class:`date` objects, the format codes for hours, minutes, and seconds -should not be used, as :class:`date` objects have no such values. If they're -used anyway, ``0`` is substituted for them. +For :class:`date` objects, the format codes for hours, minutes, seconds, and +microseconds should not be used, as :class:`date` objects have no such +values. If they're used anyway, ``0`` is substituted for them. + +:class:`time` and :class:`datetime` objects support a ``%f`` format code +which expands to the number of microseconds in the object, zero-padded on +the left to six places. + +.. versionadded:: 2.6 + +For a naive object, the ``%z`` and ``%Z`` format codes are replaced by empty +strings. + +For an aware object: + +``%z`` + :meth:`utcoffset` is transformed into a 5-character string of the form +HHMM or + -HHMM, where HH is a 2-digit string giving the number of UTC offset hours, and + MM is a 2-digit string giving the number of UTC offset minutes. For example, if + :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``, ``%z`` is + replaced with the string ``'-0330'``. + +``%Z`` + If :meth:`tzname` returns ``None``, ``%Z`` is replaced by an empty string. + Otherwise ``%Z`` is replaced by the returned value, which must be a string. The full set of format codes supported varies across platforms, because Python calls the platform C library's :func:`strftime` function, and platform @@ -1521,6 +1543,10 @@ platforms. Regardless of platform, years before 1900 cannot be used. | ``%d`` | Day of the month as a decimal | | | | number [01,31]. | | +-----------+--------------------------------+-------+ +| ``%f`` | Microsecond as a decimal | \(1) | +| | number [0,999999], zero-padded | | +| | on the left | | ++-----------+--------------------------------+-------+ | ``%H`` | Hour (24-hour clock) as a | | | | decimal number [00,23]. | | +-----------+--------------------------------+-------+ @@ -1536,13 +1562,13 @@ platforms. Regardless of platform, years before 1900 cannot be used. | ``%M`` | Minute as a decimal number | | | | [00,59]. | | +-----------+--------------------------------+-------+ -| ``%p`` | Locale's equivalent of either | \(1) | +| ``%p`` | Locale's equivalent of either | \(2) | | | AM or PM. | | +-----------+--------------------------------+-------+ -| ``%S`` | Second as a decimal number | \(2) | +| ``%S`` | Second as a decimal number | \(3) | | | [00,61]. | | +-----------+--------------------------------+-------+ -| ``%U`` | Week number of the year | \(3) | +| ``%U`` | Week number of the year | \(4) | | | (Sunday as the first day of | | | | the week) as a decimal number | | | | [00,53]. All days in a new | | @@ -1553,7 +1579,7 @@ platforms. Regardless of platform, years before 1900 cannot be used. | ``%w`` | Weekday as a decimal number | | | | [0(Sunday),6]. | | +-----------+--------------------------------+-------+ -| ``%W`` | Week number of the year | \(3) | +| ``%W`` | Week number of the year | \(4) | | | (Monday as the first day of | | | | the week) as a decimal number | | | | [00,53]. All days in a new | | @@ -1573,7 +1599,7 @@ platforms. Regardless of platform, years before 1900 cannot be used. | ``%Y`` | Year with century as a decimal | | | | number. | | +-----------+--------------------------------+-------+ -| ``%z`` | UTC offset in the form +HHMM | \(4) | +| ``%z`` | UTC offset in the form +HHMM | \(5) | | | or -HHMM (empty string if the | | | | the object is naive). | | +-----------+--------------------------------+-------+ @@ -1586,17 +1612,22 @@ platforms. Regardless of platform, years before 1900 cannot be used. Notes: (1) + When used with the :func:`strptime` function, the ``%f`` directive + accepts from one to six digits and zero pads on the right. ``%f`` is + an extension to the set of format characters in the C standard. + +(2) When used with the :func:`strptime` function, the ``%p`` directive only affects the output hour field if the ``%I`` directive is used to parse the hour. -(2) +(3) The range really is ``0`` to ``61``; this accounts for leap seconds and the (very rare) double leap seconds. -(3) +(4) When used with the :func:`strptime` function, ``%U`` and ``%W`` are only used in calculations when the day of the week and the year are specified. -(4) +(5) For example, if :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``, ``%z`` is replaced with the string ``'-0330'``. diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 5b09847..3af9250 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -412,21 +412,24 @@ Miscellaneous opcodes. .. opcode:: WITH_CLEANUP () - Cleans up the stack when a :keyword:`with` statement block exits. TOS is the - context manager's :meth:`__exit__` bound method. Below that are 1--3 values - indicating how/why the finally clause was entered: + Cleans up the stack when a :keyword:`with` statement block exits. On top of + the stack are 1--3 values indicating how/why the finally clause was entered: - * SECOND = ``None`` - * (SECOND, THIRD) = (``WHY_{RETURN,CONTINUE}``), retval - * SECOND = ``WHY_*``; no retval below it - * (SECOND, THIRD, FOURTH) = exc_info() + * TOP = ``None`` + * (TOP, SECOND) = (``WHY_{RETURN,CONTINUE}``), retval + * TOP = ``WHY_*``; no retval below it + * (TOP, SECOND, THIRD) = exc_info() - In the last case, ``TOS(SECOND, THIRD, FOURTH)`` is called, otherwise - ``TOS(None, None, None)``. + Under them is EXIT, the context manager's :meth:`__exit__` bound method. - In addition, if the stack represents an exception, *and* the function call - returns a 'true' value, this information is "zapped", to prevent ``END_FINALLY`` - from re-raising the exception. (But non-local gotos should still be resumed.) + In the last case, ``EXIT(TOP, SECOND, THIRD)`` is called, otherwise + ``EXIT(None, None, None)``. + + EXIT is removed from the stack, leaving the values above it in the same + order. In addition, if the stack represents an exception, *and* the function + call returns a 'true' value, this information is "zapped", to prevent + ``END_FINALLY`` from re-raising the exception. (But non-local gotos should + still be resumed.) .. XXX explain the WHY stuff! diff --git a/Doc/library/email.message.rst b/Doc/library/email.message.rst index 7f3cf6f..2b0df34 100644 --- a/Doc/library/email.message.rst +++ b/Doc/library/email.message.rst @@ -38,7 +38,7 @@ Here are the methods of the :class:`Message` class: .. method:: Message.as_string([unixfrom]) - Return the entire message flatten as a string. When optional *unixfrom* is + Return the entire message flattened as a string. When optional *unixfrom* is ``True``, the envelope header is included in the returned string. *unixfrom* defaults to ``False``. diff --git a/Doc/library/heapq.rst b/Doc/library/heapq.rst index f26d29b..1530144 100644 --- a/Doc/library/heapq.rst +++ b/Doc/library/heapq.rst @@ -43,6 +43,13 @@ The following functions are provided: Pop and return the smallest item from the *heap*, maintaining the heap invariant. If the heap is empty, :exc:`IndexError` is raised. +.. function:: heappushpop(heap, item) + + Push *item* on the heap, then pop and return the smallest item from the + *heap*. The combined action runs more efficiently than :func:`heappush` + followed by a separate call to :func:`heappop`. + + .. versionadded:: 2.6 .. function:: heapify(x) diff --git a/Doc/library/imaplib.rst b/Doc/library/imaplib.rst index 10f3a42..01249b2 100644 --- a/Doc/library/imaplib.rst +++ b/Doc/library/imaplib.rst @@ -116,7 +116,7 @@ example of usage. Documents describing the protocol, and sources and binaries for servers implementing it, can all be found at the University of Washington's *IMAP - Information Center* (http://www.cac.washington.edu/imap/). + Information Center* (http://www.washington.edu/imap/). .. _imap4-objects: diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index e05f44a..b5773f4 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -403,7 +403,7 @@ remarks: Notes on Maildir by its inventor. Includes an updated name-creation scheme and details on "info" semantics. - `maildir man page from Courier <http://www.courier-mta.org/?maildir.html>`_ + `maildir man page from Courier <http://www.courier-mta.org/maildir.html>`_ Another specification of the format. Describes a common extension for supporting folders. @@ -460,7 +460,7 @@ remarks: `mbox man page from tin <http://www.tin.org/bin/man.cgi?section=5&topic=mbox>`_ Another specification of the format, with details on locking. - `Configuring Netscape Mail on Unix: Why The Content-Length Format is Bad <http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html>`_ + `Configuring Netscape Mail on Unix: Why The Content-Length Format is Bad <http://www.jwz.org/doc/content-length.html>`_ An argument for using the original mbox format rather than a variation. `"mbox" is a family of several mutually incompatible mailbox formats <http://homepages.tesco.net./~J.deBoynePollard/FGA/mail-mbox-formats.html>`_ @@ -664,7 +664,7 @@ remarks: `Format of Version 5 Babyl Files <http://quimby.gnus.org/notes/BABYL>`_ A specification of the Babyl format. - `Reading Mail with Rmail <http://www.gnu.org/software/emacs/manual/html_node/Rmail.html>`_ + `Reading Mail with Rmail <http://www.gnu.org/software/emacs/manual/html_node/emacs/Rmail.html>`_ The Rmail manual, with some information on Babyl semantics. @@ -1540,10 +1540,6 @@ counterparts are as follows: :class:`UnixMailbox` except that individual messages are separated by only ``From`` lines. - For more information, see `Configuring Netscape Mail on Unix: Why the - Content-Length Format is Bad - <http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html>`_. - .. class:: PortableUnixMailbox(fp[, factory]) @@ -1629,7 +1625,7 @@ format-specific information that can be converted:: destination = mailbox.MH('~/Mail') destination.lock() for message in mailbox.Babyl('~/RMAIL'): - destination.add(MHMessage(message)) + destination.add(mailbox.MHMessage(message)) destination.flush() destination.unlock() diff --git a/Doc/library/mimetools.rst b/Doc/library/mimetools.rst index 8da385e..7813867 100644 --- a/Doc/library/mimetools.rst +++ b/Doc/library/mimetools.rst @@ -73,7 +73,7 @@ It defines the following items: Module :mod:`multifile` Support for reading files which contain distinct parts, such as MIME data. - http://www.cs.uu.nl/wais/html/na-dir/mail/mime-faq/.html + http://faqs.cs.uu.nl/na-dir/mail/mime-faq/.html The MIME Frequently Asked Questions document. For an overview of MIME, see the answer to question 1.1 in Part 1 of this document. diff --git a/Doc/library/mimetypes.rst b/Doc/library/mimetypes.rst index f59cd82..cc11dfc 100644 --- a/Doc/library/mimetypes.rst +++ b/Doc/library/mimetypes.rst @@ -41,7 +41,7 @@ the information :func:`init` sets up. Optional *strict* is a flag specifying whether the list of known MIME types is limited to only the official types `registered with IANA - <http://www.isi.edu/in-notes/iana/assignments/media-types>`_ are recognized. + <http://www.iana.org/assignments/media-types/>`_ are recognized. When *strict* is true (the default), only the IANA types are supported; when *strict* is false, some additional non-standard but commonly used MIME types are also recognized. diff --git a/Doc/library/operator.rst b/Doc/library/operator.rst index ca056ab..590098b 100644 --- a/Doc/library/operator.rst +++ b/Doc/library/operator.rst @@ -428,21 +428,43 @@ expect a function argument. .. function:: itemgetter(item[, args...]) - Return a callable object that fetches *item* from its operand. If more than one - item is requested, returns a tuple of items. After, ``f=itemgetter(2)``, the - call ``f(b)`` returns ``b[2]``. After, ``f=itemgetter(2,5,3)``, the call - ``f(b)`` returns ``(b[2], b[5], b[3])``. - - -Examples:: - - >>> from operator import itemgetter - >>> inventory = [('apple', 3), ('banana', 2), ('pear', 5), ('orange', 1)] - >>> getcount = itemgetter(1) - >>> map(getcount, inventory) - [3, 2, 5, 1] - >>> sorted(inventory, key=getcount) - [('orange', 1), ('banana', 2), ('apple', 3), ('pear', 5)] + Return a callable object that fetches *item* from its operand using the + operand's :meth:`__getitem__` method. If multiple items are specified, + returns a tuple of lookup values. Equivalent to:: + + def itemgetter(*items): + if len(items) == 1: + item = items[0] + def g(obj): + return obj[item] + else: + def g(obj): + return tuple(obj[item] for item in items) + return g + + The items can be any type accepted by the operand's :meth:`__getitem__` + method. Dictionaries accept any hashable value. Lists, tuples, and + strings accept an index or a slice:: + + >>> itemgetter(1)('ABCDEFG') + 'B' + >>> itemgetter(1,3,5)('ABCDEFG') + ('B', 'D', 'F') + >>> itemgetter(slice(2,None))('ABCDEFG') + 'CDEFG' + + .. versionadded:: 2.4 + + Example of using :func:`itemgetter` to retrieve specific fields from a + tuple record:: + + >>> from operator import itemgetter + >>> inventory = [('apple', 3), ('banana', 2), ('pear', 5), ('orange', 1)] + >>> getcount = itemgetter(1) + >>> map(getcount, inventory) + [3, 2, 5, 1] + >>> sorted(inventory, key=getcount) + [('orange', 1), ('banana', 2), ('apple', 3), ('pear', 5)] .. function:: methodcaller(name[, args...]) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index ef81304..ec35c3b 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1387,7 +1387,8 @@ written in Python, such as a mail server's external command delivery program. .. function:: fork() Fork a child process. Return ``0`` in the child and the child's process id in the - parent. Availability: Macintosh, Unix. + parent. If an error occurs :exc:`OSError` is raised. + Availability: Macintosh, Unix. .. function:: forkpty() @@ -1396,7 +1397,8 @@ written in Python, such as a mail server's external command delivery program. terminal. Return a pair of ``(pid, fd)``, where *pid* is ``0`` in the child, the new child's process id in the parent, and *fd* is the file descriptor of the master end of the pseudo-terminal. For a more portable approach, use the - :mod:`pty` module. Availability: Macintosh, some flavors of Unix. + :mod:`pty` module. If an error occurs :exc:`OSError` is raised. + Availability: Macintosh, some flavors of Unix. .. function:: kill(pid, sig) diff --git a/Doc/library/othergui.rst b/Doc/library/othergui.rst index b36568d..ab4efdb 100644 --- a/Doc/library/othergui.rst +++ b/Doc/library/othergui.rst @@ -36,14 +36,12 @@ also available for Python: `PyGTK <http://www.pygtk.org/>`_ is a set of bindings for the `GTK <http://www.gtk.org/>`_ widget set. It - provides an object oriented interface that is slightly higher level than the C - one. It comes with many more widgets than Tkinter provides, and - has good Python-specific reference documentation. There are also `bindings - <http://www.daa.com.au/~james/gnome/>`_ to `GNOME <http://www.gnome.org>`_. - One well known PyGTK application is - `PythonCAD <http://www.pythoncad.org/>`_. An - online `tutorial <http://www.pygtk.org/pygtk2tutorial/index.html>`_ is - available. + provides an object oriented interface that is slightly higher level than + the C one. It comes with many more widgets than Tkinter provides, and has + good Python-specific reference documentation. There are also bindings to + `GNOME <http://www.gnome.org>`_. One well known PyGTK application is + `PythonCAD <http://www.pythoncad.org/>`_. An online `tutorial + <http://www.pygtk.org/pygtk2tutorial/index.html>`_ is available. `PyQt <http://www.riverbankcomputing.co.uk/pyqt/index.php>`_ PyQt is a :program:`sip`\ -wrapped binding to the Qt toolkit. Qt is an diff --git a/Doc/library/pdb.rst b/Doc/library/pdb.rst index 017fbd6..df8cf6c 100644 --- a/Doc/library/pdb.rst +++ b/Doc/library/pdb.rst @@ -103,9 +103,12 @@ slightly different way: being debugged (e.g. when an assertion fails). -.. function:: post_mortem(traceback) +.. function:: post_mortem([traceback]) - Enter post-mortem debugging of the given *traceback* object. + Enter post-mortem debugging of the given *traceback* object. If no + *traceback* is given, it uses the one of the exception that is currently + being handled (an exception must be being handled if the default is to be + used). .. function:: pm() diff --git a/Doc/library/py_compile.rst b/Doc/library/py_compile.rst index de9a80e..77ed8cf 100644 --- a/Doc/library/py_compile.rst +++ b/Doc/library/py_compile.rst @@ -42,7 +42,12 @@ byte-code cache files in the directory containing the source code. structure to locate source files; it only compiles files named explicitly. When this module is run as a script, the :func:`main` is used to compile all the -files named on the command line. +files named on the command line. The exit status is nonzero if one of the files +could not be compiled. + +.. versionchanged:: 2.6 + + Added the nonzero exit status. .. seealso:: diff --git a/Doc/library/re.rst b/Doc/library/re.rst index c3ec777..d7eb6f6 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -539,14 +539,26 @@ form. >>> re.split('\W+', 'Words, words, words.', 1) ['Words', 'words, words.'] + If there are capturing groups in the separator and it matches at the start of + the string, the result will start with an empty string. The same holds for + the end of the string:: + + >>> re.split('(\W+)', '...words, words...') + ['', '...', 'words', ', ', 'words', '...', ''] + + That way, separator components are always found at the same relative + indices within the result list (e.g., if there's one capturing group + in the separator, the 0th, the 2nd and so forth). + Note that *split* will never split a string on an empty pattern match. - For example :: + For example:: >>> re.split('x*', 'foo') ['foo'] >>> re.split("(?m)^$", "foo\n\nbar\n") ['foo\n\nbar\n'] + .. function:: findall(pattern, string[, flags]) Return all non-overlapping matches of *pattern* in *string*, as a list of diff --git a/Doc/library/robotparser.rst b/Doc/library/robotparser.rst index 2451799..6cc7df8 100644 --- a/Doc/library/robotparser.rst +++ b/Doc/library/robotparser.rst @@ -15,9 +15,8 @@ This module provides a single class, :class:`RobotFileParser`, which answers questions about whether or not a particular user agent can fetch a URL on the -Web site that published the :file:`robots.txt` file. For more details on the -structure of :file:`robots.txt` files, see -http://www.robotstxt.org/wc/norobots.html. +Web site that published the :file:`robots.txt` file. For more details on the +structure of :file:`robots.txt` files, see http://www.robotstxt.org/orig.html. .. class:: RobotFileParser() diff --git a/Doc/library/socketserver.rst b/Doc/library/socketserver.rst index 2c85c86..a8eb953 100644 --- a/Doc/library/socketserver.rst +++ b/Doc/library/socketserver.rst @@ -113,7 +113,8 @@ or inappropriate for the service) is to maintain an explicit table of partially finished requests and to use :func:`select` to decide which request to work on next (or whether to handle a new incoming request). This is particularly important for stream services where each client can potentially be connected for -a long time (if threads or subprocesses cannot be used). +a long time (if threads or subprocesses cannot be used). See :mod:`asyncore` for +another way to manage this. .. XXX should data and methods be intermingled, or separate? how should the distinction between class and instance variables be drawn? @@ -132,16 +133,24 @@ Server Objects .. function:: handle_request() - Process a single request. This function calls the following methods in order: - :meth:`get_request`, :meth:`verify_request`, and :meth:`process_request`. If - the user-provided :meth:`handle` method of the handler class raises an - exception, the server's :meth:`handle_error` method will be called. + Process a single request. This function calls the following methods in + order: :meth:`get_request`, :meth:`verify_request`, and + :meth:`process_request`. If the user-provided :meth:`handle` method of the + handler class raises an exception, the server's :meth:`handle_error` method + will be called. If no request is received within :attr:`self.timeout` + seconds, :meth:`handle_timeout` will be called and :meth:`handle_request` + will return. -.. function:: serve_forever() +.. function:: serve_forever(poll_interval=0.5) - Handle an infinite number of requests. This simply calls :meth:`handle_request` - inside an infinite loop. + Handle requests until an explicit :meth:`shutdown` request. Polls for + shutdown every *poll_interval* seconds. + + +.. function:: shutdown() + + Tells the :meth:`serve_forever` loop to stop and waits until it does. .. data:: address_family @@ -195,10 +204,9 @@ The server classes support the following class variables: .. data:: timeout - Timeout duration, measured in seconds, or :const:`None` if no timeout is desired. - If no incoming requests are received within the timeout period, - the :meth:`handle_timeout` method is called and then the server resumes waiting for - requests. + Timeout duration, measured in seconds, or :const:`None` if no timeout is + desired. If :meth:`handle_request` receives no incoming requests within the + timeout period, the :meth:`handle_timeout` method is called. There are various server methods that can be overridden by subclasses of base server classes like :class:`TCPServer`; these methods aren't useful to external diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst index ee568e6..924cb60 100644 --- a/Doc/library/struct.rst +++ b/Doc/library/struct.rst @@ -73,7 +73,7 @@ Python values should be obvious given their types: +--------+-------------------------+--------------------+-------+ | ``B`` | :ctype:`unsigned char` | integer | | +--------+-------------------------+--------------------+-------+ -| ``t`` | :ctype:`_Bool` | bool | \(1) | +| ``?`` | :ctype:`_Bool` | bool | \(1) | +--------+-------------------------+--------------------+-------+ | ``h`` | :ctype:`short` | integer | | +--------+-------------------------+--------------------+-------+ @@ -106,7 +106,7 @@ Python values should be obvious given their types: Notes: (1) - The ``'t'`` conversion code corresponds to the :ctype:`_Bool` type defined by + The ``'?'`` conversion code corresponds to the :ctype:`_Bool` type defined by C99. If this type is not available, it is simulated using a :ctype:`char`. In standard mode, it is always represented by one byte. @@ -141,7 +141,7 @@ bytes, but that the string returned can never contain more than 255 characters. -For the ``'t'`` format character, the return value is either :const:`True` or +For the ``'?'`` format character, the return value is either :const:`True` or :const:`False`. When packing, the truth value of the argument object is used. Either 0 or 1 in the native or standard bool representation will be packed, and any non-zero value will be True when unpacking. diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index 6f3e95b..3f62e69 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -724,3 +724,26 @@ Currently, :class:`Lock`, :class:`RLock`, :class:`Condition`, with some_rlock: print("some_rlock is locked while this executes") + +.. _threaded-imports: + +Importing in threaded code +-------------------------- + +While the import machinery is thread safe, there are two key +restrictions on threaded imports due to inherent limitations in the way +that thread safety is provided: + +* Firstly, other than in the main module, an import should not have the + side effect of spawning a new thread and then waiting for that thread in + any way. Failing to abide by this restriction can lead to a deadlock if + the spawned thread directly or indirectly attempts to import a module. +* Secondly, all import attempts must be completed before the interpreter + starts shutting itself down. This can be most easily achieved by only + performing imports from non-daemon threads created through the threading + module. Daemon threads and threads created directly with the thread + module will require some other form of synchronization to ensure they do + not attempt imports after system shutdown has commenced. Failure to + abide by this restriction will lead to intermittent exceptions and + crashes during interpreter shutdown (as the late imports attempt to + access machinery which is no longer in a valid state). diff --git a/Doc/library/tix.rst b/Doc/library/tix.rst index f4bb20f..ad14cc4 100644 --- a/Doc/library/tix.rst +++ b/Doc/library/tix.rst @@ -35,7 +35,7 @@ special needs of your application and users. `Tix Programming Guide <http://tix.sourceforge.net/dist/current/docs/tix-book/tix.book.html>`_ On-line version of the programmer's reference material. - `Tix Development Applications <http://tix.sourceforge.net/Tide/>`_ + `Tix Development Applications <http://tix.sourceforge.net/Tixapps/src/Tide.html>`_ Tix applications for development of Tix and Tkinter programs. Tide applications work under Tk or Tkinter, and include :program:`TixInspect`, an inspector to remotely modify and debug Tix/Tk/Tkinter applications. diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 4d5cce8..e03d959 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -21,7 +21,7 @@ of Python; it is maintained at ActiveState.) `An Introduction to Tkinter <http://www.pythonware.com/library/an-introduction-to-tkinter.htm>`_ Fredrik Lundh's on-line reference material. - `Tkinter reference: a GUI for Python <http://www.nmt.edu/tcc/help/pubs/lang.html>`_ + `Tkinter reference: a GUI for Python <http://infohost.nmt.edu/tcc/help/pubs/lang.html>`_ On-line reference material. `Tkinter for JPython <http://jtkinter.sourceforge.net>`_ diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index 7703ad9..8188e70 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -562,6 +562,7 @@ failures. .. method:: TestCase.assert_(expr[, msg]) TestCase.failUnless(expr[, msg]) + TestCase.assertTrue(expr[, msg]) Signal a test failure if *expr* is false; the explanation for the error will be *msg* if given, otherwise it will be :const:`None`. @@ -618,6 +619,7 @@ failures. .. method:: TestCase.failIf(expr[, msg]) + TestCase.assertFalse(expr[, msg]) The inverse of the :meth:`failUnless` method is the :meth:`failIf` method. This signals a test failure if *expr* is true, with *msg* or :const:`None` for the diff --git a/Doc/library/urllib.rst b/Doc/library/urllib.rst index 63fb53e..e976cb1 100644 --- a/Doc/library/urllib.rst +++ b/Doc/library/urllib.rst @@ -107,10 +107,6 @@ High-level interface filehandle = urllib.urlopen(some_url, proxies=None) filehandle = urllib.urlopen(some_url) - The :func:`urlopen` function does not support explicit proxy specification. If - you need to override environmental proxy settings, use :class:`URLopener`, or a - subclass such as :class:`FancyURLopener`. - Proxies which require authentication for use are not currently supported; this is considered an implementation limitation. diff --git a/Doc/library/xml.dom.rst b/Doc/library/xml.dom.rst index 768c9c8..2a0c788 100644 --- a/Doc/library/xml.dom.rst +++ b/Doc/library/xml.dom.rst @@ -506,7 +506,7 @@ Document Objects ^^^^^^^^^^^^^^^^ A :class:`Document` represents an entire XML document, including its constituent -elements, attributes, processing instructions, comments etc. Remeber that it +elements, attributes, processing instructions, comments etc. Remember that it inherits properties from :class:`Node`. diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst index c90f946..b1c9038 100644 --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -11,7 +11,7 @@ The ZIP file format is a common archive and compression standard. This module provides tools to create, read, write, append, and list a ZIP file. Any advanced use of this module will require an understanding of the format, as defined in `PKZIP Application Note -<http://www.pkware.com/business_and_developers/developer/appnote/>`_. +<http://www.pkware.com/documents/casestudies/APPNOTE.TXT>`_. This module does not currently handle multi-disk ZIP files, or ZIP files which have appended comments (although it correctly handles comments @@ -81,7 +81,7 @@ The module defines the following items: .. seealso:: - `PKZIP Application Note <http://www.pkware.com/business_and_developers/developer/appnote/>`_ + `PKZIP Application Note <http://www.pkware.com/documents/casestudies/APPNOTE.TXT>`_ Documentation on the ZIP file format by Phil Katz, the creator of the format and algorithms used. @@ -361,7 +361,7 @@ Instances have the following attributes: .. attribute:: ZipInfo.extra Expansion field data. The `PKZIP Application Note - <http://www.pkware.com/business_and_developers/developer/appnote/>`_ contains + <http://www.pkware.com/documents/casestudies/APPNOTE.TXT>`_ contains some comments on the internal structure of the data contained in this string. diff --git a/Doc/library/zipimport.rst b/Doc/library/zipimport.rst index ed9c631..f8d0b1d 100644 --- a/Doc/library/zipimport.rst +++ b/Doc/library/zipimport.rst @@ -29,7 +29,7 @@ doesn't contain :file:`.pyc` files, importing may be rather slow. .. seealso:: - `PKZIP Application Note <http://www.pkware.com/business_and_developers/developer/appnote/>`_ + `PKZIP Application Note <http://www.pkware.com/documents/casestudies/APPNOTE.TXT>`_ Documentation on the ZIP file format by Phil Katz, the creator of the format and algorithms used. diff --git a/Doc/license.rst b/Doc/license.rst index 6ffa65f..0226ec5 100644 --- a/Doc/license.rst +++ b/Doc/license.rst @@ -347,7 +347,7 @@ Sockets The :mod:`socket` module uses the functions, :func:`getaddrinfo`, and :func:`getnameinfo`, which are coded in separate source files from the WIDE -Project, http://www.wide.ad.jp/about/index.html. :: +Project, http://www.wide.ad.jp/. :: Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. All rights reserved. diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 74833df..5b590ce 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -52,6 +52,7 @@ Summarizing: : | `with_stmt` : | `funcdef` : | `classdef` + : | `decorated` suite: `stmt_list` NEWLINE | NEWLINE INDENT `statement`+ DEDENT statement: `stmt_list` NEWLINE | `compound_stmt` stmt_list: `simple_stmt` (";" `simple_stmt`)* [";"] @@ -424,6 +425,7 @@ A function definition defines a user-defined function object (see section funcdef: [`decorators`] "def" `funcname` "(" [`parameter_list`] ")" ["->" `expression`]? ":" `suite` decorators: `decorator`+ decorator: "@" `dotted_name` ["(" [`argument_list` [","]] ")"] NEWLINE + funcdef: "def" `funcname` "(" [`parameter_list`] ")" ":" `suite` dotted_name: `identifier` ("." `identifier`)* parameter_list: (`defparameter` ",")* : ( "*" [`parameter`] ("," `defparameter`)* @@ -585,6 +587,10 @@ implementation details. :pep:`3129` - Class Decorators +Class definitions, like function definitions, may be wrapped by one or +more :term:`decorator` expressions. The evaluation rules for the +decorator expressions are the same as for functions. The result must +be a class object, which is then bound to the class name. .. rubric:: Footnotes diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index 1dc49f3..e149710 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -539,9 +539,13 @@ The :keyword:`continue` statement :keyword:`continue` may only occur syntactically nested in a :keyword:`for` or :keyword:`while` loop, but not nested in a function or class definition or -:keyword:`finally` statement within that loop. [#]_ It continues with the next +:keyword:`finally` clause within that loop. It continues with the next cycle of the nearest enclosing loop. +When :keyword:`continue` passes control out of a :keyword:`try` statement with a +:keyword:`finally` clause, that :keyword:`finally` clause is executed before +really starting the next loop cycle. + .. _import: .. _from: @@ -832,4 +836,3 @@ pre-existing bindings in the local scope. .. [#] It may occur within an :keyword:`except` or :keyword:`else` clause. The restriction on occurring in the :keyword:`try` clause is implementor's laziness and will eventually be lifted. - diff --git a/Doc/tutorial/classes.rst b/Doc/tutorial/classes.rst index d9e2f46..b9db87b 100644 --- a/Doc/tutorial/classes.rst +++ b/Doc/tutorial/classes.rst @@ -124,6 +124,8 @@ found outside of the innermost scope are read-only (an attempt to write to such a variable will simply create a *new* local variable in the innermost scope, leaving the identically named outer variable unchanged). +.. XXX mention nonlocal + Usually, the local scope references the local names of the (textually) current function. Outside functions, the local scope references the same namespace as the global scope: the module's namespace. Class definitions place yet another @@ -137,12 +139,15 @@ language definition is evolving towards static name resolution, at "compile" time, so don't rely on dynamic name resolution! (In fact, local variables are already determined statically.) -A special quirk of Python is that assignments normally go into the innermost -scope. Assignments do not copy data --- they just bind names to objects. The -same is true for deletions: the statement ``del x`` removes the binding of ``x`` -from the namespace referenced by the local scope. In fact, all operations that -introduce new names use the local scope: in particular, import statements and -function definitions bind the module or function name in the local scope. +A special quirk of Python is that -- if no :keyword:`global` or +:keyword:`nonlocal` statement is in effect -- assignments to names always go +into the innermost scope. Assignments do not copy data --- they just bind names +to objects. The same is true for deletions: the statement ``del x`` removes the +binding of ``x`` from the namespace referenced by the local scope. In fact, all +operations that introduce new names use the local scope: in particular, import +statements and function definitions bind the module or function name in the +local scope. (The :keyword:`global` statement can be used to indicate that +particular variables live in the global scope.) The :keyword:`global` statement can be used to indicate that particular variables live in the global scope and should be rebound there; the @@ -466,6 +471,9 @@ classes defined in it. Usually, the class containing the method is itself defined in this global scope, and in the next section we'll find some good reasons why a method would want to reference its own class! +Each value is an object, and therefore has a *class* (also called its *type*). +It is stored as ``object.__class__``. + .. _tut-inheritance: @@ -515,6 +523,19 @@ arguments)``. This is occasionally useful to clients as well. (Note that this only works if the base class is defined or imported directly in the global scope.) +Python has two builtin functions that work with inheritance: + +* Use :func:`isinstance` to check an object's type: ``isinstance(obj, int)`` + will be ``True`` only if ``obj.__class__`` is :class:`int` or some class + derived from :class:`int`. + +* Use :func:`issubclass` to check class inheritance: ``issubclass(bool, int)`` + is ``True`` since :class:`bool` is a subclass of :class:`int`. However, + ``issubclass(unicode, str)`` is ``False`` since :class:`unicode` is not a + subclass of :class:`str` (they only share a common ancestor, + :class:`basestring`). + + .. _tut-multiple: diff --git a/Doc/tutorial/whatnow.rst b/Doc/tutorial/whatnow.rst index 25d42a8..b950cbc 100644 --- a/Doc/tutorial/whatnow.rst +++ b/Doc/tutorial/whatnow.rst @@ -38,9 +38,9 @@ More Python resources: * http://docs.python.org: Fast access to Python's documentation. -* http://cheeseshop.python.org: The Python Package Index, nicknamed the Cheese - Shop, is an index of user-created Python modules that are available for - download. Once you begin releasing code, you can register it here so that +* http://pypi.python.org: The Python Package Index, previously also nicknamed + the Cheese Shop, is an index of user-created Python modules that are available + for download. Once you begin releasing code, you can register it here so that others can find it. * http://aspn.activestate.com/ASPN/Python/Cookbook/: The Python Cookbook is a diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index 3dcfc7e..a94c3e7 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -311,7 +311,8 @@ These environment variables influence Python's behavior. Augment the default search path for module files. The format is the same as the shell's :envvar:`PATH`: one or more directory pathnames separated by - colons. Non-existent directories are silently ignored. + :data:`os.pathsep` (e.g. colons on Unix or semicolons on Windows). + Non-existent directories are silently ignored. The default search path is installation dependent, but generally begins with :file:`{prefix}/lib/python{version}`` (see :envvar:`PYTHONHOME` above). It diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst index bba46c9..20f17c7 100644 --- a/Doc/whatsnew/2.6.rst +++ b/Doc/whatsnew/2.6.rst @@ -117,8 +117,12 @@ LaTeX to reStructured Text. New Issue Tracker: Roundup -------------------------------------------------- -XXX write this. +XXX write this -- this section is currently just brief notes. +The developers were growing increasingly annoyed by SourceForge's +bug tracker. (Discuss problems in a sentence or two.) + +Hosting provided by XXX. New Documentation Format: ReStructured Text -------------------------------------------------- @@ -455,7 +459,46 @@ can now be used in scripts running from inside a package. PEP 3101: Advanced String Formatting ===================================================== -XXX write this +XXX write this -- this section is currently just brief notes. + +8-bit and Unicode strings have a .format() method that takes the arguments +to be formatted. + +.format() uses curly brackets ({, }) as special characters: + + format("User ID: {0}", "root") -> "User ID: root" + format("Empty dict: {{}}") -> "Empty dict: {}" + 0.name + 0[name] + +Format specifiers: + + 0:8 -> left-align, pad + 0:>8 -> right-align, pad + +Format data types:: + + ... take table from PEP 3101 + +Classes and types can define a __format__ method to control how it's +formatted. It receives a single argument, the format specifier:: + + def __format__(self, format_spec): + if isinstance(format_spec, unicode): + return unicode(str(self)) + else: + return str(self) + +There's also a format() built-in that will format a single value. It calls +the type's :meth:`__format__` method with the provided specifier:: + + >>> format(75.6564, '.2f') + '75.66' + +.. seealso:: + + :pep:`3101` - Advanced String Formatting + PEP written by Talin. .. ====================================================================== @@ -509,12 +552,30 @@ work. .. ====================================================================== +.. _pep-3112: + +PEP 3112: Byte Literals +===================================================== + +Python 3.0 adopts Unicode as the language's fundamental string type, and +denotes 8-bit literals differently, either as ``b'string'`` +or using a :class:`bytes` constructor. For future compatibility, +Python 2.6 adds :class:`bytes` as a synonym for the :class:`str` type, +and it also supports the ``b''`` notation. + +.. seealso:: + + :pep:`3112` - Bytes literals in Python 3000 + PEP written by Jason Orendorff; backported to 2.6 by Christian Heimes. + +.. ====================================================================== + .. _pep-3119: PEP 3119: Abstract Base Classes ===================================================== -XXX +XXX write this -- this section is currently just brief notes. How to identify a file object? @@ -558,16 +619,23 @@ an abstract method. PEP 3127: Integer Literal Support and Syntax ===================================================== -XXX write this +XXX write this -- this section is currently just brief notes. Python 3.0 changes the syntax for octal integer literals, and adds supports for binary integers: 0o instad of 0, and 0b for binary. Python 2.6 doesn't support this, but a bin() -builtin was added, and +builtin was added. + +XXX changes to the hex/oct builtins New bin() built-in returns the binary form of a number. +.. seealso:: + + :pep:`3127` - Integer Literal Support and Syntax + PEP written by Patrick Maupin. + .. ====================================================================== .. _pep-3129: @@ -575,7 +643,30 @@ New bin() built-in returns the binary form of a number. PEP 3129: Class Decorators ===================================================== -XXX write this. +XXX write this -- this section is currently just brief notes. + +Class decorators are analogous to function decorators. After defining a class, +it's passed through the specified series of decorator functions +and the ultimate return value is recorded as the class. + +:: + + class A: + pass + A = foo(bar(A)) + + + @foo + @bar + class A: + pass + +XXX need to find a good motivating example. + +.. seealso:: + + :pep:`3129` - Class Decorators + PEP written by Collin Winter. .. ====================================================================== @@ -631,11 +722,14 @@ one, :func:`math.trunc`, that's been backported to Python 2.6. .. seealso:: + :pep:`3141` - A Type Hierarchy for Numbers + PEP written by Jeffrey Yasskin. + XXX link: Discusses Scheme's numeric tower. -The Fraction Module +The :mod:`fractions` Module -------------------------------------------------- To fill out the hierarchy of numeric types, a rational-number class @@ -657,11 +751,27 @@ that will be the numerator and denominator of the resulting fraction. :: >>> a/b Fraction(5, 3) +To help in converting floating-point numbers to rationals, +the float type now has a :meth:`as_integer_ratio()` method that returns +the numerator and denominator for a fraction that evaluates to the same +floating-point value:: + + >>> (2.5) .as_integer_ratio() + (5, 2) + >>> (3.1415) .as_integer_ratio() + (7074029114692207L, 2251799813685248L) + >>> (1./3) .as_integer_ratio() + (6004799503160661L, 18014398509481984L) + +Note that values that can only be approximated by floating-point +numbers, such as 1./3, are not simplified to the number being +approximated; the fraction attempts to match the floating-point value +**exactly**. + The :mod:`fractions` module is based upon an implementation by Sjoerd Mullender that was in Python's :file:`Demo/classes/` directory for a long time. This implementation was significantly updated by Jeffrey -Yaskin. - +Yasskin. Other Language Changes ====================== @@ -740,7 +850,7 @@ Here are all of the changes that Python 2.6 makes to the core Python language. positive or negative infinity. This works on any platform with IEEE 754 semantics. (Contributed by Christian Heimes.) - .. Patch 1635. + .. Patch 1635 Other functions in the :mod:`math` module, :func:`isinf` and :func:`isnan`, return true if their floating-point argument is @@ -767,6 +877,12 @@ Here are all of the changes that Python 2.6 makes to the core Python language. .. Patch #1537 +* Generator objects now have a :attr:`gi_code` attribute that refers to + the original code object backing the generator. + (Contributed by Collin Winter.) + + .. Patch #1473257 + * The :func:`compile` built-in function now accepts keyword arguments as well as positional parameters. (Contributed by Thomas Wouters.) @@ -816,7 +932,7 @@ Optimizations (Original optimization implemented by Armin Rigo, updated for Python 2.6 by Kevin Jacobs.) - .. % Patch 1700288 + .. Patch 1700288 * All of the functions in the :mod:`struct` module have been rewritten in C, thanks to work at the Need For Speed sprint. @@ -1041,7 +1157,7 @@ complete list of changes, or look through the CVS logs for all the details. (2, 3, 1, 3), (2, 3, 1, 4), (2, 3, 2, 3), (2, 3, 2, 4), (2, 4, 1, 3), (2, 4, 1, 4), (2, 4, 2, 3), (2, 4, 2, 4)] - ``combinations(iter, r)`` returns combinations of length *r* from + ``combinations(iter, r)`` returns sub-sequences of length *r* from the elements of *iterable*. :: itertools.combinations('123', 2) -> @@ -1054,8 +1170,18 @@ complete list of changes, or look through the CVS logs for all the details. [('1', '2', '3'), ('1', '2', '4'), ('1', '3', '4'), ('2', '3', '4')] + ``permutations(iter[, r])`` returns all the permutations of length *r* of + the iterable's elements. If *r* is not specified, it will default to the + number of elements produced by the iterable. + + itertools.permutations([1,2,3,4], 2) -> + [(1, 2), (1, 3), (1, 4), + (2, 1), (2, 3), (2, 4), + (3, 1), (3, 2), (3, 4), + (4, 1), (4, 2), (4, 3)] + ``itertools.chain(*iterables)` is an existing function in - :mod:`itertools` that gained a new constructor. + :mod:`itertools` that gained a new constructor in Python 2.6. ``itertools.chain.from_iterable(iterable)`` takes a single iterable that should return other iterables. :func:`chain` will then return all the elements of the first iterable, then @@ -1066,6 +1192,13 @@ complete list of changes, or look through the CVS logs for all the details. (All contributed by Raymond Hettinger.) +* The :mod:`logging` module's :class:`FileHandler` class + and its subclasses :class:`WatchedFileHandler`, :class:`RotatingFileHandler`, + and :class:`TimedRotatingFileHandler` now + have an optional *delay* parameter to its constructor. If *delay* + is true, opening of the log file is deferred until the first + :meth:`emit` call is made. (Contributed by Vinay Sajip.) + * The :mod:`macfs` module has been removed. This in turn required the :func:`macostools.touched` function to be removed because it depended on the :mod:`macfs` module. @@ -1171,6 +1304,13 @@ complete list of changes, or look through the CVS logs for all the details. changed and :const:`UF_APPEND` to indicate that data can only be appended to the file. (Contributed by M. Levinson.) + ``os.closerange(*low*, *high*)`` efficiently closes all file descriptors + from *low* to *high*, ignoring any errors and not including *high* itself. + This function is now used by the :mod:`subprocess` module to make starting + processes faster. (Contributed by Georg Brandl.) + + .. Patch #1663329 + * The :mod:`pyexpat` module's :class:`Parser` objects now allow setting their :attr:`buffer_size` attribute to change the size of the buffer used to hold character data. @@ -1199,10 +1339,18 @@ complete list of changes, or look through the CVS logs for all the details. long searches can now be interrupted. (Contributed by Josh Hoyt and Ralf Schmitt.) - .. % Patch 846388 + .. Patch 846388 * The :mod:`rgbimg` module has been removed. +* The :mod:`sched` module's :class:`scheduler` instances now + have a read-only :attr:`queue` attribute that returns the + contents of the scheduler's queue, represented as a list of + named tuples with the fields ``(time, priority, action, argument)``. + (Contributed by Raymond Hettinger XXX check.) + + .. Patch 1861 + * The :mod:`sets` module has been deprecated; it's better to use the built-in :class:`set` and :class:`frozenset` types. @@ -1223,9 +1371,9 @@ complete list of changes, or look through the CVS logs for all the details. On receiving a signal, a byte will be written and the main event loop will be woken up, without the need to poll. - Contributed by Adam Olsen. + (Contributed by Adam Olsen.) - .. % Patch 1583 + .. Patch 1583 The :func:`siginterrupt` function is now available from Python code, and allows changing whether signals can interrupt system calls or not. @@ -1250,7 +1398,7 @@ complete list of changes, or look through the CVS logs for all the details. * In the :mod:`smtplib` module, SMTP.starttls() now complies with :rfc:`3207` and forgets any knowledge obtained from the server not obtained from - the TLS negotiation itself. Patch contributed by Bill Fenner. + the TLS negotiation itself. (Patch contributed by Bill Fenner.) .. Issue 829951 @@ -1267,6 +1415,10 @@ complete list of changes, or look through the CVS logs for all the details. by Michael Pomraning.) .. Patch #742598 + +* The :mod:`struct` module now supports the C99 :ctype:`_Bool` type, + using the format character ``'?'``. + (Contributed by David Remahl.) * A new variable in the :mod:`sys` module, :attr:`float_info`, is an object @@ -1297,6 +1449,12 @@ complete list of changes, or look through the CVS logs for all the details. These attributes are all read-only. (Contributed by Christian Heimes.) + It's now possible to determine the current profiler and tracer functions + by calling :func:`sys.getprofile` and :func:`sys.gettrace`. + (Contributed by Georg Brandl.) + + .. Patch #1648 + * The :mod:`tarfile` module now supports POSIX.1-2001 (pax) and POSIX.1-1988 (ustar) format tarfiles, in addition to the GNU tar format that was already supported. The default format @@ -1547,11 +1705,13 @@ Changes to Python's build process and to the C API include: .. Issue 1635 -* Some macros were renamed to make it clearer that they are macros, +* Some macros were renamed in both 3.0 and 2.6 to make it clearer that + they are macros, not functions. :cmacro:`Py_Size()` became :cmacro:`Py_SIZE()`, :cmacro:`Py_Type()` became :cmacro:`Py_TYPE()`, and - :cmacro:`Py_Refcnt()` became :cmacro:`Py_REFCNT()`. Macros for backward - compatibility are still available for Python 2.6. + :cmacro:`Py_Refcnt()` became :cmacro:`Py_REFCNT()`. + The mixed-case macros are still available + in Python 2.6 for backward compatibility. .. Issue 1629 |