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

annotate Doc/tutorial/datastructures.rst @ 87690:66c1c9f32567 default tip

Add use_weakref option to functools.lru_cache The use_weakref option makes lru_cache create weak references to the function arguments when creating the cache key, which prevents them from staying in the memory forever even after all other references to them are gone. This is a proof of concept for http://bugs.python.org/issue19859

author	Radomir Dopieralski <devel@sheep.art.pl>
date	Tue, 03 Dec 2013 16:02:48 +0100
parents	d9b58229aabe
children

rev	line source
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1 .. _tut-structures:
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 Data Structures
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 This chapter describes some things you've learned about already in more detail,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 and adds some new things as well.
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 .. _tut-morelists:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12 More on Lists
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13 =============
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 The list data type has some more methods. Here are all of the methods of list
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16 objects:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19 .. method:: list.append(x)
45996 376b5cb8a014 Merged revisions 61687-61688,61696,61700,61704-61705,61707-61709,61711-61712,61714-61716,61718-61722 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	20 :noindex:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21
72808 352d075839f7 Closes #12192: Document that mutating list methods do not return the instance (original patch by Mike Hoy). Georg Brandl <georg@python.org> parents: 68257 diff changeset	22 Add an item to the end of the list. Equivalent to ``a[len(a):] = [x]``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 .. method:: list.extend(L)
45996 376b5cb8a014 Merged revisions 61687-61688,61696,61700,61704-61705,61707-61709,61711-61712,61714-61716,61718-61722 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	26 :noindex:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27
72808 352d075839f7 Closes #12192: Document that mutating list methods do not return the instance (original patch by Mike Hoy). Georg Brandl <georg@python.org> parents: 68257 diff changeset	28 Extend the list by appending all the items in the given list. Equivalent to
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29 ``a[len(a):] = L``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32 .. method:: list.insert(i, x)
45996 376b5cb8a014 Merged revisions 61687-61688,61696,61700,61704-61705,61707-61709,61711-61712,61714-61716,61718-61722 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	33 :noindex:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35 Insert an item at a given position. The first argument is the index of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36 element before which to insert, so ``a.insert(0, x)`` inserts at the front of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37 the list, and ``a.insert(len(a), x)`` is equivalent to ``a.append(x)``.
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 .. method:: list.remove(x)
45996 376b5cb8a014 Merged revisions 61687-61688,61696,61700,61704-61705,61707-61709,61711-61712,61714-61716,61718-61722 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	41 :noindex:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42
72808 352d075839f7 Closes #12192: Document that mutating list methods do not return the instance (original patch by Mike Hoy). Georg Brandl <georg@python.org> parents: 68257 diff changeset	43 Remove the first item from the list whose value is x. It is an error if
352d075839f7 Closes #12192: Document that mutating list methods do not return the instance (original patch by Mike Hoy). Georg Brandl <georg@python.org> parents: 68257 diff changeset	44 there is no such item.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47 .. method:: list.pop([i])
45996 376b5cb8a014 Merged revisions 61687-61688,61696,61700,61704-61705,61707-61709,61711-61712,61714-61716,61718-61722 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	48 :noindex:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50 Remove the item at the given position in the list, and return it. If no index
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51 is specified, ``a.pop()`` removes and returns the last item in the list. (The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52 square brackets around the i in the method signature denote that the parameter
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53 is optional, not that you should type square brackets at that position. You
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54 will see this notation frequently in the Python Library Reference.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56
86073 d9b58229aabe Add missing list methods. Found by Leonardo Pereira on docs@. Georg Brandl <georg@python.org> parents: 80461 diff changeset	57 .. method:: list.clear()
d9b58229aabe Add missing list methods. Found by Leonardo Pereira on docs@. Georg Brandl <georg@python.org> parents: 80461 diff changeset	58 :noindex:
d9b58229aabe Add missing list methods. Found by Leonardo Pereira on docs@. Georg Brandl <georg@python.org> parents: 80461 diff changeset	59
d9b58229aabe Add missing list methods. Found by Leonardo Pereira on docs@. Georg Brandl <georg@python.org> parents: 80461 diff changeset	60 Remove all items from the list. Equivalent to ``del a[:]``.
d9b58229aabe Add missing list methods. Found by Leonardo Pereira on docs@. Georg Brandl <georg@python.org> parents: 80461 diff changeset	61
d9b58229aabe Add missing list methods. Found by Leonardo Pereira on docs@. Georg Brandl <georg@python.org> parents: 80461 diff changeset	62
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63 .. method:: list.index(x)
45996 376b5cb8a014 Merged revisions 61687-61688,61696,61700,61704-61705,61707-61709,61711-61712,61714-61716,61718-61722 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	64 :noindex:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 Return the index in the list of the first item whose value is x. It is an
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67 error if there is no such item.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 .. method:: list.count(x)
45996 376b5cb8a014 Merged revisions 61687-61688,61696,61700,61704-61705,61707-61709,61711-61712,61714-61716,61718-61722 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	71 :noindex:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73 Return the number of times x appears in the list.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76 .. method:: list.sort()
45996 376b5cb8a014 Merged revisions 61687-61688,61696,61700,61704-61705,61707-61709,61711-61712,61714-61716,61718-61722 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	77 :noindex:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78
72808 352d075839f7 Closes #12192: Document that mutating list methods do not return the instance (original patch by Mike Hoy). Georg Brandl <georg@python.org> parents: 68257 diff changeset	79 Sort the items of the list in place.
42604 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 .. method:: list.reverse()
45996 376b5cb8a014 Merged revisions 61687-61688,61696,61700,61704-61705,61707-61709,61711-61712,61714-61716,61718-61722 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	83 :noindex:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84
72808 352d075839f7 Closes #12192: Document that mutating list methods do not return the instance (original patch by Mike Hoy). Georg Brandl <georg@python.org> parents: 68257 diff changeset	85 Reverse the elements of the list in place.
352d075839f7 Closes #12192: Document that mutating list methods do not return the instance (original patch by Mike Hoy). Georg Brandl <georg@python.org> parents: 68257 diff changeset	86
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87
86073 d9b58229aabe Add missing list methods. Found by Leonardo Pereira on docs@. Georg Brandl <georg@python.org> parents: 80461 diff changeset	88 .. method:: list.copy()
d9b58229aabe Add missing list methods. Found by Leonardo Pereira on docs@. Georg Brandl <georg@python.org> parents: 80461 diff changeset	89 :noindex:
d9b58229aabe Add missing list methods. Found by Leonardo Pereira on docs@. Georg Brandl <georg@python.org> parents: 80461 diff changeset	90
d9b58229aabe Add missing list methods. Found by Leonardo Pereira on docs@. Georg Brandl <georg@python.org> parents: 80461 diff changeset	91 Return a shallow copy of the list. Equivalent to ``a[:]``.
d9b58229aabe Add missing list methods. Found by Leonardo Pereira on docs@. Georg Brandl <georg@python.org> parents: 80461 diff changeset	92
d9b58229aabe Add missing list methods. Found by Leonardo Pereira on docs@. Georg Brandl <georg@python.org> parents: 80461 diff changeset	93
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 An example that uses most of the list methods::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96 >>> a = [66.25, 333, 333, 1, 1234.5]
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	97 >>> print(a.count(333), a.count(66.25), a.count('x'))
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98 2 1 0
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99 >>> a.insert(2, -1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100 >>> a.append(333)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101 >>> a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 [66.25, 333, -1, 333, 1, 1234.5, 333]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103 >>> a.index(333)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104 1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105 >>> a.remove(333)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106 >>> a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107 [66.25, -1, 333, 1, 1234.5, 333]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108 >>> a.reverse()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109 >>> a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110 [333, 1234.5, 1, 333, -1, 66.25]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111 >>> a.sort()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112 >>> a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113 [-1, 1, 66.25, 333, 333, 1234.5]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114
72808 352d075839f7 Closes #12192: Document that mutating list methods do not return the instance (original patch by Mike Hoy). Georg Brandl <georg@python.org> parents: 68257 diff changeset	115 You might have noticed that methods like ``insert``, ``remove`` or ``sort`` that
352d075839f7 Closes #12192: Document that mutating list methods do not return the instance (original patch by Mike Hoy). Georg Brandl <georg@python.org> parents: 68257 diff changeset	116 modify the list have no return value printed -- they return ``None``. [1]_ This
352d075839f7 Closes #12192: Document that mutating list methods do not return the instance (original patch by Mike Hoy). Georg Brandl <georg@python.org> parents: 68257 diff changeset	117 is a design principle for all mutable data structures in Python.
352d075839f7 Closes #12192: Document that mutating list methods do not return the instance (original patch by Mike Hoy). Georg Brandl <georg@python.org> parents: 68257 diff changeset	118
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120 .. _tut-lists-as-stacks:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122 Using Lists as Stacks
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123 ---------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125 .. sectionauthor:: Ka-Ping Yee <ping@lfw.org>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128 The list methods make it very easy to use a list as a stack, where the last
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129 element added is the first element retrieved ("last-in, first-out"). To add an
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130 item to the top of the stack, use :meth:`append`. To retrieve an item from the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131 top of the stack, use :meth:`pop` without an explicit index. For example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133 >>> stack = [3, 4, 5]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134 >>> stack.append(6)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135 >>> stack.append(7)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136 >>> stack
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137 [3, 4, 5, 6, 7]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138 >>> stack.pop()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139 7
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140 >>> stack
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141 [3, 4, 5, 6]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142 >>> stack.pop()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143 6
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144 >>> stack.pop()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145 5
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146 >>> stack
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147 [3, 4]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	148
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 .. _tut-lists-as-queues:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 Using Lists as Queues
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155 .. sectionauthor:: Ka-Ping Yee <ping@lfw.org>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156
60103 e4f969012e68 Merged revisions 79525 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 54773 diff changeset	157 It is also possible to use a list as a queue, where the first element added is
e4f969012e68 Merged revisions 79525 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 54773 diff changeset	158 the first element retrieved ("first-in, first-out"); however, lists are not
e4f969012e68 Merged revisions 79525 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 54773 diff changeset	159 efficient for this purpose. While appends and pops from the end of list are
e4f969012e68 Merged revisions 79525 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 54773 diff changeset	160 fast, doing inserts or pops from the beginning of a list is slow (because all
e4f969012e68 Merged revisions 79525 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 54773 diff changeset	161 of the other elements have to be shifted by one).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162
60103 e4f969012e68 Merged revisions 79525 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 54773 diff changeset	163 To implement a queue, use :class:`collections.deque` which was designed to
e4f969012e68 Merged revisions 79525 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 54773 diff changeset	164 have fast appends and pops from both ends. For example::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165
60103 e4f969012e68 Merged revisions 79525 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 54773 diff changeset	166 >>> from collections import deque
e4f969012e68 Merged revisions 79525 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 54773 diff changeset	167 >>> queue = deque(["Eric", "John", "Michael"])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168 >>> queue.append("Terry") # Terry arrives
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169 >>> queue.append("Graham") # Graham arrives
60103 e4f969012e68 Merged revisions 79525 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 54773 diff changeset	170 >>> queue.popleft() # The first to arrive now leaves
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171 'Eric'
60103 e4f969012e68 Merged revisions 79525 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 54773 diff changeset	172 >>> queue.popleft() # The second to arrive now leaves
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	173 'John'
60103 e4f969012e68 Merged revisions 79525 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 54773 diff changeset	174 >>> queue # Remaining queue in order of arrival
e4f969012e68 Merged revisions 79525 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 54773 diff changeset	175 deque(['Michael', 'Terry', 'Graham'])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	176
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	177
54769 eea4d237c16d Expand a bit on dict views. Georg Brandl <georg@python.org> parents: 54632 diff changeset	178 .. _tut-listcomps:
eea4d237c16d Expand a bit on dict views. Georg Brandl <georg@python.org> parents: 54632 diff changeset	179
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	180 List Comprehensions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	181 -------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	183 List comprehensions provide a concise way to create lists.
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	184 Common applications are to make new lists where each element is the result of
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	185 some operations applied to each member of another sequence or iterable, or to
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	186 create a subsequence of those elements that satisfy a certain condition.
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	187
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	188 For example, assume we want to create a list of squares, like::
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	189
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	190 >>> squares = []
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	191 >>> for x in range(10):
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	192 ... squares.append(x**2)
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	193 ...
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	194 >>> squares
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	195 [0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	196
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	197 We can obtain the same result with::
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	198
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	199 squares = [x**2 for x in range(10)]
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	200
79211 6c96878eb729 Close issue #16073: fix map() example in list comprehension documentation. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 78512 diff changeset	201 This is also equivalent to ``squares = list(map(lambda x: x**2, range(10)))``,
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	202 but it's more concise and readable.
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	203
54630 2795d6fb21e2 Elaborate encoding recommendations, and fix ambiguous wording for list comprehensions. Georg Brandl <georg@python.org> parents: 52892 diff changeset	204 A list comprehension consists of brackets containing an expression followed
2795d6fb21e2 Elaborate encoding recommendations, and fix ambiguous wording for list comprehensions. Georg Brandl <georg@python.org> parents: 52892 diff changeset	205 by a :keyword:`for` clause, then zero or more :keyword:`for` or :keyword:`if`
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	206 clauses. The result will be a new list resulting from evaluating the expression
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	207 in the context of the :keyword:`for` and :keyword:`if` clauses which follow it.
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	208 For example, this listcomp combines the elements of two lists if they are not
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	209 equal::
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	210
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	211 >>> [(x, y) for x in [1,2,3] for y in [3,1,4] if x != y]
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	212 [(1, 3), (1, 4), (2, 3), (2, 1), (2, 4), (3, 1), (3, 4)]
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	213
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	214 and it's equivalent to::
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	215
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	216 >>> combs = []
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	217 >>> for x in [1,2,3]:
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	218 ... for y in [3,1,4]:
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	219 ... if x != y:
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	220 ... combs.append((x, y))
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	221 ...
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	222 >>> combs
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	223 [(1, 3), (1, 4), (2, 3), (2, 1), (2, 4), (3, 1), (3, 4)]
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	224
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	225 Note how the order of the :keyword:`for` and :keyword:`if` statements is the
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	226 same in both these snippets.
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	227
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	228 If the expression is a tuple (e.g. the ``(x, y)`` in the previous example),
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	229 it must be parenthesized. ::
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	230
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	231 >>> vec = [-4, -2, 0, 2, 4]
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	232 >>> # create a new list with the values doubled
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	233 >>> [x*2 for x in vec]
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	234 [-8, -4, 0, 4, 8]
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	235 >>> # filter the list to exclude negative numbers
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	236 >>> [x for x in vec if x >= 0]
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	237 [0, 2, 4]
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	238 >>> # apply a function to all the elements
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	239 >>> [abs(x) for x in vec]
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	240 [4, 2, 0, 2, 4]
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	241 >>> # call a method on each element
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242 >>> freshfruit = [' banana', ' loganberry ', 'passion fruit ']
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243 >>> [weapon.strip() for weapon in freshfruit]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244 ['banana', 'loganberry', 'passion fruit']
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	245 >>> # create a list of 2-tuples like (number, square)
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	246 >>> [(x, x**2) for x in range(6)]
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	247 [(0, 0), (1, 1), (2, 4), (3, 9), (4, 16), (5, 25)]
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	248 >>> # the tuple must be parenthesized, otherwise an error is raised
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	249 >>> [x, x**2 for x in range(6)]
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250 File "<stdin>", line 1, in ?
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	251 [x, x**2 for x in range(6)]
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	252 ^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253 SyntaxError: invalid syntax
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	254 >>> # flatten a list using a listcomp with two 'for'
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	255 >>> vec = [[1,2,3], [4,5,6], [7,8,9]]
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	256 >>> [num for elem in vec for num in elem]
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	257 [1, 2, 3, 4, 5, 6, 7, 8, 9]
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	258
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	259 List comprehensions can contain complex expressions and nested functions::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	261 >>> from math import pi
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	262 >>> [str(round(pi, i)) for i in range(1, 6)]
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263 ['3.1', '3.14', '3.142', '3.1416', '3.14159']
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264
44310 e70acbf26cda Merged revisions 59488-59511 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 43497 diff changeset	265 Nested List Comprehensions
e70acbf26cda Merged revisions 59488-59511 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 43497 diff changeset	266 --------------------------
e70acbf26cda Merged revisions 59488-59511 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 43497 diff changeset	267
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	268 The initial expression in a list comprehension can be any arbitrary expression,
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	269 including another list comprehension.
44310 e70acbf26cda Merged revisions 59488-59511 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 43497 diff changeset	270
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	271 Consider the following example of a 3x4 matrix implemented as a list of
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	272 3 lists of length 4::
44310 e70acbf26cda Merged revisions 59488-59511 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 43497 diff changeset	273
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	274 >>> matrix = [
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	275 ... [1, 2, 3, 4],
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	276 ... [5, 6, 7, 8],
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	277 ... [9, 10, 11, 12],
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	278 ... ]
44310 e70acbf26cda Merged revisions 59488-59511 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 43497 diff changeset	279
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	280 The following list comprehension will transpose rows and columns::
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	281
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	282 >>> [[row[i] for row in matrix] for i in range(4)]
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	283 [[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	284
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	285 As we saw in the previous section, the nested listcomp is evaluated in
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	286 the context of the :keyword:`for` that follows it, so this example is
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	287 equivalent to::
44310 e70acbf26cda Merged revisions 59488-59511 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 43497 diff changeset	288
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	289 >>> transposed = []
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	290 >>> for i in range(4):
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	291 ... transposed.append([row[i] for row in matrix])
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	292 ...
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	293 >>> transposed
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	294 [[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]
44310 e70acbf26cda Merged revisions 59488-59511 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 43497 diff changeset	295
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	296 which, in turn, is the same as::
44310 e70acbf26cda Merged revisions 59488-59511 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 43497 diff changeset	297
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	298 >>> transposed = []
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	299 >>> for i in range(4):
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	300 ... # the following 3 lines implement the nested listcomp
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	301 ... transposed_row = []
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	302 ... for row in matrix:
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	303 ... transposed_row.append(row[i])
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	304 ... transposed.append(transposed_row)
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	305 ...
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	306 >>> transposed
ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	307 [[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]
44310 e70acbf26cda Merged revisions 59488-59511 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 43497 diff changeset	308
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	309 In the real world, you should prefer built-in functions to complex flow statements.
44310 e70acbf26cda Merged revisions 59488-59511 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 43497 diff changeset	310 The :func:`zip` function would do a great job for this use case::
e70acbf26cda Merged revisions 59488-59511 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 43497 diff changeset	311
78512 233673503217 zip() returns an iterator, make a list() of it; thanks to Martin from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 77496 diff changeset	312 >>> list(zip(*matrix))
73952 ad5c70296c7b #13549: improve tutorial section about listcomps. Ezio Melotti <ezio.melotti@gmail.com> parents: 68257 diff changeset	313 [(1, 5, 9), (2, 6, 10), (3, 7, 11), (4, 8, 12)]
44310 e70acbf26cda Merged revisions 59488-59511 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 43497 diff changeset	314
e70acbf26cda Merged revisions 59488-59511 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 43497 diff changeset	315 See :ref:`tut-unpacking-arguments` for details on the asterisk in this line.
e70acbf26cda Merged revisions 59488-59511 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 43497 diff changeset	316
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317 .. _tut-del:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319 The :keyword:`del` statement
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320 ============================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322 There is a way to remove an item from a list given its index instead of its
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323 value: the :keyword:`del` statement. This differs from the :meth:`pop` method
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324 which returns a value. The :keyword:`del` statement can also be used to remove
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325 slices from a list or clear the entire list (which we did earlier by assignment
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326 of an empty list to the slice). For example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328 >>> a = [-1, 1, 66.25, 333, 333, 1234.5]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329 >>> del a[0]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330 >>> a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331 [1, 66.25, 333, 333, 1234.5]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	332 >>> del a[2:4]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333 >>> a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334 [1, 66.25, 1234.5]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335 >>> del a[:]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336 >>> a
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	339 :keyword:`del` can also be used to delete entire variables::
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 >>> del a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	343 Referencing the name ``a`` hereafter is an error (at least until another value
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344 is assigned to it). We'll find other uses for :keyword:`del` later.
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
49180 c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48665 diff changeset	347 .. _tut-tuples:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	349 Tuples and Sequences
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	350 ====================
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	351
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	352 We saw that lists and strings have many common properties, such as indexing and
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	353 slicing operations. They are two examples of sequence data types (see
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	354 :ref:`typesseq`). Since Python is an evolving language, other sequence data
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	355 types may be added. There is also another standard sequence data type: the
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	356 tuple.
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	357
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	358 A tuple consists of a number of values separated by commas, for instance::
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	359
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	360 >>> t = 12345, 54321, 'hello!'
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	361 >>> t[0]
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	362 12345
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	363 >>> t
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	364 (12345, 54321, 'hello!')
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	365 >>> # Tuples may be nested:
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	366 ... u = t, (1, 2, 3, 4, 5)
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	367 >>> u
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	368 ((12345, 54321, 'hello!'), (1, 2, 3, 4, 5))
77496 3550416d83b3 #14840: Add a bit on the difference between tuples and lists. Initial patch by Zachary Ware. Ezio Melotti <ezio.melotti@gmail.com> parents: 73952 diff changeset	369 >>> # Tuples are immutable:
3550416d83b3 #14840: Add a bit on the difference between tuples and lists. Initial patch by Zachary Ware. Ezio Melotti <ezio.melotti@gmail.com> parents: 73952 diff changeset	370 ... t[0] = 88888
3550416d83b3 #14840: Add a bit on the difference between tuples and lists. Initial patch by Zachary Ware. Ezio Melotti <ezio.melotti@gmail.com> parents: 73952 diff changeset	371 Traceback (most recent call last):
3550416d83b3 #14840: Add a bit on the difference between tuples and lists. Initial patch by Zachary Ware. Ezio Melotti <ezio.melotti@gmail.com> parents: 73952 diff changeset	372 File "<stdin>", line 1, in <module>
3550416d83b3 #14840: Add a bit on the difference between tuples and lists. Initial patch by Zachary Ware. Ezio Melotti <ezio.melotti@gmail.com> parents: 73952 diff changeset	373 TypeError: 'tuple' object does not support item assignment
3550416d83b3 #14840: Add a bit on the difference between tuples and lists. Initial patch by Zachary Ware. Ezio Melotti <ezio.melotti@gmail.com> parents: 73952 diff changeset	374 >>> # but they can contain mutable objects:
3550416d83b3 #14840: Add a bit on the difference between tuples and lists. Initial patch by Zachary Ware. Ezio Melotti <ezio.melotti@gmail.com> parents: 73952 diff changeset	375 ... v = ([1, 2, 3], [3, 2, 1])
3550416d83b3 #14840: Add a bit on the difference between tuples and lists. Initial patch by Zachary Ware. Ezio Melotti <ezio.melotti@gmail.com> parents: 73952 diff changeset	376 >>> v
3550416d83b3 #14840: Add a bit on the difference between tuples and lists. Initial patch by Zachary Ware. Ezio Melotti <ezio.melotti@gmail.com> parents: 73952 diff changeset	377 ([1, 2, 3], [3, 2, 1])
3550416d83b3 #14840: Add a bit on the difference between tuples and lists. Initial patch by Zachary Ware. Ezio Melotti <ezio.melotti@gmail.com> parents: 73952 diff changeset	378
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	379
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	380 As you see, on output tuples are always enclosed in parentheses, so that nested
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	381 tuples are interpreted correctly; they may be input with or without surrounding
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	382 parentheses, although often parentheses are necessary anyway (if the tuple is
77496 3550416d83b3 #14840: Add a bit on the difference between tuples and lists. Initial patch by Zachary Ware. Ezio Melotti <ezio.melotti@gmail.com> parents: 73952 diff changeset	383 part of a larger expression). It is not possible to assign to the individual
3550416d83b3 #14840: Add a bit on the difference between tuples and lists. Initial patch by Zachary Ware. Ezio Melotti <ezio.melotti@gmail.com> parents: 73952 diff changeset	384 items of a tuple, however it is possible to create tuples which contain mutable
3550416d83b3 #14840: Add a bit on the difference between tuples and lists. Initial patch by Zachary Ware. Ezio Melotti <ezio.melotti@gmail.com> parents: 73952 diff changeset	385 objects, such as lists.
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	386
77496 3550416d83b3 #14840: Add a bit on the difference between tuples and lists. Initial patch by Zachary Ware. Ezio Melotti <ezio.melotti@gmail.com> parents: 73952 diff changeset	387 Though tuples may seem similar to lists, they are often used in different
3550416d83b3 #14840: Add a bit on the difference between tuples and lists. Initial patch by Zachary Ware. Ezio Melotti <ezio.melotti@gmail.com> parents: 73952 diff changeset	388 situations and for different purposes.
3550416d83b3 #14840: Add a bit on the difference between tuples and lists. Initial patch by Zachary Ware. Ezio Melotti <ezio.melotti@gmail.com> parents: 73952 diff changeset	389 Tuples are :term:`immutable`, and usually contain an heterogeneous sequence of
3550416d83b3 #14840: Add a bit on the difference between tuples and lists. Initial patch by Zachary Ware. Ezio Melotti <ezio.melotti@gmail.com> parents: 73952 diff changeset	390 elements that are accessed via unpacking (see later in this section) or indexing
3550416d83b3 #14840: Add a bit on the difference between tuples and lists. Initial patch by Zachary Ware. Ezio Melotti <ezio.melotti@gmail.com> parents: 73952 diff changeset	391 (or even by attribute in the case of :func:`namedtuples <collections.namedtuple>`).
3550416d83b3 #14840: Add a bit on the difference between tuples and lists. Initial patch by Zachary Ware. Ezio Melotti <ezio.melotti@gmail.com> parents: 73952 diff changeset	392 Lists are :term:`mutable`, and their elements are usually homogeneous and are
3550416d83b3 #14840: Add a bit on the difference between tuples and lists. Initial patch by Zachary Ware. Ezio Melotti <ezio.melotti@gmail.com> parents: 73952 diff changeset	393 accessed by iterating over the list.
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	394
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	395 A special problem is the construction of tuples containing 0 or 1 items: the
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	396 syntax has some extra quirks to accommodate these. Empty tuples are constructed
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	397 by an empty pair of parentheses; a tuple with one item is constructed by
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	398 following a value with a comma (it is not sufficient to enclose a single value
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	399 in parentheses). Ugly, but effective. For example::
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	400
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	401 >>> empty = ()
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	402 >>> singleton = 'hello', # <-- note trailing comma
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	403 >>> len(empty)
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	404 0
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	405 >>> len(singleton)
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	406 1
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	407 >>> singleton
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	408 ('hello',)
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	409
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	410 The statement ``t = 12345, 54321, 'hello!'`` is an example of tuple packing:
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	411 the values ``12345``, ``54321`` and ``'hello!'`` are packed together in a tuple.
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	412 The reverse operation is also possible::
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	413
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	414 >>> x, y, z = t
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	415
52892 792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 51776 diff changeset	416 This is called, appropriately enough, sequence unpacking and works for any
54630 2795d6fb21e2 Elaborate encoding recommendations, and fix ambiguous wording for list comprehensions. Georg Brandl <georg@python.org> parents: 52892 diff changeset	417 sequence on the right-hand side. Sequence unpacking requires that there are as
2795d6fb21e2 Elaborate encoding recommendations, and fix ambiguous wording for list comprehensions. Georg Brandl <georg@python.org> parents: 52892 diff changeset	418 many variables on the left side of the equals sign as there are elements in the
52892 792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 51776 diff changeset	419 sequence. Note that multiple assignment is really just a combination of tuple
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 51776 diff changeset	420 packing and sequence unpacking.
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	421
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44310 diff changeset	422
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	423 .. _tut-sets:
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 Sets
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	426 ====
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428 Python also includes a data type for sets. A set is an unordered collection
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	429 with no duplicate elements. Basic uses include membership testing and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	430 eliminating duplicate entries. Set objects also support mathematical operations
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	431 like union, intersection, difference, and symmetric difference.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	432
80460 49cf38158c8b Rephrase a sentence in the set and dict comprehensions tutorial page. Ezio Melotti <ezio.melotti@gmail.com> parents: 79727 diff changeset	433 Curly braces or the :func:`set` function can be used to create sets. Note: to
54632 255db70bb316 Fix markup. Georg Brandl <georg@python.org> parents: 54630 diff changeset	434 create an empty set you have to use ``set()``, not ``{}``; the latter creates an
255db70bb316 Fix markup. Georg Brandl <georg@python.org> parents: 54630 diff changeset	435 empty dictionary, a data structure that we discuss in the next section.
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	436
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	437 Here is a brief demonstration::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	438
63813 28fef9e7c3bb Issue #4570: Clean-up tutorial example Raymond Hettinger <python@rcn.com> parents: 61802 diff changeset	439 >>> basket = {'apple', 'orange', 'apple', 'pear', 'orange', 'banana'}
28fef9e7c3bb Issue #4570: Clean-up tutorial example Raymond Hettinger <python@rcn.com> parents: 61802 diff changeset	440 >>> print(basket) # show that duplicates have been removed
66478 7281937b2d65 Merged revisions 86134,86315-86316,86390,86424-86425,86428,86550,86561-86562,86564-86565,86705,86708,86713 via svnmerge from Georg Brandl <georg@python.org> parents: 65119 diff changeset	441 {'orange', 'banana', 'pear', 'apple'}
63813 28fef9e7c3bb Issue #4570: Clean-up tutorial example Raymond Hettinger <python@rcn.com> parents: 61802 diff changeset	442 >>> 'orange' in basket # fast membership testing
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	443 True
63813 28fef9e7c3bb Issue #4570: Clean-up tutorial example Raymond Hettinger <python@rcn.com> parents: 61802 diff changeset	444 >>> 'crabgrass' in basket
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	445 False
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	446
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	447 >>> # Demonstrate set operations on unique letters from two words
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	448 ...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	449 >>> a = set('abracadabra')
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	450 >>> b = set('alacazam')
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	451 >>> a # unique letters in a
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	452 {'a', 'r', 'b', 'c', 'd'}
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	453 >>> a - b # letters in a but not in b
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	454 {'r', 'd', 'b'}
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	455 >>> a \| b # letters in either a or b
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	456 {'a', 'c', 'r', 'd', 'b', 'm', 'z', 'l'}
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	457 >>> a & b # letters in both a and b
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	458 {'a', 'c'}
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	459 >>> a ^ b # letters in a or b but not both
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	460 {'r', 'd', 'b', 'm', 'z', 'l'}
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	461
80460 49cf38158c8b Rephrase a sentence in the set and dict comprehensions tutorial page. Ezio Melotti <ezio.melotti@gmail.com> parents: 79727 diff changeset	462 Similarly to :ref:`list comprehensions <tut-listcomps>`, set comprehensions
49cf38158c8b Rephrase a sentence in the set and dict comprehensions tutorial page. Ezio Melotti <ezio.melotti@gmail.com> parents: 79727 diff changeset	463 are also supported::
45084 38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44396 diff changeset	464
38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44396 diff changeset	465 >>> a = {x for x in 'abracadabra' if x not in 'abc'}
38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44396 diff changeset	466 >>> a
38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44396 diff changeset	467 {'r', 'd'}
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	468
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	469
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	470 .. _tut-dictionaries:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	471
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	472 Dictionaries
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	473 ============
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	474
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	475 Another useful data type built into Python is the dictionary (see
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	476 :ref:`typesmapping`). Dictionaries are sometimes found in other languages as
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	477 "associative memories" or "associative arrays". Unlike sequences, which are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	478 indexed by a range of numbers, dictionaries are indexed by keys, which can be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	479 any immutable type; strings and numbers can always be keys. Tuples can be used
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	480 as keys if they contain only strings, numbers, or tuples; if a tuple contains
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	481 any mutable object either directly or indirectly, it cannot be used as a key.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	482 You can't use lists as keys, since lists can be modified in place using index
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	483 assignments, slice assignments, or methods like :meth:`append` and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	484 :meth:`extend`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	485
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	486 It is best to think of a dictionary as an unordered set of key: value pairs,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	487 with the requirement that the keys are unique (within one dictionary). A pair of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	488 braces creates an empty dictionary: ``{}``. Placing a comma-separated list of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	489 key:value pairs within the braces adds initial key:value pairs to the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	490 dictionary; this is also the way dictionaries are written on output.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	491
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	492 The main operations on a dictionary are storing a value with some key and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	493 extracting the value given the key. It is also possible to delete a key:value
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	494 pair with ``del``. If you store using a key that is already in use, the old
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	495 value associated with that key is forgotten. It is an error to extract a value
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	496 using a non-existent key.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	497
50176 ea9c6026ae7e #4667: fix some 2.x leftovers in the tutorial. Georg Brandl <georg@python.org> parents: 50165 diff changeset	498 Performing ``list(d.keys())`` on a dictionary returns a list of all the keys
54769 eea4d237c16d Expand a bit on dict views. Georg Brandl <georg@python.org> parents: 54632 diff changeset	499 used in the dictionary, in arbitrary order (if you want it sorted, just use
72808 352d075839f7 Closes #12192: Document that mutating list methods do not return the instance (original patch by Mike Hoy). Georg Brandl <georg@python.org> parents: 68257 diff changeset	500 ``sorted(d.keys())`` instead). [2]_ To check whether a single key is in the
54769 eea4d237c16d Expand a bit on dict views. Georg Brandl <georg@python.org> parents: 54632 diff changeset	501 dictionary, use the :keyword:`in` keyword.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	502
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	503 Here is a small example using a dictionary::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	504
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	505 >>> tel = {'jack': 4098, 'sape': 4139}
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	506 >>> tel['guido'] = 4127
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	507 >>> tel
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	508 {'sape': 4139, 'guido': 4127, 'jack': 4098}
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	509 >>> tel['jack']
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	510 4098
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	511 >>> del tel['sape']
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	512 >>> tel['irv'] = 4127
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	513 >>> tel
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	514 {'guido': 4127, 'irv': 4127, 'jack': 4098}
43117 7ea1367ba275 A few more fixes to the tutorial Neal Norwitz <nnorwitz@gmail.com> parents: 43115 diff changeset	515 >>> list(tel.keys())
50176 ea9c6026ae7e #4667: fix some 2.x leftovers in the tutorial. Georg Brandl <georg@python.org> parents: 50165 diff changeset	516 ['irv', 'guido', 'jack']
ea9c6026ae7e #4667: fix some 2.x leftovers in the tutorial. Georg Brandl <georg@python.org> parents: 50165 diff changeset	517 >>> sorted(tel.keys())
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	518 ['guido', 'irv', 'jack']
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	519 >>> 'guido' in tel
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	520 True
43117 7ea1367ba275 A few more fixes to the tutorial Neal Norwitz <nnorwitz@gmail.com> parents: 43115 diff changeset	521 >>> 'jack' not in tel
7ea1367ba275 A few more fixes to the tutorial Neal Norwitz <nnorwitz@gmail.com> parents: 43115 diff changeset	522 False
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	523
54769 eea4d237c16d Expand a bit on dict views. Georg Brandl <georg@python.org> parents: 54632 diff changeset	524 The :func:`dict` constructor builds dictionaries directly from sequences of
54773 f0195daadffb The key-value pairs can be lists or tuples or any iterable. Raymond Hettinger <python@rcn.com> parents: 54769 diff changeset	525 key-value pairs::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	526
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	527 >>> dict([('sape', 4139), ('guido', 4127), ('jack', 4098)])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	528 {'sape': 4139, 'jack': 4098, 'guido': 4127}
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	529
45084 38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44396 diff changeset	530 In addition, dict comprehensions can be used to create dictionaries from
38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44396 diff changeset	531 arbitrary key and value expressions::
38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44396 diff changeset	532
38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44396 diff changeset	533 >>> {x: x**2 for x in (2, 4, 6)}
38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44396 diff changeset	534 {2: 4, 4: 16, 6: 36}
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	535
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	536 When the keys are simple strings, it is sometimes easier to specify pairs using
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	537 keyword 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 >>> dict(sape=4139, guido=4127, jack=4098)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	540 {'sape': 4139, 'jack': 4098, 'guido': 4127}
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543 .. _tut-loopidioms:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	544
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	545 Looping Techniques
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	546 ==================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	547
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	548 When looping through dictionaries, the key and corresponding value can be
43117 7ea1367ba275 A few more fixes to the tutorial Neal Norwitz <nnorwitz@gmail.com> parents: 43115 diff changeset	549 retrieved at the same time using the :meth:`items` method. ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	550
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	551 >>> knights = {'gallahad': 'the pure', 'robin': 'the brave'}
43117 7ea1367ba275 A few more fixes to the tutorial Neal Norwitz <nnorwitz@gmail.com> parents: 43115 diff changeset	552 >>> for k, v in knights.items():
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	553 ... print(k, v)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	554 ...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	555 gallahad the pure
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	556 robin the brave
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	557
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	558 When looping through a sequence, the position index and corresponding value can
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	559 be retrieved at the same time using the :func:`enumerate` function. ::
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 >>> for i, v in enumerate(['tic', 'tac', 'toe']):
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	562 ... print(i, v)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	563 ...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	564 0 tic
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	565 1 tac
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	566 2 toe
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	567
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	568 To loop over two or more sequences at the same time, the entries can be paired
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	569 with the :func:`zip` function. ::
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 >>> questions = ['name', 'quest', 'favorite color']
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	572 >>> answers = ['lancelot', 'the holy grail', 'blue']
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	573 >>> for q, a in zip(questions, answers):
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 46978 diff changeset	574 ... print('What is your {0}? It is {1}.'.format(q, a))
50517 83efc2467faf Fix a few remaining problems found by rstlint. Georg Brandl <georg@python.org> parents: 50515 diff changeset	575 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	576 What is your name? It is lancelot.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	577 What is your quest? It is the holy grail.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	578 What is your favorite color? It is blue.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	579
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	580 To loop over a sequence in reverse, first specify the sequence in a forward
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	581 direction and then call the :func:`reversed` function. ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	582
43201 4902671dd678 Tutorial formatting patch by Robin Stocker. Georg Brandl <georg@python.org> parents: 43117 diff changeset	583 >>> for i in reversed(range(1, 10, 2)):
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	584 ... print(i)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	585 ...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	586 9
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	587 7
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	588 5
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	589 3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	590 1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	591
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	592 To loop over a sequence in sorted order, use the :func:`sorted` function which
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	593 returns a new sorted list while leaving the source unaltered. ::
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 >>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana']
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	596 >>> for f in sorted(set(basket)):
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	597 ... print(f)
50517 83efc2467faf Fix a few remaining problems found by rstlint. Georg Brandl <georg@python.org> parents: 50515 diff changeset	598 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	599 apple
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	600 banana
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	601 orange
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	602 pear
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	603
79727 1f1bf6a3abbc Issue #16225: Add additional note to tutorial about changing sequence while looping. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79211 diff changeset	604 To change a sequence you are iterating over while inside the loop (for
1f1bf6a3abbc Issue #16225: Add additional note to tutorial about changing sequence while looping. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79211 diff changeset	605 example to duplicate certain items), it is recommended that you first make
1f1bf6a3abbc Issue #16225: Add additional note to tutorial about changing sequence while looping. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79211 diff changeset	606 a copy. Looping over a sequence does not implicitly make a copy. The slice
1f1bf6a3abbc Issue #16225: Add additional note to tutorial about changing sequence while looping. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79211 diff changeset	607 notation makes this especially convenient::
1f1bf6a3abbc Issue #16225: Add additional note to tutorial about changing sequence while looping. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79211 diff changeset	608
1f1bf6a3abbc Issue #16225: Add additional note to tutorial about changing sequence while looping. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79211 diff changeset	609 >>> words = ['cat', 'window', 'defenestrate']
1f1bf6a3abbc Issue #16225: Add additional note to tutorial about changing sequence while looping. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79211 diff changeset	610 >>> for w in words[:]: # Loop over a slice copy of the entire list.
1f1bf6a3abbc Issue #16225: Add additional note to tutorial about changing sequence while looping. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79211 diff changeset	611 ... if len(w) > 6:
1f1bf6a3abbc Issue #16225: Add additional note to tutorial about changing sequence while looping. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79211 diff changeset	612 ... words.insert(0, w)
1f1bf6a3abbc Issue #16225: Add additional note to tutorial about changing sequence while looping. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79211 diff changeset	613 ...
1f1bf6a3abbc Issue #16225: Add additional note to tutorial about changing sequence while looping. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79211 diff changeset	614 >>> words
1f1bf6a3abbc Issue #16225: Add additional note to tutorial about changing sequence while looping. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79211 diff changeset	615 ['defenestrate', 'cat', 'window', 'defenestrate']
1f1bf6a3abbc Issue #16225: Add additional note to tutorial about changing sequence while looping. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79211 diff changeset	616
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	617
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	618 .. _tut-conditions:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	619
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	620 More on Conditions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	621 ==================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	622
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	623 The conditions used in ``while`` and ``if`` statements can contain any
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	624 operators, not just comparisons.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	625
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	626 The comparison operators ``in`` and ``not in`` check whether a value occurs
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	627 (does not occur) in a sequence. The operators ``is`` and ``is not`` compare
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	628 whether two objects are really the same object; this only matters for mutable
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	629 objects like lists. All comparison operators have the same priority, which is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	630 lower than that of all numerical operators.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	631
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	632 Comparisons can be chained. For example, ``a < b == c`` tests whether ``a`` is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	633 less than ``b`` and moreover ``b`` equals ``c``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	634
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	635 Comparisons may be combined using the Boolean operators ``and`` and ``or``, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	636 the outcome of a comparison (or of any other Boolean expression) may be negated
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	637 with ``not``. These have lower priorities than comparison operators; between
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	638 them, ``not`` has the highest priority and ``or`` the lowest, so that ``A and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	639 not B or C`` is equivalent to ``(A and (not B)) or C``. As always, parentheses
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	640 can be used to express the desired composition.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	641
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	642 The Boolean operators ``and`` and ``or`` are so-called short-circuit
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	643 operators: their arguments are evaluated from left to right, and evaluation
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	644 stops as soon as the outcome is determined. For example, if ``A`` and ``C`` are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	645 true but ``B`` is false, ``A and B and C`` does not evaluate the expression
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	646 ``C``. When used as a general value and not as a Boolean, the return value of a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	647 short-circuit operator is the last evaluated argument.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	648
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	649 It is possible to assign the result of a comparison or other Boolean expression
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	650 to a variable. For example, ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	651
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	652 >>> string1, string2, string3 = '', 'Trondheim', 'Hammer Dance'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	653 >>> non_null = string1 or string2 or string3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	654 >>> non_null
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	655 'Trondheim'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	656
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	657 Note that in Python, unlike C, assignment cannot occur inside expressions. C
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	658 programmers may grumble about this, but it avoids a common class of problems
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	659 encountered in C programs: typing ``=`` in an expression when ``==`` was
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	660 intended.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	661
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	662
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	663 .. _tut-comparing:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	664
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	665 Comparing Sequences and Other Types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	666 ===================================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	667
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	668 Sequence objects may be compared to other objects with the same sequence type.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	669 The comparison uses lexicographical ordering: first the first two items are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	670 compared, and if they differ this determines the outcome of the comparison; if
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	671 they are equal, the next two items are compared, and so on, until either
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	672 sequence is exhausted. If two items to be compared are themselves sequences of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	673 the same type, the lexicographical comparison is carried out recursively. If
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	674 all items of two sequences compare equal, the sequences are considered equal.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	675 If one sequence is an initial sub-sequence of the other, the shorter sequence is
54769 eea4d237c16d Expand a bit on dict views. Georg Brandl <georg@python.org> parents: 54632 diff changeset	676 the smaller (lesser) one. Lexicographical ordering for strings uses the Unicode
eea4d237c16d Expand a bit on dict views. Georg Brandl <georg@python.org> parents: 54632 diff changeset	677 codepoint number to order individual characters. Some examples of comparisons
eea4d237c16d Expand a bit on dict views. Georg Brandl <georg@python.org> parents: 54632 diff changeset	678 between sequences of the same type::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	679
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	680 (1, 2, 3) < (1, 2, 4)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	681 [1, 2, 3] < [1, 2, 4]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	682 'ABC' < 'C' < 'Pascal' < 'Python'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	683 (1, 2, 3, 4) < (1, 2, 4)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	684 (1, 2) < (1, 2, -1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	685 (1, 2, 3) == (1.0, 2.0, 3.0)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	686 (1, 2, ('aa', 'ab')) < (1, 2, ('abc', 'a'), 4)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	687
43497 6614d42d7f0a #1228: new comparison behavior. Georg Brandl <georg@python.org> parents: 43303 diff changeset	688 Note that comparing objects of different types with ``<`` or ``>`` is legal
6614d42d7f0a #1228: new comparison behavior. Georg Brandl <georg@python.org> parents: 43303 diff changeset	689 provided that the objects have appropriate comparison methods. For example,
6614d42d7f0a #1228: new comparison behavior. Georg Brandl <georg@python.org> parents: 43303 diff changeset	690 mixed numeric types are compared according to their numeric value, so 0 equals
6614d42d7f0a #1228: new comparison behavior. Georg Brandl <georg@python.org> parents: 43303 diff changeset	691 0.0, etc. Otherwise, rather than providing an arbitrary ordering, the
6614d42d7f0a #1228: new comparison behavior. Georg Brandl <georg@python.org> parents: 43303 diff changeset	692 interpreter will raise a :exc:`TypeError` exception.
54769 eea4d237c16d Expand a bit on dict views. Georg Brandl <georg@python.org> parents: 54632 diff changeset	693
eea4d237c16d Expand a bit on dict views. Georg Brandl <georg@python.org> parents: 54632 diff changeset	694
eea4d237c16d Expand a bit on dict views. Georg Brandl <georg@python.org> parents: 54632 diff changeset	695 .. rubric:: Footnotes
eea4d237c16d Expand a bit on dict views. Georg Brandl <georg@python.org> parents: 54632 diff changeset	696
72808 352d075839f7 Closes #12192: Document that mutating list methods do not return the instance (original patch by Mike Hoy). Georg Brandl <georg@python.org> parents: 68257 diff changeset	697 .. [1] Other languages may return the mutated object, which allows method
352d075839f7 Closes #12192: Document that mutating list methods do not return the instance (original patch by Mike Hoy). Georg Brandl <georg@python.org> parents: 68257 diff changeset	698 chaining, such as ``d->insert("a")->remove("b")->sort();``.
352d075839f7 Closes #12192: Document that mutating list methods do not return the instance (original patch by Mike Hoy). Georg Brandl <georg@python.org> parents: 68257 diff changeset	699
352d075839f7 Closes #12192: Document that mutating list methods do not return the instance (original patch by Mike Hoy). Georg Brandl <georg@python.org> parents: 68257 diff changeset	700 .. [2] Calling ``d.keys()`` will return a :dfn:`dictionary view` object. It
54769 eea4d237c16d Expand a bit on dict views. Georg Brandl <georg@python.org> parents: 54632 diff changeset	701 supports operations like membership test and iteration, but its contents
eea4d237c16d Expand a bit on dict views. Georg Brandl <georg@python.org> parents: 54632 diff changeset	702 are not independent of the original dictionary -- it is only a view.

Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/datastructures.rst @ 87690:66c1c9f32567 default tip