cpython-lru_cache-weakref: Doc/tutorial/controlflow.rst annotate

annotate Doc/tutorial/controlflow.rst @ 79675:c0a2294de787 2.7

Issue #16199: Backport 2to3 typo fix from 3.2.

author	Chris Jerdonek <chris.jerdonek@gmail.com>
date	Thu, 11 Oct 2012 16:15:46 -0700
parents	332566c29ab4
children	dc006b6212e7

rev	line source
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1 .. _tut-morecontrol:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3 ***********************
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 More Control Flow Tools
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 ***********************
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7 Besides the :keyword:`while` statement just introduced, Python knows the usual
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 control flow statements known from other languages, with some twists.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 .. _tut-if:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13 :keyword:`if` Statements
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14 ========================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16 Perhaps the most well-known statement type is the :keyword:`if` statement. For
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17 example::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19 >>> x = int(raw_input("Please enter an integer: "))
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	20 Please enter an integer: 42
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 >>> if x < 0:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 ... x = 0
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 ... print 'Negative changed to zero'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 ... elif x == 0:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 ... print 'Zero'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26 ... elif x == 1:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27 ... print 'Single'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 ... else:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29 ... print 'More'
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	30 ...
feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	31 More
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33 There can be zero or more :keyword:`elif` parts, and the :keyword:`else` part is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34 optional. The keyword ':keyword:`elif`' is short for 'else if', and is useful
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35 to avoid excessive indentation. An :keyword:`if` ... :keyword:`elif` ...
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43715 diff changeset	36 :keyword:`elif` ... sequence is a substitute for the ``switch`` or
3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43715 diff changeset	37 ``case`` statements found in other languages.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40 .. _tut-for:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 :keyword:`for` Statements
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43 =========================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46 statement: for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47 statement: for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49 The :keyword:`for` statement in Python differs a bit from what you may be used
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50 to in C or Pascal. Rather than always iterating over an arithmetic progression
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51 of numbers (like in Pascal), or giving the user the ability to define both the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52 iteration step and halting condition (as C), Python's :keyword:`for` statement
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53 iterates over the items of any sequence (a list or a string), in the order that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54 they appear in the sequence. For example (no pun intended):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43715 diff changeset	56 .. One suggestion was to give a real C example here, but that may only serve to
3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43715 diff changeset	57 confuse non-C programmers.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59 ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61 >>> # Measure some strings:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62 ... a = ['cat', 'window', 'defenestrate']
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63 >>> for x in a:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64 ... print x, len(x)
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50305 diff changeset	65 ...
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 cat 3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67 window 6
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68 defenestrate 12
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 It is not safe to modify the sequence being iterated over in the loop (this can
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 only happen for mutable sequence types, such as lists). If you need to modify
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72 the list you are iterating over (for example, to duplicate selected items) you
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73 must iterate over a copy. The slice notation makes this particularly
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74 convenient::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76 >>> for x in a[:]: # make a slice copy of the entire list
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77 ... if len(x) > 6: a.insert(0, x)
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50305 diff changeset	78 ...
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 >>> a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80 ['defenestrate', 'cat', 'window', 'defenestrate']
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83 .. _tut-range:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85 The :func:`range` Function
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86 ==========================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88 If you do need to iterate over a sequence of numbers, the built-in function
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89 :func:`range` comes in handy. It generates lists containing arithmetic
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90 progressions::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92 >>> range(10)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95 The given end point is never part of the generated list; ``range(10)`` generates
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96 a list of 10 values, the legal indices for items of a sequence of length 10. It
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97 is possible to let the range start at another number, or to specify a different
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98 increment (even negative; sometimes this is called the 'step')::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100 >>> range(5, 10)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101 [5, 6, 7, 8, 9]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 >>> range(0, 10, 3)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103 [0, 3, 6, 9]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104 >>> range(-10, -100, -30)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105 [-10, -40, -70]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106
50008 11bf59fe10b9 Merged revisions 67326,67498,67531-67532,67538,67553-67554,67556-67557 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	107 To iterate over the indices of a sequence, you can combine :func:`range` and
11bf59fe10b9 Merged revisions 67326,67498,67531-67532,67538,67553-67554,67556-67557 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	108 :func:`len` as follows::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110 >>> a = ['Mary', 'had', 'a', 'little', 'lamb']
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111 >>> for i in range(len(a)):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112 ... print i, a[i]
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50305 diff changeset	113 ...
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114 0 Mary
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115 1 had
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116 2 a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117 3 little
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118 4 lamb
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119
50008 11bf59fe10b9 Merged revisions 67326,67498,67531-67532,67538,67553-67554,67556-67557 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	120 In most such cases, however, it is convenient to use the :func:`enumerate`
11bf59fe10b9 Merged revisions 67326,67498,67531-67532,67538,67553-67554,67556-67557 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	121 function, see :ref:`tut-loopidioms`.
11bf59fe10b9 Merged revisions 67326,67498,67531-67532,67538,67553-67554,67556-67557 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	122
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124 .. _tut-break:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126 :keyword:`break` and :keyword:`continue` Statements, and :keyword:`else` Clauses on Loops
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127 =========================================================================================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129 The :keyword:`break` statement, like in C, breaks out of the smallest enclosing
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130 :keyword:`for` or :keyword:`while` loop.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132 Loop statements may have an ``else`` clause; it is executed when the loop
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133 terminates through exhaustion of the list (with :keyword:`for`) or when the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134 condition becomes false (with :keyword:`while`), but not when the loop is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135 terminated by a :keyword:`break` statement. This is exemplified by the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136 following loop, which searches for prime numbers::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138 >>> for n in range(2, 10):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139 ... for x in range(2, n):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140 ... if n % x == 0:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141 ... print n, 'equals', x, '*', n/x
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142 ... break
48129 0aff3bf0a342 revert last revision; code was right Benjamin Peterson <benjamin@python.org> parents: 48128 diff changeset	143 ... else:
0aff3bf0a342 revert last revision; code was right Benjamin Peterson <benjamin@python.org> parents: 48128 diff changeset	144 ... # loop fell through without finding a factor
0aff3bf0a342 revert last revision; code was right Benjamin Peterson <benjamin@python.org> parents: 48128 diff changeset	145 ... print n, 'is a prime number'
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50305 diff changeset	146 ...
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147 2 is a prime number
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	148 3 is a prime number
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149 4 equals 2 * 2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 5 is a prime number
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151 6 equals 2 * 3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 7 is a prime number
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153 8 equals 2 * 4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154 9 equals 3 * 3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155
71776 10f20ad2fbb6 Confirm that the prime example is actually correct. We get so many complaints about a "buggy example" on docs@python, let us hope this cuts them in half at least. Georg Brandl <georg@python.org> parents: 70168 diff changeset	156 (Yes, this is the correct code. Look closely: the ``else`` clause belongs to
10f20ad2fbb6 Confirm that the prime example is actually correct. We get so many complaints about a "buggy example" on docs@python, let us hope this cuts them in half at least. Georg Brandl <georg@python.org> parents: 70168 diff changeset	157 the :keyword:`for` loop, not the :keyword:`if` statement.)
10f20ad2fbb6 Confirm that the prime example is actually correct. We get so many complaints about a "buggy example" on docs@python, let us hope this cuts them in half at least. Georg Brandl <georg@python.org> parents: 70168 diff changeset	158
77371 d79c837b6bf3 Nudge readers towards a more accurate mental model for loop else clauses (Backport from 3.x) Nick Coghlan <ncoghlan@gmail.com> parents: 73954 diff changeset	159 When used with a loop, the ``else`` clause has more in common with the
d79c837b6bf3 Nudge readers towards a more accurate mental model for loop else clauses (Backport from 3.x) Nick Coghlan <ncoghlan@gmail.com> parents: 73954 diff changeset	160 ``else`` clause of a :keyword:`try` statement than it does that of
d79c837b6bf3 Nudge readers towards a more accurate mental model for loop else clauses (Backport from 3.x) Nick Coghlan <ncoghlan@gmail.com> parents: 73954 diff changeset	161 :keyword:`if` statements: a :keyword:`try` statement's ``else`` clause runs
d79c837b6bf3 Nudge readers towards a more accurate mental model for loop else clauses (Backport from 3.x) Nick Coghlan <ncoghlan@gmail.com> parents: 73954 diff changeset	162 when no exception occurs, and a loop's ``else`` clause runs when no ``break``
d79c837b6bf3 Nudge readers towards a more accurate mental model for loop else clauses (Backport from 3.x) Nick Coghlan <ncoghlan@gmail.com> parents: 73954 diff changeset	163 occurs. For more on the :keyword:`try` statement and exceptions, see
d79c837b6bf3 Nudge readers towards a more accurate mental model for loop else clauses (Backport from 3.x) Nick Coghlan <ncoghlan@gmail.com> parents: 73954 diff changeset	164 :ref:`tut-handling`.
d79c837b6bf3 Nudge readers towards a more accurate mental model for loop else clauses (Backport from 3.x) Nick Coghlan <ncoghlan@gmail.com> parents: 73954 diff changeset	165
78536 a4d5ac78a76b Issue #15630: Add an example for "continue" statement in the tutorial. Patch by Senthil Kumaran <senthil@uthcode.com> parents: 77371 diff changeset	166 The :keyword:`continue` statement, also borrowed from C, continues with the next
a4d5ac78a76b Issue #15630: Add an example for "continue" statement in the tutorial. Patch by Senthil Kumaran <senthil@uthcode.com> parents: 77371 diff changeset	167 iteration of the loop::
a4d5ac78a76b Issue #15630: Add an example for "continue" statement in the tutorial. Patch by Senthil Kumaran <senthil@uthcode.com> parents: 77371 diff changeset	168
a4d5ac78a76b Issue #15630: Add an example for "continue" statement in the tutorial. Patch by Senthil Kumaran <senthil@uthcode.com> parents: 77371 diff changeset	169 >>> for num in range(2, 10):
78639 332566c29ab4 Fix typo in tutorial Eli Bendersky <eliben@gmail.com> parents: 78536 diff changeset	170 ... if num % 2 == 0:
78536 a4d5ac78a76b Issue #15630: Add an example for "continue" statement in the tutorial. Patch by Senthil Kumaran <senthil@uthcode.com> parents: 77371 diff changeset	171 ... print("Found an even number", num)
a4d5ac78a76b Issue #15630: Add an example for "continue" statement in the tutorial. Patch by Senthil Kumaran <senthil@uthcode.com> parents: 77371 diff changeset	172 ... continue
a4d5ac78a76b Issue #15630: Add an example for "continue" statement in the tutorial. Patch by Senthil Kumaran <senthil@uthcode.com> parents: 77371 diff changeset	173 ... print("Found a number", num)
a4d5ac78a76b Issue #15630: Add an example for "continue" statement in the tutorial. Patch by Senthil Kumaran <senthil@uthcode.com> parents: 77371 diff changeset	174 Found an even number 2
a4d5ac78a76b Issue #15630: Add an example for "continue" statement in the tutorial. Patch by Senthil Kumaran <senthil@uthcode.com> parents: 77371 diff changeset	175 Found a number 3
a4d5ac78a76b Issue #15630: Add an example for "continue" statement in the tutorial. Patch by Senthil Kumaran <senthil@uthcode.com> parents: 77371 diff changeset	176 Found an even number 4
a4d5ac78a76b Issue #15630: Add an example for "continue" statement in the tutorial. Patch by Senthil Kumaran <senthil@uthcode.com> parents: 77371 diff changeset	177 Found a number 5
a4d5ac78a76b Issue #15630: Add an example for "continue" statement in the tutorial. Patch by Senthil Kumaran <senthil@uthcode.com> parents: 77371 diff changeset	178 Found an even number 6
a4d5ac78a76b Issue #15630: Add an example for "continue" statement in the tutorial. Patch by Senthil Kumaran <senthil@uthcode.com> parents: 77371 diff changeset	179 Found a number 7
a4d5ac78a76b Issue #15630: Add an example for "continue" statement in the tutorial. Patch by Senthil Kumaran <senthil@uthcode.com> parents: 77371 diff changeset	180 Found an even number 8
a4d5ac78a76b Issue #15630: Add an example for "continue" statement in the tutorial. Patch by Senthil Kumaran <senthil@uthcode.com> parents: 77371 diff changeset	181 Found a number 9
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	183 .. _tut-pass:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185 :keyword:`pass` Statements
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186 ==========================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188 The :keyword:`pass` statement does nothing. It can be used when a statement is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	189 required syntactically but the program requires no action. For example::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	190
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191 >>> while True:
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	192 ... pass # Busy-wait for keyboard interrupt (Ctrl+C)
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50305 diff changeset	193 ...
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194
50305 e673632e1885 Merged revisions 67898,67904-67907,67912,67918,67920-67921,67923-67924,67927,67930,67932,67943 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50008 diff changeset	195 This is commonly used for creating minimal classes::
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49179 diff changeset	196
50305 e673632e1885 Merged revisions 67898,67904-67907,67912,67918,67920-67921,67923-67924,67927,67930,67932,67943 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50008 diff changeset	197 >>> class MyEmptyClass:
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49179 diff changeset	198 ... pass
50305 e673632e1885 Merged revisions 67898,67904-67907,67912,67918,67920-67921,67923-67924,67927,67930,67932,67943 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50008 diff changeset	199 ...
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49179 diff changeset	200
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49179 diff changeset	201 Another place :keyword:`pass` can be used is as a place-holder for a function or
50305 e673632e1885 Merged revisions 67898,67904-67907,67912,67918,67920-67921,67923-67924,67927,67930,67932,67943 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50008 diff changeset	202 conditional body when you are working on new code, allowing you to keep thinking
e673632e1885 Merged revisions 67898,67904-67907,67912,67918,67920-67921,67923-67924,67927,67930,67932,67943 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50008 diff changeset	203 at a more abstract level. The :keyword:`pass` is silently ignored::
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49179 diff changeset	204
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49179 diff changeset	205 >>> def initlog(*args):
50305 e673632e1885 Merged revisions 67898,67904-67907,67912,67918,67920-67921,67923-67924,67927,67930,67932,67943 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50008 diff changeset	206 ... pass # Remember to implement this!
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50305 diff changeset	207 ...
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49179 diff changeset	208
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209 .. _tut-functions:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211 Defining Functions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212 ==================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214 We can create a function that writes the Fibonacci series to an arbitrary
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215 boundary::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217 >>> def fib(n): # write Fibonacci series up to n
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 ... """Print a Fibonacci series up to n."""
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219 ... a, b = 0, 1
57408 2639ea7b92ed Merged revisions 76460 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56812 diff changeset	220 ... while a < n:
2639ea7b92ed Merged revisions 76460 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56812 diff changeset	221 ... print a,
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222 ... a, b = b, a+b
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50305 diff changeset	223 ...
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224 >>> # Now call the function we just defined:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225 ... fib(2000)
57408 2639ea7b92ed Merged revisions 76460 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56812 diff changeset	226 0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229 single: documentation strings
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230 single: docstrings
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231 single: strings, documentation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	232
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233 The keyword :keyword:`def` introduces a function definition. It must be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234 followed by the function name and the parenthesized list of formal parameters.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235 The statements that form the body of the function start at the next line, and
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	236 must be indented.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	238 The first statement of the function body can optionally be a string literal;
feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	239 this string literal is the function's documentation string, or :dfn:`docstring`.
feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	240 (More about docstrings can be found in the section :ref:`tut-docstrings`.)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241 There are tools which use docstrings to automatically produce online or printed
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242 documentation, or to let the user interactively browse through code; it's good
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	243 practice to include docstrings in code that you write, so make a habit of it.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245 The execution of a function introduces a new symbol table used for the local
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246 variables of the function. More precisely, all variable assignments in a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247 function store the value in the local symbol table; whereas variable references
44842 1990fa6b9e82 #997912: acknowledge nested scopes in tutorial. Georg Brandl <georg@python.org> parents: 44545 diff changeset	248 first look in the local symbol table, then in the local symbol tables of
1990fa6b9e82 #997912: acknowledge nested scopes in tutorial. Georg Brandl <georg@python.org> parents: 44545 diff changeset	249 enclosing functions, then in the global symbol table, and finally in the table
1990fa6b9e82 #997912: acknowledge nested scopes in tutorial. Georg Brandl <georg@python.org> parents: 44545 diff changeset	250 of built-in names. Thus, global variables cannot be directly assigned a value
1990fa6b9e82 #997912: acknowledge nested scopes in tutorial. Georg Brandl <georg@python.org> parents: 44545 diff changeset	251 within a function (unless named in a :keyword:`global` statement), although they
1990fa6b9e82 #997912: acknowledge nested scopes in tutorial. Georg Brandl <georg@python.org> parents: 44545 diff changeset	252 may be referenced.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	254 The actual parameters (arguments) to a function call are introduced in the local
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	255 symbol table of the called function when it is called; thus, arguments are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	256 passed using call by value (where the value is always an object reference,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	257 not the value of the object). [#]_ When a function calls another function, a new
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258 local symbol table is created for that call.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 A function definition introduces the function name in the current symbol table.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261 The value of the function name has a type that is recognized by the interpreter
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 as a user-defined function. This value can be assigned to another name which
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263 can then also be used as a function. This serves as a general renaming
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264 mechanism::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266 >>> fib
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	267 <function fib at 10042ed0>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	268 >>> f = fib
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269 >>> f(100)
57408 2639ea7b92ed Merged revisions 76460 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56812 diff changeset	270 0 1 1 2 3 5 8 13 21 34 55 89
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	271
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	272 Coming from other languages, you might object that ``fib`` is not a function but
feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	273 a procedure since it doesn't return a value. In fact, even functions without a
feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	274 :keyword:`return` statement do return a value, albeit a rather boring one. This
feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	275 value is called ``None`` (it's a built-in name). Writing the value ``None`` is
feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	276 normally suppressed by the interpreter if it would be the only value written.
feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	277 You can see it if you really want to using :keyword:`print`::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278
43715 e2fe58604cb1 Make example about hiding None return values at the prompt clearer. Georg Brandl <georg@python.org> parents: 42603 diff changeset	279 >>> fib(0)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280 >>> print fib(0)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281 None
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	282
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	283 It is simple to write a function that returns a list of the numbers of the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284 Fibonacci series, instead of printing it::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	285
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286 >>> def fib2(n): # return Fibonacci series up to n
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287 ... """Return a list containing the Fibonacci series up to n."""
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288 ... result = []
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	289 ... a, b = 0, 1
57408 2639ea7b92ed Merged revisions 76460 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56812 diff changeset	290 ... while a < n:
2639ea7b92ed Merged revisions 76460 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56812 diff changeset	291 ... result.append(a) # see below
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	292 ... a, b = b, a+b
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	293 ... return result
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50305 diff changeset	294 ...
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	295 >>> f100 = fib2(100) # call it
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	296 >>> f100 # write the result
57408 2639ea7b92ed Merged revisions 76460 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56812 diff changeset	297 [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	298
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	299 This example, as usual, demonstrates some new Python features:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	300
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	301 * The :keyword:`return` statement returns with a value from a function.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	302 :keyword:`return` without an expression argument returns ``None``. Falling off
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	303 the end of a function also returns ``None``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	304
57408 2639ea7b92ed Merged revisions 76460 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56812 diff changeset	305 * The statement ``result.append(a)`` calls a method of the list object
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	306 ``result``. A method is a function that 'belongs' to an object and is named
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	307 ``obj.methodname``, where ``obj`` is some object (this may be an expression),
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	308 and ``methodname`` is the name of a method that is defined by the object's type.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	309 Different types define different methods. Methods of different types may have
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310 the same name without causing ambiguity. (It is possible to define your own
56812 a1b0936b027c Merged revisions 72558,72745,72750,72876,73042,73045-73048,73069,73089,73163,73186,73213,73215,73217,73257-73258,73260 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	311 object types and methods, using classes, see :ref:`tut-classes`)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312 The method :meth:`append` shown in the example is defined for list objects; it
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313 adds a new element at the end of the list. In this example it is equivalent to
57408 2639ea7b92ed Merged revisions 76460 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56812 diff changeset	314 ``result = result + [a]``, but more efficient.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317 .. _tut-defining:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319 More on Defining Functions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320 ==========================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322 It is also possible to define functions with a variable number of arguments.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323 There are three forms, which can be combined.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326 .. _tut-defaultargs:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328 Default Argument Values
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329 -----------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331 The most useful form is to specify a default value for one or more arguments.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	332 This creates a function that can be called with fewer arguments than it is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333 defined to allow. For example::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335 def ask_ok(prompt, retries=4, complaint='Yes or no, please!'):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336 while True:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337 ok = raw_input(prompt)
56812 a1b0936b027c Merged revisions 72558,72745,72750,72876,73042,73045-73048,73069,73089,73163,73186,73213,73215,73217,73257-73258,73260 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	338 if ok in ('y', 'ye', 'yes'):
a1b0936b027c Merged revisions 72558,72745,72750,72876,73042,73045-73048,73069,73089,73163,73186,73213,73215,73217,73257-73258,73260 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	339 return True
a1b0936b027c Merged revisions 72558,72745,72750,72876,73042,73045-73048,73069,73089,73163,73186,73213,73215,73217,73257-73258,73260 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	340 if ok in ('n', 'no', 'nop', 'nope'):
a1b0936b027c Merged revisions 72558,72745,72750,72876,73042,73045-73048,73069,73089,73163,73186,73213,73215,73217,73257-73258,73260 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	341 return False
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342 retries = retries - 1
56812 a1b0936b027c Merged revisions 72558,72745,72750,72876,73042,73045-73048,73069,73089,73163,73186,73213,73215,73217,73257-73258,73260 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	343 if retries < 0:
a1b0936b027c Merged revisions 72558,72745,72750,72876,73042,73045-73048,73069,73089,73163,73186,73213,73215,73217,73257-73258,73260 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	344 raise IOError('refusenik user')
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345 print complaint
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346
56812 a1b0936b027c Merged revisions 72558,72745,72750,72876,73042,73045-73048,73069,73089,73163,73186,73213,73215,73217,73257-73258,73260 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	347 This function can be called in several ways:
a1b0936b027c Merged revisions 72558,72745,72750,72876,73042,73045-73048,73069,73089,73163,73186,73213,73215,73217,73257-73258,73260 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	348
a1b0936b027c Merged revisions 72558,72745,72750,72876,73042,73045-73048,73069,73089,73163,73186,73213,73215,73217,73257-73258,73260 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	349 * giving only the mandatory argument:
a1b0936b027c Merged revisions 72558,72745,72750,72876,73042,73045-73048,73069,73089,73163,73186,73213,73215,73217,73257-73258,73260 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	350 ``ask_ok('Do you really want to quit?')``
a1b0936b027c Merged revisions 72558,72745,72750,72876,73042,73045-73048,73069,73089,73163,73186,73213,73215,73217,73257-73258,73260 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	351 * giving one of the optional arguments:
a1b0936b027c Merged revisions 72558,72745,72750,72876,73042,73045-73048,73069,73089,73163,73186,73213,73215,73217,73257-73258,73260 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	352 ``ask_ok('OK to overwrite the file?', 2)``
a1b0936b027c Merged revisions 72558,72745,72750,72876,73042,73045-73048,73069,73089,73163,73186,73213,73215,73217,73257-73258,73260 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	353 * or even giving all arguments:
a1b0936b027c Merged revisions 72558,72745,72750,72876,73042,73045-73048,73069,73089,73163,73186,73213,73215,73217,73257-73258,73260 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	354 ``ask_ok('OK to overwrite the file?', 2, 'Come on, only yes or no!')``
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	355
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356 This example also introduces the :keyword:`in` keyword. This tests whether or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357 not a sequence contains a certain value.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359 The default values are evaluated at the point of function definition in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360 defining scope, so that ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	361
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362 i = 5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	363
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	364 def f(arg=i):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	365 print arg
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	366
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	367 i = 6
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	368 f()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	369
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	370 will print ``5``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	371
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	372 Important warning: The default value is evaluated only once. This makes a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	373 difference when the default is a mutable object such as a list, dictionary, or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	374 instances of most classes. For example, the following function accumulates the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	375 arguments passed to it on subsequent calls::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	376
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	377 def f(a, L=[]):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	378 L.append(a)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	379 return L
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	380
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	381 print f(1)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	382 print f(2)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	383 print f(3)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	384
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	385 This will print ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	386
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	387 [1]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	388 [1, 2]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	389 [1, 2, 3]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	390
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391 If you don't want the default to be shared between subsequent calls, you can
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	392 write the function like this instead::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	393
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	394 def f(a, L=None):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	395 if L is None:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396 L = []
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	397 L.append(a)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	398 return L
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	399
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	401 .. _tut-keywordargs:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	402
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	403 Keyword Arguments
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	404 -----------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405
73954 d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	406 Functions can also be called using :term:`keyword arguments <keyword argument>`
d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	407 of the form ``kwarg=value``. For instance, the following function::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409 def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	410 print "-- This parrot wouldn't", action,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411 print "if you put", voltage, "volts through it."
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	412 print "-- Lovely plumage, the", type
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	413 print "-- It's", state, "!"
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414
73954 d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	415 accepts one required argument (``voltage``) and three optional arguments
d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	416 (``state``, ``action``, and ``type``). This function can be called in any
d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	417 of the following ways::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	418
73954 d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	419 parrot(1000) # 1 positional argument
d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	420 parrot(voltage=1000) # 1 keyword argument
d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	421 parrot(voltage=1000000, action='VOOOOOM') # 2 keyword arguments
d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	422 parrot(action='VOOOOOM', voltage=1000000) # 2 keyword arguments
d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	423 parrot('a million', 'bereft of life', 'jump') # 3 positional arguments
d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	424 parrot('a thousand', state='pushing up the daisies') # 1 positional, 1 keyword
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	425
73954 d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	426 but all the following calls would be invalid::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428 parrot() # required argument missing
73954 d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	429 parrot(voltage=5.0, 'dead') # non-keyword argument after a keyword argument
d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	430 parrot(110, voltage=220) # duplicate value for the same argument
d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	431 parrot(actor='John Cleese') # unknown keyword argument
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	432
73954 d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	433 In a function call, keyword arguments must follow positional arguments.
d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	434 All the keyword arguments passed must match one of the arguments
d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	435 accepted by the function (e.g. ``actor`` is not a valid argument for the
d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	436 ``parrot`` function), and their order is not important. This also includes
d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	437 non-optional arguments (e.g. ``parrot(voltage=1000)`` is valid too).
d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	438 No argument may receive a value more than once.
d60856651139 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71776 diff changeset	439 Here's an example that fails due to this restriction::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	440
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	441 >>> def function(a):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	442 ... pass
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50305 diff changeset	443 ...
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	444 >>> function(0, a=0)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	445 Traceback (most recent call last):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	446 File "<stdin>", line 1, in ?
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	447 TypeError: function() got multiple values for keyword argument 'a'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	448
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	449 When a final formal parameter of the form ``**name`` is present, it receives a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	450 dictionary (see :ref:`typesmapping`) containing all keyword arguments except for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	451 those corresponding to a formal parameter. This may be combined with a formal
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	452 parameter of the form ``*name`` (described in the next subsection) which
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	453 receives a tuple containing the positional arguments beyond the formal parameter
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	454 list. (``name`` must occur before ``*name``.) For example, if we define a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	455 function like this::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	456
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	457 def cheeseshop(kind, arguments, *keywords):
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	458 print "-- Do you have any", kind, "?"
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	459 print "-- I'm sorry, we're all out of", kind
66453 8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from Georg Brandl <georg@python.org> parents: 65360 diff changeset	460 for arg in arguments:
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from Georg Brandl <georg@python.org> parents: 65360 diff changeset	461 print arg
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	462 print "-" * 40
65360 80fe066c135a #8267: Use sorted() to get a sorted list of dict keys. Georg Brandl <georg@python.org> parents: 57407 diff changeset	463 keys = sorted(keywords.keys())
80fe066c135a #8267: Use sorted() to get a sorted list of dict keys. Georg Brandl <georg@python.org> parents: 57407 diff changeset	464 for kw in keys:
80fe066c135a #8267: Use sorted() to get a sorted list of dict keys. Georg Brandl <georg@python.org> parents: 57407 diff changeset	465 print kw, ":", keywords[kw]
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	466
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	467 It could be called like this::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	468
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	469 cheeseshop("Limburger", "It's very runny, sir.",
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	470 "It's really very, VERY runny, sir.",
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	471 shopkeeper='Michael Palin',
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	472 client="John Cleese",
feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	473 sketch="Cheese Shop Sketch")
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	474
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	475 and of course it would print::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	476
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	477 -- Do you have any Limburger ?
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	478 -- I'm sorry, we're all out of Limburger
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	479 It's very runny, sir.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	480 It's really very, VERY runny, sir.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	481 ----------------------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	482 client : John Cleese
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	483 shopkeeper : Michael Palin
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	484 sketch : Cheese Shop Sketch
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	485
70168 c449d3c3e0da #12092: backport rephrasing of a paragraph in the tutorial. Ezio Melotti <ezio.melotti@gmail.com> parents: 68256 diff changeset	486 Note that the list of keyword argument names is created by sorting the result
c449d3c3e0da #12092: backport rephrasing of a paragraph in the tutorial. Ezio Melotti <ezio.melotti@gmail.com> parents: 68256 diff changeset	487 of the keywords dictionary's ``keys()`` method before printing its contents;
c449d3c3e0da #12092: backport rephrasing of a paragraph in the tutorial. Ezio Melotti <ezio.melotti@gmail.com> parents: 68256 diff changeset	488 if this is not done, the order in which the arguments are printed is undefined.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	489
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	490 .. _tut-arbitraryargs:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	491
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	492 Arbitrary Argument Lists
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	493 ------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	494
46457 3e095ab75fc8 Add ,,@ to index, as suggested by Andrew M. Kuchling <amk@amk.ca>* parents: 44842 diff changeset	495 .. index::
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50305 diff changeset	496 statement: *
46457 3e095ab75fc8 Add ,,@ to index, as suggested by Andrew M. Kuchling <amk@amk.ca>* parents: 44842 diff changeset	497
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	498 Finally, the least frequently used option is to specify that a function can be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499 called with an arbitrary number of arguments. These arguments will be wrapped
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	500 up in a tuple (see :ref:`tut-tuples`). Before the variable number of arguments,
feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	501 zero or more normal arguments may occur. ::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	502
47359 09065b010c95 fix spelling Benjamin Peterson <benjamin@python.org> parents: 47355 diff changeset	503 def write_multiple_items(file, separator, *args):
09065b010c95 fix spelling Benjamin Peterson <benjamin@python.org> parents: 47355 diff changeset	504 file.write(separator.join(args))
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	505
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	506
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	507 .. _tut-unpacking-arguments:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	508
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	509 Unpacking Argument Lists
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	510 ------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	511
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	512 The reverse situation occurs when the arguments are already in a list or tuple
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	513 but need to be unpacked for a function call requiring separate positional
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	514 arguments. For instance, the built-in :func:`range` function expects separate
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	515 start and stop arguments. If they are not available separately, write the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	516 function call with the ``*``\ -operator to unpack the arguments out of a list
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	517 or tuple::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	518
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	519 >>> range(3, 6) # normal call with separate arguments
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	520 [3, 4, 5]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	521 >>> args = [3, 6]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	522 >>> range(*args) # call with arguments unpacked from a list
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	523 [3, 4, 5]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	524
46457 3e095ab75fc8 Add ,,@ to index, as suggested by Andrew M. Kuchling <amk@amk.ca>* parents: 44842 diff changeset	525 .. index::
3e095ab75fc8 Add ,,@ to index, as suggested by Andrew M. Kuchling <amk@amk.ca>* parents: 44842 diff changeset	526 statement: **
3e095ab75fc8 Add ,,@ to index, as suggested by Andrew M. Kuchling <amk@amk.ca>* parents: 44842 diff changeset	527
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	528 In the same fashion, dictionaries can deliver keyword arguments with the ``**``\
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	529 -operator::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	530
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	531 >>> def parrot(voltage, state='a stiff', action='voom'):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	532 ... print "-- This parrot wouldn't", action,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	533 ... print "if you put", voltage, "volts through it.",
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	534 ... print "E's", state, "!"
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	535 ...
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	536 >>> d = {"voltage": "four million", "state": "bleedin' demised", "action": "VOOM"}
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	537 >>> parrot(**d)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	538 -- This parrot wouldn't VOOM if you put four million volts through it. E's bleedin' demised !
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	539
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	540
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	541 .. _tut-lambda:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	542
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543 Lambda Forms
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	544 ------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	545
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	546 By popular demand, a few features commonly found in functional programming
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	547 languages like Lisp have been added to Python. With the :keyword:`lambda`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	548 keyword, small anonymous functions can be created. Here's a function that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	549 returns the sum of its two arguments: ``lambda a, b: a+b``. Lambda forms can be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	550 used wherever function objects are required. They are syntactically restricted
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	551 to a single expression. Semantically, they are just syntactic sugar for a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	552 normal function definition. Like nested function definitions, lambda forms can
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	553 reference variables from the containing scope::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	554
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	555 >>> def make_incrementor(n):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	556 ... return lambda x: x + n
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	557 ...
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	558 >>> f = make_incrementor(42)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	559 >>> f(0)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	560 42
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	561 >>> f(1)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	562 43
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	563
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	564
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	565 .. _tut-docstrings:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	566
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	567 Documentation Strings
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	568 ---------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	569
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	570 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	571 single: docstrings
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	572 single: documentation strings
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	573 single: strings, documentation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	574
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	575 There are emerging conventions about the content and formatting of documentation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	576 strings.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	577
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	578 The first line should always be a short, concise summary of the object's
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	579 purpose. For brevity, it should not explicitly state the object's name or type,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	580 since these are available by other means (except if the name happens to be a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	581 verb describing a function's operation). This line should begin with a capital
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	582 letter and end with a period.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	583
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	584 If there are more lines in the documentation string, the second line should be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	585 blank, visually separating the summary from the rest of the description. The
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	586 following lines should be one or more paragraphs describing the object's calling
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	587 conventions, its side effects, etc.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	588
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	589 The Python parser does not strip indentation from multi-line string literals in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	590 Python, so tools that process documentation have to strip indentation if
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	591 desired. This is done using the following convention. The first non-blank line
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	592 after the first line of the string determines the amount of indentation for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	593 the entire documentation string. (We can't use the first line since it is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	594 generally adjacent to the string's opening quotes so its indentation is not
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	595 apparent in the string literal.) Whitespace "equivalent" to this indentation is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	596 then stripped from the start of all lines of the string. Lines that are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	597 indented less should not occur, but if they occur all their leading whitespace
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	598 should be stripped. Equivalence of whitespace should be tested after expansion
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	599 of tabs (to 8 spaces, normally).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	600
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	601 Here is an example of a multi-line docstring::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	602
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	603 >>> def my_function():
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	604 ... """Do nothing, but document it.
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50305 diff changeset	605 ...
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	606 ... No, really, it doesn't do anything.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	607 ... """
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	608 ... pass
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50305 diff changeset	609 ...
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	610 >>> print my_function.__doc__
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	611 Do nothing, but document it.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	612
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	613 No, really, it doesn't do anything.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	614
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	615
44545 13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	616 .. _tut-codingstyle:
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	617
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	618 Intermezzo: Coding Style
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	619 ========================
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	620
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	621 .. sectionauthor:: Georg Brandl <georg@python.org>
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	622 .. index:: pair: coding; style
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	623
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	624 Now that you are about to write longer, more complex pieces of Python, it is a
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	625 good time to talk about coding style. Most languages can be written (or more
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	626 concise, formatted) in different styles; some are more readable than others.
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	627 Making it easy for others to read your code is always a good idea, and adopting
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	628 a nice coding style helps tremendously for that.
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	629
46458 19fd463ea728 Typo fix Andrew M. Kuchling <amk@amk.ca> parents: 46457 diff changeset	630 For Python, :pep:`8` has emerged as the style guide that most projects adhere to;
44545 13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	631 it promotes a very readable and eye-pleasing coding style. Every Python
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	632 developer should read it at some point; here are the most important points
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	633 extracted for you:
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	634
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	635 * Use 4-space indentation, and no tabs.
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	636
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	637 4 spaces are a good compromise between small indentation (allows greater
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	638 nesting depth) and large indentation (easier to read). Tabs introduce
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	639 confusion, and are best left out.
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	640
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	641 * Wrap lines so that they don't exceed 79 characters.
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	642
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	643 This helps users with small displays and makes it possible to have several
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	644 code files side-by-side on larger displays.
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	645
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	646 * Use blank lines to separate functions and classes, and larger blocks of
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	647 code inside functions.
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	648
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	649 * When possible, put comments on a line of their own.
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	650
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	651 * Use docstrings.
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	652
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	653 * Use spaces around operators and after commas, but not directly inside
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	654 bracketing constructs: ``a = f(1, 2) + g(3, 4)``.
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	655
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	656 * Name your classes and functions consistently; the convention is to use
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	657 ``CamelCase`` for classes and ``lower_case_with_underscores`` for functions
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	658 and methods. Always use ``self`` as the name for the first method argument
feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	659 (see :ref:`tut-firstclasses` for more on classes and methods).
44545 13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	660
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	661 * Don't use fancy encodings if your code is meant to be used in international
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	662 environments. Plain ASCII works best in any case.
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	663
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	664
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	665 .. rubric:: Footnotes
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	666
44545 13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	667 .. [#] Actually, call by object reference would be a better description,
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	668 since if a mutable object is passed, the caller will see any changes the
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	669 callee makes to it (items inserted into a list).
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	670

Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/controlflow.rst @ 79675:c0a2294de787 2.7