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

annotate Doc/tutorial/classes.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	012380d57e44
children

rev	line source
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1 .. _tut-classes:
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 Classes
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
66472 a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	7 Compared with other programming languages, Python's class mechanism adds classes
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	8 with a minimum of new syntax and semantics. It is a mixture of the class
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	9 mechanisms found in C++ and Modula-3. Python classes provide all the standard
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	10 features of Object Oriented Programming: the class inheritance mechanism allows
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 multiple base classes, a derived class can override any methods of its base
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12 class or classes, and a method can call the method of a base class with the same
66472 a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	13 name. Objects can contain arbitrary amounts and kinds of data. As is true for
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	14 modules, classes partake of the dynamic nature of Python: they are created at
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	15 runtime, and can be modified further after creation.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50076 diff changeset	17 In C++ terminology, normally class members (including the data members) are
66472 a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	18 public (except see below :ref:`tut-private`), and all member functions are
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	19 virtual. As in Modula-3, there are no shorthands for referencing the object's
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	20 members from its methods: the method function is declared with an explicit first
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	21 argument representing the object, which is provided implicitly by the call. As
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	22 in Smalltalk, classes themselves are objects. This provides semantics for
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	23 importing and renaming. Unlike C++ and Modula-3, built-in types can be used as
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	24 base classes for extension by the user. Also, like in C++, most built-in
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	25 operators with special syntax (arithmetic operators, subscripting etc.) can be
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	26 redefined for class instances.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	28 (Lacking universally accepted terminology to talk about classes, I will make
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	29 occasional use of Smalltalk and C++ terms. I would use Modula-3 terms, since
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30 its object-oriented semantics are closer to those of Python than C++, but I
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31 expect that few readers have heard of it.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	33
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	34 .. _tut-object:
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	35
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	36 A Word About Names and Objects
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	37 ==============================
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	38
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 Objects have individuality, and multiple names (in multiple scopes) can be bound
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40 to the same object. This is known as aliasing in other languages. This is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41 usually not appreciated on a first glance at Python, and can be safely ignored
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 when dealing with immutable basic types (numbers, strings, tuples). However,
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	43 aliasing has a possibly surprising effect on the semantics of Python code
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	44 involving mutable objects such as lists, dictionaries, and most other types.
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	45 This is usually used to the benefit of the program, since aliases behave like
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	46 pointers in some respects. For example, passing an object is cheap since only a
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	47 pointer is passed by the implementation; and if a function modifies an object
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	48 passed as an argument, the caller will see the change --- this eliminates the
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	49 need for two different argument passing mechanisms as in Pascal.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52 .. _tut-scopes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53
55797 afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from Georg Brandl <georg@python.org> parents: 55622 diff changeset	54 Python Scopes and Namespaces
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from Georg Brandl <georg@python.org> parents: 55622 diff changeset	55 ============================
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57 Before introducing classes, I first have to tell you something about Python's
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58 scope rules. Class definitions play some neat tricks with namespaces, and you
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59 need to know how scopes and namespaces work to fully understand what's going on.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60 Incidentally, knowledge about this subject is useful for any advanced Python
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61 programmer.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63 Let's begin with some definitions.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65 A namespace is a mapping from names to objects. Most namespaces are currently
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 implemented as Python dictionaries, but that's normally not noticeable in any
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67 way (except for performance), and it may change in the future. Examples of
65116 90e1735df4d9 Merged revisions 83561,83563,83565-83566,83569,83571,83574-83575,83580,83584,83599,83612,83659,83977,84015-84018,84020,84141 via svnmerge from Georg Brandl <georg@python.org> parents: 63490 diff changeset	68 namespaces are: the set of built-in names (containing functions such as :func:`abs`, and
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69 built-in exception names); the global names in a module; and the local names in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 a function invocation. In a sense the set of attributes of an object also form
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 a namespace. The important thing to know about namespaces is that there is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72 absolutely no relation between names in different namespaces; for instance, two
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	73 different modules may both define a function ``maximize`` without confusion ---
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74 users of the modules must prefix it with the module name.
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 By the way, I use the word attribute for any name following a dot --- for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77 example, in the expression ``z.real``, ``real`` is an attribute of the object
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78 ``z``. Strictly speaking, references to names in modules are attribute
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 references: in the expression ``modname.funcname``, ``modname`` is a module
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80 object and ``funcname`` is an attribute of it. In this case there happens to be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81 a straightforward mapping between the module's attributes and the global names
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82 defined in the module: they share the same namespace! [#]_
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84 Attributes may be read-only or writable. In the latter case, assignment to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85 attributes is possible. Module attributes are writable: you can write
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86 ``modname.the_answer = 42``. Writable attributes may also be deleted with the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87 :keyword:`del` statement. For example, ``del modname.the_answer`` will remove
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88 the attribute :attr:`the_answer` from the object named by ``modname``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89
55797 afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from Georg Brandl <georg@python.org> parents: 55622 diff changeset	90 Namespaces are created at different moments and have different lifetimes. The
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91 namespace containing the built-in names is created when the Python interpreter
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92 starts up, and is never deleted. The global namespace for a module is created
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93 when the module definition is read in; normally, module namespaces also last
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 until the interpreter quits. The statements executed by the top-level
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95 invocation of the interpreter, either read from a script file or interactively,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96 are considered part of a module called :mod:`__main__`, so they have their own
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97 global namespace. (The built-in names actually also live in a module; this is
44098 0889daf6d0d9 #1535: rename __builtin__ module to builtins. Georg Brandl <georg@python.org> parents: 44026 diff changeset	98 called :mod:`builtins`.)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100 The local namespace for a function is created when the function is called, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101 deleted when the function returns or raises an exception that is not handled
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 within the function. (Actually, forgetting would be a better way to describe
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103 what actually happens.) Of course, recursive invocations each have their own
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104 local namespace.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106 A scope is a textual region of a Python program where a namespace is directly
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107 accessible. "Directly accessible" here means that an unqualified reference to a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108 name attempts to find the name in the namespace.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110 Although scopes are determined statically, they are used dynamically. At any
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111 time during execution, there are at least three nested scopes whose namespaces
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	112 are directly accessible:
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	113
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	114 * the innermost scope, which is searched first, contains the local names
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	115 * the scopes of any enclosing functions, which are searched starting with the
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	116 nearest enclosing scope, contains non-local, but also non-global names
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	117 * the next-to-last scope contains the current module's global names
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	118 * the outermost scope (searched last) is the namespace containing built-in names
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 If a name is declared global, then all references and assignments go directly to
50076 c7abfab4dcdb Merged revisions 67525-67527,67529,67548-67549,67551-67552,67555,67578,67586,67593-67594,67596,67605-67606,67609,67612,67616-67617,67632,67635,67638 via svnmerge from Georg Brandl <georg@python.org> parents: 49180 diff changeset	121 the middle scope containing the module's global names. To rebind variables
c7abfab4dcdb Merged revisions 67525-67527,67529,67548-67549,67551-67552,67555,67578,67586,67593-67594,67596,67605-67606,67609,67612,67616-67617,67632,67635,67638 via svnmerge from Georg Brandl <georg@python.org> parents: 49180 diff changeset	122 found outside of the innermost scope, the :keyword:`nonlocal` statement can be
c7abfab4dcdb Merged revisions 67525-67527,67529,67548-67549,67551-67552,67555,67578,67586,67593-67594,67596,67605-67606,67609,67612,67616-67617,67632,67635,67638 via svnmerge from Georg Brandl <georg@python.org> parents: 49180 diff changeset	123 used; if not declared nonlocal, those variable are read-only (an attempt to
c7abfab4dcdb Merged revisions 67525-67527,67529,67548-67549,67551-67552,67555,67578,67586,67593-67594,67596,67605-67606,67609,67612,67616-67617,67632,67635,67638 via svnmerge from Georg Brandl <georg@python.org> parents: 49180 diff changeset	124 write to such a variable will simply create a new local variable in the
c7abfab4dcdb Merged revisions 67525-67527,67529,67548-67549,67551-67552,67555,67578,67586,67593-67594,67596,67605-67606,67609,67612,67616-67617,67632,67635,67638 via svnmerge from Georg Brandl <georg@python.org> parents: 49180 diff changeset	125 innermost scope, leaving the identically named outer variable unchanged).
45773 832c820e9d14 Merged revisions 61239-61249,61252-61257,61260-61264,61269-61275,61278-61279,61285-61286,61288-61290,61298,61303-61305,61312-61314,61317,61329,61332,61344,61350-61351,61363-61376,61378-61379,61382-61383,61387-61388,61392,61395-61396,61402-61403 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	126
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127 Usually, the local scope references the local names of the (textually) current
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128 function. Outside functions, the local scope references the same namespace as
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129 the global scope: the module's namespace. Class definitions place yet another
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130 namespace in the local scope.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132 It is important to realize that scopes are determined textually: the global
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133 scope of a function defined in a module is that module's namespace, no matter
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134 from where or by what alias the function is called. On the other hand, the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135 actual search for names is done dynamically, at run time --- however, the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136 language definition is evolving towards static name resolution, at "compile"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137 time, so don't rely on dynamic name resolution! (In fact, local variables are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138 already determined statically.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	140 A special quirk of Python is that -- if no :keyword:`global` statement is in
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	141 effect -- assignments to names always go into the innermost scope. Assignments
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	142 do not copy data --- they just bind names to objects. The same is true for
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	143 deletions: the statement ``del x`` removes the binding of ``x`` from the
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	144 namespace referenced by the local scope. In fact, all operations that introduce
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	145 new names use the local scope: in particular, :keyword:`import` statements and
55616 91e40eb41956 Merged revisions 74403 via svnmerge from Georg Brandl <georg@python.org> parents: 55580 diff changeset	146 function definitions bind the module or function name in the local scope.
44152 1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	147
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	148 The :keyword:`global` statement can be used to indicate that particular
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	149 variables live in the global scope and should be rebound there; the
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	150 :keyword:`nonlocal` statement indicates that particular variables live in
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	151 an enclosing scope and should be rebound there.
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	152
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	153 .. _tut-scopeexample:
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	154
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	155 Scopes and Namespaces Example
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	156 -----------------------------
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	157
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	158 This is an example demonstrating how to reference the different scopes and
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	159 namespaces, and how :keyword:`global` and :keyword:`nonlocal` affect variable
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	160 binding::
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	161
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	162 def scope_test():
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	163 def do_local():
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	164 spam = "local spam"
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	165 def do_nonlocal():
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	166 nonlocal spam
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	167 spam = "nonlocal spam"
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	168 def do_global():
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	169 global spam
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	170 spam = "global spam"
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	171 spam = "test spam"
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	172 do_local()
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	173 print("After local assignment:", spam)
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	174 do_nonlocal()
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	175 print("After nonlocal assignment:", spam)
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	176 do_global()
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	177 print("After global assignment:", spam)
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	178
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	179 scope_test()
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	180 print("In global scope:", spam)
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	181
75502 aaf45928899c Fix closes Issue: 14217 - 3.2 branch Senthil Kumaran <senthil@uthcode.com> parents: 74336 diff changeset	182 The output of the example code is:
aaf45928899c Fix closes Issue: 14217 - 3.2 branch Senthil Kumaran <senthil@uthcode.com> parents: 74336 diff changeset	183
aaf45928899c Fix closes Issue: 14217 - 3.2 branch Senthil Kumaran <senthil@uthcode.com> parents: 74336 diff changeset	184 .. code-block:: none
aaf45928899c Fix closes Issue: 14217 - 3.2 branch Senthil Kumaran <senthil@uthcode.com> parents: 74336 diff changeset	185
44152 1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	186 After local assignment: test spam
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	187 After nonlocal assignment: nonlocal spam
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	188 After global assignment: nonlocal spam
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	189 In global scope: global spam
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	190
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	191 Note how the local assignment (which is default) didn't change scope_test\'s
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	192 binding of spam. The :keyword:`nonlocal` assignment changed scope_test\'s
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	193 binding of spam, and the :keyword:`global` assignment changed the module-level
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	194 binding.
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	195
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	196 You can also see that there was no previous binding for spam before the
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	197 :keyword:`global` assignment.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200 .. _tut-firstclasses:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202 A First Look at Classes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203 =======================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205 Classes introduce a little bit of new syntax, three new object types, and some
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206 new semantics.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209 .. _tut-classdefinition:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211 Class Definition Syntax
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212 -----------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214 The simplest form of class definition looks like this::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216 class ClassName:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217 <statement-1>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 .
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219 .
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220 .
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221 <statement-N>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223 Class definitions, like function definitions (:keyword:`def` statements) must be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224 executed before they have any effect. (You could conceivably place a class
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225 definition in a branch of an :keyword:`if` statement, or inside a function.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227 In practice, the statements inside a class definition will usually be function
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228 definitions, but other statements are allowed, and sometimes useful --- we'll
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229 come back to this later. The function definitions inside a class normally have
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230 a peculiar form of argument list, dictated by the calling conventions for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231 methods --- again, this is explained later.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	232
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233 When a class definition is entered, a new namespace is created, and used as the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234 local scope --- thus, all assignments to local variables go into this new
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235 namespace. In particular, function definitions bind the name of the new
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236 function here.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238 When a class definition is left normally (via the end), a class object is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239 created. This is basically a wrapper around the contents of the namespace
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240 created by the class definition; we'll learn more about class objects in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241 next section. The original local scope (the one in effect just before the class
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242 definition was entered) is reinstated, and the class object is bound here to the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243 class name given in the class definition header (:class:`ClassName` in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244 example).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247 .. _tut-classobjects:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249 Class Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250 -------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	251
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	252 Class objects support two kinds of operations: attribute references and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253 instantiation.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	254
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	255 Attribute references use the standard syntax used for all attribute references
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	256 in Python: ``obj.name``. Valid attribute names are all the names that were in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	257 the class's namespace when the class object was created. So, if the class
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258 definition looked like this::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 class MyClass:
49180 c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48667 diff changeset	261 """A simple example class"""
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 i = 12345
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263 def f(self):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264 return 'hello world'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266 then ``MyClass.i`` and ``MyClass.f`` are valid attribute references, returning
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	267 an integer and a function object, respectively. Class attributes can also be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	268 assigned to, so you can change the value of ``MyClass.i`` by assignment.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269 :attr:`__doc__` is also a valid attribute, returning the docstring belonging to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	270 the class: ``"A simple example class"``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	271
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	272 Class instantiation uses function notation. Just pretend that the class
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273 object is a parameterless function that returns a new instance of the class.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	274 For example (assuming the above class)::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	275
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276 x = MyClass()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278 creates a new instance of the class and assigns this object to the local
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279 variable ``x``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281 The instantiation operation ("calling" a class object) creates an empty object.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	282 Many classes like to create objects with instances customized to a specific
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	283 initial state. Therefore a class may define a special method named
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284 :meth:`__init__`, like this::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	285
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286 def __init__(self):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287 self.data = []
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	289 When a class defines an :meth:`__init__` method, class instantiation
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	290 automatically invokes :meth:`__init__` for the newly-created class instance. So
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	291 in this example, a new, initialized instance can be obtained by::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	292
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	293 x = MyClass()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	295 Of course, the :meth:`__init__` method may have arguments for greater
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	296 flexibility. In that case, arguments given to the class instantiation operator
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	297 are passed on to :meth:`__init__`. For example, ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	298
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	299 >>> class Complex:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	300 ... def __init__(self, realpart, imagpart):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	301 ... self.r = realpart
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	302 ... self.i = imagpart
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50076 diff changeset	303 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	304 >>> x = Complex(3.0, -4.5)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	305 >>> x.r, x.i
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	306 (3.0, -4.5)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	307
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	308
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	309 .. _tut-instanceobjects:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311 Instance Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312 ----------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314 Now what can we do with instance objects? The only operations understood by
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315 instance objects are attribute references. There are two kinds of valid
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316 attribute names, data attributes and methods.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318 data attributes correspond to "instance variables" in Smalltalk, and to "data
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319 members" in C++. Data attributes need not be declared; like local variables,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320 they spring into existence when they are first assigned to. For example, if
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321 ``x`` is the instance of :class:`MyClass` created above, the following piece of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322 code will print the value ``16``, without leaving a trace::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324 x.counter = 1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325 while x.counter < 10:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326 x.counter = x.counter * 2
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	327 print(x.counter)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328 del x.counter
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330 The other kind of instance attribute reference is a method. A method is a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331 function that "belongs to" an object. (In Python, the term method is not unique
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	332 to class instances: other object types can have methods as well. For example,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333 list objects have methods called append, insert, remove, sort, and so on.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334 However, in the following discussion, we'll use the term method exclusively to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335 mean methods of class instance objects, unless explicitly stated otherwise.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337 .. index:: object: method
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 Valid method names of an instance object depend on its class. By definition,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340 all attributes of a class that are function objects define corresponding
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	341 methods of its instances. So in our example, ``x.f`` is a valid method
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342 reference, since ``MyClass.f`` is a function, but ``x.i`` is not, since
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	343 ``MyClass.i`` is not. But ``x.f`` is not the same thing as ``MyClass.f`` --- it
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344 is a method object, not a function object.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347 .. _tut-methodobjects:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	349 Method Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	350 --------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	351
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	352 Usually, a method is called right after it is bound::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	353
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	354 x.f()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	355
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356 In the :class:`MyClass` example, this will return the string ``'hello world'``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357 However, it is not necessary to call a method right away: ``x.f`` is a method
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358 object, and can be stored away and called at a later time. For example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360 xf = x.f
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	361 while True:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	362 print(xf())
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	363
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	364 will continue to print ``hello world`` until the end of time.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	365
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	366 What exactly happens when a method is called? You may have noticed that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	367 ``x.f()`` was called without an argument above, even though the function
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	368 definition for :meth:`f` specified an argument. What happened to the argument?
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	369 Surely Python raises an exception when a function that requires an argument is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	370 called without any --- even if the argument isn't actually used...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	371
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	372 Actually, you may have guessed the answer: the special thing about methods is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	373 that the object is passed as the first argument of the function. In our
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	374 example, the call ``x.f()`` is exactly equivalent to ``MyClass.f(x)``. In
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	375 general, calling a method with a list of n arguments is equivalent to calling
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	376 the corresponding function with an argument list that is created by inserting
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	377 the method's object before the first argument.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	378
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	379 If you still don't understand how methods work, a look at the implementation can
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	380 perhaps clarify matters. When an instance attribute is referenced that isn't a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	381 data attribute, its class is searched. If the name denotes a valid class
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	382 attribute that is a function object, a method object is created by packing
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	383 (pointers to) the instance object and the function object just found together in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	384 an abstract object: this is the method object. When the method object is called
55797 afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from Georg Brandl <georg@python.org> parents: 55622 diff changeset	385 with an argument list, a new argument list is constructed from the instance
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from Georg Brandl <georg@python.org> parents: 55622 diff changeset	386 object and the argument list, and the function object is called with this new
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from Georg Brandl <georg@python.org> parents: 55622 diff changeset	387 argument list.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	388
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	389
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	390 .. _tut-remarks:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	392 Random Remarks
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	393 ==============
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	394
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44152 diff changeset	395 .. These should perhaps be placed more carefully...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	397 Data attributes override method attributes with the same name; to avoid
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	398 accidental name conflicts, which may cause hard-to-find bugs in large programs,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	399 it is wise to use some kind of convention that minimizes the chance of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400 conflicts. Possible conventions include capitalizing method names, prefixing
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	401 data attribute names with a small unique string (perhaps just an underscore), or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	402 using verbs for methods and nouns for data attributes.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	403
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	404 Data attributes may be referenced by methods as well as by ordinary users
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405 ("clients") of an object. In other words, classes are not usable to implement
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	406 pure abstract data types. In fact, nothing in Python makes it possible to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	407 enforce data hiding --- it is all based upon convention. (On the other hand,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408 the Python implementation, written in C, can completely hide implementation
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409 details and control access to an object if necessary; this can be used by
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	410 extensions to Python written in C.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	412 Clients should use data attributes with care --- clients may mess up invariants
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	413 maintained by the methods by stamping on their data attributes. Note that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414 clients may add data attributes of their own to an instance object without
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	415 affecting the validity of the methods, as long as name conflicts are avoided ---
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416 again, a naming convention can save a lot of headaches here.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	418 There is no shorthand for referencing data attributes (or other methods!) from
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419 within methods. I find that this actually increases the readability of methods:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	420 there is no chance of confusing local variables and instance variables when
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	421 glancing through a method.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	422
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	423 Often, the first argument of a method is called ``self``. This is nothing more
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	424 than a convention: the name ``self`` has absolutely no special meaning to
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	425 Python. Note, however, that by not following the convention your code may be
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	426 less readable to other Python programmers, and it is also conceivable that a
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	427 class browser program might be written that relies upon such a convention.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	429 Any function object that is a class attribute defines a method for instances of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	430 that class. It is not necessary that the function definition is textually
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	431 enclosed in the class definition: assigning a function object to a local
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	432 variable in the class is also ok. For example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	433
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	434 # Function defined outside the class
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	435 def f1(self, x, y):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	436 return min(x, x+y)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	437
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	438 class C:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	439 f = f1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	440 def g(self):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	441 return 'hello world'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	442 h = g
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	443
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	444 Now ``f``, ``g`` and ``h`` are all attributes of class :class:`C` that refer to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	445 function objects, and consequently they are all methods of instances of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	446 :class:`C` --- ``h`` being exactly equivalent to ``g``. Note that this practice
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	447 usually only serves to confuse the reader of a program.
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 Methods may call other methods by using method attributes of the ``self``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	450 argument::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	451
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	452 class Bag:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	453 def __init__(self):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	454 self.data = []
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	455 def add(self, x):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	456 self.data.append(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	457 def addtwice(self, x):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	458 self.add(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	459 self.add(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	460
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	461 Methods may reference global names in the same way as ordinary functions. The
74336 32ea3675fba2 Minor correction. #11418 Terry Jan Reedy <tjreedy@udel.edu> parents: 71553 diff changeset	462 global scope associated with a method is the module containing its
32ea3675fba2 Minor correction. #11418 Terry Jan Reedy <tjreedy@udel.edu> parents: 71553 diff changeset	463 definition. (A class is never used as a global scope.) While one
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	464 rarely encounters a good reason for using global data in a method, there are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	465 many legitimate uses of the global scope: for one thing, functions and modules
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	466 imported into the global scope can be used by methods, as well as functions and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	467 classes defined in it. Usually, the class containing the method is itself
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	468 defined in this global scope, and in the next section we'll find some good
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	469 reasons why a method would want to reference its own class.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	470
45773 832c820e9d14 Merged revisions 61239-61249,61252-61257,61260-61264,61269-61275,61278-61279,61285-61286,61288-61290,61298,61303-61305,61312-61314,61317,61329,61332,61344,61350-61351,61363-61376,61378-61379,61382-61383,61387-61388,61392,61395-61396,61402-61403 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	471 Each value is an object, and therefore has a class (also called its type).
832c820e9d14 Merged revisions 61239-61249,61252-61257,61260-61264,61269-61275,61278-61279,61285-61286,61288-61290,61298,61303-61305,61312-61314,61317,61329,61332,61344,61350-61351,61363-61376,61378-61379,61382-61383,61387-61388,61392,61395-61396,61402-61403 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	472 It is stored as ``object.__class__``.
832c820e9d14 Merged revisions 61239-61249,61252-61257,61260-61264,61269-61275,61278-61279,61285-61286,61288-61290,61298,61303-61305,61312-61314,61317,61329,61332,61344,61350-61351,61363-61376,61378-61379,61382-61383,61387-61388,61392,61395-61396,61402-61403 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	473
42604 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 .. _tut-inheritance:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	476
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	477 Inheritance
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	478 ===========
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	479
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	480 Of course, a language feature would not be worthy of the name "class" without
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	481 supporting inheritance. The syntax for a derived class definition looks like
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	482 this::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	483
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	484 class DerivedClassName(BaseClassName):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	485 <statement-1>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	486 .
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	487 .
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	488 .
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	489 <statement-N>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	490
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	491 The name :class:`BaseClassName` must be defined in a scope containing the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	492 derived class definition. In place of a base class name, other arbitrary
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	493 expressions are also allowed. This can be useful, for example, when the base
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	494 class is defined in another module::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	495
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	496 class DerivedClassName(modname.BaseClassName):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	497
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	498 Execution of a derived class definition proceeds the same as for a base class.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499 When the class object is constructed, the base class is remembered. This is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	500 used for resolving attribute references: if a requested attribute is not found
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	501 in the class, the search proceeds to look in the base class. This rule is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	502 applied recursively if the base class itself is derived from some other class.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	503
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	504 There's nothing special about instantiation of derived classes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	505 ``DerivedClassName()`` creates a new instance of the class. Method references
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	506 are resolved as follows: the corresponding class attribute is searched,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	507 descending down the chain of base classes if necessary, and the method reference
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	508 is valid if this yields a function object.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	509
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	510 Derived classes may override methods of their base classes. Because methods
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	511 have no special privileges when calling other methods of the same object, a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	512 method of a base class that calls another method defined in the same base class
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	513 may end up calling a method of a derived class that overrides it. (For C++
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44152 diff changeset	514 programmers: all methods in Python are effectively ``virtual``.)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	515
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	516 An overriding method in a derived class may in fact want to extend rather than
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	517 simply replace the base class method of the same name. There is a simple way to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	518 call the base class method directly: just call ``BaseClassName.methodname(self,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	519 arguments)``. This is occasionally useful to clients as well. (Note that this
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	520 only works if the base class is accessible as ``BaseClassName`` in the global
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	521 scope.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	522
51776 d06a3ebf306f Merged revisions 69846 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 50566 diff changeset	523 Python has two built-in functions that work with inheritance:
45773 832c820e9d14 Merged revisions 61239-61249,61252-61257,61260-61264,61269-61275,61278-61279,61285-61286,61288-61290,61298,61303-61305,61312-61314,61317,61329,61332,61344,61350-61351,61363-61376,61378-61379,61382-61383,61387-61388,61392,61395-61396,61402-61403 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	524
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	525 * Use :func:`isinstance` to check an instance's type: ``isinstance(obj, int)``
45773 832c820e9d14 Merged revisions 61239-61249,61252-61257,61260-61264,61269-61275,61278-61279,61285-61286,61288-61290,61298,61303-61305,61312-61314,61317,61329,61332,61344,61350-61351,61363-61376,61378-61379,61382-61383,61387-61388,61392,61395-61396,61402-61403 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	526 will be ``True`` only if ``obj.__class__`` is :class:`int` or some class
832c820e9d14 Merged revisions 61239-61249,61252-61257,61260-61264,61269-61275,61278-61279,61285-61286,61288-61290,61298,61303-61305,61312-61314,61317,61329,61332,61344,61350-61351,61363-61376,61378-61379,61382-61383,61387-61388,61392,61395-61396,61402-61403 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	527 derived from :class:`int`.
832c820e9d14 Merged revisions 61239-61249,61252-61257,61260-61264,61269-61275,61278-61279,61285-61286,61288-61290,61298,61303-61305,61312-61314,61317,61329,61332,61344,61350-61351,61363-61376,61378-61379,61382-61383,61387-61388,61392,61395-61396,61402-61403 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	528
832c820e9d14 Merged revisions 61239-61249,61252-61257,61260-61264,61269-61275,61278-61279,61285-61286,61288-61290,61298,61303-61305,61312-61314,61317,61329,61332,61344,61350-61351,61363-61376,61378-61379,61382-61383,61387-61388,61392,61395-61396,61402-61403 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	529 * Use :func:`issubclass` to check class inheritance: ``issubclass(bool, int)``
832c820e9d14 Merged revisions 61239-61249,61252-61257,61260-61264,61269-61275,61278-61279,61285-61286,61288-61290,61298,61303-61305,61312-61314,61317,61329,61332,61344,61350-61351,61363-61376,61378-61379,61382-61383,61387-61388,61392,61395-61396,61402-61403 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	530 is ``True`` since :class:`bool` is a subclass of :class:`int`. However,
48507 604febd204cb #3310: stop referring to basestring. Georg Brandl <georg@python.org> parents: 45773 diff changeset	531 ``issubclass(float, int)`` is ``False`` since :class:`float` is not a
604febd204cb #3310: stop referring to basestring. Georg Brandl <georg@python.org> parents: 45773 diff changeset	532 subclass of :class:`int`.
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50076 diff changeset	533
45773 832c820e9d14 Merged revisions 61239-61249,61252-61257,61260-61264,61269-61275,61278-61279,61285-61286,61288-61290,61298,61303-61305,61312-61314,61317,61329,61332,61344,61350-61351,61363-61376,61378-61379,61382-61383,61387-61388,61392,61395-61396,61402-61403 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	534
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 .. _tut-multiple:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	537
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	538 Multiple Inheritance
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	539 --------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	540
43449 7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial. Georg Brandl <georg@python.org> parents: 43305 diff changeset	541 Python supports a form of multiple inheritance as well. A class definition with
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial. Georg Brandl <georg@python.org> parents: 43305 diff changeset	542 multiple base classes looks like this::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	544 class DerivedClassName(Base1, Base2, Base3):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	545 <statement-1>
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 .
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	549 <statement-N>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	550
43449 7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial. Georg Brandl <georg@python.org> parents: 43305 diff changeset	551 For most purposes, in the simplest cases, you can think of the search for
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial. Georg Brandl <georg@python.org> parents: 43305 diff changeset	552 attributes inherited from a parent class as depth-first, left-to-right, not
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial. Georg Brandl <georg@python.org> parents: 43305 diff changeset	553 searching twice in the same class where there is an overlap in the hierarchy.
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial. Georg Brandl <georg@python.org> parents: 43305 diff changeset	554 Thus, if an attribute is not found in :class:`DerivedClassName`, it is searched
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial. Georg Brandl <georg@python.org> parents: 43305 diff changeset	555 for in :class:`Base1`, then (recursively) in the base classes of :class:`Base1`,
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial. Georg Brandl <georg@python.org> parents: 43305 diff changeset	556 and if it was not found there, it was searched for in :class:`Base2`, and so on.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	557
43449 7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial. Georg Brandl <georg@python.org> parents: 43305 diff changeset	558 In fact, it is slightly more complex than that; the method resolution order
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial. Georg Brandl <georg@python.org> parents: 43305 diff changeset	559 changes dynamically to support cooperative calls to :func:`super`. This
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial. Georg Brandl <georg@python.org> parents: 43305 diff changeset	560 approach is known in some other multiple-inheritance languages as
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial. Georg Brandl <georg@python.org> parents: 43305 diff changeset	561 call-next-method and is more powerful than the super call found in
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial. Georg Brandl <georg@python.org> parents: 43305 diff changeset	562 single-inheritance languages.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	563
43155 335ef86a8c5c - document bytes() Georg Brandl <georg@python.org> parents: 43115 diff changeset	564 Dynamic ordering is necessary because all cases of multiple inheritance exhibit
43737 3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43449 diff changeset	565 one or more diamond relationships (where at least one of the parent classes
43155 335ef86a8c5c - document bytes() Georg Brandl <georg@python.org> parents: 43115 diff changeset	566 can be accessed through multiple paths from the bottommost class). For example,
335ef86a8c5c - document bytes() Georg Brandl <georg@python.org> parents: 43115 diff changeset	567 all classes inherit from :class:`object`, so any case of multiple inheritance
335ef86a8c5c - document bytes() Georg Brandl <georg@python.org> parents: 43115 diff changeset	568 provides more than one path to reach :class:`object`. To keep the base classes
335ef86a8c5c - document bytes() Georg Brandl <georg@python.org> parents: 43115 diff changeset	569 from being accessed more than once, the dynamic algorithm linearizes the search
335ef86a8c5c - document bytes() Georg Brandl <georg@python.org> parents: 43115 diff changeset	570 order in a way that preserves the left-to-right ordering specified in each
335ef86a8c5c - document bytes() Georg Brandl <georg@python.org> parents: 43115 diff changeset	571 class, that calls each parent only once, and that is monotonic (meaning that a
335ef86a8c5c - document bytes() Georg Brandl <georg@python.org> parents: 43115 diff changeset	572 class can be subclassed without affecting the precedence order of its parents).
335ef86a8c5c - document bytes() Georg Brandl <georg@python.org> parents: 43115 diff changeset	573 Taken together, these properties make it possible to design reliable and
335ef86a8c5c - document bytes() Georg Brandl <georg@python.org> parents: 43115 diff changeset	574 extensible classes with multiple inheritance. For more detail, see
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	575 http://www.python.org/download/releases/2.3/mro/.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	576
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	577
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	578 .. _tut-private:
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 Private Variables
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	581 =================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	582
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	583 "Private" instance variables that cannot be accessed except from inside an
62962 365eeab4a350 Merged revisions 82301 via svnmerge from Georg Brandl <georg@python.org> parents: 55797 diff changeset	584 object don't exist in Python. However, there is a convention that is followed
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	585 by most Python code: a name prefixed with an underscore (e.g. ``_spam``) should
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	586 be treated as a non-public part of the API (whether it is a function, a method
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	587 or a data member). It should be considered an implementation detail and subject
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	588 to change without notice.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	589
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	590 Since there is a valid use-case for class-private members (namely to avoid name
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	591 clashes of names with names defined by subclasses), there is limited support for
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	592 such a mechanism, called :dfn:`name mangling`. Any identifier of the form
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	593 ``__spam`` (at least two leading underscores, at most one trailing underscore)
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	594 is textually replaced with ``_classname__spam``, where ``classname`` is the
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	595 current class name with leading underscore(s) stripped. This mangling is done
55622 e3d51319b9d0 Merged revisions 74412 via svnmerge from Georg Brandl <georg@python.org> parents: 55616 diff changeset	596 without regard to the syntactic position of the identifier, as long as it
e3d51319b9d0 Merged revisions 74412 via svnmerge from Georg Brandl <georg@python.org> parents: 55616 diff changeset	597 occurs within the definition of a class.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	598
70974 79f9698777b7 Issue 12086: add example showing how to use name mangling. Raymond Hettinger <python@rcn.com> parents: 69738 diff changeset	599 Name mangling is helpful for letting subclasses override methods without
79f9698777b7 Issue 12086: add example showing how to use name mangling. Raymond Hettinger <python@rcn.com> parents: 69738 diff changeset	600 breaking intraclass method calls. For example::
79f9698777b7 Issue 12086: add example showing how to use name mangling. Raymond Hettinger <python@rcn.com> parents: 69738 diff changeset	601
71553 fc75798f292e Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70974 diff changeset	602 class Mapping:
fc75798f292e Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70974 diff changeset	603 def __init__(self, iterable):
fc75798f292e Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70974 diff changeset	604 self.items_list = []
fc75798f292e Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70974 diff changeset	605 self.__update(iterable)
70974 79f9698777b7 Issue 12086: add example showing how to use name mangling. Raymond Hettinger <python@rcn.com> parents: 69738 diff changeset	606
71553 fc75798f292e Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70974 diff changeset	607 def update(self, iterable):
fc75798f292e Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70974 diff changeset	608 for item in iterable:
fc75798f292e Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70974 diff changeset	609 self.items_list.append(item)
70974 79f9698777b7 Issue 12086: add example showing how to use name mangling. Raymond Hettinger <python@rcn.com> parents: 69738 diff changeset	610
71553 fc75798f292e Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70974 diff changeset	611 __update = update # private copy of original update() method
70974 79f9698777b7 Issue 12086: add example showing how to use name mangling. Raymond Hettinger <python@rcn.com> parents: 69738 diff changeset	612
71553 fc75798f292e Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70974 diff changeset	613 class MappingSubclass(Mapping):
70974 79f9698777b7 Issue 12086: add example showing how to use name mangling. Raymond Hettinger <python@rcn.com> parents: 69738 diff changeset	614
71553 fc75798f292e Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70974 diff changeset	615 def update(self, keys, values):
fc75798f292e Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70974 diff changeset	616 # provides new signature for update()
fc75798f292e Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70974 diff changeset	617 # but does not break __init__()
fc75798f292e Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70974 diff changeset	618 for item in zip(keys, values):
fc75798f292e Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70974 diff changeset	619 self.items_list.append(item)
70974 79f9698777b7 Issue 12086: add example showing how to use name mangling. Raymond Hettinger <python@rcn.com> parents: 69738 diff changeset	620
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	621 Note that the mangling rules are designed mostly to avoid accidents; it still is
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	622 possible to access or modify a variable that is considered private. This can
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	623 even be useful in special circumstances, such as in the debugger.
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	624
62984 8e42c7a5dab8 Merged revisions 82835 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 62962 diff changeset	625 Notice that code passed to ``exec()`` or ``eval()`` does not consider the
8e42c7a5dab8 Merged revisions 82835 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 62962 diff changeset	626 classname of the invoking class to be the current class; this is similar to the
8e42c7a5dab8 Merged revisions 82835 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 62962 diff changeset	627 effect of the ``global`` statement, the effect of which is likewise restricted
8e42c7a5dab8 Merged revisions 82835 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 62962 diff changeset	628 to code that is byte-compiled together. The same restriction applies to
8e42c7a5dab8 Merged revisions 82835 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 62962 diff changeset	629 ``getattr()``, ``setattr()`` and ``delattr()``, as well as when referencing
8e42c7a5dab8 Merged revisions 82835 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 62962 diff changeset	630 ``__dict__`` directly.
42604 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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	633 .. _tut-odds:
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 Odds and Ends
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	636 =============
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	637
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	638 Sometimes it is useful to have a data type similar to the Pascal "record" or C
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	639 "struct", bundling together a few named data items. An empty class definition
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	640 will do nicely::
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 class Employee:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	643 pass
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	644
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	645 john = Employee() # Create an empty employee record
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	646
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	647 # Fill the fields of the record
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	648 john.name = 'John Doe'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	649 john.dept = 'computer lab'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	650 john.salary = 1000
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 A piece of Python code that expects a particular abstract data type can often be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	653 passed a class that emulates the methods of that data type instead. For
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	654 instance, if you have a function that formats some data from a file object, you
86171 012380d57e44 Issue #19193: Improved cross-references in the tutorial. Serhiy Storchaka <storchaka@gmail.com> parents: 86003 diff changeset	655 can define a class with methods :meth:`read` and :meth:`!readline` that get the
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	656 data from a string buffer instead, and pass it as an argument.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	657
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44152 diff changeset	658 .. (Unfortunately, this technique has its limitations: a class can't define
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44152 diff changeset	659 operations that are accessed by special syntax such as sequence subscripting
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44152 diff changeset	660 or arithmetic operators, and assigning such a "pseudo-file" to sys.stdin will
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44152 diff changeset	661 not cause the interpreter to read further input from it.)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	662
44026 48af6375207e Removed the API to create unbound methods and simplified the API for bound methods. The signature is PyMethod_New(func, instance). Christian Heimes <christian@cheimes.de> parents: 43737 diff changeset	663 Instance method objects have attributes, too: ``m.__self__`` is the instance
48af6375207e Removed the API to create unbound methods and simplified the API for bound methods. The signature is PyMethod_New(func, instance). Christian Heimes <christian@cheimes.de> parents: 43737 diff changeset	664 object with the method :meth:`m`, and ``m.__func__`` is the function object
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	665 corresponding to the method.
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 .. _tut-exceptionclasses:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	669
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	670 Exceptions Are Classes Too
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	671 ==========================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	672
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	673 User-defined exceptions are identified by classes as well. Using this mechanism
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	674 it is possible to create extensible hierarchies of exceptions.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	675
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	676 There are two new valid (semantic) forms for the :keyword:`raise` statement::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	677
43305 75b265c08c91 Update tutorial/classes.rst to remove references to the old two-argument form of the raise statement. Collin Winter <collinw@gmail.com> parents: 43201 diff changeset	678 raise Class
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	679
43305 75b265c08c91 Update tutorial/classes.rst to remove references to the old two-argument form of the raise statement. Collin Winter <collinw@gmail.com> parents: 43201 diff changeset	680 raise Instance
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	681
43305 75b265c08c91 Update tutorial/classes.rst to remove references to the old two-argument form of the raise statement. Collin Winter <collinw@gmail.com> parents: 43201 diff changeset	682 In the first form, ``Class`` must be an instance of :class:`type` or of a
75b265c08c91 Update tutorial/classes.rst to remove references to the old two-argument form of the raise statement. Collin Winter <collinw@gmail.com> parents: 43201 diff changeset	683 class derived from it. The first form is a shorthand for::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	684
43305 75b265c08c91 Update tutorial/classes.rst to remove references to the old two-argument form of the raise statement. Collin Winter <collinw@gmail.com> parents: 43201 diff changeset	685 raise Class()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	686
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	687 A class in an :keyword:`except` clause is compatible with an exception if it is
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	688 the same class or a base class thereof (but not the other way around --- an
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	689 except clause listing a derived class is not compatible with a base class). For
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51776 diff changeset	690 example, the following code will print B, C, D in that order::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	691
48667 949b9a2b9867 #3525: 3.0 exception changes in tutorial. Georg Brandl <georg@python.org> parents: 48507 diff changeset	692 class B(Exception):
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	693 pass
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	694 class C(B):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	695 pass
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	696 class D(C):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	697 pass
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	698
68314 88fe1ac48460 Name c -> cls in example. Georg Brandl <georg@python.org> parents: 68257 diff changeset	699 for cls in [B, C, D]:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	700 try:
68314 88fe1ac48460 Name c -> cls in example. Georg Brandl <georg@python.org> parents: 68257 diff changeset	701 raise cls()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	702 except D:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	703 print("D")
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	704 except C:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	705 print("C")
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	706 except B:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	707 print("B")
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	708
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	709 Note that if the except clauses were reversed (with ``except B`` first), it
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	710 would have printed B, B, B --- the first matching except clause is triggered.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	711
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	712 When an error message is printed for an unhandled exception, the exception's
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	713 class name is printed, then a colon and a space, and finally the instance
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	714 converted to a string using the built-in function :func:`str`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	715
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	716
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	717 .. _tut-iterators:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	718
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	719 Iterators
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	720 =========
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	721
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	722 By now you have probably noticed that most container objects can be looped over
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	723 using a :keyword:`for` statement::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	724
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	725 for element in [1, 2, 3]:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	726 print(element)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	727 for element in (1, 2, 3):
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	728 print(element)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	729 for key in {'one':1, 'two':2}:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	730 print(key)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	731 for char in "123":
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	732 print(char)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	733 for line in open("myfile.txt"):
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	734 print(line)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	735
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	736 This style of access is clear, concise, and convenient. The use of iterators
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	737 pervades and unifies Python. Behind the scenes, the :keyword:`for` statement
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	738 calls :func:`iter` on the container object. The function returns an iterator
79689 d6ba5441a2e9 Fix links to the __next__ method. Ezio Melotti <ezio.melotti@gmail.com> parents: 75502 diff changeset	739 object that defines the method :meth:`~iterator.__next__` which accesses
d6ba5441a2e9 Fix links to the __next__ method. Ezio Melotti <ezio.melotti@gmail.com> parents: 75502 diff changeset	740 elements in the container one at a time. When there are no more elements,
86171 012380d57e44 Issue #19193: Improved cross-references in the tutorial. Serhiy Storchaka <storchaka@gmail.com> parents: 86003 diff changeset	741 :meth:`~iterator.__next__` raises a :exc:`StopIteration` exception which tells the
012380d57e44 Issue #19193: Improved cross-references in the tutorial. Serhiy Storchaka <storchaka@gmail.com> parents: 86003 diff changeset	742 :keyword:`for` loop to terminate. You can call the :meth:`~iterator.__next__` method
79689 d6ba5441a2e9 Fix links to the __next__ method. Ezio Melotti <ezio.melotti@gmail.com> parents: 75502 diff changeset	743 using the :func:`next` built-in function; this example shows how it all works::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	744
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	745 >>> s = 'abc'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	746 >>> it = iter(s)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	747 >>> it
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	748 <iterator object at 0x00A1DB50>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	749 >>> next(it)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	750 'a'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	751 >>> next(it)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	752 'b'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	753 >>> next(it)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	754 'c'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	755 >>> next(it)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	756 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	757 File "<stdin>", line 1, in ?
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	758 next(it)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	759 StopIteration
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	760
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	761 Having seen the mechanics behind the iterator protocol, it is easy to add
63490 f46dcd8a3113 Merged revisions 82965 via svnmerge from Georg Brandl <georg@python.org> parents: 62984 diff changeset	762 iterator behavior to your classes. Define an :meth:`__iter__` method which
79689 d6ba5441a2e9 Fix links to the __next__ method. Ezio Melotti <ezio.melotti@gmail.com> parents: 75502 diff changeset	763 returns an object with a :meth:`~iterator.__next__` method. If the class
d6ba5441a2e9 Fix links to the __next__ method. Ezio Melotti <ezio.melotti@gmail.com> parents: 75502 diff changeset	764 defines :meth:`__next__`, then :meth:`__iter__` can just return ``self``::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	765
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	766 class Reverse:
69738 13878873ccc7 Split combined code/doctest code blocks in two blocks, to enable proper highlighting. Georg Brandl <georg@python.org> parents: 68257 diff changeset	767 """Iterator for looping over a sequence backwards."""
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	768 def __init__(self, data):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	769 self.data = data
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	770 self.index = len(data)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	771 def __iter__(self):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	772 return self
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	773 def __next__(self):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	774 if self.index == 0:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	775 raise StopIteration
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	776 self.index = self.index - 1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	777 return self.data[self.index]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	778
69738 13878873ccc7 Split combined code/doctest code blocks in two blocks, to enable proper highlighting. Georg Brandl <georg@python.org> parents: 68257 diff changeset	779 ::
13878873ccc7 Split combined code/doctest code blocks in two blocks, to enable proper highlighting. Georg Brandl <georg@python.org> parents: 68257 diff changeset	780
63490 f46dcd8a3113 Merged revisions 82965 via svnmerge from Georg Brandl <georg@python.org> parents: 62984 diff changeset	781 >>> rev = Reverse('spam')
f46dcd8a3113 Merged revisions 82965 via svnmerge from Georg Brandl <georg@python.org> parents: 62984 diff changeset	782 >>> iter(rev)
f46dcd8a3113 Merged revisions 82965 via svnmerge from Georg Brandl <georg@python.org> parents: 62984 diff changeset	783 <__main__.Reverse object at 0x00A1DB50>
f46dcd8a3113 Merged revisions 82965 via svnmerge from Georg Brandl <georg@python.org> parents: 62984 diff changeset	784 >>> for char in rev:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	785 ... print(char)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	786 ...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	787 m
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	788 a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	789 p
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	790 s
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	791
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	792
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	793 .. _tut-generators:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	794
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	795 Generators
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	796 ==========
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	797
43737 3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43449 diff changeset	798 :term:`Generator`\s are a simple and powerful tool for creating iterators. They
3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43449 diff changeset	799 are written like regular functions but use the :keyword:`yield` statement
3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43449 diff changeset	800 whenever they want to return data. Each time :func:`next` is called on it, the
3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43449 diff changeset	801 generator resumes where it left-off (it remembers all the data values and which
3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43449 diff changeset	802 statement was last executed). An example shows that generators can be trivially
3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43449 diff changeset	803 easy to create::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	804
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	805 def reverse(data):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	806 for index in range(len(data)-1, -1, -1):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	807 yield data[index]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	808
69738 13878873ccc7 Split combined code/doctest code blocks in two blocks, to enable proper highlighting. Georg Brandl <georg@python.org> parents: 68257 diff changeset	809 ::
13878873ccc7 Split combined code/doctest code blocks in two blocks, to enable proper highlighting. Georg Brandl <georg@python.org> parents: 68257 diff changeset	810
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	811 >>> for char in reverse('golf'):
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	812 ... print(char)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	813 ...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	814 f
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	815 l
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	816 o
50566 ea7e307ddd51 Merged revisions 68229 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	817 g
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	818
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	819 Anything that can be done with generators can also be done with class based
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	820 iterators as described in the previous section. What makes generators so
79689 d6ba5441a2e9 Fix links to the __next__ method. Ezio Melotti <ezio.melotti@gmail.com> parents: 75502 diff changeset	821 compact is that the :meth:`__iter__` and :meth:`~generator.__next__` methods
d6ba5441a2e9 Fix links to the __next__ method. Ezio Melotti <ezio.melotti@gmail.com> parents: 75502 diff changeset	822 are created automatically.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	823
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	824 Another key feature is that the local variables and execution state are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	825 automatically saved between calls. This made the function easier to write and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	826 much more clear than an approach using instance variables like ``self.index``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	827 and ``self.data``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	828
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	829 In addition to automatic method creation and saving program state, when
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	830 generators terminate, they automatically raise :exc:`StopIteration`. In
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	831 combination, these features make it easy to create iterators with no more effort
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	832 than writing a regular function.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	833
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	834
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	835 .. _tut-genexps:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	836
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	837 Generator Expressions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	838 =====================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	839
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	840 Some simple generators can be coded succinctly as expressions using a syntax
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	841 similar to list comprehensions but with parentheses instead of brackets. These
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	842 expressions are designed for situations where the generator is used right away
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	843 by an enclosing function. Generator expressions are more compact but less
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	844 versatile than full generator definitions and tend to be more memory friendly
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	845 than equivalent list comprehensions.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	846
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	847 Examples::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	848
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	849 >>> sum(i*i for i in range(10)) # sum of squares
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	850 285
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	851
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	852 >>> xvec = [10, 20, 30]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	853 >>> yvec = [7, 5, 3]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	854 >>> sum(x*y for x,y in zip(xvec, yvec)) # dot product
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	855 260
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	856
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	857 >>> from math import pi, sin
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	858 >>> sine_table = {x: sin(x*pi/180) for x in range(0, 91)}
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	859
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	860 >>> unique_words = set(word for line in page for word in line.split())
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	861
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	862 >>> valedictorian = max((student.gpa, student.name) for student in graduates)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	863
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	864 >>> data = 'golf'
43201 4902671dd678 Tutorial formatting patch by Robin Stocker. Georg Brandl <georg@python.org> parents: 43155 diff changeset	865 >>> list(data[i] for i in range(len(data)-1, -1, -1))
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	866 ['f', 'l', 'o', 'g']
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	867
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	868
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	869
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	870 .. rubric:: Footnotes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	871
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	872 .. [#] Except for one thing. Module objects have a secret read-only attribute called
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	873 :attr:`__dict__` which returns the dictionary used to implement the module's
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	874 namespace; the name :attr:`__dict__` is an attribute but not a global name.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	875 Obviously, using this violates the abstraction of namespace implementation, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	876 should be restricted to things like post-mortem debuggers.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	877

Mercurial > cpython-lru_cache-weakref

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