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