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

annotate Doc/tutorial/classes.rst @ 66978:aed2bbafa550 3.1

Blocked revisions 87324 via svnmerge ........ r87324 | r.david.murray | 2010-12-16 14:08:51 -0500 (Thu, 16 Dec 2010) | 9 lines #10719: restore messages generated on invalid compileall args Before the introduction of filename arguments to compileall it gave semi useful messages about not being able to 'list' names that weren't valid directories. This fix restores that behavior. In addition to the test for this case, the patch also adds a test for the default behavior of compileall when no arguments are provided, and fixes a bug in one of the previously added tests. ........

author	R. David Murray <rdmurray@bitdance.com>
date	Thu, 16 Dec 2010 19:10:16 +0000
parents	a9f0ec604c8a
children	3c9232a684ae

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"
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50076 diff changeset	171
44152 1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	172 spam = "test spam"
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	173 do_local()
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	174 print("After local assignment:", spam)
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	175 do_nonlocal()
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	176 print("After nonlocal assignment:", spam)
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	177 do_global()
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	178 print("After global assignment:", spam)
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	179
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	180 scope_test()
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	181 print("In global scope:", spam)
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	182
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	183 The output of the example code is::
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	184
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	185 After local assignment: test spam
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	186 After nonlocal assignment: nonlocal spam
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	187 After global assignment: nonlocal spam
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	188 In global scope: global spam
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	189
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	190 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	191 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	192 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	193 binding.
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	194
1e726aeab6a5 Document nonlocal statement. Written for GHOP by "Canadabear". Georg Brandl <georg@python.org> parents: 44098 diff changeset	195 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	196 :keyword:`global` assignment.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199 .. _tut-firstclasses:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201 A First Look at Classes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202 =======================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204 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	205 new semantics.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206
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 .. _tut-classdefinition:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210 Class Definition Syntax
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211 -----------------------
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 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	214
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215 class ClassName:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216 <statement-1>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217 .
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 <statement-N>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222 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	223 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	224 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	225
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226 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	227 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	228 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	229 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	230 methods --- again, this is explained later.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	232 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	233 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	234 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	235 function here.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237 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	238 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	239 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	240 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	241 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	242 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	243 example).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244
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 .. _tut-classobjects:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248 Class Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249 -------------
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 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	252 instantiation.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	254 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	255 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	256 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	257 definition looked like this::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259 class MyClass:
49180 c87b84db244c Forward-port of r66447. Georg Brandl <georg@python.org> parents: 48667 diff changeset	260 """A simple example class"""
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261 i = 12345
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 def f(self):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263 return 'hello world'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265 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	266 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	267 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	268 :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	269 the class: ``"A simple example class"``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	270
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	271 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	272 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	273 For example (assuming the above class)::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	274
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	275 x = MyClass()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277 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	278 variable ``x``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280 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	281 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	282 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	283 :meth:`__init__`, like this::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	285 def __init__(self):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286 self.data = []
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288 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	289 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	290 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	291
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	292 x = MyClass()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	293
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294 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	295 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	296 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	297
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	298 >>> class Complex:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	299 ... def __init__(self, realpart, imagpart):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	300 ... self.r = realpart
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	301 ... self.i = imagpart
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50076 diff changeset	302 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	303 >>> x = Complex(3.0, -4.5)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	304 >>> x.r, x.i
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	305 (3.0, -4.5)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	306
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 .. _tut-instanceobjects:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	309
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310 Instance Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311 ----------------
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 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	314 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	315 attribute names, data attributes and methods.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317 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	318 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	319 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	320 ``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	321 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	322
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323 x.counter = 1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324 while x.counter < 10:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325 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	326 print(x.counter)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327 del x.counter
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329 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	330 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	331 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	332 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	333 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	334 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	335
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336 .. index:: object: method
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338 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	339 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	340 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	341 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	342 ``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	343 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	344
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 .. _tut-methodobjects:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348 Method Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	349 --------------
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 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	352
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	353 x.f()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	354
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	355 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	356 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	357 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	358
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359 xf = x.f
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360 while True:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	361 print(xf())
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	363 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	364
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	365 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	366 ``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	367 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	368 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	369 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	370
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	371 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	372 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	373 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	374 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	375 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	376 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	377
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	378 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	379 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	380 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	381 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	382 (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	383 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	384 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	385 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	386 argument list.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	387
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	388
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	389 .. _tut-remarks:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	390
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391 Random Remarks
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	392 ==============
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	393
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44152 diff changeset	394 .. 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	395
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396 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	397 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	398 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	399 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	400 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	401 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	402
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	403 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	404 ("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	405 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	406 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	407 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	408 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	409 extensions to Python written in C.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	410
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411 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	412 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	413 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	414 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	415 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	416
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417 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	418 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	419 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	420 glancing through a method.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	421
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	422 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	423 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	424 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	425 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	426 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	427
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428 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	429 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	430 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	431 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	432
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	433 # Function defined outside the class
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	434 def f1(self, x, y):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	435 return min(x, x+y)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	436
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	437 class C:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	438 f = f1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	439 def g(self):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	440 return 'hello world'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	441 h = g
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	442
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	443 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	444 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	445 :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	446 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	447
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	448 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	449 argument::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	450
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	451 class Bag:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	452 def __init__(self):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	453 self.data = []
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	454 def add(self, x):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	455 self.data.append(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	456 def addtwice(self, x):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	457 self.add(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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	460 Methods may reference global names in the same way as ordinary functions. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	461 global scope associated with a method is the module containing the class
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	462 definition. (The class itself 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	463 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	464 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	465 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	466 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	467 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	468 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	469
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	470 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	471 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	472
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	473
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	474 .. _tut-inheritance:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	475
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	476 Inheritance
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	477 ===========
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 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	480 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	481 this::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	482
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	483 class DerivedClassName(BaseClassName):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	484 <statement-1>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	485 .
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	486 .
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 <statement-N>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	489
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	490 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	491 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	492 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	493 class is defined in another module::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	494
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	495 class DerivedClassName(modname.BaseClassName):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	496
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	497 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	498 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	499 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	500 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	501 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	502
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	503 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	504 ``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	505 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	506 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	507 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	508
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	509 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	510 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	511 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	512 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	513 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	514
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	515 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	516 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	517 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	518 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	519 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	520 scope.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	521
51776 d06a3ebf306f Merged revisions 69846 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 50566 diff changeset	522 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	523
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	524 * 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	525 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	526 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	527
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 * 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	529 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	530 ``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	531 subclass of :class:`int`.
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50076 diff changeset	532
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	533
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	534
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	535 .. _tut-multiple:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	536
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	537 Multiple Inheritance
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	538 --------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	539
43449 7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial. Georg Brandl <georg@python.org> parents: 43305 diff changeset	540 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	541 multiple base classes looks like this::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	542
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543 class DerivedClassName(Base1, Base2, Base3):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	544 <statement-1>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	545 .
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 <statement-N>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	549
43449 7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial. Georg Brandl <georg@python.org> parents: 43305 diff changeset	550 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	551 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	552 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	553 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	554 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	555 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	556
43449 7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial. Georg Brandl <georg@python.org> parents: 43305 diff changeset	557 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	558 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	559 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	560 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	561 single-inheritance languages.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	562
43155 335ef86a8c5c - document bytes() Georg Brandl <georg@python.org> parents: 43115 diff changeset	563 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	564 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	565 can be accessed through multiple paths from the bottommost class). For example,
335ef86a8c5c - document bytes() Georg Brandl <georg@python.org> parents: 43115 diff changeset	566 all classes inherit from :class:`object`, so any case of multiple inheritance
335ef86a8c5c - document bytes() Georg Brandl <georg@python.org> parents: 43115 diff changeset	567 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	568 from being accessed more than once, the dynamic algorithm linearizes the search
335ef86a8c5c - document bytes() Georg Brandl <georg@python.org> parents: 43115 diff changeset	569 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	570 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	571 class can be subclassed without affecting the precedence order of its parents).
335ef86a8c5c - document bytes() Georg Brandl <georg@python.org> parents: 43115 diff changeset	572 Taken together, these properties make it possible to design reliable and
335ef86a8c5c - document bytes() Georg Brandl <georg@python.org> parents: 43115 diff changeset	573 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	574 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	575
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 .. _tut-private:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	578
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	579 Private Variables
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	580 =================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	581
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	582 "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	583 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	584 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	585 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	586 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	587 to change without notice.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	588
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	589 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	590 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	591 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	592 ``__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	593 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	594 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	595 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	596 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	597
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	598 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	599 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	600 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	601
62984 8e42c7a5dab8 Merged revisions 82835 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 62962 diff changeset	602 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	603 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	604 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	605 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	606 ``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	607 ``__dict__`` directly.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	608
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	609
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	610 .. _tut-odds:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	611
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	612 Odds and Ends
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	613 =============
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	614
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	615 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	616 "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	617 will do nicely::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	618
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	619 class Employee:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	620 pass
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	621
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	622 john = Employee() # Create an empty employee record
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	623
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	624 # Fill the fields of the record
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	625 john.name = 'John Doe'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	626 john.dept = 'computer lab'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	627 john.salary = 1000
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	628
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	629 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	630 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	631 instance, if you have a function that formats some data from a file object, you
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	632 can define a class with methods :meth:`read` and :meth:`readline` that get the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	633 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	634
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44152 diff changeset	635 .. (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	636 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	637 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	638 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	639
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	640 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	641 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	642 corresponding to the method.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	643
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 .. _tut-exceptionclasses:
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 Exceptions Are Classes Too
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	648 ==========================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	649
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	650 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	651 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	652
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	653 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	654
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	655 raise Class
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	656
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	657 raise Instance
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	658
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	659 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	660 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	661
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	662 raise Class()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	663
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	664 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	665 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	666 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	667 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	668
48667 949b9a2b9867 #3525: 3.0 exception changes in tutorial. Georg Brandl <georg@python.org> parents: 48507 diff changeset	669 class B(Exception):
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	670 pass
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	671 class C(B):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	672 pass
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	673 class D(C):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	674 pass
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	675
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	676 for c in [B, C, D]:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	677 try:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	678 raise c()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	679 except D:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	680 print("D")
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	681 except C:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	682 print("C")
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	683 except B:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	684 print("B")
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	685
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	686 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	687 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	688
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	689 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	690 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	691 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	692
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	693
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	694 .. _tut-iterators:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	695
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	696 Iterators
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	697 =========
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	698
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	699 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	700 using a :keyword:`for` statement::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	701
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	702 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	703 print(element)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	704 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	705 print(element)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	706 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	707 print(key)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	708 for char in "123":
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	709 print(char)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	710 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	711 print(line)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	712
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	713 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	714 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	715 calls :func:`iter` on the container object. The function returns an iterator
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	716 object that defines the method :meth:`__next__` which accesses elements in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	717 container one at a time. When there are no more elements, :meth:`__next__`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	718 raises a :exc:`StopIteration` exception which tells the :keyword:`for` loop to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	719 terminate. You can call the :meth:`__next__` method using the :func:`next`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	720 builtin; this example shows how it all works::
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 >>> s = 'abc'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	723 >>> it = iter(s)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	724 >>> it
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	725 <iterator object at 0x00A1DB50>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	726 >>> next(it)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	727 'a'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	728 >>> next(it)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	729 'b'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	730 >>> next(it)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	731 'c'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	732 >>> next(it)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	733
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	734 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	735 File "<stdin>", line 1, in ?
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	736 next(it)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	737 StopIteration
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	738
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	739 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	740 iterator behavior to your classes. Define an :meth:`__iter__` method which
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	741 returns an object with a :meth:`__next__` method. If the class defines
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	742 :meth:`__next__`, then :meth:`__iter__` can just return ``self``::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	743
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	744 class Reverse:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	745 "Iterator for looping over a sequence backwards"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	746 def __init__(self, data):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	747 self.data = data
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	748 self.index = len(data)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	749 def __iter__(self):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	750 return self
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	751 def __next__(self):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	752 if self.index == 0:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	753 raise StopIteration
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	754 self.index = self.index - 1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	755 return self.data[self.index]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	756
63490 f46dcd8a3113 Merged revisions 82965 via svnmerge from Georg Brandl <georg@python.org> parents: 62984 diff changeset	757 >>> rev = Reverse('spam')
f46dcd8a3113 Merged revisions 82965 via svnmerge from Georg Brandl <georg@python.org> parents: 62984 diff changeset	758 >>> iter(rev)
f46dcd8a3113 Merged revisions 82965 via svnmerge from Georg Brandl <georg@python.org> parents: 62984 diff changeset	759 <__main__.Reverse object at 0x00A1DB50>
f46dcd8a3113 Merged revisions 82965 via svnmerge from Georg Brandl <georg@python.org> parents: 62984 diff changeset	760 >>> for char in rev:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	761 ... print(char)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	762 ...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	763 m
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	764 a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	765 p
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	766 s
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	767
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	768
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	769 .. _tut-generators:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	770
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	771 Generators
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	772 ==========
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	773
43737 3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43449 diff changeset	774 :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	775 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	776 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	777 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	778 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	779 easy to create::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	780
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	781 def reverse(data):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	782 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	783 yield data[index]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	784
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	785 >>> 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	786 ... print(char)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	787 ...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	788 f
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	789 l
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	790 o
50566 ea7e307ddd51 Merged revisions 68229 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	791 g
42604 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 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	794 iterators as described in the previous section. What makes generators so
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	795 compact is that the :meth:`__iter__` and :meth:`__next__` methods are created
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	796 automatically.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	797
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	798 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	799 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	800 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	801 and ``self.data``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	802
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	803 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	804 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	805 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	806 than writing a regular function.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	807
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	808
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	809 .. _tut-genexps:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	810
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	811 Generator Expressions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	812 =====================
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 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	815 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	816 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	817 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	818 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	819 than equivalent list comprehensions.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	820
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	821 Examples::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	822
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	823 >>> 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	824 285
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	825
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	826 >>> xvec = [10, 20, 30]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	827 >>> yvec = [7, 5, 3]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	828 >>> 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	829 260
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	830
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	831 >>> 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	832 >>> 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	833
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	834 >>> 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	835
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	836 >>> 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	837
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	838 >>> data = 'golf'
43201 4902671dd678 Tutorial formatting patch by Robin Stocker. Georg Brandl <georg@python.org> parents: 43155 diff changeset	839 >>> 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	840 ['f', 'l', 'o', 'g']
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	841
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	842
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	843
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	844 .. rubric:: Footnotes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	845
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	846 .. [#] 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	847 :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	848 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	849 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	850 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	851

Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/classes.rst @ 66978:aed2bbafa550 3.1