Debian Codegraph @

Doc/tutorial/classes.rst

raw
1 .. _tut-classes:
2
3 *******
4 Classes
5 *******
6
7 Classes provide a means of bundling data and functionality together. Creating
8 a new class creates a new *type* of object, allowing new *instances* of that
9 type to be made. Each class instance can have attributes attached to it for
10 maintaining its state. Class instances can also have methods (defined by its
11 class) for modifying its state.
12
13 Compared with other programming languages, Python's class mechanism adds classes
14 with a minimum of new syntax and semantics. It is a mixture of the class
15 mechanisms found in C++ and Modula-3. Python classes provide all the standard
16 features of Object Oriented Programming: the class inheritance mechanism allows
17 multiple base classes, a derived class can override any methods of its base
18 class or classes, and a method can call the method of a base class with the same
19 name. Objects can contain arbitrary amounts and kinds of data. As is true for
20 modules, classes partake of the dynamic nature of Python: they are created at
21 runtime, and can be modified further after creation.
22
23 In C++ terminology, normally class members (including the data members) are
24 *public* (except see below :ref:`tut-private`), and all member functions are
25 *virtual*. As in Modula-3, there are no shorthands for referencing the object's
26 members from its methods: the method function is declared with an explicit first
27 argument representing the object, which is provided implicitly by the call. As
28 in Smalltalk, classes themselves are objects. This provides semantics for
29 importing and renaming. Unlike C++ and Modula-3, built-in types can be used as
30 base classes for extension by the user. Also, like in C++, most built-in
31 operators with special syntax (arithmetic operators, subscripting etc.) can be
32 redefined for class instances.
33
34 (Lacking universally accepted terminology to talk about classes, I will make
35 occasional use of Smalltalk and C++ terms. I would use Modula-3 terms, since
36 its object-oriented semantics are closer to those of Python than C++, but I
37 expect that few readers have heard of it.)
38
39
40 .. _tut-object:
41
42 A Word About Names and Objects
43 ==============================
44
45 Objects have individuality, and multiple names (in multiple scopes) can be bound
46 to the same object. This is known as aliasing in other languages. This is
47 usually not appreciated on a first glance at Python, and can be safely ignored
48 when dealing with immutable basic types (numbers, strings, tuples). However,
49 aliasing has a possibly surprising effect on the semantics of Python code
50 involving mutable objects such as lists, dictionaries, and most other types.
51 This is usually used to the benefit of the program, since aliases behave like
52 pointers in some respects. For example, passing an object is cheap since only a
53 pointer is passed by the implementation; and if a function modifies an object
54 passed as an argument, the caller will see the change --- this eliminates the
55 need for two different argument passing mechanisms as in Pascal.
56
57
58 .. _tut-scopes:
59
60 Python Scopes and Namespaces
61 ============================
62
63 Before introducing classes, I first have to tell you something about Python's
64 scope rules. Class definitions play some neat tricks with namespaces, and you
65 need to know how scopes and namespaces work to fully understand what's going on.
66 Incidentally, knowledge about this subject is useful for any advanced Python
67 programmer.
68
69 Let's begin with some definitions.
70
71 A *namespace* is a mapping from names to objects. Most namespaces are currently
72 implemented as Python dictionaries, but that's normally not noticeable in any
73 way (except for performance), and it may change in the future. Examples of
74 namespaces are: the set of built-in names (containing functions such as :func:`abs`, and
75 built-in exception names); the global names in a module; and the local names in
76 a function invocation. In a sense the set of attributes of an object also form
77 a namespace. The important thing to know about namespaces is that there is
78 absolutely no relation between names in different namespaces; for instance, two
79 different modules may both define a function ``maximize`` without confusion ---
80 users of the modules must prefix it with the module name.
81
82 By the way, I use the word *attribute* for any name following a dot --- for
83 example, in the expression ``z.real``, ``real`` is an attribute of the object
84 ``z``. Strictly speaking, references to names in modules are attribute
85 references: in the expression ``modname.funcname``, ``modname`` is a module
86 object and ``funcname`` is an attribute of it. In this case there happens to be
87 a straightforward mapping between the module's attributes and the global names
88 defined in the module: they share the same namespace! [#]_
89
90 Attributes may be read-only or writable. In the latter case, assignment to
91 attributes is possible. Module attributes are writable: you can write
92 ``modname.the_answer = 42``. Writable attributes may also be deleted with the
93 :keyword:`del` statement. For example, ``del modname.the_answer`` will remove
94 the attribute :attr:`!the_answer` from the object named by ``modname``.
95
96 Namespaces are created at different moments and have different lifetimes. The
97 namespace containing the built-in names is created when the Python interpreter
98 starts up, and is never deleted. The global namespace for a module is created
99 when the module definition is read in; normally, module namespaces also last
100 until the interpreter quits. The statements executed by the top-level
101 invocation of the interpreter, either read from a script file or interactively,
102 are considered part of a module called :mod:`__main__`, so they have their own
103 global namespace. (The built-in names actually also live in a module; this is
104 called :mod:`builtins`.)
105
106 The local namespace for a function is created when the function is called, and
107 deleted when the function returns or raises an exception that is not handled
108 within the function. (Actually, forgetting would be a better way to describe
109 what actually happens.) Of course, recursive invocations each have their own
110 local namespace.
111
112 A *scope* is a textual region of a Python program where a namespace is directly
113 accessible. "Directly accessible" here means that an unqualified reference to a
114 name attempts to find the name in the namespace.
115
116 Although scopes are determined statically, they are used dynamically. At any
117 time during execution, there are 3 or 4 nested scopes whose namespaces are
118 directly accessible:
119
120 * the innermost scope, which is searched first, contains the local names
121 * the scopes of any enclosing functions, which are searched starting with the
122 nearest enclosing scope, contain non-local, but also non-global names
123 * the next-to-last scope contains the current module's global names
124 * the outermost scope (searched last) is the namespace containing built-in names
125
126 If a name is declared global, then all references and assignments go directly to
127 the next-to-last scope containing the module's global names. To rebind variables
128 found outside of the innermost scope, the :keyword:`nonlocal` statement can be
129 used; if not declared nonlocal, those variables are read-only (an attempt to
130 write to such a variable will simply create a *new* local variable in the
131 innermost scope, leaving the identically named outer variable unchanged).
132
133 Usually, the local scope references the local names of the (textually) current
134 function. Outside functions, the local scope references the same namespace as
135 the global scope: the module's namespace. Class definitions place yet another
136 namespace in the local scope.
137
138 It is important to realize that scopes are determined textually: the global
139 scope of a function defined in a module is that module's namespace, no matter
140 from where or by what alias the function is called. On the other hand, the
141 actual search for names is done dynamically, at run time --- however, the
142 language definition is evolving towards static name resolution, at "compile"
143 time, so don't rely on dynamic name resolution! (In fact, local variables are
144 already determined statically.)
145
146 A special quirk of Python is that -- if no :keyword:`global` or :keyword:`nonlocal`
147 statement is in effect -- assignments to names always go into the innermost scope.
148 Assignments do not copy data --- they just bind names to objects. The same is true
149 for deletions: the statement ``del x`` removes the binding of ``x`` from the
150 namespace referenced by the local scope. In fact, all operations that introduce
151 new names use the local scope: in particular, :keyword:`import` statements and
152 function definitions bind the module or function name in the local scope.
153
154 The :keyword:`global` statement can be used to indicate that particular
155 variables live in the global scope and should be rebound there; the
156 :keyword:`nonlocal` statement indicates that particular variables live in
157 an enclosing scope and should be rebound there.
158
159 .. _tut-scopeexample:
160
161 Scopes and Namespaces Example
162 -----------------------------
163
164 This is an example demonstrating how to reference the different scopes and
165 namespaces, and how :keyword:`global` and :keyword:`nonlocal` affect variable
166 binding::
167
168 def scope_test():
169 def do_local():
170 spam = "local spam"
171
172 def do_nonlocal():
173 nonlocal spam
174 spam = "nonlocal spam"
175
176 def do_global():
177 global spam
178 spam = "global spam"
179
180 spam = "test spam"
181 do_local()
182 print("After local assignment:", spam)
183 do_nonlocal()
184 print("After nonlocal assignment:", spam)
185 do_global()
186 print("After global assignment:", spam)
187
188 scope_test()
189 print("In global scope:", spam)
190
191 The output of the example code is:
192
193 .. code-block:: none
194
195 After local assignment: test spam
196 After nonlocal assignment: nonlocal spam
197 After global assignment: nonlocal spam
198 In global scope: global spam
199
200 Note how the *local* assignment (which is default) didn't change *scope_test*\'s
201 binding of *spam*. The :keyword:`nonlocal` assignment changed *scope_test*\'s
202 binding of *spam*, and the :keyword:`global` assignment changed the module-level
203 binding.
204
205 You can also see that there was no previous binding for *spam* before the
206 :keyword:`global` assignment.
207
208
209 .. _tut-firstclasses:
210
211 A First Look at Classes
212 =======================
213
214 Classes introduce a little bit of new syntax, three new object types, and some
215 new semantics.
216
217
218 .. _tut-classdefinition:
219
220 Class Definition Syntax
221 -----------------------
222
223 The simplest form of class definition looks like this::
224
225 class ClassName:
226 <statement-1>
227 .
228 .
229 .
230 <statement-N>
231
232 Class definitions, like function definitions (:keyword:`def` statements) must be
233 executed before they have any effect. (You could conceivably place a class
234 definition in a branch of an :keyword:`if` statement, or inside a function.)
235
236 In practice, the statements inside a class definition will usually be function
237 definitions, but other statements are allowed, and sometimes useful --- we'll
238 come back to this later. The function definitions inside a class normally have
239 a peculiar form of argument list, dictated by the calling conventions for
240 methods --- again, this is explained later.
241
242 When a class definition is entered, a new namespace is created, and used as the
243 local scope --- thus, all assignments to local variables go into this new
244 namespace. In particular, function definitions bind the name of the new
245 function here.
246
247 When a class definition is left normally (via the end), a *class object* is
248 created. This is basically a wrapper around the contents of the namespace
249 created by the class definition; we'll learn more about class objects in the
250 next section. The original local scope (the one in effect just before the class
251 definition was entered) is reinstated, and the class object is bound here to the
252 class name given in the class definition header (:class:`!ClassName` in the
253 example).
254
255
256 .. _tut-classobjects:
257
258 Class Objects
259 -------------
260
261 Class objects support two kinds of operations: attribute references and
262 instantiation.
263
264 *Attribute references* use the standard syntax used for all attribute references
265 in Python: ``obj.name``. Valid attribute names are all the names that were in
266 the class's namespace when the class object was created. So, if the class
267 definition looked like this::
268
269 class MyClass:
270 """A simple example class"""
271 i = 12345
272
273 def f(self):
274 return 'hello world'
275
276 then ``MyClass.i`` and ``MyClass.f`` are valid attribute references, returning
277 an integer and a function object, respectively. Class attributes can also be
278 assigned to, so you can change the value of ``MyClass.i`` by assignment.
279 :attr:`~type.__doc__` is also a valid attribute, returning the docstring
280 belonging to the class: ``"A simple example class"``.
281
282 Class *instantiation* uses function notation. Just pretend that the class
283 object is a parameterless function that returns a new instance of the class.
284 For example (assuming the above class)::
285
286 x = MyClass()
287
288 creates a new *instance* of the class and assigns this object to the local
289 variable ``x``.
290
291 The instantiation operation ("calling" a class object) creates an empty object.
292 Many classes like to create objects with instances customized to a specific
293 initial state. Therefore a class may define a special method named
294 :meth:`~object.__init__`, like this::
295
296 def __init__(self):
297 self.data = []
298
299 When a class defines an :meth:`~object.__init__` method, class instantiation
300 automatically invokes :meth:`!__init__` for the newly created class instance. So
301 in this example, a new, initialized instance can be obtained by::
302
303 x = MyClass()
304
305 Of course, the :meth:`~object.__init__` method may have arguments for greater
306 flexibility. In that case, arguments given to the class instantiation operator
307 are passed on to :meth:`!__init__`. For example, ::
308
309 >>> class Complex:
310 ... def __init__(self, realpart, imagpart):
311 ... self.r = realpart
312 ... self.i = imagpart
313 ...
314 >>> x = Complex(3.0, -4.5)
315 >>> x.r, x.i
316 (3.0, -4.5)
317
318
319 .. _tut-instanceobjects:
320
321 Instance Objects
322 ----------------
323
324 Now what can we do with instance objects? The only operations understood by
325 instance objects are attribute references. There are two kinds of valid
326 attribute names: data attributes and methods.
327
328 *Data attributes* correspond to "instance variables" in Smalltalk, and to "data
329 members" in C++. Data attributes need not be declared; like local variables,
330 they spring into existence when they are first assigned to. For example, if
331 ``x`` is the instance of :class:`!MyClass` created above, the following piece of
332 code will print the value ``16``, without leaving a trace::
333
334 x.counter = 1
335 while x.counter < 10:
336 x.counter = x.counter * 2
337 print(x.counter)
338 del x.counter
339
340 The other kind of instance attribute reference is a *method*. A method is a
341 function that "belongs to" an object.
342
343 .. index:: pair: object; method
344
345 Valid method names of an instance object depend on its class. By definition,
346 all attributes of a class that are function objects define corresponding
347 methods of its instances. So in our example, ``x.f`` is a valid method
348 reference, since ``MyClass.f`` is a function, but ``x.i`` is not, since
349 ``MyClass.i`` is not. But ``x.f`` is not the same thing as ``MyClass.f`` --- it
350 is a *method object*, not a function object.
351
352
353 .. _tut-methodobjects:
354
355 Method Objects
356 --------------
357
358 Usually, a method is called right after it is bound::
359
360 x.f()
361
362 If ``x = MyClass()``, as above, this will return the string ``'hello world'``.
363 However, it is not necessary to call a method right away: ``x.f`` is a method
364 object, and can be stored away and called at a later time. For example::
365
366 xf = x.f
367 while True:
368 print(xf())
369
370 will continue to print ``hello world`` until the end of time.
371
372 What exactly happens when a method is called? You may have noticed that
373 ``x.f()`` was called without an argument above, even though the function
374 definition for :meth:`!f` specified an argument. What happened to the argument?
375 Surely Python raises an exception when a function that requires an argument is
376 called without any --- even if the argument isn't actually used...
377
378 Actually, you may have guessed the answer: the special thing about methods is
379 that the instance object is passed as the first argument of the function. In our
380 example, the call ``x.f()`` is exactly equivalent to ``MyClass.f(x)``. In
381 general, calling a method with a list of *n* arguments is equivalent to calling
382 the corresponding function with an argument list that is created by inserting
383 the method's instance object before the first argument.
384
385 In general, methods work as follows. When a non-data attribute
386 of an instance is referenced, the instance's class is searched.
387 If the name denotes a valid class attribute that is a function object,
388 references to both the instance object and the function object
389 are packed into a method object. When the method object is called
390 with an argument list, a new argument list is constructed from the instance
391 object and the argument list, and the function object is called with this new
392 argument list.
393
394
395 .. _tut-class-and-instance-variables:
396
397 Class and Instance Variables
398 ----------------------------
399
400 Generally speaking, instance variables are for data unique to each instance
401 and class variables are for attributes and methods shared by all instances
402 of the class::
403
404 class Dog:
405
406 kind = 'canine' # class variable shared by all instances
407
408 def __init__(self, name):
409 self.name = name # instance variable unique to each instance
410
411 >>> d = Dog('Fido')
412 >>> e = Dog('Buddy')
413 >>> d.kind # shared by all dogs
414 'canine'
415 >>> e.kind # shared by all dogs
416 'canine'
417 >>> d.name # unique to d
418 'Fido'
419 >>> e.name # unique to e
420 'Buddy'
421
422 As discussed in :ref:`tut-object`, shared data can have possibly surprising
423 effects involving :term:`mutable` objects such as lists and dictionaries.
424 For example, the *tricks* list in the following code should not be used as a
425 class variable because just a single list would be shared by all *Dog*
426 instances::
427
428 class Dog:
429
430 tricks = [] # mistaken use of a class variable
431
432 def __init__(self, name):
433 self.name = name
434
435 def add_trick(self, trick):
436 self.tricks.append(trick)
437
438 >>> d = Dog('Fido')
439 >>> e = Dog('Buddy')
440 >>> d.add_trick('roll over')
441 >>> e.add_trick('play dead')
442 >>> d.tricks # unexpectedly shared by all dogs
443 ['roll over', 'play dead']
444
445 Correct design of the class should use an instance variable instead::
446
447 class Dog:
448
449 def __init__(self, name):
450 self.name = name
451 self.tricks = [] # creates a new empty list for each dog
452
453 def add_trick(self, trick):
454 self.tricks.append(trick)
455
456 >>> d = Dog('Fido')
457 >>> e = Dog('Buddy')
458 >>> d.add_trick('roll over')
459 >>> e.add_trick('play dead')
460 >>> d.tricks
461 ['roll over']
462 >>> e.tricks
463 ['play dead']
464
465
466 .. _tut-remarks:
467
468 Random Remarks
469 ==============
470
471 .. These should perhaps be placed more carefully...
472
473 If the same attribute name occurs in both an instance and in a class,
474 then attribute lookup prioritizes the instance::
475
476 >>> class Warehouse:
477 ... purpose = 'storage'
478 ... region = 'west'
479 ...
480 >>> w1 = Warehouse()
481 >>> print(w1.purpose, w1.region)
482 storage west
483 >>> w2 = Warehouse()
484 >>> w2.region = 'east'
485 >>> print(w2.purpose, w2.region)
486 storage east
487
488 Data attributes may be referenced by methods as well as by ordinary users
489 ("clients") of an object. In other words, classes are not usable to implement
490 pure abstract data types. In fact, nothing in Python makes it possible to
491 enforce data hiding --- it is all based upon convention. (On the other hand,
492 the Python implementation, written in C, can completely hide implementation
493 details and control access to an object if necessary; this can be used by
494 extensions to Python written in C.)
495
496 Clients should use data attributes with care --- clients may mess up invariants
497 maintained by the methods by stamping on their data attributes. Note that
498 clients may add data attributes of their own to an instance object without
499 affecting the validity of the methods, as long as name conflicts are avoided ---
500 again, a naming convention can save a lot of headaches here.
501
502 There is no shorthand for referencing data attributes (or other methods!) from
503 within methods. I find that this actually increases the readability of methods:
504 there is no chance of confusing local variables and instance variables when
505 glancing through a method.
506
507 Often, the first argument of a method is called ``self``. This is nothing more
508 than a convention: the name ``self`` has absolutely no special meaning to
509 Python. Note, however, that by not following the convention your code may be
510 less readable to other Python programmers, and it is also conceivable that a
511 *class browser* program might be written that relies upon such a convention.
512
513 Any function object that is a class attribute defines a method for instances of
514 that class. It is not necessary that the function definition is textually
515 enclosed in the class definition: assigning a function object to a local
516 variable in the class is also ok. For example::
517
518 # Function defined outside the class
519 def f1(self, x, y):
520 return min(x, x+y)
521
522 class C:
523 f = f1
524
525 def g(self):
526 return 'hello world'
527
528 h = g
529
530 Now ``f``, ``g`` and ``h`` are all attributes of class :class:`!C` that refer to
531 function objects, and consequently they are all methods of instances of
532 :class:`!C` --- ``h`` being exactly equivalent to ``g``. Note that this practice
533 usually only serves to confuse the reader of a program.
534
535 Methods may call other methods by using method attributes of the ``self``
536 argument::
537
538 class Bag:
539 def __init__(self):
540 self.data = []
541
542 def add(self, x):
543 self.data.append(x)
544
545 def addtwice(self, x):
546 self.add(x)
547 self.add(x)
548
549 Methods may reference global names in the same way as ordinary functions. The
550 global scope associated with a method is the module containing its
551 definition. (A class is never used as a global scope.) While one
552 rarely encounters a good reason for using global data in a method, there are
553 many legitimate uses of the global scope: for one thing, functions and modules
554 imported into the global scope can be used by methods, as well as functions and
555 classes defined in it. Usually, the class containing the method is itself
556 defined in this global scope, and in the next section we'll find some good
557 reasons why a method would want to reference its own class.
558
559 Each value is an object, and therefore has a *class* (also called its *type*).
560 It is stored as ``object.__class__``.
561
562
563 .. _tut-inheritance:
564
565 Inheritance
566 ===========
567
568 Of course, a language feature would not be worthy of the name "class" without
569 supporting inheritance. The syntax for a derived class definition looks like
570 this::
571
572 class DerivedClassName(BaseClassName):
573 <statement-1>
574 .
575 .
576 .
577 <statement-N>
578
579 The name :class:`!BaseClassName` must be defined in a
580 namespace accessible from the scope containing the
581 derived class definition. In place of a base class name, other arbitrary
582 expressions are also allowed. This can be useful, for example, when the base
583 class is defined in another module::
584
585 class DerivedClassName(modname.BaseClassName):
586
587 Execution of a derived class definition proceeds the same as for a base class.
588 When the class object is constructed, the base class is remembered. This is
589 used for resolving attribute references: if a requested attribute is not found
590 in the class, the search proceeds to look in the base class. This rule is
591 applied recursively if the base class itself is derived from some other class.
592
593 There's nothing special about instantiation of derived classes:
594 ``DerivedClassName()`` creates a new instance of the class. Method references
595 are resolved as follows: the corresponding class attribute is searched,
596 descending down the chain of base classes if necessary, and the method reference
597 is valid if this yields a function object.
598
599 Derived classes may override methods of their base classes. Because methods
600 have no special privileges when calling other methods of the same object, a
601 method of a base class that calls another method defined in the same base class
602 may end up calling a method of a derived class that overrides it. (For C++
603 programmers: all methods in Python are effectively ``virtual``.)
604
605 An overriding method in a derived class may in fact want to extend rather than
606 simply replace the base class method of the same name. There is a simple way to
607 call the base class method directly: just call ``BaseClassName.methodname(self,
608 arguments)``. This is occasionally useful to clients as well. (Note that this
609 only works if the base class is accessible as ``BaseClassName`` in the global
610 scope.)
611
612 Python has two built-in functions that work with inheritance:
613
614 * Use :func:`isinstance` to check an instance's type: ``isinstance(obj, int)``
615 will be ``True`` only if ``obj.__class__`` is :class:`int` or some class
616 derived from :class:`int`.
617
618 * Use :func:`issubclass` to check class inheritance: ``issubclass(bool, int)``
619 is ``True`` since :class:`bool` is a subclass of :class:`int`. However,
620 ``issubclass(float, int)`` is ``False`` since :class:`float` is not a
621 subclass of :class:`int`.
622
623
624
625 .. _tut-multiple:
626
627 Multiple Inheritance
628 --------------------
629
630 Python supports a form of multiple inheritance as well. A class definition with
631 multiple base classes looks like this::
632
633 class DerivedClassName(Base1, Base2, Base3):
634 <statement-1>
635 .
636 .
637 .
638 <statement-N>
639
640 For most purposes, in the simplest cases, you can think of the search for
641 attributes inherited from a parent class as depth-first, left-to-right, not
642 searching twice in the same class where there is an overlap in the hierarchy.
643 Thus, if an attribute is not found in :class:`!DerivedClassName`, it is searched
644 for in :class:`!Base1`, then (recursively) in the base classes of :class:`!Base1`,
645 and if it was not found there, it was searched for in :class:`!Base2`, and so on.
646
647 In fact, it is slightly more complex than that; the method resolution order
648 changes dynamically to support cooperative calls to :func:`super`. This
649 approach is known in some other multiple-inheritance languages as
650 call-next-method and is more powerful than the super call found in
651 single-inheritance languages.
652
653 Dynamic ordering is necessary because all cases of multiple inheritance exhibit
654 one or more diamond relationships (where at least one of the parent classes
655 can be accessed through multiple paths from the bottommost class). For example,
656 all classes inherit from :class:`object`, so any case of multiple inheritance
657 provides more than one path to reach :class:`object`. To keep the base classes
658 from being accessed more than once, the dynamic algorithm linearizes the search
659 order in a way that preserves the left-to-right ordering specified in each
660 class, that calls each parent only once, and that is monotonic (meaning that a
661 class can be subclassed without affecting the precedence order of its parents).
662 Taken together, these properties make it possible to design reliable and
663 extensible classes with multiple inheritance. For more detail, see
664 :ref:`python_2.3_mro`.
665
666
667 .. _tut-private:
668
669 Private Variables
670 =================
671
672 "Private" instance variables that cannot be accessed except from inside an
673 object don't exist in Python. However, there is a convention that is followed
674 by most Python code: a name prefixed with an underscore (e.g. ``_spam``) should
675 be treated as a non-public part of the API (whether it is a function, a method
676 or a data member). It should be considered an implementation detail and subject
677 to change without notice.
678
679 .. index::
680 pair: name; mangling
681
682 Since there is a valid use-case for class-private members (namely to avoid name
683 clashes of names with names defined by subclasses), there is limited support for
684 such a mechanism, called :dfn:`name mangling`. Any identifier of the form
685 ``__spam`` (at least two leading underscores, at most one trailing underscore)
686 is textually replaced with ``_classname__spam``, where ``classname`` is the
687 current class name with leading underscore(s) stripped. This mangling is done
688 without regard to the syntactic position of the identifier, as long as it
689 occurs within the definition of a class.
690
691 .. seealso::
692
693 The :ref:`private name mangling specifications <private-name-mangling>`
694 for details and special cases.
695
696 Name mangling is helpful for letting subclasses override methods without
697 breaking intraclass method calls. For example::
698
699 class Mapping:
700 def __init__(self, iterable):
701 self.items_list = []
702 self.__update(iterable)
703
704 def update(self, iterable):
705 for item in iterable:
706 self.items_list.append(item)
707
708 __update = update # private copy of original update() method
709
710 class MappingSubclass(Mapping):
711
712 def update(self, keys, values):
713 # provides new signature for update()
714 # but does not break __init__()
715 for item in zip(keys, values):
716 self.items_list.append(item)
717
718 The above example would work even if ``MappingSubclass`` were to introduce a
719 ``__update`` identifier since it is replaced with ``_Mapping__update`` in the
720 ``Mapping`` class and ``_MappingSubclass__update`` in the ``MappingSubclass``
721 class respectively.
722
723 Note that the mangling rules are designed mostly to avoid accidents; it still is
724 possible to access or modify a variable that is considered private. This can
725 even be useful in special circumstances, such as in the debugger.
726
727 Notice that code passed to ``exec()`` or ``eval()`` does not consider the
728 classname of the invoking class to be the current class; this is similar to the
729 effect of the ``global`` statement, the effect of which is likewise restricted
730 to code that is byte-compiled together. The same restriction applies to
731 ``getattr()``, ``setattr()`` and ``delattr()``, as well as when referencing
732 ``__dict__`` directly.
733
734
735 .. _tut-odds:
736
737 Odds and Ends
738 =============
739
740 Sometimes it is useful to have a data type similar to the Pascal "record" or C
741 "struct", bundling together a few named data items. The idiomatic approach
742 is to use :mod:`dataclasses` for this purpose::
743
744 from dataclasses import dataclass
745
746 @dataclass
747 class Employee:
748 name: str
749 dept: str
750 salary: int
751
752 ::
753
754 >>> john = Employee('john', 'computer lab', 1000)
755 >>> john.dept
756 'computer lab'
757 >>> john.salary
758 1000
759
760 A piece of Python code that expects a particular abstract data type can often be
761 passed a class that emulates the methods of that data type instead. For
762 instance, if you have a function that formats some data from a file object, you
763 can define a class with methods :meth:`~io.TextIOBase.read` and
764 :meth:`~io.TextIOBase.readline` that get the
765 data from a string buffer instead, and pass it as an argument.
766
767 .. (Unfortunately, this technique has its limitations: a class can't define
768 operations that are accessed by special syntax such as sequence subscripting
769 or arithmetic operators, and assigning such a "pseudo-file" to sys.stdin will
770 not cause the interpreter to read further input from it.)
771
772 :ref:`Instance method objects <instance-methods>` have attributes, too:
773 :attr:`m.__self__ <method.__self__>` is the instance
774 object with the method :meth:`!m`, and :attr:`m.__func__ <method.__func__>` is
775 the :ref:`function object <user-defined-funcs>`
776 corresponding to the method.
777
778
779 .. _tut-iterators:
780
781 Iterators
782 =========
783
784 By now you have probably noticed that most container objects can be looped over
785 using a :keyword:`for` statement::
786
787 for element in [1, 2, 3]:
788 print(element)
789 for element in (1, 2, 3):
790 print(element)
791 for key in {'one':1, 'two':2}:
792 print(key)
793 for char in "123":
794 print(char)
795 for line in open("myfile.txt"):
796 print(line, end='')
797
798 This style of access is clear, concise, and convenient. The use of iterators
799 pervades and unifies Python. Behind the scenes, the :keyword:`for` statement
800 calls :func:`iter` on the container object. The function returns an iterator
801 object that defines the method :meth:`~iterator.__next__` which accesses
802 elements in the container one at a time. When there are no more elements,
803 :meth:`~iterator.__next__` raises a :exc:`StopIteration` exception which tells the
804 :keyword:`!for` loop to terminate. You can call the :meth:`~iterator.__next__` method
805 using the :func:`next` built-in function; this example shows how it all works::
806
807 >>> s = 'abc'
808 >>> it = iter(s)
809 >>> it
810 <str_iterator object at 0x10c90e650>
811 >>> next(it)
812 'a'
813 >>> next(it)
814 'b'
815 >>> next(it)
816 'c'
817 >>> next(it)
818 Traceback (most recent call last):
819 File "<stdin>", line 1, in <module>
820 next(it)
821 StopIteration
822
823 Having seen the mechanics behind the iterator protocol, it is easy to add
824 iterator behavior to your classes. Define an :meth:`~container.__iter__` method which
825 returns an object with a :meth:`~iterator.__next__` method. If the class
826 defines :meth:`!__next__`, then :meth:`!__iter__` can just return ``self``::
827
828 class Reverse:
829 """Iterator for looping over a sequence backwards."""
830 def __init__(self, data):
831 self.data = data
832 self.index = len(data)
833
834 def __iter__(self):
835 return self
836
837 def __next__(self):
838 if self.index == 0:
839 raise StopIteration
840 self.index = self.index - 1
841 return self.data[self.index]
842
843 ::
844
845 >>> rev = Reverse('spam')
846 >>> iter(rev)
847 <__main__.Reverse object at 0x00A1DB50>
848 >>> for char in rev:
849 ... print(char)
850 ...
851 m
852 a
853 p
854 s
855
856
857 .. _tut-generators:
858
859 Generators
860 ==========
861
862 :term:`Generators <generator>` are a simple and powerful tool for creating iterators. They
863 are written like regular functions but use the :keyword:`yield` statement
864 whenever they want to return data. Each time :func:`next` is called on it, the
865 generator resumes where it left off (it remembers all the data values and which
866 statement was last executed). An example shows that generators can be trivially
867 easy to create::
868
869 def reverse(data):
870 for index in range(len(data)-1, -1, -1):
871 yield data[index]
872
873 ::
874
875 >>> for char in reverse('golf'):
876 ... print(char)
877 ...
878 f
879 l
880 o
881 g
882
883 Anything that can be done with generators can also be done with class-based
884 iterators as described in the previous section. What makes generators so
885 compact is that the :meth:`~iterator.__iter__` and :meth:`~generator.__next__` methods
886 are created automatically.
887
888 Another key feature is that the local variables and execution state are
889 automatically saved between calls. This made the function easier to write and
890 much more clear than an approach using instance variables like ``self.index``
891 and ``self.data``.
892
893 In addition to automatic method creation and saving program state, when
894 generators terminate, they automatically raise :exc:`StopIteration`. In
895 combination, these features make it easy to create iterators with no more effort
896 than writing a regular function.
897
898
899 .. _tut-genexps:
900
901 Generator Expressions
902 =====================
903
904 Some simple generators can be coded succinctly as expressions using a syntax
905 similar to list comprehensions but with parentheses instead of square brackets.
906 These expressions are designed for situations where the generator is used right
907 away by an enclosing function. Generator expressions are more compact but less
908 versatile than full generator definitions and tend to be more memory friendly
909 than equivalent list comprehensions.
910
911 Examples::
912
913 >>> sum(i*i for i in range(10)) # sum of squares
914 285
915
916 >>> xvec = [10, 20, 30]
917 >>> yvec = [7, 5, 3]
918 >>> sum(x*y for x,y in zip(xvec, yvec)) # dot product
919 260
920
921 >>> unique_words = set(word for line in page for word in line.split())
922
923 >>> valedictorian = max((student.gpa, student.name) for student in graduates)
924
925 >>> data = 'golf'
926 >>> list(data[i] for i in range(len(data)-1, -1, -1))
927 ['f', 'l', 'o', 'g']
928
929
930
931 .. rubric:: Footnotes
932
933 .. [#] Except for one thing. Module objects have a secret read-only attribute called
934 :attr:`~object.__dict__` which returns the dictionary used to implement the module's
935 namespace; the name ``__dict__`` is an attribute but not a global name.
936 Obviously, using this violates the abstraction of namespace implementation, and
937 should be restricted to things like post-mortem debuggers.