Merged revisions 66457-66459,66465-66468,66483-66485,66487-66491 via svnmerge from

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

........
  r66457 | antoine.pitrou | 2008-09-13 15:30:30 -0500 (Sat, 13 Sep 2008) | 5 lines

  Issue #3850: Misc/find_recursionlimit.py was broken.

  Reviewed by A.M. Kuchling.
........
  r66458 | benjamin.peterson | 2008-09-13 17:54:43 -0500 (Sat, 13 Sep 2008) | 1 line

  fix a name issue; note all doc files should be encoded in utf8
........
  r66459 | benjamin.peterson | 2008-09-14 11:02:22 -0500 (Sun, 14 Sep 2008) | 1 line

  clarify that radix for int is not 'guessed'
........
  r66465 | skip.montanaro | 2008-09-14 21:03:05 -0500 (Sun, 14 Sep 2008) | 3 lines

  Review usage.  Fix a mistake in the new-style class definition.  Add a
  couple new definitions (CPython and virtual machine).
........
  r66466 | skip.montanaro | 2008-09-14 21:19:53 -0500 (Sun, 14 Sep 2008) | 2 lines

  Pick up a few more definitions from the glossary on the wiki.
........
  r66467 | benjamin.peterson | 2008-09-14 21:53:23 -0500 (Sun, 14 Sep 2008) | 1 line

  mention that object.__init__ no longer takes arbitrary args and kwargs
........
  r66468 | andrew.kuchling | 2008-09-15 08:08:32 -0500 (Mon, 15 Sep 2008) | 1 line

  Rewrite item a bit
........
  r66483 | georg.brandl | 2008-09-16 05:17:45 -0500 (Tue, 16 Sep 2008) | 2 lines

  Fix typo.
........
  r66484 | benjamin.peterson | 2008-09-16 16:20:28 -0500 (Tue, 16 Sep 2008) | 2 lines

  be less wordy
........
  r66485 | georg.brandl | 2008-09-17 03:45:54 -0500 (Wed, 17 Sep 2008) | 2 lines

  #3888: add some deprecated modules in whatsnew.
........
  r66487 | skip.montanaro | 2008-09-17 06:50:36 -0500 (Wed, 17 Sep 2008) | 2 lines

  usage
........
  r66488 | andrew.kuchling | 2008-09-17 07:57:04 -0500 (Wed, 17 Sep 2008) | 1 line

  Markup fixes
........
  r66489 | andrew.kuchling | 2008-09-17 07:58:22 -0500 (Wed, 17 Sep 2008) | 2 lines

  Remove comment about improvement: pystone is about the same, and
  the improvements seem to be difficult to quantify
........
  r66490 | andrew.kuchling | 2008-09-17 08:04:53 -0500 (Wed, 17 Sep 2008) | 1 line

  Note sqlite3 version; move item
........
  r66491 | benjamin.peterson | 2008-09-17 16:54:56 -0500 (Wed, 17 Sep 2008) | 1 line

  document compileall command flags
........

1 files changed, 149 insertions, 85 deletions

diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 41bf081..424f679 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -9,16 +9,17 @@ Glossary
 .. glossary::
 
    ``>>>``
-      The typical Python prompt of the interactive shell.  Often seen for code
-      examples that can be tried right away in the interpreter.
+      The default Python prompt of the interactive shell.  Often seen for code
+      examples which can be executed interactively in the interpreter.
     
    ``...``
-      The typical Python prompt of the interactive shell when entering code for
-      an indented code block.
+      The default Python prompt of the interactive shell when entering code for
+      an indented code block or within a pair of matching left and right
+      delimiters (parentheses, square brackets or curly braces).
 
    2to3
       A tool that tries to convert Python 2.x code to Python 3.x code by
-      handling most of the incompatibilites that can be detected by parsing the
+      handling most of the incompatibilites which can be detected by parsing the
       source and traversing the parse tree.
 
       2to3 is available in the standard library as :mod:`lib2to3`; a standalone
@@ -34,15 +35,21 @@ Glossary
       ABC with the :mod:`abc` module.
 
    argument
-      A value passed to a function or method, assigned to a name local to
-      the body.  A function or method may have both positional arguments and
-      keyword arguments in its definition.  Positional and keyword arguments
-      may be variable-length: ``*`` accepts or passes (if in the function
-      definition or call) several positional arguments in a list, while ``**``
-      does the same for keyword arguments in a dictionary.
+      A value passed to a function or method, assigned to a named local
+      variable in the function body.  A function or method may have both
+      positional arguments and keyword arguments in its definition.
+      Positional and keyword arguments may be variable-length: ``*`` accepts
+      or passes (if in the function definition or call) several positional
+      arguments in a list, while ``**`` does the same for keyword arguments
+      in a dictionary.
 
       Any expression may be used within the argument list, and the evaluated
       value is passed to the local variable.
+
+   attribute
+      A value associated with an object which is referenced by name using
+      dotted expressions.  For example, if an object *o* has an attribute
+      *a* it would be referenced as *o.a*.
     
    BDFL
       Benevolent Dictator For Life, a.k.a. `Guido van Rossum
@@ -53,8 +60,26 @@ Glossary
       of a Python program in the interpreter.  The bytecode is also cached in
       ``.pyc`` and ``.pyo`` files so that executing the same file is faster the
       second time (recompilation from source to bytecode can be avoided).  This
-      "intermediate language" is said to run on a "virtual machine" that calls
-      the subroutines corresponding to each bytecode.
+      "intermediate language" is said to run on a :term:`virtual machine`
+      that executes the machine code corresponding to each bytecode.
+
+   class
+      A template for creating user-defined objects. Class definitions
+      normally contain method definitions which operate on instances of the
+      class.
+    
+   coercion
+      The implicit conversion of an instance of one type to another during an
+      operation which involves two arguments of the same type.  For example,
+      ``int(3.15)`` converts the floating point number to the integer ``3``, but
+      in ``3+4.5``, each argument is of a different type (one int, one float),
+      and both must be converted to the same type before they can be added or it
+      will raise a ``TypeError``.  Coercion between two operands can be
+      performed with the ``coerce`` builtin function; thus, ``3+4.5`` is
+      equivalent to calling ``operator.add(*coerce(3, 4.5))`` and results in
+      ``operator.add(3.0, 4.5)``.  Without coercion, all arguments of even
+      compatible types would have to be normalized to the same value by the
+      programmer, e.g., ``float(3)+4.5`` rather than just ``3+4.5``.
     
    complex number
       An extension of the familiar real number system in which all numbers are
@@ -69,10 +94,15 @@ Glossary
       it's almost certain you can safely ignore them.
     
    context manager
-      An objects that controls the environment seen in a :keyword:`with`
+      An object which controls the environment seen in a :keyword:`with`
       statement by defining :meth:`__enter__` and :meth:`__exit__` methods.
       See :pep:`343`.
 
+   CPython
+      The canonical implementation of the Python programming language.  The
+      term "CPython" is used in contexts when necessary to distinguish this
+      implementation from others such as Jython or IronPython.
+
    decorator
       A function returning another function, usually applied as a function
       transformation using the ``@wrapper`` syntax.  Common examples for
@@ -92,7 +122,7 @@ Glossary
       The same concept exists for classes, but is less commonly used there.
 
    descriptor
-      An object that defines the methods :meth:`__get__`, :meth:`__set__`, or
+      Any object which defines the methods :meth:`__get__`, :meth:`__set__`, or
       :meth:`__delete__`.  When a class attribute is a descriptor, its special
       binding behavior is triggered upon attribute lookup.  Normally, using
       *a.b* to get, set or delete an attribute looks up the object named *b* in
@@ -106,20 +136,20 @@ Glossary
     
    dictionary
       An associative array, where arbitrary keys are mapped to values.  The use
-      of :class:`dict` much resembles that for :class:`list`, but the keys can
-      be any object with a :meth:`__hash__` function, not just integers starting
-      from zero.  Called a hash in Perl.
+      of :class:`dict` closely resembles that for :class:`list`, but the keys can
+      be any object with a :meth:`__hash__` function, not just integers.
+      Called a hash in Perl.
 
    docstring
-      A docstring ("documentation string") is a string literal that appears as
-      the first thing in a class or function suite.  While ignored when the
-      suite is executed, it is recognized by the compiler and put into the
-      :attr:`__doc__` attribute of the class or function.  Since it is available
-      via introspection, it is the canonical place for documentation of the
+      A string literal which appears as the first expression in a class,
+      function or module.  While ignored when the suite is executed, it is
+      recognized by the compiler and put into the :attr:`__doc__` attribute
+      of the enclosing class, function or module.  Since it is available via
+      introspection, it is the canonical place for documentation of the
       object.
     
    duck-typing 
-      Pythonic programming style that determines an object's type by inspection
+      A pythonic programming style which determines an object's type by inspection
       of its method or attribute signature rather than by explicit relationship
       to some type object ("If it looks like a duck and quacks like a duck, it
       must be a duck.")  By emphasizing interfaces rather than specific types,
@@ -134,20 +164,20 @@ Glossary
       style assumes the existence of valid keys or attributes and catches
       exceptions if the assumption proves false.  This clean and fast style is
       characterized by the presence of many :keyword:`try` and :keyword:`except`
-      statements.  The technique contrasts with the :term:`LBYL` style that is
-      common in many other languages such as C.
+      statements.  The technique contrasts with the :term:`LBYL` style 
+      common to many other languages such as C.
 
    expression
       A piece of syntax which can be evaluated to some value.  In other words,
-      an expression is an accumulation of expression elements like literals, names,
-      attribute access, operators or function calls that all return a value.
-      In contrast to other languages, not all language constructs are expressions,
-      but there are also :term:`statement`\s that cannot be used as expressions,
-      such as :keyword:`while` or :keyword:`if`.  Assignments are also not
-      expressions.
+      an expression is an accumulation of expression elements like literals,
+      names, attribute access, operators or function calls which all return a
+      value.  In contrast to many other languages, not all language constructs
+      are expressions.  There are also :term:`statement`\s which cannot be used
+      as expressions, such as :keyword:`if`.  Assignments are also statements,
+      not expressions.
 
    extension module
-      A module written in C, using Python's C API to interact with the core and
+      A module written in C or C++, using Python's C API to interact with the core and
       with user code.
 
    function
@@ -178,10 +208,10 @@ Glossary
       collector that is able to detect and break reference cycles.
     
    generator
-      A function that returns an iterator.  It looks like a normal function
+      A function which returns an iterator.  It looks like a normal function
       except that values are returned to the caller using a :keyword:`yield`
       statement instead of a :keyword:`return` statement.  Generator functions
-      often contain one or more :keyword:`for` or :keyword:`while` loops that
+      often contain one or more :keyword:`for` or :keyword:`while` loops which
       :keyword:`yield` elements back to the caller.  The function execution is
       stopped at the :keyword:`yield` keyword (returning the result) and is
       resumed there when the next element is requested by calling the
@@ -202,39 +232,41 @@ Glossary
       See :term:`global interpreter lock`.
     
    global interpreter lock
-      The lock used by Python threads to assure that only one thread can be run
-      at a time.  This simplifies Python by assuring that no two processes can
-      access the same memory at the same time.  Locking the entire interpreter
-      makes it easier for the interpreter to be multi-threaded, at the expense
-      of some parallelism on multi-processor machines.  Efforts have been made
-      in the past to create a "free-threaded" interpreter (one which locks
-      shared data at a much finer granularity), but performance suffered in the
-      common single-processor case.
+      The lock used by Python threads to assure that only one thread
+      executes in the :term:`CPython` :term:`virtual machine` at a time.
+      This simplifies the CPython implementation by assuring that no two
+      processes can access the same memory at the same time.  Locking the
+      entire interpreter makes it easier for the interpreter to be
+      multi-threaded, at the expense of much of the parallelism afforded by
+      multi-processor machines.  Efforts have been made in the past to
+      create a "free-threaded" interpreter (one which locks shared data at a
+      much finer granularity), but so far none have been successful because
+      performance suffered in the common single-processor case.
 
    hashable
-      An object is *hashable* if it has a hash value that never changes during
+      An object is *hashable* if it has a hash value which never changes during
       its lifetime (it needs a :meth:`__hash__` method), and can be compared to
       other objects (it needs an :meth:`__eq__` or :meth:`__cmp__` method).
-      Hashable objects that compare equal must have the same hash value.
+      Hashable objects which compare equal must have the same hash value.
 
       Hashability makes an object usable as a dictionary key and a set member,
       because these data structures use the hash value internally.
 
-      All of Python's immutable built-in objects are hashable, while all mutable
-      containers (such as lists or dictionaries) are not.  Objects that are
+      All of Python's immutable built-in objects are hashable, while no mutable
+      containers (such as lists or dictionaries) are.  Objects which are
       instances of user-defined classes are hashable by default; they all
       compare unequal, and their hash value is their :func:`id`.
     
    IDLE
       An Integrated Development Environment for Python.  IDLE is a basic editor
-      and interpreter environment that ships with the standard distribution of
+      and interpreter environment which ships with the standard distribution of
       Python.  Good for beginners, it also serves as clear example code for
       those wanting to implement a moderately sophisticated, multi-platform GUI
       application.
     
    immutable
-      An object with fixed value.  Immutable objects are numbers, strings or
-      tuples (and more).  Such an object cannot be altered.  A new object has to
+      An object with a fixed value.  Immutable objects include numbers, strings and
+      tuples.  Such an object cannot be altered.  A new object has to
       be created if a different value has to be stored.  They play an important
       role in places where a constant hash value is needed, for example as a key
       in a dictionary.
@@ -252,18 +284,21 @@ Glossary
       :term:`__future__`.
     
    interactive
-      Python has an interactive interpreter which means that you can try out
-      things and immediately see their results.  Just launch ``python`` with no
-      arguments (possibly by selecting it from your computer's main menu). It is
-      a very powerful way to test out new ideas or inspect modules and packages
-      (remember ``help(x)``).
+      Python has an interactive interpreter which means you can enter
+      statements and expressions at the interpreter prompt, immediately
+      execute them and see their results.  Just launch ``python`` with no
+      arguments (possibly by selecting it from your computer's main
+      menu). It is a very powerful way to test out new ideas or inspect
+      modules and packages (remember ``help(x)``).
     
    interpreted
-      Python is an interpreted language, as opposed to a compiled one.  This
-      means that the source files can be run directly without first creating an
-      executable which is then run.  Interpreted languages typically have a
-      shorter development/debug cycle than compiled ones, though their programs
-      generally also run more slowly.  See also :term:`interactive`.
+      Python is an interpreted language, as opposed to a compiled one,
+      though the distinction can be blurry because of the presence of the
+      bytecode compiler.  This means that source files can be run directly
+      without explicitly creating an executable which is then run.
+      Interpreted languages typically have a shorter development/debug cycle
+      than compiled ones, though their programs generally also run more
+      slowly.  See also :term:`interactive`.
     
    iterable
       A container object capable of returning its members one at a
@@ -283,15 +318,15 @@ Glossary
     
    iterator
       An object representing a stream of data.  Repeated calls to the iterator's
-      :meth:`__next__` (or passing it to the builtin function) :func:`next`
-      method return successive items in the stream.  When no more data is
+      :meth:`__next__` (or passing it to the builtin function)  :func:`next`
+      method return successive items in the stream.  When no more data are
       available a :exc:`StopIteration` exception is raised instead.  At this
       point, the iterator object is exhausted and any further calls to its
-      :meth:`__next__` method just raise :exc:`StopIteration` again.  Iterators
-      are required to have an :meth:`__iter__` method that returns the iterator
+      :meth:`next` method just raise :exc:`StopIteration` again.  Iterators are
+      required to have an :meth:`__iter__` method that returns the iterator
       object itself so every iterator is also iterable and may be used in most
       places where other iterables are accepted.  One notable exception is code
-      that attempts multiple iteration passes.  A container object (such as a
+      which attempts multiple iteration passes.  A container object (such as a
       :class:`list`) produces a fresh new iterator each time you pass it to the
       :func:`iter` function or use it in a :keyword:`for` loop.  Attempting this
       with an iterator will just return the same exhausted iterator object used
@@ -315,17 +350,22 @@ Glossary
       pre-conditions before making calls or lookups.  This style contrasts with
       the :term:`EAFP` approach and is characterized by the presence of many
       :keyword:`if` statements.
+
+   list
+      A built-in Python :term:`sequence`.  Despite its name it is more akin
+      to an array in other languages than to a linked list since access to
+      elements are O(1).
     
    list comprehension
-      A compact way to process all or a subset of elements in a sequence and
+      A compact way to process all or part of the elements in a sequence and
       return a list with the results.  ``result = ["0x%02x" % x for x in
-      range(256) if x % 2 == 0]`` generates a list of strings containing hex
-      numbers (0x..) that are even and in the range from 0 to 255. The
-      :keyword:`if` clause is optional.  If omitted, all elements in
-      ``range(256)`` are processed.
+      range(256) if x % 2 == 0]`` generates a list of strings containing
+      even hex numbers (0x..) in the range from 0 to 255. The :keyword:`if`
+      clause is optional.  If omitted, all elements in ``range(256)`` are
+      processed.
     
    mapping
-      A container object (such as :class:`dict`) that supports arbitrary key
+      A container object (such as :class:`dict`) which supports arbitrary key
       lookups using the special method :meth:`__getitem__`.
     
    metaclass
@@ -342,7 +382,7 @@ Glossary
       More information can be found in :ref:`metaclasses`.
 
    method
-      A function that is defined inside a class body.  If called as an attribute
+      A function which is defined inside a class body.  If called as an attribute
       of an instance of that class, the method will get the instance object as
       its first :term:`argument` (which is usually called ``self``).
       See :term:`function` and :term:`nested scope`.
@@ -352,7 +392,7 @@ Glossary
       also :term:`immutable`.
 
    named tuple
-      Any tuple subclass whose indexable fields are also accessible with
+      Any tuple subclass whose indexable elements are also accessible using
       named attributes (for example, :func:`time.localtime` returns a
       tuple-like object where the *year* is accessible either with an
       index such as ``t[0]`` or with a named attribute like ``t.tm_year``).
@@ -374,7 +414,7 @@ Glossary
       it clear which module implements a function.  For instance, writing
       :func:`random.seed` or :func:`itertools.izip` makes it clear that those
       functions are implemented by the :mod:`random` and :mod:`itertools`
-      modules respectively.
+      modules, respectively.
     
    nested scope
       The ability to refer to a variable in an enclosing definition.  For
@@ -390,6 +430,13 @@ Glossary
       versatile features like :attr:`__slots__`, descriptors, properties,
       :meth:`__getattribute__`, class methods, and static methods.
 
+      More information can be found in :ref:`newstyle`.
+
+   object
+      Any data with state (attributes or value) and defined behavior
+      (methods).  Also the ultimate base class of any :term:`new-style
+      class`.
+    
    positional argument
       The arguments assigned to local names inside a function or method,
       determined by the order in which they were given in the call.  ``*`` is
@@ -403,11 +450,12 @@ Glossary
       abbreviated "Py3k".
 
    Pythonic
-      An idea or piece of code which closely follows the most common idioms of
-      the Python language, rather than implementing code using concepts common
-      in other languages.  For example, a common idiom in Python is the :keyword:`for`
-      loop structure; other languages don't have this easy keyword, so people
-      use a numerical counter instead::
+      An idea or piece of code which closely follows the most common idioms
+      of the Python language, rather than implementing code using concepts
+      common to other languages.  For example, a common idiom in Python is
+      to loop over all elements of an iterable using a :keyword:`for`
+      statement.  Many other languages don't have this type of construct, so
+      people unfamiliar with Python sometimes use a numerical counter instead::
      
           for i in range(len(food)):
               print(food[i])
@@ -418,11 +466,13 @@ Glossary
              print(piece)
 
    reference count
-      The number of places where a certain object is referenced to.  When the
-      reference count drops to zero, an object is deallocated.  While reference
-      counting is invisible on the Python code level, it is used on the
-      implementation level to keep track of allocated memory.
-    
+      The number of references to an object.  When the reference count of an
+      object drops to zero, it is deallocated.  Reference counting is
+      generally not visible to Python code, but it is a key element of the
+      :term:`CPython` implementation.  The :mod:`sys` module defines a
+      :func:`getrefcount` function that programmers can call to return the
+      reference count for a particular object.
+
    __slots__
       A declaration inside a class that saves memory by pre-declaring space for
       instance attributes and eliminating instance dictionaries.  Though
@@ -432,7 +482,8 @@ Glossary
     
    sequence
       An :term:`iterable` which supports efficient element access using integer
-      indices via the :meth:`__getitem__` and :meth:`__len__` special methods.
+      indices via the :meth:`__getitem__` special method and defines a
+      :meth:`len` method that returns the length of the sequence.
       Some built-in sequence types are :class:`list`, :class:`str`,
       :class:`tuple`, and :class:`unicode`. Note that :class:`dict` also
       supports :meth:`__getitem__` and :meth:`__len__`, but is considered a
@@ -450,10 +501,23 @@ Glossary
       an :term:`expression` or a one of several constructs with a keyword, such
       as :keyword:`if`, :keyword:`while` or :keyword:`for`.
 
+   triple-quoted string
+      A string which is bound by three instances of either a quotation mark
+      (") or an apostrophe (').  While they don't provide any functionality
+      not available with single-quoted strings, they are useful for a number
+      of reasons.  They allow you to include unescaped single and double
+      quotes within a string and they can span multiple lines without the
+      use of the continuation character, making them especially useful when
+      writing docstrings.
+
    type
       The type of a Python object determines what kind of object it is; every
       object has a type.  An object's type is accessible as its
       :attr:`__class__` attribute or can be retrieved with ``type(obj)``.
+
+   virtual machine
+      A computer defined entirely in software.  Python's virtual machine
+      executes the :term:`bytecode` emitted by the bytecode compiler.
     
    Zen of Python
       Listing of Python design principles and philosophies that are helpful in