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

annotate Doc/tutorial/controlflow.rst @ 78069:a8aa77458e12 3.2

Add c_size_t and c_ssize_t to the ctypes summary table.

author	Antoine Pitrou <solipsis@pitrou.net>
date	Thu, 12 Jul 2012 20:31:50 +0200
parents	6e4ec47fba6a
children	e855e6c26dfb

rev	line source
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1 .. _tut-morecontrol:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3 ***********************
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 More Control Flow Tools
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 ***********************
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6
9e1529bf0442 Move the 3k 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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 control flow statements known from other languages, with some twists.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 .. _tut-if:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13 :keyword:`if` Statements
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14 ========================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15
9e1529bf0442 Move the 3k 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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17 example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18
42642 9fc21c8babb9 No need to define raw_input(), input() does the same. Georg Brandl <georg@python.org> parents: 42604 diff changeset	19 >>> x = int(input("Please enter an integer: "))
49180 c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	20 Please enter an integer: 42
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 >>> if x < 0:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 ... x = 0
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	23 ... print('Negative changed to zero')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 ... elif x == 0:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	25 ... print('Zero')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26 ... elif x == 1:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	27 ... print('Single')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 ... else:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	29 ... print('More')
49180 c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	30 ...
c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	31 More
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32
9e1529bf0442 Move the 3k 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
9e1529bf0442 Move the 3k 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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35 to avoid excessive indentation. An :keyword:`if` ... :keyword:`elif` ...
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 43737 diff changeset	36 :keyword:`elif` ... sequence is a substitute for the ``switch`` or
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 43737 diff changeset	37 ``case`` statements found in other languages.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40 .. _tut-for:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 :keyword:`for` Statements
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43 =========================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46 statement: for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48 The :keyword:`for` statement in Python differs a bit from what you may be used
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49 to in C or Pascal. Rather than always iterating over an arithmetic progression
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50 of numbers (like in Pascal), or giving the user the ability to define both the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51 iteration step and halting condition (as C), Python's :keyword:`for` statement
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52 iterates over the items of any sequence (a list or a string), in the order that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53 they appear in the sequence. For example (no pun intended):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 43737 diff changeset	55 .. One suggestion was to give a real C example here, but that may only serve to
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 43737 diff changeset	56 confuse non-C programmers.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58 ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60 >>> # Measure some strings:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61 ... a = ['cat', 'window', 'defenestrate']
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62 >>> for x in a:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	63 ... print(x, len(x))
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	64 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65 cat 3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 window 6
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67 defenestrate 12
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69 It is not safe to modify the sequence being iterated over in the loop (this can
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 only happen for mutable sequence types, such as lists). If you need to modify
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 the list you are iterating over (for example, to duplicate selected items) you
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72 must iterate over a copy. The slice notation makes this particularly
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73 convenient::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75 >>> for x in a[:]: # make a slice copy of the entire list
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76 ... if len(x) > 6: a.insert(0, x)
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	77 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78 >>> a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 ['defenestrate', 'cat', 'window', 'defenestrate']
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82 .. _tut-range:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84 The :func:`range` Function
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85 ==========================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87 If you do need to iterate over a sequence of numbers, the built-in function
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	88 :func:`range` comes in handy. It generates arithmetic progressions::
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	89
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	90 >>> for i in range(5):
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	91 ... print(i)
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	92 ...
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	93 0
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	94 1
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	95 2
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	96 3
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	97 4
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	98
62537 1a3d8ec0c5fa Wording fix. Georg Brandl <georg@python.org> parents: 57410 diff changeset	99 The given end point is never part of the generated sequence; ``range(10)`` generates
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	100 10 values, the legal indices for items of a sequence of length 10. It
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101 is possible to let the range start at another number, or to specify a different
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 increment (even negative; sometimes this is called the 'step')::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	104 range(5, 10)
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	105 5 through 9
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	106
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	107 range(0, 10, 3)
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	108 0, 3, 6, 9
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	109
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	110 range(-10, -100, -30)
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	111 -10, -40, -70
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112
50078 63ee6a0f7358 Manual merge of r67636 from py3k branch: Georg Brandl <georg@python.org> parents: 49679 diff changeset	113 To iterate over the indices of a sequence, you can combine :func:`range` and
63ee6a0f7358 Manual merge of r67636 from py3k branch: Georg Brandl <georg@python.org> parents: 49679 diff changeset	114 :func:`len` as follows::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116 >>> a = ['Mary', 'had', 'a', 'little', 'lamb']
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117 >>> for i in range(len(a)):
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	118 ... print(i, a[i])
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	119 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120 0 Mary
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121 1 had
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122 2 a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123 3 little
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124 4 lamb
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125
50078 63ee6a0f7358 Manual merge of r67636 from py3k branch: Georg Brandl <georg@python.org> parents: 49679 diff changeset	126 In most such cases, however, it is convenient to use the :func:`enumerate`
63ee6a0f7358 Manual merge of r67636 from py3k branch: Georg Brandl <georg@python.org> parents: 49679 diff changeset	127 function, see :ref:`tut-loopidioms`.
63ee6a0f7358 Manual merge of r67636 from py3k branch: Georg Brandl <georg@python.org> parents: 49679 diff changeset	128
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	129 A strange thing happens if you just print a range::
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	130
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	131 >>> print(range(10))
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	132 range(0, 10)
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	133
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	134 In many ways the object returned by :func:`range` behaves as if it is a list,
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	135 but in fact it isn't. It is an object which returns the successive items of
93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	136 the desired sequence when you iterate over it, but it doesn't really make
93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	137 the list, thus saving space.
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	138
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	139 We say such an object is iterable, that is, suitable as a target for
93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	140 functions and constructs that expect something from which they can
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	141 obtain successive items until the supply is exhausted. We have seen that
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	142 the :keyword:`for` statement is such an iterator. The function :func:`list`
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	143 is another; it creates lists from iterables::
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	144
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	145
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	146 >>> list(range(5))
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	147 [0, 1, 2, 3, 4]
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	148
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	149 Later we will see more functions that return iterables and take iterables as argument.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150
50078 63ee6a0f7358 Manual merge of r67636 from py3k branch: Georg Brandl <georg@python.org> parents: 49679 diff changeset	151
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 .. _tut-break:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154 :keyword:`break` and :keyword:`continue` Statements, and :keyword:`else` Clauses on Loops
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155 =========================================================================================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	157 The :keyword:`break` statement, like in C, breaks out of the smallest enclosing
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158 :keyword:`for` or :keyword:`while` loop.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160 The :keyword:`continue` statement, also borrowed from C, continues with the next
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161 iteration of the loop.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163 Loop statements may have an ``else`` clause; it is executed when the loop
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164 terminates through exhaustion of the list (with :keyword:`for`) or when the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165 condition becomes false (with :keyword:`while`), but not when the loop is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	166 terminated by a :keyword:`break` statement. This is exemplified by the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167 following loop, which searches for prime numbers::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169 >>> for n in range(2, 10):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170 ... for x in range(2, n):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171 ... if n % x == 0:
46618 87d3137c31d4 Don't output floats in prime example. Georg Brandl <georg@python.org> parents: 46478 diff changeset	172 ... print(n, 'equals', x, '*', n//x)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	173 ... break
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	174 ... else:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	175 ... # loop fell through without finding a factor
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	176 ... print(n, 'is a prime number')
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	177 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	178 2 is a prime number
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179 3 is a prime number
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	180 4 equals 2 * 2
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	181 5 is a prime number
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182 6 equals 2 * 3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	183 7 is a prime number
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184 8 equals 2 * 4
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185 9 equals 3 * 3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186
71774 0e5433cfe404 Confirm that the prime example is actually correct. We get so many complaints about a "buggy example" on docs@python, let us hope this cuts them in half at least. Georg Brandl <georg@python.org> parents: 65361 diff changeset	187 (Yes, this is the correct code. Look closely: the ``else`` clause belongs to
0e5433cfe404 Confirm that the prime example is actually correct. We get so many complaints about a "buggy example" on docs@python, let us hope this cuts them in half at least. Georg Brandl <georg@python.org> parents: 65361 diff changeset	188 the :keyword:`for` loop, not the :keyword:`if` statement.)
0e5433cfe404 Confirm that the prime example is actually correct. We get so many complaints about a "buggy example" on docs@python, let us hope this cuts them in half at least. Georg Brandl <georg@python.org> parents: 65361 diff changeset	189
77369 6e4ec47fba6a Nudge readers towards a more accurate mental model for loop else clauses Nick Coghlan <ncoghlan@gmail.com> parents: 73955 diff changeset	190 When used with a loop, the ``else`` clause has more in common with the
6e4ec47fba6a Nudge readers towards a more accurate mental model for loop else clauses Nick Coghlan <ncoghlan@gmail.com> parents: 73955 diff changeset	191 ``else`` clause of a :keyword:`try` statement than it does that of
6e4ec47fba6a Nudge readers towards a more accurate mental model for loop else clauses Nick Coghlan <ncoghlan@gmail.com> parents: 73955 diff changeset	192 :keyword:`if` statements: a :keyword:`try` statement's ``else`` clause runs
6e4ec47fba6a Nudge readers towards a more accurate mental model for loop else clauses Nick Coghlan <ncoghlan@gmail.com> parents: 73955 diff changeset	193 when no exception occurs, and a loop's ``else`` clause runs when no ``break``
6e4ec47fba6a Nudge readers towards a more accurate mental model for loop else clauses Nick Coghlan <ncoghlan@gmail.com> parents: 73955 diff changeset	194 occurs. For more on the :keyword:`try` statement and exceptions, see
6e4ec47fba6a Nudge readers towards a more accurate mental model for loop else clauses Nick Coghlan <ncoghlan@gmail.com> parents: 73955 diff changeset	195 :ref:`tut-handling`.
6e4ec47fba6a Nudge readers towards a more accurate mental model for loop else clauses Nick Coghlan <ncoghlan@gmail.com> parents: 73955 diff changeset	196
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198 .. _tut-pass:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200 :keyword:`pass` Statements
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201 ==========================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203 The :keyword:`pass` statement does nothing. It can be used when a statement is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204 required syntactically but the program requires no action. For example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206 >>> while True:
49180 c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	207 ... pass # Busy-wait for keyboard interrupt (Ctrl+C)
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	208 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209
50364 3d447b7b1363 Merged revisions 67948-67950 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50078 diff changeset	210 This is commonly used for creating minimal classes::
49679 1f7f41f20ac5 Merged revisions 67117-67119,67123-67124,67143 via svnmerge from Georg Brandl <georg@python.org> parents: 49180 diff changeset	211
50364 3d447b7b1363 Merged revisions 67948-67950 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50078 diff changeset	212 >>> class MyEmptyClass:
49679 1f7f41f20ac5 Merged revisions 67117-67119,67123-67124,67143 via svnmerge from Georg Brandl <georg@python.org> parents: 49180 diff changeset	213 ... pass
50364 3d447b7b1363 Merged revisions 67948-67950 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50078 diff changeset	214 ...
49679 1f7f41f20ac5 Merged revisions 67117-67119,67123-67124,67143 via svnmerge from Georg Brandl <georg@python.org> parents: 49180 diff changeset	215
1f7f41f20ac5 Merged revisions 67117-67119,67123-67124,67143 via svnmerge from Georg Brandl <georg@python.org> parents: 49180 diff changeset	216 Another place :keyword:`pass` can be used is as a place-holder for a function or
50364 3d447b7b1363 Merged revisions 67948-67950 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50078 diff changeset	217 conditional body when you are working on new code, allowing you to keep thinking
3d447b7b1363 Merged revisions 67948-67950 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50078 diff changeset	218 at a more abstract level. The :keyword:`pass` is silently ignored::
49679 1f7f41f20ac5 Merged revisions 67117-67119,67123-67124,67143 via svnmerge from Georg Brandl <georg@python.org> parents: 49180 diff changeset	219
1f7f41f20ac5 Merged revisions 67117-67119,67123-67124,67143 via svnmerge from Georg Brandl <georg@python.org> parents: 49180 diff changeset	220 >>> def initlog(*args):
50364 3d447b7b1363 Merged revisions 67948-67950 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50078 diff changeset	221 ... pass # Remember to implement this!
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	222 ...
49679 1f7f41f20ac5 Merged revisions 67117-67119,67123-67124,67143 via svnmerge from Georg Brandl <georg@python.org> parents: 49180 diff changeset	223
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224 .. _tut-functions:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226 Defining Functions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227 ==================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229 We can create a function that writes the Fibonacci series to an arbitrary
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230 boundary::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	232 >>> def fib(n): # write Fibonacci series up to n
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233 ... """Print a Fibonacci series up to n."""
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234 ... a, b = 0, 1
57410 c2ecca5ff659 Merged revisions 76462 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 54630 diff changeset	235 ... while a < n:
c2ecca5ff659 Merged revisions 76462 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 54630 diff changeset	236 ... print(a, end=' ')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237 ... a, b = b, a+b
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	238 ... print()
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	239 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240 >>> # Now call the function we just defined:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241 ... fib(2000)
57410 c2ecca5ff659 Merged revisions 76462 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 54630 diff changeset	242 0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245 single: documentation strings
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246 single: docstrings
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247 single: strings, documentation
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249 The keyword :keyword:`def` introduces a function definition. It must be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250 followed by the function name and the parenthesized list of formal parameters.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	251 The statements that form the body of the function start at the next line, and
49180 c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	252 must be indented.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253
49180 c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	254 The first statement of the function body can optionally be a string literal;
c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	255 this string literal is the function's documentation string, or :dfn:`docstring`.
c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	256 (More about docstrings can be found in the section :ref:`tut-docstrings`.)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	257 There are tools which use docstrings to automatically produce online or printed
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258 documentation, or to let the user interactively browse through code; it's good
49180 c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	259 practice to include docstrings in code that you write, so make a habit of it.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261 The execution of a function introduces a new symbol table used for the local
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 variables of the function. More precisely, all variable assignments in a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263 function store the value in the local symbol table; whereas variable references
44859 feba5d5cac22 Merged revisions 60151-60159,60161-60168,60170,60172-60173,60175 via svnmerge from Georg Brandl <georg@python.org> parents: 44816 diff changeset	264 first look in the local symbol table, then in the local symbol tables of
feba5d5cac22 Merged revisions 60151-60159,60161-60168,60170,60172-60173,60175 via svnmerge from Georg Brandl <georg@python.org> parents: 44816 diff changeset	265 enclosing functions, then in the global symbol table, and finally in the table
feba5d5cac22 Merged revisions 60151-60159,60161-60168,60170,60172-60173,60175 via svnmerge from Georg Brandl <georg@python.org> parents: 44816 diff changeset	266 of built-in names. Thus, global variables cannot be directly assigned a value
feba5d5cac22 Merged revisions 60151-60159,60161-60168,60170,60172-60173,60175 via svnmerge from Georg Brandl <georg@python.org> parents: 44816 diff changeset	267 within a function (unless named in a :keyword:`global` statement), although they
feba5d5cac22 Merged revisions 60151-60159,60161-60168,60170,60172-60173,60175 via svnmerge from Georg Brandl <georg@python.org> parents: 44816 diff changeset	268 may be referenced.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	270 The actual parameters (arguments) to a function call are introduced in the local
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	271 symbol table of the called function when it is called; thus, arguments are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	272 passed using call by value (where the value is always an object reference,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273 not the value of the object). [#]_ When a function calls another function, a new
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	274 local symbol table is created for that call.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	275
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276 A function definition introduces the function name in the current symbol table.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277 The value of the function name has a type that is recognized by the interpreter
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278 as a user-defined function. This value can be assigned to another name which
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279 can then also be used as a function. This serves as a general renaming
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280 mechanism::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	282 >>> fib
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	283 <function fib at 10042ed0>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284 >>> f = fib
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	285 >>> f(100)
57410 c2ecca5ff659 Merged revisions 76462 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 54630 diff changeset	286 0 1 1 2 3 5 8 13 21 34 55 89
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287
49180 c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	288 Coming from other languages, you might object that ``fib`` is not a function but
c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	289 a procedure since it doesn't return a value. In fact, even functions without a
c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	290 :keyword:`return` statement do return a value, albeit a rather boring one. This
c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	291 value is called ``None`` (it's a built-in name). Writing the value ``None`` is
c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	292 normally suppressed by the interpreter if it would be the only value written.
c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	293 You can see it if you really want to using :func:`print`::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294
43737 3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43309 diff changeset	295 >>> fib(0)
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	296 >>> print(fib(0))
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	297 None
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	298
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	299 It is simple to write a function that returns a list of the numbers of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	300 Fibonacci series, instead of printing it::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	301
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	302 >>> def fib2(n): # return Fibonacci series up to n
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	303 ... """Return a list containing the Fibonacci series up to n."""
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	304 ... result = []
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	305 ... a, b = 0, 1
57410 c2ecca5ff659 Merged revisions 76462 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 54630 diff changeset	306 ... while a < n:
c2ecca5ff659 Merged revisions 76462 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 54630 diff changeset	307 ... result.append(a) # see below
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	308 ... a, b = b, a+b
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	309 ... return result
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	310 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311 >>> f100 = fib2(100) # call it
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312 >>> f100 # write the result
57410 c2ecca5ff659 Merged revisions 76462 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 54630 diff changeset	313 [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315 This example, as usual, demonstrates some new Python features:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317 * The :keyword:`return` statement returns with a value from a function.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318 :keyword:`return` without an expression argument returns ``None``. Falling off
49180 c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	319 the end of a function also returns ``None``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320
57410 c2ecca5ff659 Merged revisions 76462 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 54630 diff changeset	321 * The statement ``result.append(a)`` calls a method of the list object
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322 ``result``. A method is a function that 'belongs' to an object and is named
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323 ``obj.methodname``, where ``obj`` is some object (this may be an expression),
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324 and ``methodname`` is the name of a method that is defined by the object's type.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325 Different types define different methods. Methods of different types may have
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326 the same name without causing ambiguity. (It is possible to define your own
54626 7ad2f22f13e6 Merged revisions 73190,73213,73257-73258,73260,73275,73294 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	327 object types and methods, using classes, see :ref:`tut-classes`)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328 The method :meth:`append` shown in the example is defined for list objects; it
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329 adds a new element at the end of the list. In this example it is equivalent to
57410 c2ecca5ff659 Merged revisions 76462 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 54630 diff changeset	330 ``result = result + [a]``, but more efficient.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	332
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333 .. _tut-defining:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335 More on Defining Functions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336 ==========================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338 It is also possible to define functions with a variable number of arguments.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	339 There are three forms, which can be combined.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	341
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342 .. _tut-defaultargs:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	343
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344 Default Argument Values
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345 -----------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347 The most useful form is to specify a default value for one or more arguments.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348 This creates a function that can be called with fewer arguments than it is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	349 defined to allow. For example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	350
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	351 def ask_ok(prompt, retries=4, complaint='Yes or no, please!'):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	352 while True:
42642 9fc21c8babb9 No need to define raw_input(), input() does the same. Georg Brandl <georg@python.org> parents: 42604 diff changeset	353 ok = input(prompt)
54626 7ad2f22f13e6 Merged revisions 73190,73213,73257-73258,73260,73275,73294 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	354 if ok in ('y', 'ye', 'yes'):
7ad2f22f13e6 Merged revisions 73190,73213,73257-73258,73260,73275,73294 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	355 return True
7ad2f22f13e6 Merged revisions 73190,73213,73257-73258,73260,73275,73294 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	356 if ok in ('n', 'no', 'nop', 'nope'):
7ad2f22f13e6 Merged revisions 73190,73213,73257-73258,73260,73275,73294 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	357 return False
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358 retries = retries - 1
43309 09287f2055ab Fix more raise statments in the docs. Collin Winter <collinw@gmail.com> parents: 43201 diff changeset	359 if retries < 0:
09287f2055ab Fix more raise statments in the docs. Collin Winter <collinw@gmail.com> parents: 43201 diff changeset	360 raise IOError('refusenik user')
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	361 print(complaint)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362
54626 7ad2f22f13e6 Merged revisions 73190,73213,73257-73258,73260,73275,73294 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	363 This function can be called in several ways:
7ad2f22f13e6 Merged revisions 73190,73213,73257-73258,73260,73275,73294 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	364
7ad2f22f13e6 Merged revisions 73190,73213,73257-73258,73260,73275,73294 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	365 * giving only the mandatory argument:
7ad2f22f13e6 Merged revisions 73190,73213,73257-73258,73260,73275,73294 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	366 ``ask_ok('Do you really want to quit?')``
7ad2f22f13e6 Merged revisions 73190,73213,73257-73258,73260,73275,73294 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	367 * giving one of the optional arguments:
7ad2f22f13e6 Merged revisions 73190,73213,73257-73258,73260,73275,73294 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	368 ``ask_ok('OK to overwrite the file?', 2)``
7ad2f22f13e6 Merged revisions 73190,73213,73257-73258,73260,73275,73294 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	369 * or even giving all arguments:
7ad2f22f13e6 Merged revisions 73190,73213,73257-73258,73260,73275,73294 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	370 ``ask_ok('OK to overwrite the file?', 2, 'Come on, only yes or no!')``
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	371
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	372 This example also introduces the :keyword:`in` keyword. This tests whether or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	373 not a sequence contains a certain value.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	374
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	375 The default values are evaluated at the point of function definition in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	376 defining scope, so that ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	377
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	378 i = 5
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	379
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	380 def f(arg=i):
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	381 print(arg)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	382
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	383 i = 6
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	384 f()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	385
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	386 will print ``5``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	387
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	388 Important warning: The default value is evaluated only once. This makes a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	389 difference when the default is a mutable object such as a list, dictionary, or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	390 instances of most classes. For example, the following function accumulates the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391 arguments passed to it on subsequent calls::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	392
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	393 def f(a, L=[]):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	394 L.append(a)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	395 return L
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	397 print(f(1))
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	398 print(f(2))
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	399 print(f(3))
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	401 This will print ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	402
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	403 [1]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	404 [1, 2]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405 [1, 2, 3]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	406
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	407 If you don't want the default to be shared between subsequent calls, you can
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408 write the function like this instead::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	410 def f(a, L=None):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411 if L is None:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	412 L = []
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	413 L.append(a)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414 return L
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	415
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417 .. _tut-keywordargs:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	418
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419 Keyword Arguments
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	420 -----------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	421
73955 44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	422 Functions can also be called using :term:`keyword arguments <keyword argument>`
44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	423 of the form ``kwarg=value``. For instance, the following function::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	424
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	425 def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
43201 4902671dd678 Tutorial formatting patch by Robin Stocker. Georg Brandl <georg@python.org> parents: 43117 diff changeset	426 print("-- This parrot wouldn't", action, end=' ')
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	427 print("if you put", voltage, "volts through it.")
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	428 print("-- Lovely plumage, the", type)
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	429 print("-- It's", state, "!")
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	430
73955 44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	431 accepts one required argument (``voltage``) and three optional arguments
44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	432 (``state``, ``action``, and ``type``). This function can be called in any
44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	433 of the following ways::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	434
73955 44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	435 parrot(1000) # 1 positional argument
44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	436 parrot(voltage=1000) # 1 keyword argument
44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	437 parrot(voltage=1000000, action='VOOOOOM') # 2 keyword arguments
44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	438 parrot(action='VOOOOOM', voltage=1000000) # 2 keyword arguments
44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	439 parrot('a million', 'bereft of life', 'jump') # 3 positional arguments
44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	440 parrot('a thousand', state='pushing up the daisies') # 1 positional, 1 keyword
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	441
73955 44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	442 but all the following calls would be invalid::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	443
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	444 parrot() # required argument missing
73955 44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	445 parrot(voltage=5.0, 'dead') # non-keyword argument after a keyword argument
44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	446 parrot(110, voltage=220) # duplicate value for the same argument
44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	447 parrot(actor='John Cleese') # unknown keyword argument
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	448
73955 44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	449 In a function call, keyword arguments must follow positional arguments.
44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	450 All the keyword arguments passed must match one of the arguments
44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	451 accepted by the function (e.g. ``actor`` is not a valid argument for the
44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	452 ``parrot`` function), and their order is not important. This also includes
44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	453 non-optional arguments (e.g. ``parrot(voltage=1000)`` is valid too).
44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	454 No argument may receive a value more than once.
44ca4264dc88 #6570: clarify tutorial section about keyword arguments. Ezio Melotti <ezio.melotti@gmail.com> parents: 71774 diff changeset	455 Here's an example that fails due to this restriction::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	456
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	457 >>> def function(a):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	458 ... pass
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	459 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	460 >>> function(0, a=0)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	461 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	462 File "<stdin>", line 1, in ?
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	463 TypeError: function() got multiple values for keyword argument 'a'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	464
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	465 When a final formal parameter of the form ``**name`` is present, it receives a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	466 dictionary (see :ref:`typesmapping`) containing all keyword arguments except for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	467 those corresponding to a formal parameter. This may be combined with a formal
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	468 parameter of the form ``*name`` (described in the next subsection) which
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	469 receives a tuple containing the positional arguments beyond the formal parameter
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	470 list. (``name`` must occur before ``*name``.) For example, if we define a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	471 function like this::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	472
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	473 def cheeseshop(kind, arguments, *keywords):
49180 c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	474 print("-- Do you have any", kind, "?")
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	475 print("-- I'm sorry, we're all out of", kind)
65361 41868ca52744 Refrain from using inline suites. Georg Brandl <georg@python.org> parents: 62537 diff changeset	476 for arg in arguments:
41868ca52744 Refrain from using inline suites. Georg Brandl <georg@python.org> parents: 62537 diff changeset	477 print(arg)
49180 c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	478 print("-" * 40)
43117 7ea1367ba275 A few more fixes to the tutorial Neal Norwitz <nnorwitz@gmail.com> parents: 43115 diff changeset	479 keys = sorted(keywords.keys())
65361 41868ca52744 Refrain from using inline suites. Georg Brandl <georg@python.org> parents: 62537 diff changeset	480 for kw in keys:
41868ca52744 Refrain from using inline suites. Georg Brandl <georg@python.org> parents: 62537 diff changeset	481 print(kw, ":", keywords[kw])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	482
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	483 It could be called like this::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	484
49180 c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	485 cheeseshop("Limburger", "It's very runny, sir.",
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	486 "It's really very, VERY runny, sir.",
49180 c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	487 shopkeeper="Michael Palin",
c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	488 client="John Cleese",
c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	489 sketch="Cheese Shop Sketch")
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	490
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	491 and of course it would print::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	492
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	493 -- Do you have any Limburger ?
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	494 -- I'm sorry, we're all out of Limburger
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	495 It's very runny, sir.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	496 It's really very, VERY runny, sir.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	497 ----------------------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	498 client : John Cleese
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499 shopkeeper : Michael Palin
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	500 sketch : Cheese Shop Sketch
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	501
44538 1811eb03ba00 Clarify sentence in tutorial. Thanks to Marek Kubica. Georg Brandl <georg@python.org> parents: 44396 diff changeset	502 Note that the list of keyword argument names is created by sorting the result
1811eb03ba00 Clarify sentence in tutorial. Thanks to Marek Kubica. Georg Brandl <georg@python.org> parents: 44396 diff changeset	503 of the keywords dictionary's ``keys()`` method before printing its contents;
1811eb03ba00 Clarify sentence in tutorial. Thanks to Marek Kubica. Georg Brandl <georg@python.org> parents: 44396 diff changeset	504 if this is not done, the order in which the arguments are printed is undefined.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	505
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	506 .. _tut-arbitraryargs:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	507
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	508 Arbitrary Argument Lists
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	509 ------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	510
46478 beb7abcd6c01 Merged revisions 62350-62355,62358-62359,62364-62365,62370,62372-62375,62378-62379,62381 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44859 diff changeset	511 .. index::
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	512 statement: *
46478 beb7abcd6c01 Merged revisions 62350-62355,62358-62359,62364-62365,62370,62372-62375,62378-62379,62381 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44859 diff changeset	513
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	514 Finally, the least frequently used option is to specify that a function can be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	515 called with an arbitrary number of arguments. These arguments will be wrapped
49180 c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	516 up in a tuple (see :ref:`tut-tuples`). Before the variable number of arguments,
c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	517 zero or more normal arguments may occur. ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	518
47557 98827a21e352 Merged revisions 63724,63726,63732,63744,63754-63755,63757-63758,63760,63775,63781-63782,63787,63805-63808,63818-63819,63823-63824 via svnmerge from Georg Brandl <georg@python.org> parents: 47283 diff changeset	519 def write_multiple_items(file, separator, *args):
98827a21e352 Merged revisions 63724,63726,63732,63744,63754-63755,63757-63758,63760,63775,63781-63782,63787,63805-63808,63818-63819,63823-63824 via svnmerge from Georg Brandl <georg@python.org> parents: 47283 diff changeset	520 file.write(separator.join(args))
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	521
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	522
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	523 Normally, these ``variadic`` arguments will be last in the list of formal
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	524 parameters, because they scoop up all remaining input arguments that are
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	525 passed to the function. Any formal parameters which occur after the ``*args``
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	526 parameter are 'keyword-only' arguments, meaning that they can only be used as
43201 4902671dd678 Tutorial formatting patch by Robin Stocker. Georg Brandl <georg@python.org> parents: 43117 diff changeset	527 keywords rather than positional arguments. ::
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	528
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	529 >>> def concat(*args, sep="/"):
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	530 ... return sep.join(args)
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	531 ...
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	532 >>> concat("earth", "mars", "venus")
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	533 'earth/mars/venus'
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	534 >>> concat("earth", "mars", "venus", sep=".")
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	535 'earth.mars.venus'
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	536
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	537 .. _tut-unpacking-arguments:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	538
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	539 Unpacking Argument Lists
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	540 ------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	541
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	542 The reverse situation occurs when the arguments are already in a list or tuple
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543 but need to be unpacked for a function call requiring separate positional
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	544 arguments. For instance, the built-in :func:`range` function expects separate
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	545 start and stop arguments. If they are not available separately, write the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	546 function call with the ``*``\ -operator to unpack the arguments out of a list
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	547 or tuple::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	548
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	549 >>> list(range(3, 6)) # normal call with separate arguments
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	550 [3, 4, 5]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	551 >>> args = [3, 6]
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	552 >>> list(range(*args)) # call with arguments unpacked from a list
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	553 [3, 4, 5]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	554
46478 beb7abcd6c01 Merged revisions 62350-62355,62358-62359,62364-62365,62370,62372-62375,62378-62379,62381 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44859 diff changeset	555 .. index::
beb7abcd6c01 Merged revisions 62350-62355,62358-62359,62364-62365,62370,62372-62375,62378-62379,62381 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44859 diff changeset	556 statement: **
beb7abcd6c01 Merged revisions 62350-62355,62358-62359,62364-62365,62370,62372-62375,62378-62379,62381 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44859 diff changeset	557
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	558 In the same fashion, dictionaries can deliver keyword arguments with the ``**``\
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	559 -operator::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	560
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	561 >>> def parrot(voltage, state='a stiff', action='voom'):
43201 4902671dd678 Tutorial formatting patch by Robin Stocker. Georg Brandl <georg@python.org> parents: 43117 diff changeset	562 ... print("-- This parrot wouldn't", action, end=' ')
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	563 ... print("if you put", voltage, "volts through it.", end=' ')
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	564 ... print("E's", state, "!")
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	565 ...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	566 >>> d = {"voltage": "four million", "state": "bleedin' demised", "action": "VOOM"}
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	567 >>> parrot(**d)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	568 -- This parrot wouldn't VOOM if you put four million volts through it. E's bleedin' demised !
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	569
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	570
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	571 .. _tut-lambda:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	572
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	573 Lambda Forms
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	574 ------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	575
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	576 By popular demand, a few features commonly found in functional programming
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	577 languages like Lisp have been added to Python. With the :keyword:`lambda`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	578 keyword, small anonymous functions can be created. Here's a function that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	579 returns the sum of its two arguments: ``lambda a, b: a+b``. Lambda forms can be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	580 used wherever function objects are required. They are syntactically restricted
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	581 to a single expression. Semantically, they are just syntactic sugar for a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	582 normal function definition. Like nested function definitions, lambda forms can
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	583 reference variables from the containing scope::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	584
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	585 >>> def make_incrementor(n):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	586 ... return lambda x: x + n
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	587 ...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	588 >>> f = make_incrementor(42)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	589 >>> f(0)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	590 42
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	591 >>> f(1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	592 43
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	593
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	594
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	595 .. _tut-docstrings:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	596
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	597 Documentation Strings
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	598 ---------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	599
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	600 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	601 single: docstrings
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	602 single: documentation strings
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	603 single: strings, documentation
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	604
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	605 Here are some conventions about the content and formatting of documentation
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	606 strings.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	607
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	608 The first line should always be a short, concise summary of the object's
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	609 purpose. For brevity, it should not explicitly state the object's name or type,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	610 since these are available by other means (except if the name happens to be a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	611 verb describing a function's operation). This line should begin with a capital
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	612 letter and end with a period.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	613
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	614 If there are more lines in the documentation string, the second line should be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	615 blank, visually separating the summary from the rest of the description. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	616 following lines should be one or more paragraphs describing the object's calling
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	617 conventions, its side effects, etc.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	618
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	619 The Python parser does not strip indentation from multi-line string literals in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	620 Python, so tools that process documentation have to strip indentation if
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	621 desired. This is done using the following convention. The first non-blank line
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	622 after the first line of the string determines the amount of indentation for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	623 the entire documentation string. (We can't use the first line since it is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	624 generally adjacent to the string's opening quotes so its indentation is not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	625 apparent in the string literal.) Whitespace "equivalent" to this indentation is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	626 then stripped from the start of all lines of the string. Lines that are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	627 indented less should not occur, but if they occur all their leading whitespace
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	628 should be stripped. Equivalence of whitespace should be tested after expansion
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	629 of tabs (to 8 spaces, normally).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	630
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	631 Here is an example of a multi-line docstring::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	632
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	633 >>> def my_function():
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	634 ... """Do nothing, but document it.
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	635 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	636 ... No, really, it doesn't do anything.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	637 ... """
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	638 ... pass
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50364 diff changeset	639 ...
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	640 >>> print(my_function.__doc__)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	641 Do nothing, but document it.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	642
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	643 No, really, it doesn't do anything.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	644
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	645
44568 305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	646 .. _tut-codingstyle:
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	647
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	648 Intermezzo: Coding Style
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	649 ========================
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	650
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	651 .. sectionauthor:: Georg Brandl <georg@python.org>
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	652 .. index:: pair: coding; style
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	653
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	654 Now that you are about to write longer, more complex pieces of Python, it is a
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	655 good time to talk about coding style. Most languages can be written (or more
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	656 concise, formatted) in different styles; some are more readable than others.
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	657 Making it easy for others to read your code is always a good idea, and adopting
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	658 a nice coding style helps tremendously for that.
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	659
46478 beb7abcd6c01 Merged revisions 62350-62355,62358-62359,62364-62365,62370,62372-62375,62378-62379,62381 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44859 diff changeset	660 For Python, :pep:`8` has emerged as the style guide that most projects adhere to;
44568 305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	661 it promotes a very readable and eye-pleasing coding style. Every Python
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	662 developer should read it at some point; here are the most important points
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	663 extracted for you:
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	664
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	665 * Use 4-space indentation, and no tabs.
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	666
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	667 4 spaces are a good compromise between small indentation (allows greater
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	668 nesting depth) and large indentation (easier to read). Tabs introduce
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	669 confusion, and are best left out.
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	670
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	671 * Wrap lines so that they don't exceed 79 characters.
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	672
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	673 This helps users with small displays and makes it possible to have several
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	674 code files side-by-side on larger displays.
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	675
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	676 * Use blank lines to separate functions and classes, and larger blocks of
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	677 code inside functions.
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	678
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	679 * When possible, put comments on a line of their own.
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	680
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	681 * Use docstrings.
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	682
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	683 * Use spaces around operators and after commas, but not directly inside
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	684 bracketing constructs: ``a = f(1, 2) + g(3, 4)``.
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	685
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	686 * Name your classes and functions consistently; the convention is to use
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	687 ``CamelCase`` for classes and ``lower_case_with_underscores`` for functions
49180 c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	688 and methods. Always use ``self`` as the name for the first method argument
c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48655 diff changeset	689 (see :ref:`tut-firstclasses` for more on classes and methods).
44568 305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	690
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	691 * Don't use fancy encodings if your code is meant to be used in international
54630 2795d6fb21e2 Elaborate encoding recommendations, and fix ambiguous wording for list comprehensions. Georg Brandl <georg@python.org> parents: 54626 diff changeset	692 environments. Python's default, UTF-8, or even plain ASCII work best in any
2795d6fb21e2 Elaborate encoding recommendations, and fix ambiguous wording for list comprehensions. Georg Brandl <georg@python.org> parents: 54626 diff changeset	693 case.
2795d6fb21e2 Elaborate encoding recommendations, and fix ambiguous wording for list comprehensions. Georg Brandl <georg@python.org> parents: 54626 diff changeset	694
2795d6fb21e2 Elaborate encoding recommendations, and fix ambiguous wording for list comprehensions. Georg Brandl <georg@python.org> parents: 54626 diff changeset	695 * Likewise, don't use non-ASCII characters in identifiers if there is only the
2795d6fb21e2 Elaborate encoding recommendations, and fix ambiguous wording for list comprehensions. Georg Brandl <georg@python.org> parents: 54626 diff changeset	696 slightest chance people speaking a different language will read or maintain
2795d6fb21e2 Elaborate encoding recommendations, and fix ambiguous wording for list comprehensions. Georg Brandl <georg@python.org> parents: 54626 diff changeset	697 the code.
44568 305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	698
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	699
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	700 .. rubric:: Footnotes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	701
44568 305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	702 .. [#] Actually, call by object reference would be a better description,
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	703 since if a mutable object is passed, the caller will see any changes the
305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44538 diff changeset	704 callee makes to it (items inserted into a list).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	705

Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/controlflow.rst @ 78069:a8aa77458e12 3.2