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

annotate Doc/tutorial/classes.rst @ 63490:f46dcd8a3113 3.1

Merged revisions 82965 via svnmerge from svn+ssh://svn.python.org/python/branches/py3k ........ r82965 | georg.brandl | 2010-07-19 13:28:05 +0200 (Mo, 19 Jul 2010) | 1 line Clarification. Yay importlib! ........

author	Georg Brandl <georg@python.org>
date	Sun, 01 Aug 2010 21:28:39 +0000
parents	8e42c7a5dab8
children	90e1735df4d9

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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7 Python's class mechanism adds classes to the language with a minimum of new
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 syntax and semantics. It is a mixture of the class mechanisms found in C++ and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9 Modula-3. As is true for modules, classes in Python do not put an absolute
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10 barrier between definition and user, but rather rely on the politeness of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 user not to "break into the definition." The most important features of classes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12 are retained with full power, however: the class inheritance mechanism allows
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13 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	14 class or classes, and a method can call the method of a base class with the same
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	15 name. Objects can contain an arbitrary amount of data.
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
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	18 public (except see below :ref:`tut-private`),
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	19 and all member functions are virtual. As in Modula-3, there are no shorthands
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	20 for referencing the object's members from its methods: the method function 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	21 declared with an explicit first argument representing the object, which 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	22 provided implicitly by the call. As in Smalltalk, classes themselves are
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	23 objects. This provides semantics for importing and renaming. Unlike C++ and
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	24 Modula-3, built-in types can be used as base classes for extension by the user.
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	25 Also, like in C++, most built-in operators with special syntax (arithmetic
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26 operators, subscripting etc.) can be redefined for class instances.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68 namespaces are: the set of built-in names (functions such as :func:`abs`, and
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 @ 63490:f46dcd8a3113 3.1