Patch by Andy Holst.

- clarified the distinction between text encodings and other codecs
- clarified relationship with builtin open and the io module
- consolidated documentation of error handlers into one section
- clarified type constraints of some behaviours
- added tests for some of the new statements in the docs

Patch by Éric Araujo with help from Lars Gustäbel.

Patch by Katherine Busch.

Original patch by Berker Peksag.

The ExFileObject class was removed, some of its code went into _FileInFile.

- Remove duplicated list of links to the other modules from each
  module’s doc (people can already go up to library/archiving and
  there they can see the list).

- Link to shutil high-level operations.

Reviewed by Nadeem Vawda in #6715.

- Remove duplicate list of links to the other modules from each
  module’s doc (people can already go up to library/archiving and
  there they can see the list).

- Link to shutil high-level operations.

Reviewed by Nadeem Vawda in #6715.

Existing links have been updated to use the new reST role.  In some
files, I have also made cosmetic changes to the header.

keyword-only argument.  The preceding positional argument was deprecated,
so it made no sense to add filter as a positional argument.

(Patch reviewed by Brian Curtin and Anthony Long.)

extensions. Thus, in addition to GNUTYPE_SPARSE headers, sparse
information in pax headers created by GNU tar can now be decoded.
All three formats 0.0, 0.1 and 1.0 are supported.
On filesystems that support this, holes in files are now restored
whenever a sparse member is extracted.

svn+ssh://pythondev@svn.python.org/python/branches/py3k

........
  r84827 | antoine.pitrou | 2010-09-15 11:58:26 +0200 (mer., 15 sept. 2010) | 3 lines

  Add a glossary entry for file objects.
........
  r84828 | antoine.pitrou | 2010-09-15 12:08:31 +0200 (mer., 15 sept. 2010) | 3 lines

  Update file-related information in the FAQ.
........
  r84829 | antoine.pitrou | 2010-09-15 13:11:28 +0200 (mer., 15 sept. 2010) | 3 lines

  Add cross-references to the glossary entry for file objects.
........

Note: file system encoding cannot be None anymore (since r81190, issue #8610).

tarfile is now able to read and write pax headers with a
"hdrcharset=BINARY" record. This record was introduced in
POSIX.1-2008 as a method to store unencoded binary strings that
cannot be translated to UTF-8. In practice, this is just a workaround
that allows a tar implementation to store filenames that do not
comply with the current filesystem encoding and thus cannot be
decoded correctly.
Additionally, tarfile works around a bug in current versions of GNU
tar: undecodable filenames are stored as-is in a pax header without a
"hdrcharset" record being added. Technically, these headers are
invalid, but tarfile manages to read them correctly anyway.

(instead of replace in read mode or strict in write mode)

Merged revisions 79307,79408,79430,79533,79542,79579-79580,79585-79587,79607-79608,79622,79717,79820,79822,79828,79862,79875,79923-79924,79941-79943,79945,79947,79951-79952 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk

........
  r79307 | florent.xicluna | 2010-03-22 17:45:50 -0500 (Mon, 22 Mar 2010) | 2 lines

  #7667: Fix doctest failures with non-ASCII paths.
........
  r79408 | victor.stinner | 2010-03-24 20:18:38 -0500 (Wed, 24 Mar 2010) | 2 lines

  Fix a gcc warning introduced by r79397.
........
  r79430 | brian.curtin | 2010-03-25 18:48:54 -0500 (Thu, 25 Mar 2010) | 2 lines

  Fix #6538. Markup RegexObject and MatchObject as classes. Patch by Ryan Arana.
........
  r79533 | barry.warsaw | 2010-03-31 16:07:16 -0500 (Wed, 31 Mar 2010) | 6 lines

  - Issue #8233: When run as a script, py_compile.py optionally takes a single
    argument `-` which tells it to read files to compile from stdin.  Each line
    is read on demand and the named file is compiled immediately.  (Original
    patch by Piotr O?\197?\188arowski).
........
  r79542 | r.david.murray | 2010-03-31 20:28:39 -0500 (Wed, 31 Mar 2010) | 3 lines

  A couple small grammar fixes in test.rst, and rewrite the
  check_warnings docs to be clearer.
........
  r79579 | georg.brandl | 2010-04-02 03:34:41 -0500 (Fri, 02 Apr 2010) | 1 line

  Add 2.6.5.
........
  r79580 | georg.brandl | 2010-04-02 03:39:09 -0500 (Fri, 02 Apr 2010) | 1 line

  #2768: add a note on how to get a file descriptor.
........
  r79585 | georg.brandl | 2010-04-02 04:03:18 -0500 (Fri, 02 Apr 2010) | 1 line

  Remove col-spanning cells in logging docs.
........
  r79586 | georg.brandl | 2010-04-02 04:07:42 -0500 (Fri, 02 Apr 2010) | 1 line

  Document PyImport_ExecCodeModuleEx().
........
  r79587 | georg.brandl | 2010-04-02 04:11:49 -0500 (Fri, 02 Apr 2010) | 1 line

  #8012: clarification in generator glossary entry.
........
  r79607 | andrew.kuchling | 2010-04-02 12:48:23 -0500 (Fri, 02 Apr 2010) | 1 line

  #6647: document that catch_warnings is not thread-safe
........
  r79608 | andrew.kuchling | 2010-04-02 12:54:26 -0500 (Fri, 02 Apr 2010) | 1 line

  #6647: add note to two examples
........
  r79622 | tarek.ziade | 2010-04-02 16:34:19 -0500 (Fri, 02 Apr 2010) | 1 line

  removed documentation on code that was reverted and pushed into distutils2
........
  r79717 | antoine.pitrou | 2010-04-03 16:22:38 -0500 (Sat, 03 Apr 2010) | 4 lines

  Fix wording / typography, and a slightly misleading statement
  (memoryviews don't support complex structures right now)
........
  r79820 | benjamin.peterson | 2010-04-05 22:34:09 -0500 (Mon, 05 Apr 2010) | 1 line

  ready _sre types
........
  r79822 | georg.brandl | 2010-04-06 03:18:15 -0500 (Tue, 06 Apr 2010) | 1 line

  #8320: document return value of recv_into().
........
  r79828 | georg.brandl | 2010-04-06 09:33:44 -0500 (Tue, 06 Apr 2010) | 1 line

  Add JP.
........
  r79862 | georg.brandl | 2010-04-06 15:27:59 -0500 (Tue, 06 Apr 2010) | 1 line

  Fix syntax.
........
  r79875 | mark.dickinson | 2010-04-06 17:18:23 -0500 (Tue, 06 Apr 2010) | 1 line

  More NaN consistency doc fixes.
........
  r79923 | georg.brandl | 2010-04-10 06:15:24 -0500 (Sat, 10 Apr 2010) | 1 line

  #8360: skipTest was added in 2.7.
........
  r79924 | georg.brandl | 2010-04-10 06:16:59 -0500 (Sat, 10 Apr 2010) | 1 line

  #8346: update version.
........
  r79941 | andrew.kuchling | 2010-04-10 20:39:36 -0500 (Sat, 10 Apr 2010) | 1 line

  Two grammar fixes
........
  r79942 | andrew.kuchling | 2010-04-10 20:40:06 -0500 (Sat, 10 Apr 2010) | 1 line

  Punctuation fix
........
  r79943 | andrew.kuchling | 2010-04-10 20:40:30 -0500 (Sat, 10 Apr 2010) | 1 line

  Add various items
........
  r79945 | andrew.kuchling | 2010-04-10 20:40:49 -0500 (Sat, 10 Apr 2010) | 1 line

  name correct
........
  r79947 | andrew.kuchling | 2010-04-10 20:44:13 -0500 (Sat, 10 Apr 2010) | 1 line

  Remove distutils section
........
  r79951 | andrew.kuchling | 2010-04-11 07:48:08 -0500 (Sun, 11 Apr 2010) | 1 line

  Two typo fixes
........
  r79952 | andrew.kuchling | 2010-04-11 07:49:37 -0500 (Sun, 11 Apr 2010) | 1 line

  Add two items
........

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r78623 | lars.gustaebel | 2010-03-03 12:55:48 +0100 (Wed, 03 Mar 2010) | 3 lines

  Issue #7232: Add support for the context manager protocol
  to the TarFile class.
........

to the TarFile class.

Merged revisions 75149,75260-75263,75265-75267,75292,75300,75376,75405,75429-75433,75437,75445,75501,75551,75572,75589-75591,75657,75742,75868,75952-75957,76057,76105,76139,76143,76162,76223 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk

........
  r75149 | gregory.p.smith | 2009-09-29 16:56:31 -0500 (Tue, 29 Sep 2009) | 3 lines

  Mention issue6972 in extractall docs about overwriting things outside of
  the supplied path.
........
  r75260 | andrew.kuchling | 2009-10-05 16:24:20 -0500 (Mon, 05 Oct 2009) | 1 line

  Wording fix
........
  r75261 | andrew.kuchling | 2009-10-05 16:24:35 -0500 (Mon, 05 Oct 2009) | 1 line

  Fix narkup
........
  r75262 | andrew.kuchling | 2009-10-05 16:25:03 -0500 (Mon, 05 Oct 2009) | 1 line

  Document 'skip' parameter to constructor
........
  r75263 | andrew.kuchling | 2009-10-05 16:25:35 -0500 (Mon, 05 Oct 2009) | 1 line

  Note side benefit of socket.create_connection()
........
  r75265 | andrew.kuchling | 2009-10-05 17:31:11 -0500 (Mon, 05 Oct 2009) | 1 line

  Reword sentence
........
  r75266 | andrew.kuchling | 2009-10-05 17:32:48 -0500 (Mon, 05 Oct 2009) | 1 line

  Use standard comma punctuation; reword some sentences in the docs
........
  r75267 | andrew.kuchling | 2009-10-05 17:42:56 -0500 (Mon, 05 Oct 2009) | 1 line

  Backport r73983: Document the thousands separator.
........
  r75292 | benjamin.peterson | 2009-10-08 22:11:36 -0500 (Thu, 08 Oct 2009) | 1 line

  death to old CVS keyword
........
  r75300 | benjamin.peterson | 2009-10-09 16:48:14 -0500 (Fri, 09 Oct 2009) | 1 line

  fix some coding style
........
  r75376 | benjamin.peterson | 2009-10-11 20:26:07 -0500 (Sun, 11 Oct 2009) | 1 line

  platform we don't care about
........
  r75405 | neil.schemenauer | 2009-10-14 12:17:14 -0500 (Wed, 14 Oct 2009) | 4 lines

  Issue #1754094: Improve the stack depth calculation in the compiler.
  There should be no other effect than a small decrease in memory use.
  Patch by Christopher Tur Lesniewski-Laas.
........
  r75429 | benjamin.peterson | 2009-10-14 20:47:28 -0500 (Wed, 14 Oct 2009) | 1 line

  pep8ify if blocks
........
  r75430 | benjamin.peterson | 2009-10-14 20:49:37 -0500 (Wed, 14 Oct 2009) | 1 line

  use floor division and add a test that exercises the tabsize codepath
........
  r75431 | benjamin.peterson | 2009-10-14 20:56:25 -0500 (Wed, 14 Oct 2009) | 1 line

  change test to what I intended
........
  r75432 | benjamin.peterson | 2009-10-14 22:05:39 -0500 (Wed, 14 Oct 2009) | 1 line

  some cleanups
........
  r75433 | benjamin.peterson | 2009-10-14 22:06:55 -0500 (Wed, 14 Oct 2009) | 1 line

  make inspect.isabstract() always return a boolean; add a test for it, too #7069
........
  r75437 | benjamin.peterson | 2009-10-15 10:44:46 -0500 (Thu, 15 Oct 2009) | 1 line

  only clear a module's __dict__ if the module is the only one with a reference to it #7140
........
  r75445 | vinay.sajip | 2009-10-16 09:06:44 -0500 (Fri, 16 Oct 2009) | 1 line

  Issue #7120: logging: Removed import of multiprocessing which is causing crash in GAE.
........
  r75501 | antoine.pitrou | 2009-10-18 13:37:11 -0500 (Sun, 18 Oct 2009) | 3 lines

  Add a comment about unreachable code, and fix a typo
........
  r75551 | benjamin.peterson | 2009-10-19 22:14:10 -0500 (Mon, 19 Oct 2009) | 1 line

  use property api
........
  r75572 | benjamin.peterson | 2009-10-20 16:55:17 -0500 (Tue, 20 Oct 2009) | 1 line

  clarify buffer arg #7178
........
  r75589 | benjamin.peterson | 2009-10-21 21:26:47 -0500 (Wed, 21 Oct 2009) | 1 line

  whitespace
........
  r75590 | benjamin.peterson | 2009-10-21 21:36:47 -0500 (Wed, 21 Oct 2009) | 1 line

  rewrite to be nice to other implementations
........
  r75591 | benjamin.peterson | 2009-10-21 21:50:38 -0500 (Wed, 21 Oct 2009) | 4 lines

  rewrite for style, clarify, and comments

  Also, use the hasattr() like scheme of allowing BaseException exceptions through.
........
  r75657 | antoine.pitrou | 2009-10-24 07:41:27 -0500 (Sat, 24 Oct 2009) | 3 lines

  Fix compilation error in debug mode.
........
  r75742 | benjamin.peterson | 2009-10-26 17:51:16 -0500 (Mon, 26 Oct 2009) | 1 line

  use 'is' instead of id()
........
  r75868 | benjamin.peterson | 2009-10-27 15:59:18 -0500 (Tue, 27 Oct 2009) | 1 line

  test expect base classes
........
  r75952 | georg.brandl | 2009-10-29 15:38:32 -0500 (Thu, 29 Oct 2009) | 1 line

  Use the correct function name in docstring.
........
  r75953 | georg.brandl | 2009-10-29 15:39:50 -0500 (Thu, 29 Oct 2009) | 1 line

  Remove mention of the old -X command line switch.
........
  r75954 | georg.brandl | 2009-10-29 15:53:00 -0500 (Thu, 29 Oct 2009) | 1 line

  Use constants instead of magic integers for test result.  Do not re-run with --verbose3 for environment changing tests.
........
  r75955 | georg.brandl | 2009-10-29 15:54:03 -0500 (Thu, 29 Oct 2009) | 1 line

  Use a single style for all the docstrings in the math module.
........
  r75956 | georg.brandl | 2009-10-29 16:16:34 -0500 (Thu, 29 Oct 2009) | 1 line

  I do not think the "railroad" program mentioned is still available.
........
  r75957 | georg.brandl | 2009-10-29 16:44:56 -0500 (Thu, 29 Oct 2009) | 1 line

  Fix constant name.
........
  r76057 | benjamin.peterson | 2009-11-02 09:06:45 -0600 (Mon, 02 Nov 2009) | 1 line

  prevent a rather unlikely segfault
........
  r76105 | georg.brandl | 2009-11-04 01:38:12 -0600 (Wed, 04 Nov 2009) | 1 line

  #7259: show correct equivalent for operator.i* operations in docstring; fix minor issues in operator docs.
........
  r76139 | benjamin.peterson | 2009-11-06 19:04:38 -0600 (Fri, 06 Nov 2009) | 1 line

  spelling
........
  r76143 | georg.brandl | 2009-11-07 02:26:07 -0600 (Sat, 07 Nov 2009) | 1 line

  #7271: fix typo.
........
  r76162 | benjamin.peterson | 2009-11-08 22:10:53 -0600 (Sun, 08 Nov 2009) | 1 line

  discuss how to use -p
........
  r76223 | georg.brandl | 2009-11-12 02:29:46 -0600 (Thu, 12 Nov 2009) | 1 line

  Give the profile module a module directive.
........

svn+ssh://svn.python.org/python/branches/py3k

................
  r74821 | georg.brandl | 2009-09-16 11:42:19 +0200 (Mi, 16 Sep 2009) | 1 line

  #6885: run python 3 as python3.
................
  r74828 | georg.brandl | 2009-09-16 16:23:20 +0200 (Mi, 16 Sep 2009) | 1 line

  Use true booleans.
................
  r74829 | georg.brandl | 2009-09-16 16:24:29 +0200 (Mi, 16 Sep 2009) | 1 line

  Small PEP8 correction.
................
  r74830 | georg.brandl | 2009-09-16 16:36:22 +0200 (Mi, 16 Sep 2009) | 1 line

  Use true booleans.
................
  r74831 | georg.brandl | 2009-09-16 17:54:04 +0200 (Mi, 16 Sep 2009) | 1 line

  Use true booleans and PEP8 for argdefaults.
................
  r74833 | georg.brandl | 2009-09-16 17:58:14 +0200 (Mi, 16 Sep 2009) | 1 line

  Last round of adapting style of documenting argument default values.
................
  r74835 | georg.brandl | 2009-09-16 18:00:31 +0200 (Mi, 16 Sep 2009) | 33 lines

  Merged revisions 74817-74820,74822-74824 via svnmerge from
  svn+ssh://pythondev@svn.python.org/python/trunk

  ........
    r74817 | georg.brandl | 2009-09-16 11:05:11 +0200 (Mi, 16 Sep 2009) | 1 line

    Make deprecation notices as visible as warnings are right now.
  ........
    r74818 | georg.brandl | 2009-09-16 11:23:04 +0200 (Mi, 16 Sep 2009) | 1 line

    #6880: add reference to classes section in exceptions section, which comes earlier.
  ........
    r74819 | georg.brandl | 2009-09-16 11:24:57 +0200 (Mi, 16 Sep 2009) | 1 line

    #6876: fix base class constructor invocation in example.
  ........
    r74820 | georg.brandl | 2009-09-16 11:30:48 +0200 (Mi, 16 Sep 2009) | 1 line

    #6891: comment out dead link to Unicode article.
  ........
    r74822 | georg.brandl | 2009-09-16 12:12:06 +0200 (Mi, 16 Sep 2009) | 1 line

    #5621: refactor description of how class/instance attributes interact on a.x=a.x+1 or augassign.
  ........
    r74823 | georg.brandl | 2009-09-16 15:06:22 +0200 (Mi, 16 Sep 2009) | 1 line

    Remove strange trailing commas.
  ........
    r74824 | georg.brandl | 2009-09-16 15:11:06 +0200 (Mi, 16 Sep 2009) | 1 line

    #6892: fix optparse example involving help option.
  ........
................

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r74750 | lars.gustaebel | 2009-09-12 12:28:15 +0200 (Sat, 12 Sep 2009) | 9 lines

  Issue #6856: Add a filter keyword argument to TarFile.add().

  The filter argument must be a function that takes a TarInfo
  object argument, changes it and returns it again. If the
  function returns None the TarInfo object will be excluded
  from the archive.
  The exclude argument is deprecated from now on, because it
  does something similar but is not as flexible.
........