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