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

annotate Doc/tutorial/classes.rst @ 80661:94de77bd0b4b 2.7

Issue #16194: document imp.load_dynamic problems when read several extension modules from the same binary object file.

author	Andrew Svetlov <andrew.svetlov@gmail.com>
date	Thu, 29 Nov 2012 19:51:28 +0200
parents	15cb8d80ecc8
children	29627bd5b333

rev	line source
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1 .. _tut-classes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3 *******
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 Classes
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 *******
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6
66457 a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 63608 diff changeset	7 Compared with other programming languages, Python's class mechanism adds classes
a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 63608 diff changeset	8 with a minimum of new syntax and semantics. It is a mixture of the class
a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 63608 diff changeset	9 mechanisms found in C++ and Modula-3. Python classes provide all the standard
a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 63608 diff changeset	10 features of Object Oriented Programming: the class inheritance mechanism allows
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 multiple base classes, a derived class can override any methods of its base
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12 class or classes, and a method can call the method of a base class with the same
66457 a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 63608 diff changeset	13 name. Objects can contain arbitrary amounts and kinds of data. As is true for
a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 63608 diff changeset	14 modules, classes partake of the dynamic nature of Python: they are created at
a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 63608 diff changeset	15 runtime, and can be modified further after creation.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16
66457 a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 63608 diff changeset	17 In C++ terminology, normally class members (including the data members) are
a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 63608 diff changeset	18 public (except see below :ref:`tut-private`), and all member functions are
a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 63608 diff changeset	19 virtual. As in Modula-3, there are no shorthands for referencing the object's
a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 63608 diff changeset	20 members from its methods: the method function is declared with an explicit first
a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 63608 diff changeset	21 argument representing the object, which is provided implicitly by the call. As
a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 63608 diff changeset	22 in Smalltalk, classes themselves are objects. This provides semantics for
a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 63608 diff changeset	23 importing and renaming. Unlike C++ and Modula-3, built-in types can be used as
a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 63608 diff changeset	24 base classes for extension by the user. Also, like in C++, most built-in
a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 63608 diff changeset	25 operators with special syntax (arithmetic operators, subscripting etc.) can be
a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 63608 diff changeset	26 redefined for class instances.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27
56819 9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	28 (Lacking universally accepted terminology to talk about classes, I will make
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	29 occasional use of Smalltalk and C++ terms. I would use Modula-3 terms, since
42603 c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31 expect that few readers have heard of it.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32
56819 9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	33
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	34 .. _tut-object:
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	35
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	36 A Word About Names and Objects
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	37 ==============================
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	38
42603 c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 when dealing with immutable basic types (numbers, strings, tuples). However,
56819 9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	43 aliasing has a possibly surprising effect on the semantics of Python code
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	44 involving mutable objects such as lists, dictionaries, and most other types.
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	45 This is usually used to the benefit of the program, since aliases behave like
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	46 pointers in some respects. For example, passing an object is cheap since only a
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	47 pointer is passed by the implementation; and if a function modifies an object
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	48 passed as an argument, the caller will see the change --- this eliminates the
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	49 need for two different argument passing mechanisms as in Pascal.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52 .. _tut-scopes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53
56820 85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from Georg Brandl <georg@python.org> parents: 56819 diff changeset	54 Python Scopes and Namespaces
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from Georg Brandl <georg@python.org> parents: 56819 diff changeset	55 ============================
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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.
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61 programmer.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63 Let's begin with some definitions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
63609 a9cd2550ff40 Merged revisions 83593 via svnmerge from Georg Brandl <georg@python.org> parents: 63503 diff changeset	68 namespaces are: the set of built-in names (containing functions such as :func:`abs`, and
42603 c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
56819 9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	73 different modules may both define a function ``maximize`` without confusion ---
42603 c62f6669ae22 Move the 2.6 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.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78 ``z``. Strictly speaking, references to names in modules are attribute
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 references: in the expression ``modname.funcname``, ``modname`` is a module
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82 defined in the module: they share the same namespace! [#]_
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85 attributes is possible. Module attributes are writable: you can write
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89
56820 85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from Georg Brandl <georg@python.org> parents: 56819 diff changeset	90 Namespaces are created at different moments and have different lifetimes. The
42603 c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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,
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98 called :mod:`__builtin__`.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104 local namespace.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108 name attempts to find the name in the namespace.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
56819 9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	112 are directly accessible:
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	113
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	114 * the innermost scope, which is searched first, contains the local names
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	115 * the scopes of any enclosing functions, which are searched starting with the
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	116 nearest enclosing scope, contains non-local, but also non-global names
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	117 * the next-to-last scope contains the current module's global names
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	118 * the outermost scope (searched last) is the namespace containing built-in names
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121 the middle scope containing the module's global names. Otherwise, all variables
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122 found outside of the innermost scope are read-only (an attempt to write to such
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123 a variable will simply create a new local variable in the innermost scope,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124 leaving the identically named outer variable unchanged).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126 Usually, the local scope references the local names of the (textually) current
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127 function. Outside functions, the local scope references the same namespace as
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128 the global scope: the module's namespace. Class definitions place yet another
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129 namespace in the local scope.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131 It is important to realize that scopes are determined textually: the global
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132 scope of a function defined in a module is that module's namespace, no matter
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133 from where or by what alias the function is called. On the other hand, the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134 actual search for names is done dynamically, at run time --- however, the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135 language definition is evolving towards static name resolution, at "compile"
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136 time, so don't rely on dynamic name resolution! (In fact, local variables are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137 already determined statically.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138
56819 9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	139 A special quirk of Python is that -- if no :keyword:`global` statement is in
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	140 effect -- assignments to names always go into the innermost scope. Assignments
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	141 do not copy data --- they just bind names to objects. The same is true for
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	142 deletions: the statement ``del x`` removes the binding of ``x`` from the
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	143 namespace referenced by the local scope. In fact, all operations that introduce
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	144 new names use the local scope: in particular, :keyword:`import` statements and
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	145 function definitions bind the module or function name in the local scope. (The
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	146 :keyword:`global` statement can be used to indicate that particular variables
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	147 live in the global scope.)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	148
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 .. _tut-firstclasses:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 A First Look at Classes
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153 =======================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155 Classes introduce a little bit of new syntax, three new object types, and some
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156 new semantics.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	157
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159 .. _tut-classdefinition:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161 Class Definition Syntax
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162 -----------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164 The simplest form of class definition looks like this::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	166 class ClassName:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167 <statement-1>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168 .
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169 .
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170 .
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171 <statement-N>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	172
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	173 Class definitions, like function definitions (:keyword:`def` statements) must be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	174 executed before they have any effect. (You could conceivably place a class
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	175 definition in a branch of an :keyword:`if` statement, or inside a function.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	176
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	177 In practice, the statements inside a class definition will usually be function
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	178 definitions, but other statements are allowed, and sometimes useful --- we'll
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179 come back to this later. The function definitions inside a class normally have
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	180 a peculiar form of argument list, dictated by the calling conventions for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	181 methods --- again, this is explained later.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	183 When a class definition is entered, a new namespace is created, and used as the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184 local scope --- thus, all assignments to local variables go into this new
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185 namespace. In particular, function definitions bind the name of the new
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186 function here.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188 When a class definition is left normally (via the end), a class object is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	189 created. This is basically a wrapper around the contents of the namespace
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	190 created by the class definition; we'll learn more about class objects in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191 next section. The original local scope (the one in effect just before the class
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	192 definition was entered) is reinstated, and the class object is bound here to the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193 class name given in the class definition header (:class:`ClassName` in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194 example).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	195
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197 .. _tut-classobjects:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199 Class Objects
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200 -------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202 Class objects support two kinds of operations: attribute references and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203 instantiation.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205 Attribute references use the standard syntax used for all attribute references
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206 in Python: ``obj.name``. Valid attribute names are all the names that were in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207 the class's namespace when the class object was created. So, if the class
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208 definition looked like this::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210 class MyClass:
49179 feb7bde1a4d9 Incorporate some suggestions by Tait Stevens. Georg Brandl <georg@python.org> parents: 48041 diff changeset	211 """A simple example class"""
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212 i = 12345
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213 def f(self):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214 return 'hello world'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216 then ``MyClass.i`` and ``MyClass.f`` are valid attribute references, returning
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217 an integer and a function object, respectively. Class attributes can also be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 assigned to, so you can change the value of ``MyClass.i`` by assignment.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219 :attr:`__doc__` is also a valid attribute, returning the docstring belonging to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220 the class: ``"A simple example class"``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222 Class instantiation uses function notation. Just pretend that the class
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223 object is a parameterless function that returns a new instance of the class.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224 For example (assuming the above class)::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226 x = MyClass()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228 creates a new instance of the class and assigns this object to the local
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229 variable ``x``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231 The instantiation operation ("calling" a class object) creates an empty object.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	232 Many classes like to create objects with instances customized to a specific
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233 initial state. Therefore a class may define a special method named
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234 :meth:`__init__`, like this::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236 def __init__(self):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237 self.data = []
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239 When a class defines an :meth:`__init__` method, class instantiation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240 automatically invokes :meth:`__init__` for the newly-created class instance. So
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241 in this example, a new, initialized instance can be obtained by::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243 x = MyClass()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245 Of course, the :meth:`__init__` method may have arguments for greater
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246 flexibility. In that case, arguments given to the class instantiation operator
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247 are passed on to :meth:`__init__`. For example, ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249 >>> class Complex:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250 ... def __init__(self, realpart, imagpart):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	251 ... self.r = realpart
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	252 ... self.i = imagpart
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49179 diff changeset	253 ...
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	254 >>> x = Complex(3.0, -4.5)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	255 >>> x.r, x.i
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	256 (3.0, -4.5)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	257
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259 .. _tut-instanceobjects:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261 Instance Objects
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 ----------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264 Now what can we do with instance objects? The only operations understood by
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265 instance objects are attribute references. There are two kinds of valid
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266 attribute names, data attributes and methods.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	267
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	268 data attributes correspond to "instance variables" in Smalltalk, and to "data
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269 members" in C++. Data attributes need not be declared; like local variables,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	270 they spring into existence when they are first assigned to. For example, if
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	271 ``x`` is the instance of :class:`MyClass` created above, the following piece of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	272 code will print the value ``16``, without leaving a trace::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	274 x.counter = 1
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	275 while x.counter < 10:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276 x.counter = x.counter * 2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277 print x.counter
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278 del x.counter
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280 The other kind of instance attribute reference is a method. A method is a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281 function that "belongs to" an object. (In Python, the term method is not unique
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	282 to class instances: other object types can have methods as well. For example,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	283 list objects have methods called append, insert, remove, sort, and so on.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284 However, in the following discussion, we'll use the term method exclusively to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	285 mean methods of class instance objects, unless explicitly stated otherwise.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287 .. index:: object: method
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	289 Valid method names of an instance object depend on its class. By definition,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	290 all attributes of a class that are function objects define corresponding
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	291 methods of its instances. So in our example, ``x.f`` is a valid method
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	292 reference, since ``MyClass.f`` is a function, but ``x.i`` is not, since
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	293 ``MyClass.i`` is not. But ``x.f`` is not the same thing as ``MyClass.f`` --- it
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294 is a method object, not a function object.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	295
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	296
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	297 .. _tut-methodobjects:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	298
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	299 Method Objects
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	300 --------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	301
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	302 Usually, a method is called right after it is bound::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	303
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	304 x.f()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	305
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	306 In the :class:`MyClass` example, this will return the string ``'hello world'``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	307 However, it is not necessary to call a method right away: ``x.f`` is a method
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	308 object, and can be stored away and called at a later time. For example::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	309
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310 xf = x.f
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311 while True:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312 print xf()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314 will continue to print ``hello world`` until the end of time.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316 What exactly happens when a method is called? You may have noticed that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317 ``x.f()`` was called without an argument above, even though the function
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318 definition for :meth:`f` specified an argument. What happened to the argument?
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319 Surely Python raises an exception when a function that requires an argument is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320 called without any --- even if the argument isn't actually used...
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322 Actually, you may have guessed the answer: the special thing about methods is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323 that the object is passed as the first argument of the function. In our
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324 example, the call ``x.f()`` is exactly equivalent to ``MyClass.f(x)``. In
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325 general, calling a method with a list of n arguments is equivalent to calling
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326 the corresponding function with an argument list that is created by inserting
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327 the method's object before the first argument.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329 If you still don't understand how methods work, a look at the implementation can
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330 perhaps clarify matters. When an instance attribute is referenced that isn't a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331 data attribute, its class is searched. If the name denotes a valid class
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	332 attribute that is a function object, a method object is created by packing
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333 (pointers to) the instance object and the function object just found together in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334 an abstract object: this is the method object. When the method object is called
56820 85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from Georg Brandl <georg@python.org> parents: 56819 diff changeset	335 with an argument list, a new argument list is constructed from the instance
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from Georg Brandl <georg@python.org> parents: 56819 diff changeset	336 object and the argument list, and the function object is called with this new
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from Georg Brandl <georg@python.org> parents: 56819 diff changeset	337 argument list.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	339
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340 .. _tut-remarks:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	341
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342 Random Remarks
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	343 ==============
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43631 diff changeset	345 .. These should perhaps be placed more carefully...
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347 Data attributes override method attributes with the same name; to avoid
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348 accidental name conflicts, which may cause hard-to-find bugs in large programs,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	349 it is wise to use some kind of convention that minimizes the chance of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	350 conflicts. Possible conventions include capitalizing method names, prefixing
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	351 data attribute names with a small unique string (perhaps just an underscore), or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	352 using verbs for methods and nouns for data attributes.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	353
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	354 Data attributes may be referenced by methods as well as by ordinary users
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	355 ("clients") of an object. In other words, classes are not usable to implement
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356 pure abstract data types. In fact, nothing in Python makes it possible to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357 enforce data hiding --- it is all based upon convention. (On the other hand,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358 the Python implementation, written in C, can completely hide implementation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359 details and control access to an object if necessary; this can be used by
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360 extensions to Python written in C.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	361
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362 Clients should use data attributes with care --- clients may mess up invariants
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	363 maintained by the methods by stamping on their data attributes. Note that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	364 clients may add data attributes of their own to an instance object without
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	365 affecting the validity of the methods, as long as name conflicts are avoided ---
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	366 again, a naming convention can save a lot of headaches here.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	367
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	368 There is no shorthand for referencing data attributes (or other methods!) from
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	369 within methods. I find that this actually increases the readability of methods:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	370 there is no chance of confusing local variables and instance variables when
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	371 glancing through a method.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	372
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	373 Often, the first argument of a method is called ``self``. This is nothing more
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	374 than a convention: the name ``self`` has absolutely no special meaning to
56819 9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	375 Python. Note, however, that by not following the convention your code may be
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	376 less readable to other Python programmers, and it is also conceivable that a
56819 9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	377 class browser program might be written that relies upon such a convention.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	378
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	379 Any function object that is a class attribute defines a method for instances of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	380 that class. It is not necessary that the function definition is textually
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	381 enclosed in the class definition: assigning a function object to a local
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	382 variable in the class is also ok. For example::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	383
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	384 # Function defined outside the class
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	385 def f1(self, x, y):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	386 return min(x, x+y)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	387
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	388 class C:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	389 f = f1
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	390 def g(self):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391 return 'hello world'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	392 h = g
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	393
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	394 Now ``f``, ``g`` and ``h`` are all attributes of class :class:`C` that refer to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	395 function objects, and consequently they are all methods of instances of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396 :class:`C` --- ``h`` being exactly equivalent to ``g``. Note that this practice
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	397 usually only serves to confuse the reader of a program.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	398
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	399 Methods may call other methods by using method attributes of the ``self``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400 argument::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	401
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	402 class Bag:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	403 def __init__(self):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	404 self.data = []
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405 def add(self, x):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	406 self.data.append(x)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	407 def addtwice(self, x):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408 self.add(x)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409 self.add(x)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	410
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411 Methods may reference global names in the same way as ordinary functions. The
74335 10a5165103f9 Minor correction. Closes #11418 Terry Jan Reedy <tjreedy@udel.edu> parents: 71587 diff changeset	412 global scope associated with a method is the module containing its
10a5165103f9 Minor correction. Closes #11418 Terry Jan Reedy <tjreedy@udel.edu> parents: 71587 diff changeset	413 definition. (A class is never used as a global scope.) While one
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414 rarely encounters a good reason for using global data in a method, there are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	415 many legitimate uses of the global scope: for one thing, functions and modules
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416 imported into the global scope can be used by methods, as well as functions and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417 classes defined in it. Usually, the class containing the method is itself
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	418 defined in this global scope, and in the next section we'll find some good
56819 9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	419 reasons why a method would want to reference its own class.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	420
45688 a4c265565cb6 Add isinstance/issubclass to tutorial. Georg Brandl <georg@python.org> parents: 45687 diff changeset	421 Each value is an object, and therefore has a class (also called its type).
a4c265565cb6 Add isinstance/issubclass to tutorial. Georg Brandl <georg@python.org> parents: 45687 diff changeset	422 It is stored as ``object.__class__``.
a4c265565cb6 Add isinstance/issubclass to tutorial. Georg Brandl <georg@python.org> parents: 45687 diff changeset	423
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	424
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	425 .. _tut-inheritance:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	426
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427 Inheritance
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428 ===========
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	429
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	430 Of course, a language feature would not be worthy of the name "class" without
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	431 supporting inheritance. The syntax for a derived class definition looks like
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	432 this::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	433
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	434 class DerivedClassName(BaseClassName):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	435 <statement-1>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	436 .
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	437 .
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	438 .
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	439 <statement-N>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	440
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	441 The name :class:`BaseClassName` must be defined in a scope containing the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	442 derived class definition. In place of a base class name, other arbitrary
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	443 expressions are also allowed. This can be useful, for example, when the base
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	444 class is defined in another module::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	445
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	446 class DerivedClassName(modname.BaseClassName):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	447
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	448 Execution of a derived class definition proceeds the same as for a base class.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	449 When the class object is constructed, the base class is remembered. This is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	450 used for resolving attribute references: if a requested attribute is not found
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	451 in the class, the search proceeds to look in the base class. This rule is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	452 applied recursively if the base class itself is derived from some other class.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	453
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	454 There's nothing special about instantiation of derived classes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	455 ``DerivedClassName()`` creates a new instance of the class. Method references
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	456 are resolved as follows: the corresponding class attribute is searched,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	457 descending down the chain of base classes if necessary, and the method reference
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	458 is valid if this yields a function object.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	459
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	460 Derived classes may override methods of their base classes. Because methods
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	461 have no special privileges when calling other methods of the same object, a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	462 method of a base class that calls another method defined in the same base class
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	463 may end up calling a method of a derived class that overrides it. (For C++
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43631 diff changeset	464 programmers: all methods in Python are effectively ``virtual``.)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	465
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	466 An overriding method in a derived class may in fact want to extend rather than
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	467 simply replace the base class method of the same name. There is a simple way to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	468 call the base class method directly: just call ``BaseClassName.methodname(self,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	469 arguments)``. This is occasionally useful to clients as well. (Note that this
56819 9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	470 only works if the base class is accessible as ``BaseClassName`` in the global
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	471 scope.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	472
55049 74c0a78114ae Merged revisions 69846 via svnmerge from Jesus Cea <jcea@jcea.es> parents: 50522 diff changeset	473 Python has two built-in functions that work with inheritance:
45688 a4c265565cb6 Add isinstance/issubclass to tutorial. Georg Brandl <georg@python.org> parents: 45687 diff changeset	474
56819 9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	475 * Use :func:`isinstance` to check an instance's type: ``isinstance(obj, int)``
45688 a4c265565cb6 Add isinstance/issubclass to tutorial. Georg Brandl <georg@python.org> parents: 45687 diff changeset	476 will be ``True`` only if ``obj.__class__`` is :class:`int` or some class
a4c265565cb6 Add isinstance/issubclass to tutorial. Georg Brandl <georg@python.org> parents: 45687 diff changeset	477 derived from :class:`int`.
a4c265565cb6 Add isinstance/issubclass to tutorial. Georg Brandl <georg@python.org> parents: 45687 diff changeset	478
a4c265565cb6 Add isinstance/issubclass to tutorial. Georg Brandl <georg@python.org> parents: 45687 diff changeset	479 * Use :func:`issubclass` to check class inheritance: ``issubclass(bool, int)``
a4c265565cb6 Add isinstance/issubclass to tutorial. Georg Brandl <georg@python.org> parents: 45687 diff changeset	480 is ``True`` since :class:`bool` is a subclass of :class:`int`. However,
a4c265565cb6 Add isinstance/issubclass to tutorial. Georg Brandl <georg@python.org> parents: 45687 diff changeset	481 ``issubclass(unicode, str)`` is ``False`` since :class:`unicode` is not a
a4c265565cb6 Add isinstance/issubclass to tutorial. Georg Brandl <georg@python.org> parents: 45687 diff changeset	482 subclass of :class:`str` (they only share a common ancestor,
a4c265565cb6 Add isinstance/issubclass to tutorial. Georg Brandl <georg@python.org> parents: 45687 diff changeset	483 :class:`basestring`).
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49179 diff changeset	484
45688 a4c265565cb6 Add isinstance/issubclass to tutorial. Georg Brandl <georg@python.org> parents: 45687 diff changeset	485
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	486
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	487 .. _tut-multiple:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	488
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	489 Multiple Inheritance
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	490 --------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	491
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	492 Python supports a limited form of multiple inheritance as well. A class
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	493 definition with multiple base classes looks like this::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	494
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	495 class DerivedClassName(Base1, Base2, Base3):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	496 <statement-1>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	497 .
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	498 .
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499 .
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	500 <statement-N>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	501
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	502 For old-style classes, the only rule is depth-first, left-to-right. Thus, if an
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	503 attribute is not found in :class:`DerivedClassName`, it is searched in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	504 :class:`Base1`, then (recursively) in the base classes of :class:`Base1`, and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	505 only if it is not found there, it is searched in :class:`Base2`, and so on.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	506
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	507 (To some people breadth first --- searching :class:`Base2` and :class:`Base3`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	508 before the base classes of :class:`Base1` --- looks more natural. However, this
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	509 would require you to know whether a particular attribute of :class:`Base1` is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	510 actually defined in :class:`Base1` or in one of its base classes before you can
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	511 figure out the consequences of a name conflict with an attribute of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	512 :class:`Base2`. The depth-first rule makes no differences between direct and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	513 inherited attributes of :class:`Base1`.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	514
43631 03056365a1b6 Add :term:s for "new-style class". Georg Brandl <georg@python.org> parents: 43629 diff changeset	515 For :term:`new-style class`\es, the method resolution order changes dynamically
03056365a1b6 Add :term:s for "new-style class". Georg Brandl <georg@python.org> parents: 43629 diff changeset	516 to support cooperative calls to :func:`super`. This approach is known in some
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	517 other multiple-inheritance languages as call-next-method and is more powerful
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	518 than the super call found in single-inheritance languages.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	519
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	520 With new-style classes, dynamic ordering is necessary because all cases of
68836 b8e556541db3 Fix typo spotted by Sandro Tosi Éric Araujo <merwok@netwok.org> parents: 68256 diff changeset	521 multiple inheritance exhibit one or more diamond relationships (where at
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	522 least one of the parent classes can be accessed through multiple paths from the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	523 bottommost class). For example, all new-style classes inherit from
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	524 :class:`object`, so any case of multiple inheritance provides more than one path
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	525 to reach :class:`object`. To keep the base classes from being accessed more
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	526 than once, the dynamic algorithm linearizes the search order in a way that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	527 preserves the left-to-right ordering specified in each class, that calls each
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	528 parent only once, and that is monotonic (meaning that a class can be subclassed
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	529 without affecting the precedence order of its parents). Taken together, these
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	530 properties make it possible to design reliable and extensible classes with
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	531 multiple inheritance. For more detail, see
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	532 http://www.python.org/download/releases/2.3/mro/.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	533
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	534
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	535 .. _tut-private:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	536
76514 15cb8d80ecc8 Improve section heading for better discoverability. Raymond Hettinger <python@rcn.com> parents: 74335 diff changeset	537 Private Variables and Class-local References
15cb8d80ecc8 Improve section heading for better discoverability. Raymond Hettinger <python@rcn.com> parents: 74335 diff changeset	538 ============================================
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	539
56819 9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	540 "Private" instance variables that cannot be accessed except from inside an
62280 a10a7ce97f45 Fix punctuation. Georg Brandl <georg@python.org> parents: 55789 diff changeset	541 object don't exist in Python. However, there is a convention that is followed
56819 9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	542 by most Python code: a name prefixed with an underscore (e.g. ``_spam``) should
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	543 be treated as a non-public part of the API (whether it is a function, a method
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	544 or a data member). It should be considered an implementation detail and subject
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	545 to change without notice.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	546
56819 9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	547 Since there is a valid use-case for class-private members (namely to avoid name
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	548 clashes of names with names defined by subclasses), there is limited support for
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	549 such a mechanism, called :dfn:`name mangling`. Any identifier of the form
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	550 ``__spam`` (at least two leading underscores, at most one trailing underscore)
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	551 is textually replaced with ``_classname__spam``, where ``classname`` is the
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	552 current class name with leading underscore(s) stripped. This mangling is done
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	553 without regard to the syntactic position of the identifier, as long as it
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	554 occurs within the definition of a class.
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	555
70973 68bc3c5960a4 Issue 12086: add example showing how to use name mangling. Raymond Hettinger <python@rcn.com> parents: 69737 diff changeset	556 Name mangling is helpful for letting subclasses override methods without
68bc3c5960a4 Issue 12086: add example showing how to use name mangling. Raymond Hettinger <python@rcn.com> parents: 69737 diff changeset	557 breaking intraclass method calls. For example::
68bc3c5960a4 Issue 12086: add example showing how to use name mangling. Raymond Hettinger <python@rcn.com> parents: 69737 diff changeset	558
71587 140e4800110b Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70973 diff changeset	559 class Mapping:
140e4800110b Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70973 diff changeset	560 def __init__(self, iterable):
140e4800110b Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70973 diff changeset	561 self.items_list = []
140e4800110b Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70973 diff changeset	562 self.__update(iterable)
70973 68bc3c5960a4 Issue 12086: add example showing how to use name mangling. Raymond Hettinger <python@rcn.com> parents: 69737 diff changeset	563
71587 140e4800110b Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70973 diff changeset	564 def update(self, iterable):
140e4800110b Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70973 diff changeset	565 for item in iterable:
140e4800110b Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70973 diff changeset	566 self.items_list.append(item)
70973 68bc3c5960a4 Issue 12086: add example showing how to use name mangling. Raymond Hettinger <python@rcn.com> parents: 69737 diff changeset	567
71587 140e4800110b Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70973 diff changeset	568 __update = update # private copy of original update() method
70973 68bc3c5960a4 Issue 12086: add example showing how to use name mangling. Raymond Hettinger <python@rcn.com> parents: 69737 diff changeset	569
71587 140e4800110b Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70973 diff changeset	570 class MappingSubclass(Mapping):
70973 68bc3c5960a4 Issue 12086: add example showing how to use name mangling. Raymond Hettinger <python@rcn.com> parents: 69737 diff changeset	571
71587 140e4800110b Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70973 diff changeset	572 def update(self, keys, values):
140e4800110b Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70973 diff changeset	573 # provides new signature for update()
140e4800110b Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70973 diff changeset	574 # but does not break __init__()
140e4800110b Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70973 diff changeset	575 for item in zip(keys, values):
140e4800110b Make indentation comply with our style guide and the rest of the file Éric Araujo <merwok@netwok.org> parents: 70973 diff changeset	576 self.items_list.append(item)
70973 68bc3c5960a4 Issue 12086: add example showing how to use name mangling. Raymond Hettinger <python@rcn.com> parents: 69737 diff changeset	577
56819 9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	578 Note that the mangling rules are designed mostly to avoid accidents; it still is
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	579 possible to access or modify a variable that is considered private. This can
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	580 even be useful in special circumstances, such as in the debugger.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	581
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	582 Notice that code passed to ``exec``, ``eval()`` or ``execfile()`` does not
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	583 consider the classname of the invoking class to be the current class; this is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	584 similar to the effect of the ``global`` statement, the effect of which is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	585 likewise restricted to code that is byte-compiled together. The same
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	586 restriction applies to ``getattr()``, ``setattr()`` and ``delattr()``, as well
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	587 as when referencing ``__dict__`` directly.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	588
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	589
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	590 .. _tut-odds:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	591
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	592 Odds and Ends
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	593 =============
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	594
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	595 Sometimes it is useful to have a data type similar to the Pascal "record" or C
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	596 "struct", bundling together a few named data items. An empty class definition
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	597 will do nicely::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	598
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	599 class Employee:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	600 pass
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	601
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	602 john = Employee() # Create an empty employee record
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	603
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	604 # Fill the fields of the record
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	605 john.name = 'John Doe'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	606 john.dept = 'computer lab'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	607 john.salary = 1000
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	608
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	609 A piece of Python code that expects a particular abstract data type can often be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	610 passed a class that emulates the methods of that data type instead. For
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	611 instance, if you have a function that formats some data from a file object, you
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	612 can define a class with methods :meth:`read` and :meth:`readline` that get the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	613 data from a string buffer instead, and pass it as an argument.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	614
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43631 diff changeset	615 .. (Unfortunately, this technique has its limitations: a class can't define
3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43631 diff changeset	616 operations that are accessed by special syntax such as sequence subscripting
3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43631 diff changeset	617 or arithmetic operators, and assigning such a "pseudo-file" to sys.stdin will
3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43631 diff changeset	618 not cause the interpreter to read further input from it.)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	619
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	620 Instance method objects have attributes, too: ``m.im_self`` is the instance
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	621 object with the method :meth:`m`, and ``m.im_func`` is the function object
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	622 corresponding to the method.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	623
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	624
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	625 .. _tut-exceptionclasses:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	626
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	627 Exceptions Are Classes Too
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	628 ==========================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	629
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	630 User-defined exceptions are identified by classes as well. Using this mechanism
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	631 it is possible to create extensible hierarchies of exceptions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	632
56819 9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	633 There are two new valid (semantic) forms for the :keyword:`raise` statement::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	634
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	635 raise Class, instance
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	636
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	637 raise instance
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	638
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	639 In the first form, ``instance`` must be an instance of :class:`Class` or of a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	640 class derived from it. The second form is a shorthand for::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	641
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	642 raise instance.__class__, instance
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	643
56819 9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	644 A class in an :keyword:`except` clause is compatible with an exception if it is
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	645 the same class or a base class thereof (but not the other way around --- an
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	646 except clause listing a derived class is not compatible with a base class). For
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 55049 diff changeset	647 example, the following code will print B, C, D in that order::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	648
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	649 class B:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	650 pass
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	651 class C(B):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	652 pass
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	653 class D(C):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	654 pass
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	655
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	656 for c in [B, C, D]:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	657 try:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	658 raise c()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	659 except D:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	660 print "D"
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	661 except C:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	662 print "C"
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	663 except B:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	664 print "B"
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	665
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	666 Note that if the except clauses were reversed (with ``except B`` first), it
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	667 would have printed B, B, B --- the first matching except clause is triggered.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	668
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	669 When an error message is printed for an unhandled exception, the exception's
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	670 class name is printed, then a colon and a space, and finally the instance
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	671 converted to a string using the built-in function :func:`str`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	672
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	673
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	674 .. _tut-iterators:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	675
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	676 Iterators
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	677 =========
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	678
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	679 By now you have probably noticed that most container objects can be looped over
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	680 using a :keyword:`for` statement::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	681
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	682 for element in [1, 2, 3]:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	683 print element
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	684 for element in (1, 2, 3):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	685 print element
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	686 for key in {'one':1, 'two':2}:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	687 print key
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	688 for char in "123":
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	689 print char
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	690 for line in open("myfile.txt"):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	691 print line
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	692
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	693 This style of access is clear, concise, and convenient. The use of iterators
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	694 pervades and unifies Python. Behind the scenes, the :keyword:`for` statement
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	695 calls :func:`iter` on the container object. The function returns an iterator
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	696 object that defines the method :meth:`next` which accesses elements in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	697 container one at a time. When there are no more elements, :meth:`next` raises a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	698 :exc:`StopIteration` exception which tells the :keyword:`for` loop to terminate.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	699 This example shows how it all works::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	700
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	701 >>> s = 'abc'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	702 >>> it = iter(s)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	703 >>> it
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	704 <iterator object at 0x00A1DB50>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	705 >>> it.next()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	706 'a'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	707 >>> it.next()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	708 'b'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	709 >>> it.next()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	710 'c'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	711 >>> it.next()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	712 Traceback (most recent call last):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	713 File "<stdin>", line 1, in ?
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	714 it.next()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	715 StopIteration
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	716
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	717 Having seen the mechanics behind the iterator protocol, it is easy to add
63503 e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	718 iterator behavior to your classes. Define an :meth:`__iter__` method which
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	719 returns an object with a :meth:`next` method. If the class defines
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	720 :meth:`next`, then :meth:`__iter__` can just return ``self``::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	721
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	722 class Reverse:
69737 3d0a41407abf Split combined code/doctest code blocks in two blocks, to enable proper highlighting. Georg Brandl <georg@python.org> parents: 68836 diff changeset	723 """Iterator for looping over a sequence backwards."""
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	724 def __init__(self, data):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	725 self.data = data
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	726 self.index = len(data)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	727 def __iter__(self):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	728 return self
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	729 def next(self):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	730 if self.index == 0:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	731 raise StopIteration
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	732 self.index = self.index - 1
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	733 return self.data[self.index]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	734
69737 3d0a41407abf Split combined code/doctest code blocks in two blocks, to enable proper highlighting. Georg Brandl <georg@python.org> parents: 68836 diff changeset	735 ::
3d0a41407abf Split combined code/doctest code blocks in two blocks, to enable proper highlighting. Georg Brandl <georg@python.org> parents: 68836 diff changeset	736
63503 e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	737 >>> rev = Reverse('spam')
e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	738 >>> iter(rev)
e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	739 <__main__.Reverse object at 0x00A1DB50>
e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	740 >>> for char in rev:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	741 ... print char
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	742 ...
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	743 m
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	744 a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	745 p
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	746 s
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	747
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	748
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	749 .. _tut-generators:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	750
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	751 Generators
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	752 ==========
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	753
43629 4f662ba09f1f Add :term: for generators. Georg Brandl <georg@python.org> parents: 42603 diff changeset	754 :term:`Generator`\s are a simple and powerful tool for creating iterators. They
4f662ba09f1f Add :term: for generators. Georg Brandl <georg@python.org> parents: 42603 diff changeset	755 are written like regular functions but use the :keyword:`yield` statement
4f662ba09f1f Add :term: for generators. Georg Brandl <georg@python.org> parents: 42603 diff changeset	756 whenever they want to return data. Each time :meth:`next` is called, the
4f662ba09f1f Add :term: for generators. Georg Brandl <georg@python.org> parents: 42603 diff changeset	757 generator resumes where it left-off (it remembers all the data values and which
4f662ba09f1f Add :term: for generators. Georg Brandl <georg@python.org> parents: 42603 diff changeset	758 statement was last executed). An example shows that generators can be trivially
4f662ba09f1f Add :term: for generators. Georg Brandl <georg@python.org> parents: 42603 diff changeset	759 easy to create::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	760
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	761 def reverse(data):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	762 for index in range(len(data)-1, -1, -1):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	763 yield data[index]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	764
69737 3d0a41407abf Split combined code/doctest code blocks in two blocks, to enable proper highlighting. Georg Brandl <georg@python.org> parents: 68836 diff changeset	765 ::
3d0a41407abf Split combined code/doctest code blocks in two blocks, to enable proper highlighting. Georg Brandl <georg@python.org> parents: 68836 diff changeset	766
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	767 >>> for char in reverse('golf'):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	768 ... print char
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	769 ...
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	770 f
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	771 l
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	772 o
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49179 diff changeset	773 g
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	774
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	775 Anything that can be done with generators can also be done with class based
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	776 iterators as described in the previous section. What makes generators so
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	777 compact is that the :meth:`__iter__` and :meth:`next` methods are created
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	778 automatically.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	779
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	780 Another key feature is that the local variables and execution state are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	781 automatically saved between calls. This made the function easier to write and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	782 much more clear than an approach using instance variables like ``self.index``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	783 and ``self.data``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	784
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	785 In addition to automatic method creation and saving program state, when
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	786 generators terminate, they automatically raise :exc:`StopIteration`. In
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	787 combination, these features make it easy to create iterators with no more effort
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	788 than writing a regular function.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	789
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	790
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	791 .. _tut-genexps:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	792
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	793 Generator Expressions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	794 =====================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	795
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	796 Some simple generators can be coded succinctly as expressions using a syntax
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	797 similar to list comprehensions but with parentheses instead of brackets. These
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	798 expressions are designed for situations where the generator is used right away
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	799 by an enclosing function. Generator expressions are more compact but less
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	800 versatile than full generator definitions and tend to be more memory friendly
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	801 than equivalent list comprehensions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	802
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	803 Examples::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	804
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	805 >>> sum(i*i for i in range(10)) # sum of squares
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	806 285
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	807
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	808 >>> xvec = [10, 20, 30]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	809 >>> yvec = [7, 5, 3]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	810 >>> sum(x*y for x,y in zip(xvec, yvec)) # dot product
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	811 260
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	812
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	813 >>> from math import pi, sin
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	814 >>> sine_table = dict((x, sin(x*pi/180)) for x in range(0, 91))
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	815
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	816 >>> unique_words = set(word for line in page for word in line.split())
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	817
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	818 >>> valedictorian = max((student.gpa, student.name) for student in graduates)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	819
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	820 >>> data = 'golf'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	821 >>> list(data[i] for i in range(len(data)-1,-1,-1))
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	822 ['f', 'l', 'o', 'g']
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	823
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	824
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	825
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	826 .. rubric:: Footnotes
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	827
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	828 .. [#] Except for one thing. Module objects have a secret read-only attribute called
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	829 :attr:`__dict__` which returns the dictionary used to implement the module's
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	830 namespace; the name :attr:`__dict__` is an attribute but not a global name.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	831 Obviously, using this violates the abstraction of namespace implementation, and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	832 should be restricted to things like post-mortem debuggers.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	833

Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/classes.rst @ 80661:94de77bd0b4b 2.7