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