Merged revisions 59605-59624 via svnmerge from

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

........
  r59606 | georg.brandl | 2007-12-29 11:57:00 +0100 (Sat, 29 Dec 2007) | 2 lines

  Some cleanup in the docs.
........
  r59611 | martin.v.loewis | 2007-12-29 19:49:21 +0100 (Sat, 29 Dec 2007) | 2 lines

  Bug #1699: Define _BSD_SOURCE only on OpenBSD.
........
  r59612 | raymond.hettinger | 2007-12-29 23:09:34 +0100 (Sat, 29 Dec 2007) | 1 line

  Simpler documentation for itertools.tee().  Should be backported.
........
  r59613 | raymond.hettinger | 2007-12-29 23:16:24 +0100 (Sat, 29 Dec 2007) | 1 line

  Improve docs for itertools.groupby().  The use of xrange(0) to create a unique object is less obvious than object().
........
  r59620 | christian.heimes | 2007-12-31 15:47:07 +0100 (Mon, 31 Dec 2007) | 3 lines

  Added wininst-9.0.exe executable for VS 2008
  Integrated bdist_wininst into PCBuild9 directory
........
  r59621 | christian.heimes | 2007-12-31 15:51:18 +0100 (Mon, 31 Dec 2007) | 1 line

  Moved PCbuild directory to PC/VS7.1
........
  r59622 | christian.heimes | 2007-12-31 15:59:26 +0100 (Mon, 31 Dec 2007) | 1 line

  Fix paths for build bot
........
  r59623 | christian.heimes | 2007-12-31 16:02:41 +0100 (Mon, 31 Dec 2007) | 1 line

  Fix paths for build bot, part 2
........
  r59624 | christian.heimes | 2007-12-31 16:18:55 +0100 (Mon, 31 Dec 2007) | 1 line

  Renamed PCBuild9 directory to PCBuild
........

Doc/tutorial/appetite.rst

@@ -75,8 +75,6 @@ Now that you are all excited about Python, you'll want to examine it in some
 more detail.  Since the best way to learn a language is to use it, the tutorial
 invites you to play with the Python interpreter as you read.
 
-.. % \section{Where From Here \label{where}}
-
 In the next chapter, the mechanics of using the interpreter are explained.  This
 is rather mundane information, but essential for trying out the examples shown
 later.

Doc/tutorial/classes.rst

@@ -390,7 +390,7 @@ is called with this new argument list.
 Random Remarks
 ==============
 
-.. % [These should perhaps be placed more carefully...]
+.. These should perhaps be placed more carefully...
 
 Data attributes override method attributes with the same name; to avoid
 accidental name conflicts, which may cause hard-to-find bugs in large programs,
@@ -506,7 +506,7 @@ Derived classes may override methods of their base classes.  Because methods
 have no special privileges when calling other methods of the same object, a
 method of a base class that calls another method defined in the same base class
 may end up calling a method of a derived class that overrides it.  (For C++
-programmers: all methods in Python are effectively :keyword:`virtual`.)
+programmers: all methods in Python are effectively ``virtual``.)
 
 An overriding method in a derived class may in fact want to extend rather than
 simply replace the base class method of the same name. There is a simple way to
@@ -617,12 +617,10 @@ instance, if you have a function that formats some data from a file object, you
 can define a class with methods :meth:`read` and :meth:`readline` that get the
 data from a string buffer instead, and pass it as an argument.
 
-.. % (Unfortunately, this
-.. % technique has its limitations: a class can't define operations that
-.. % are accessed by special syntax such as sequence subscripting or
-.. % arithmetic operators, and assigning such a ``pseudo-file'' to
-.. % \code{sys.stdin} will not cause the interpreter to read further input
-.. % from it.)
+.. (Unfortunately, this technique has its limitations: a class can't define
+   operations that are accessed by special syntax such as sequence subscripting
+   or arithmetic operators, and assigning such a "pseudo-file" to sys.stdin will
+   not cause the interpreter to read further input from it.)
 
 Instance method objects have attributes, too: ``m.__self__`` is the instance
 object with the method :meth:`m`, and ``m.__func__`` is the function object

Doc/tutorial/controlflow.rst

@@ -31,11 +31,8 @@ example::
 There can be zero or more :keyword:`elif` parts, and the :keyword:`else` part is
 optional.  The keyword ':keyword:`elif`' is short for 'else if', and is useful
 to avoid excessive indentation.  An  :keyword:`if` ... :keyword:`elif` ...
-:keyword:`elif` ... sequence is a substitute for the :keyword:`switch` or
-:keyword:`case` statements found in other languages.
-
-.. % Weird spacings happen here if the wrapping of the source text
-.. % gets changed in the wrong way.
+:keyword:`elif` ... sequence is a substitute for the ``switch`` or
+``case`` statements found in other languages.
 
 
 .. _tut-for:
@@ -53,8 +50,8 @@ iteration step and halting condition (as C), Python's :keyword:`for` statement
 iterates over the items of any sequence (a list or a string), in the order that
 they appear in the sequence.  For example (no pun intended):
 
-.. % One suggestion was to give a real C example here, but that may only
-.. % serve to confuse non-C programmers.
+.. One suggestion was to give a real C example here, but that may only serve to
+   confuse non-C programmers.
 
 ::
 

Doc/tutorial/datastructures.rst

@@ -350,6 +350,70 @@ is assigned to it).  We'll find other uses for :keyword:`del` later.
 
 
 
+Tuples and Sequences
+====================
+
+We saw that lists and strings have many common properties, such as indexing and
+slicing operations.  They are two examples of *sequence* data types (see
+:ref:`typesseq`).  Since Python is an evolving language, other sequence data
+types may be added.  There is also another standard sequence data type: the
+*tuple*.
+
+A tuple consists of a number of values separated by commas, for instance::
+
+   >>> t = 12345, 54321, 'hello!'
+   >>> t[0]
+   12345
+   >>> t
+   (12345, 54321, 'hello!')
+   >>> # Tuples may be nested:
+   ... u = t, (1, 2, 3, 4, 5)
+   >>> u
+   ((12345, 54321, 'hello!'), (1, 2, 3, 4, 5))
+
+As you see, on output tuples are always enclosed in parentheses, so that nested
+tuples are interpreted correctly; they may be input with or without surrounding
+parentheses, although often parentheses are necessary anyway (if the tuple is
+part of a larger expression).
+
+Tuples have many uses.  For example: (x, y) coordinate pairs, employee records
+from a database, etc.  Tuples, like strings, are immutable: it is not possible
+to assign to the individual items of a tuple (you can simulate much of the same
+effect with slicing and concatenation, though).  It is also possible to create
+tuples which contain mutable objects, such as lists.
+
+A special problem is the construction of tuples containing 0 or 1 items: the
+syntax has some extra quirks to accommodate these.  Empty tuples are constructed
+by an empty pair of parentheses; a tuple with one item is constructed by
+following a value with a comma (it is not sufficient to enclose a single value
+in parentheses). Ugly, but effective.  For example::
+
+   >>> empty = ()
+   >>> singleton = 'hello',    # <-- note trailing comma
+   >>> len(empty)
+   0
+   >>> len(singleton)
+   1
+   >>> singleton
+   ('hello',)
+
+The statement ``t = 12345, 54321, 'hello!'`` is an example of *tuple packing*:
+the values ``12345``, ``54321`` and ``'hello!'`` are packed together in a tuple.
+The reverse operation is also possible::
+
+   >>> x, y, z = t
+
+This is called, appropriately enough, *sequence unpacking*. Sequence unpacking
+requires the list of variables on the left to have the same number of elements
+as the length of the sequence.  Note that multiple assignment is really just a
+combination of tuple packing and sequence unpacking!
+
+There is a small bit of asymmetry here:  packing multiple values always creates
+a tuple, and unpacking works for any sequence.
+
+.. XXX Add a bit on the difference between tuples and lists.
+
+
 .. _tut-sets:
 
 Sets

Doc/tutorial/inputoutput.rst

@@ -180,11 +180,9 @@ Reading and Writing Files
 :func:`open` returns a file object, and is most commonly used with two
 arguments: ``open(filename, mode)``.
 
-.. % Opening files
-
 ::
 
-   >>> f=open('/tmp/workfile', 'w')
+   >>> f = open('/tmp/workfile', 'w')
    >>> print(f)
    <open file '/tmp/workfile', mode 'w' at 80a0960>
 

Doc/tutorial/interpreter.rst

@@ -212,8 +212,8 @@ setting an environment variable named :envvar:`PYTHONSTARTUP` to the name of a
 file containing your start-up commands.  This is similar to the :file:`.profile`
 feature of the Unix shells.
 
-.. % XXX This should probably be dumped in an appendix, since most people
-.. % don't use Python interactively in non-trivial ways.
+.. XXX This should probably be dumped in an appendix, since most people
+   don't use Python interactively in non-trivial ways.
 
 This file is only read in interactive sessions, not when Python reads commands
 from a script, and not when :file:`/dev/tty` is given as the explicit source of

Doc/tutorial/introduction.rst

@@ -13,9 +13,9 @@ end a multi-line command.
 
 Many of the examples in this manual, even those entered at the interactive
 prompt, include comments.  Comments in Python start with the hash character,
-``'#'``, and extend to the end of the physical line.  A comment may appear at
+``#``, and extend to the end of the physical line.  A comment may appear at
 the start of a line or following whitespace or code, but not within a string
-literal.  A hash  character within a string literal is just a hash character.
+literal.  A hash character within a string literal is just a hash character.
 
 Some examples::
 
@@ -608,5 +608,3 @@ This example introduces several new features.
  Note that nothing appeared after the loop ended, until we printed
  a newline.
 
-
-

Doc/tutorial/modules.rst

@@ -223,11 +223,6 @@ Some tips for experts:
 * The module :mod:`compileall` can create :file:`.pyc` files (or :file:`.pyo`
   files when :option:`-O` is used) for all modules in a directory.
 
-* If using Python in a parallel processing system with a shared file system,
-  you need to patch Python to disable the creation of the compiled files 
-  because otherwise the multiple Python interpreters will encounter race 
-  conditions in creating them.
-
 
 .. _tut-standardmodules:
 
@@ -246,11 +241,7 @@ depends on the underlying platform For example, the :mod:`winreg` module is only
 provided on Windows systems. One particular module deserves some attention:
 :mod:`sys`, which is built into every Python interpreter.  The variables
 ``sys.ps1`` and ``sys.ps2`` define the strings used as primary and secondary
-prompts:
-
-.. % 
-
-::
+prompts::
 
    >>> import sys
    >>> sys.ps1
@@ -455,8 +446,6 @@ filename!  On these platforms, there is no guaranteed way to know whether a file
 file names with a capitalized first letter.)  The DOS 8+3 filename restriction
 adds another interesting problem for long module names.
 
-.. % The \code{__all__} Attribute
-
 The only solution is for the package author to provide an explicit index of the
 package.  The import statement uses the following convention: if a package's
 :file:`__init__.py` code defines a list named ``__all__``, it is taken to be the

Doc/tutorial/whatnow.rst

@@ -66,8 +66,8 @@ archives are available at http://mail.python.org/pipermail/. The FAQ answers
 many of the questions that come up again and again, and may already contain the
 solution for your problem.
 
-.. % Postings figure based on average of last six months activity as
-.. % reported by www.egroups.com; Jan. 2000 - June 2000: 21272 msgs / 182
-.. % days = 116.9 msgs / day and steadily increasing.
+.. Postings figure based on average of last six months activity as
+   reported by www.egroups.com; Jan. 2000 - June 2000: 21272 msgs / 182
+   days = 116.9 msgs / day and steadily increasing. (XXX up to date figures?)