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.
........

Doc/howto/unicode.rst

@@ -211,11 +211,12 @@ 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>.
 
-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
-things clear to you, you should try reading one of these alternate articles
-before continuing.
+Another good introductory article was written by Joel Spolsky
+<http://www.joelonsoftware.com/articles/Unicode.html>.
+If this introduction didn't make things clear to you, you should try reading this
+alternate article before continuing.
+
+.. Jason Orendorff XXX http://www.jorendorff.com/articles/unicode/ is broken
 
 Wikipedia entries are often helpful; see the entries for "character encoding"
 <http://en.wikipedia.org/wiki/Character_encoding> and UTF-8

Doc/library/optparse.rst

@@ -467,7 +467,7 @@ user-friendly (documented) options::
                      action="store_false", dest="verbose",
                      help="be vewwy quiet (I'm hunting wabbits)")
    parser.add_option("-f", "--filename",
-                     metavar="FILE", help="write output to FILE"),
+                     metavar="FILE", help="write output to FILE")
    parser.add_option("-m", "--mode",
                      default="intermediate",
                      help="interaction mode: novice, intermediate, "
@@ -1014,12 +1014,15 @@ must specify for any option using that action.
 
      from optparse import OptionParser, SUPPRESS_HELP
 
-     parser = OptionParser()
-     parser.add_option("-h", "--help", action="help"),
+     # usually, a help option is added automatically, but that can
+     # be suppressed using the add_help_option argument
+     parser = OptionParser(add_help_option=False)
+
+     parser.add_option("-h", "--help", action="help")
      parser.add_option("-v", action="store_true", dest="verbose",
                        help="Be moderately verbose")
      parser.add_option("--file", dest="filename",
-                       help="Input file to read data from"),
+                       help="Input file to read data from")
      parser.add_option("--secret", help=SUPPRESS_HELP)
 
   If :mod:`optparse` sees either ``"-h"`` or ``"--help"`` on the command line, it

Doc/library/readline.rst

@@ -205,7 +205,7 @@ support history save/restore. ::
    class HistoryConsole(code.InteractiveConsole):
        def __init__(self, locals=None, filename="<console>",
                     histfile=os.path.expanduser("~/.console-history")):
-           code.InteractiveConsole.__init__(self)
+           code.InteractiveConsole.__init__(self, locals, filename)
            self.init_history(histfile)
 
        def init_history(self, histfile):

Doc/reference/simple_stmts.rst

@@ -170,6 +170,25 @@ Assignment of an object to a single target is recursively defined as follows.
   perform the assignment, it raises an exception (usually but not necessarily
   :exc:`AttributeError`).
 
+  .. _attr-target-note:
+
+  Note: If the object is a class instance and the attribute reference occurs on
+  both sides of the assignment operator, the RHS expression, ``a.x`` can access
+  either an instance attribute or (if no instance attribute exists) a class
+  attribute.  The LHS target ``a.x`` is always set as an instance attribute,
+  creating it if necessary.  Thus, the two occurrences of ``a.x`` do not
+  necessarily refer to the same attribute: if the RHS expression refers to a
+  class attribute, the LHS creates a new instance attribute as the target of the
+  assignment::
+
+     class Cls:
+         x = 3             # class variable
+     inst = Cls()
+     inst.x = inst.x + 1   # writes inst.x as 4 leaving Cls.x as 3
+
+  This description does not necessarily apply to descriptor attributes, such as
+  properties created with :func:`property`.
+
   .. index::
      pair: subscription; assignment
      object: mutable
@@ -276,16 +295,8 @@ same way as normal assignments. Similarly, with the exception of the possible
 *in-place* behavior, the binary operation performed by augmented assignment is
 the same as the normal binary operations.
 
-For targets which are attribute references, the initial value is retrieved with
-a :meth:`getattr` and the result is assigned with a :meth:`setattr`.  Notice
-that the two methods do not necessarily refer to the same variable.  When
-:meth:`getattr` refers to a class variable, :meth:`setattr` still writes to an
-instance variable. For example::
-
-   class A:
-       x = 3    # class variable
-   a = A()
-   a.x += 1     # writes a.x as 4 leaving A.x as 3
+For targets which are attribute references, the same :ref:`caveat about class
+and instance attributes <attr-target-note>` applies as for regular assignments.
 
 
 .. _assert:

Doc/tools/sphinxext/pyspecific.py

@@ -20,6 +20,20 @@ Body.enum.converters['loweralpha'] = \
     Body.enum.converters['lowerroman'] = \
     Body.enum.converters['upperroman'] = lambda x: None
 
+# monkey-patch HTML translator to give versionmodified paragraphs a class
+def new_visit_versionmodified(self, node):
+    self.body.append(self.starttag(node, 'p', CLASS=node['type']))
+    text = versionlabels[node['type']] % node['version']
+    if len(node):
+        text += ': '
+    else:
+        text += '.'
+    self.body.append('<span class="versionmodified">%s</span>' % text)
+
+from sphinx.writers.html import HTMLTranslator
+from sphinx.locale import versionlabels
+HTMLTranslator.visit_versionmodified = new_visit_versionmodified
+
 
 def issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
     issue = utils.unescape(text)

Doc/tools/sphinxext/static/basic.css

@@ -5,15 +5,6 @@
 
 /* -- main layout ----------------------------------------------------------- */
 
-div.documentwrapper {
-    float: left;
-    width: 100%;
-}
-
-div.bodywrapper {
-    margin: 0 0 0 230px;
-}
-
 div.clearer {
     clear: both;
 }
@@ -338,6 +329,12 @@ dl.glossary dt {
     font-style: italic;
 }
 
+p.deprecated {
+    background-color: #ffe4e4;
+    border: 1px solid #f66;
+    padding: 7px
+}
+
 .system-message {
     background-color: #fda;
     padding: 5px;
@@ -394,7 +391,7 @@ img.math {
     vertical-align: middle;
 }
 
-div.math p {
+div.body div.math p {
     text-align: center;
 }
 

Doc/tutorial/errors.rst

@@ -242,9 +242,10 @@ re-raise the exception::
 User-defined Exceptions
 =======================
 
-Programs may name their own exceptions by creating a new exception class.
-Exceptions should typically be derived from the :exc:`Exception` class, either
-directly or indirectly.  For example::
+Programs may name their own exceptions by creating a new exception class (see
+:ref:`tut-classes` for more about Python classes).  Exceptions should typically
+be derived from the :exc:`Exception` class, either directly or indirectly.  For
+example::
 
    >>> class MyError(Exception):
    ...     def __init__(self, value):