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

annotate Doc/tutorial/controlflow.rst @ 58925:eecf1bef052d 2.6

Merged revisions 78207 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r78207 | ezio.melotti | 2010-02-17 01:26:09 +0200 (Wed, 17 Feb 2010) | 1 line #7930: fix stripid ........

author	Ezio Melotti <ezio.melotti@gmail.com>
date	Tue, 16 Feb 2010 23:29:44 +0000
parents	2639ea7b92ed
children	b36cb4602e21

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 The :keyword:`continue` statement, also borrowed from C, continues with the next
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133 iteration of the loop.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135 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	136 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	137 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	138 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	139 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	140
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141 >>> for n in range(2, 10):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142 ... for x in range(2, n):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143 ... if n % x == 0:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144 ... print n, 'equals', x, '*', n/x
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145 ... break
48129 0aff3bf0a342 revert last revision; code was right Benjamin Peterson <benjamin@python.org> parents: 48128 diff changeset	146 ... else:
0aff3bf0a342 revert last revision; code was right Benjamin Peterson <benjamin@python.org> parents: 48128 diff changeset	147 ... # loop fell through without finding a factor
0aff3bf0a342 revert last revision; code was right Benjamin Peterson <benjamin@python.org> parents: 48128 diff changeset	148 ... 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	149 ...
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 2 is a prime number
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151 3 is a prime number
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 4 equals 2 * 2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153 5 is a prime number
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154 6 equals 2 * 3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155 7 is a prime number
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156 8 equals 2 * 4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	157 9 equals 3 * 3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160 .. _tut-pass:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162 :keyword:`pass` Statements
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163 ==========================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165 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	166 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	167
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168 >>> while True:
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	169 ... 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	170 ...
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171
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	172 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	173
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	174 >>> 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	175 ... 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	176 ...
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	177
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	178 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	179 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	180 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	181
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	182 >>> 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	183 ... 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	184 ...
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	185
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186 .. _tut-functions:
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 Defining Functions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	189 ==================
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 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	192 boundary::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194 >>> 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	195 ... """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	196 ... a, b = 0, 1
57408 2639ea7b92ed Merged revisions 76460 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56812 diff changeset	197 ... while a < n:
2639ea7b92ed Merged revisions 76460 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56812 diff changeset	198 ... print a,
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199 ... 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	200 ...
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201 >>> # 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	202 ... fib(2000)
57408 2639ea7b92ed Merged revisions 76460 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56812 diff changeset	203 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	204
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206 single: documentation strings
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207 single: docstrings
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208 single: strings, documentation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210 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	211 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	212 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	213 must be indented.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	215 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	216 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	217 (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	218 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	219 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	220 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	221
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222 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	223 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	224 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	225 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	226 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	227 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	228 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	229 may be referenced.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231 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	232 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	233 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	234 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	235 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	236
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237 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	238 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	239 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	240 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	241 mechanism::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243 >>> fib
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244 <function fib at 10042ed0>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245 >>> f = fib
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246 >>> f(100)
57408 2639ea7b92ed Merged revisions 76460 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56812 diff changeset	247 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	248
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	249 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	250 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	251 :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	252 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	253 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	254 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	255
43715 e2fe58604cb1 Make example about hiding None return values at the prompt clearer. Georg Brandl <georg@python.org> parents: 42603 diff changeset	256 >>> fib(0)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	257 >>> print fib(0)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258 None
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 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	261 Fibonacci series, instead of printing it::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263 >>> 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	264 ... """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	265 ... result = []
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266 ... a, b = 0, 1
57408 2639ea7b92ed Merged revisions 76460 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56812 diff changeset	267 ... while a < n:
2639ea7b92ed Merged revisions 76460 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56812 diff changeset	268 ... result.append(a) # see below
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269 ... a, b = b, a+b
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	270 ... 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	271 ...
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	272 >>> f100 = fib2(100) # call it
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273 >>> f100 # write the result
57408 2639ea7b92ed Merged revisions 76460 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56812 diff changeset	274 [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	275
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276 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	277
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278 * 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	279 :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	280 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	281
57408 2639ea7b92ed Merged revisions 76460 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56812 diff changeset	282 * 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	283 ``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	284 ``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	285 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	286 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	287 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	288 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	289 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	290 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	291 ``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	292
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	293
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294 .. _tut-defining:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	295
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	296 More on Defining Functions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	297 ==========================
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 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	300 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	301
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	302
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	303 .. _tut-defaultargs:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	304
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	305 Default Argument Values
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	306 -----------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	307
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	308 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	309 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	310 defined to allow. For example::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312 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	313 while True:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314 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	315 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	316 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	317 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	318 return False
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319 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	320 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	321 raise IOError('refusenik user')
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322 print complaint
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323
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	324 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	325
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	326 * 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	327 ``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	328 * 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	329 ``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	330 * 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	331 ``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	332
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333 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	334 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	335
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336 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	337 defining scope, so that ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	339 i = 5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	341 def f(arg=i):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342 print arg
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	343
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344 i = 6
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345 f()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347 will print ``5``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	349 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	350 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	351 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	352 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	353
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	354 def f(a, L=[]):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	355 L.append(a)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356 return L
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358 print f(1)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359 print f(2)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360 print f(3)
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 This will print ::
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 [1]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	365 [1, 2]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	366 [1, 2, 3]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	367
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	368 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	369 write the function like this instead::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	370
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	371 def f(a, L=None):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	372 if L is None:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	373 L = []
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	374 L.append(a)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	375 return L
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	378 .. _tut-keywordargs:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	379
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	380 Keyword Arguments
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	381 -----------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	382
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	383 Functions can also be called using keyword arguments of the form ``keyword =
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	384 value``. For instance, the following function::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	385
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	386 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	387 print "-- This parrot wouldn't", action,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	388 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	389 print "-- Lovely plumage, the", type
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	390 print "-- It's", state, "!"
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	392 could be called in any of the following ways::
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 parrot(1000)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	395 parrot(action = 'VOOOOOM', voltage = 1000000)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396 parrot('a thousand', state = 'pushing up the daisies')
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	397 parrot('a million', 'bereft of life', 'jump')
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	398
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	399 but the following calls would all be invalid::
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 parrot() # required argument missing
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	402 parrot(voltage=5.0, 'dead') # non-keyword argument following keyword
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	403 parrot(110, voltage=220) # duplicate value for argument
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	404 parrot(actor='John Cleese') # unknown keyword
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	406 In general, an argument list must have any positional arguments followed by any
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	407 keyword arguments, where the keywords must be chosen from the formal parameter
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408 names. It's not important whether a formal parameter has a default value or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409 not. No argument may receive a value more than once --- formal parameter names
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	410 corresponding to positional arguments cannot be used as keywords in the same
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411 calls. Here's an example that fails due to this restriction::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	412
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	413 >>> def function(a):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414 ... 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	415 ...
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416 >>> function(0, a=0)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417 Traceback (most recent call last):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	418 File "<stdin>", line 1, in ?
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419 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	420
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	421 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	422 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	423 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	424 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	425 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	426 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	427 function like this::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	429 def cheeseshop(kind, arguments, *keywords):
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	430 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	431 print "-- I'm sorry, we're all out of", kind
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	432 for arg in arguments: print arg
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	433 print "-" * 40
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	434 keys = keywords.keys()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	435 keys.sort()
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	436 for kw in keys: print kw, ":", keywords[kw]
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	437
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	438 It could be called like this::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	439
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	440 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	441 "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	442 shopkeeper='Michael Palin',
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	443 client="John Cleese",
feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48129 diff changeset	444 sketch="Cheese Shop Sketch")
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	445
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	446 and of course it would print::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	447
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	448 -- Do you have any Limburger ?
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	449 -- 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	450 It's very runny, sir.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	451 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	452 ----------------------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	453 client : John Cleese
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	454 shopkeeper : Michael Palin
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	455 sketch : Cheese Shop Sketch
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 Note that the :meth:`sort` method of the list of keyword argument names is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	458 called before printing the contents of the ``keywords`` dictionary; if this is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	459 not done, the order in which the arguments are printed is undefined.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	460
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	461
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	462 .. _tut-arbitraryargs:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	463
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	464 Arbitrary Argument Lists
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	465 ------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	466
46457 3e095ab75fc8 Add ,,@ to index, as suggested by Andrew M. Kuchling <amk@amk.ca>* parents: 44842 diff changeset	467 .. 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	468 statement: *
46457 3e095ab75fc8 Add ,,@ to index, as suggested by Andrew M. Kuchling <amk@amk.ca>* parents: 44842 diff changeset	469
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	470 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	471 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	472 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	473 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	474
47359 09065b010c95 fix spelling Benjamin Peterson <benjamin@python.org> parents: 47355 diff changeset	475 def write_multiple_items(file, separator, *args):
09065b010c95 fix spelling Benjamin Peterson <benjamin@python.org> parents: 47355 diff changeset	476 file.write(separator.join(args))
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	477
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	478
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	479 .. _tut-unpacking-arguments:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	480
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	481 Unpacking Argument Lists
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	482 ------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	483
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	484 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	485 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	486 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	487 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	488 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	489 or tuple::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	490
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	491 >>> 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	492 [3, 4, 5]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	493 >>> args = [3, 6]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	494 >>> 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	495 [3, 4, 5]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	496
46457 3e095ab75fc8 Add ,,@ to index, as suggested by Andrew M. Kuchling <amk@amk.ca>* parents: 44842 diff changeset	497 .. index::
3e095ab75fc8 Add ,,@ to index, as suggested by Andrew M. Kuchling <amk@amk.ca>* parents: 44842 diff changeset	498 statement: **
3e095ab75fc8 Add ,,@ to index, as suggested by Andrew M. Kuchling <amk@amk.ca>* parents: 44842 diff changeset	499
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	500 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	501 -operator::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	502
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	503 >>> 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	504 ... print "-- This parrot wouldn't", action,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	505 ... 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	506 ... print "E's", state, "!"
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	507 ...
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	508 >>> 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	509 >>> parrot(**d)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	510 -- 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	511
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	512
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	513 .. _tut-lambda:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	514
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	515 Lambda Forms
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	516 ------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	517
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	518 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	519 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	520 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	521 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	522 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	523 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	524 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	525 reference variables from the containing scope::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	526
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	527 >>> def make_incrementor(n):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	528 ... return lambda x: x + n
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	529 ...
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	530 >>> f = make_incrementor(42)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	531 >>> f(0)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	532 42
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	533 >>> f(1)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	534 43
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	537 .. _tut-docstrings:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	538
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	539 Documentation Strings
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	542 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543 single: docstrings
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	544 single: documentation strings
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	545 single: strings, documentation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	546
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	547 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	548 strings.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	549
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	550 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	551 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	552 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	553 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	554 letter and end with a period.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	555
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	556 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	557 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	558 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	559 conventions, its side effects, etc.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	560
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	561 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	562 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	563 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	564 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	565 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	566 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	567 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	568 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	569 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	570 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	571 of tabs (to 8 spaces, normally).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	572
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	573 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	574
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	575 >>> def my_function():
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	576 ... """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	577 ...
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	578 ... 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	579 ... """
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	580 ... 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	581 ...
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	582 >>> print my_function.__doc__
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	583 Do nothing, but document it.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	584
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	585 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	586
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	587
44545 13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	588 .. _tut-codingstyle:
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	589
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	590 Intermezzo: Coding Style
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	591 ========================
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	592
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	593 .. sectionauthor:: Georg Brandl <georg@python.org>
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	594 .. index:: pair: coding; style
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	595
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	596 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	597 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	598 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	599 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	600 a nice coding style helps tremendously for that.
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	601
46458 19fd463ea728 Typo fix Andrew M. Kuchling <amk@amk.ca> parents: 46457 diff changeset	602 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	603 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	604 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	605 extracted for you:
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	606
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	607 * Use 4-space indentation, and no tabs.
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	608
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	609 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	610 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	611 confusion, and are best left out.
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	612
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	613 * 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	614
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	615 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	616 code files side-by-side on larger displays.
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 * 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	619 code inside functions.
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 * 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	622
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	623 * Use docstrings.
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	624
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	625 * 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	626 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	627
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	628 * 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	629 ``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	630 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	631 (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	632
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	633 * 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	634 environments. Plain ASCII works best in any case.
13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	635
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	636
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	637 .. rubric:: Footnotes
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	638
44545 13b7ca04bd70 Add tutorial section about coding style. Georg Brandl <georg@python.org> parents: 44383 diff changeset	639 .. [#] 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	640 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	641 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	642

Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/controlflow.rst @ 58925:eecf1bef052d 2.6