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