blob: 8e25f58d7aa20ef76509d3605bc95a98ab6788e4 [file] [log] [blame]
Tim Peters95c99e52001-09-03 01:24:30 +00001# This contains most of the executable examples from Guido's descr
2# tutorial, once at
3#
4# http://www.python.org/2.2/descrintro.html
5#
6# A few examples left implicit in the writeup were fleshed out, a few were
7# skipped due to lack of interest (e.g., faking super() by hand isn't
8# of much interest anymore), and a few were fiddled to make the output
9# deterministic.
10
Benjamin Petersonee8712c2008-05-20 21:35:26 +000011from test.support import sortdict
Tim Peters95c99e52001-09-03 01:24:30 +000012import pprint
13
Tim Petersa427a2b2001-10-29 22:25:45 +000014class defaultdict(dict):
Tim Peters95c99e52001-09-03 01:24:30 +000015 def __init__(self, default=None):
Tim Petersa427a2b2001-10-29 22:25:45 +000016 dict.__init__(self)
Tim Peters95c99e52001-09-03 01:24:30 +000017 self.default = default
18
19 def __getitem__(self, key):
20 try:
Tim Petersa427a2b2001-10-29 22:25:45 +000021 return dict.__getitem__(self, key)
Tim Peters95c99e52001-09-03 01:24:30 +000022 except KeyError:
23 return self.default
24
25 def get(self, key, *args):
26 if not args:
27 args = (self.default,)
Tim Petersa427a2b2001-10-29 22:25:45 +000028 return dict.get(self, key, *args)
Tim Peters95c99e52001-09-03 01:24:30 +000029
30 def merge(self, other):
31 for key in other:
32 if key not in self:
33 self[key] = other[key]
34
35test_1 = """
36
37Here's the new type at work:
38
Georg Brandl88fc6642007-02-09 21:28:07 +000039 >>> print(defaultdict) # show our type
Benjamin Petersonab078e92016-07-13 21:13:29 -070040 <class 'test.test_descrtut.defaultdict'>
Georg Brandl88fc6642007-02-09 21:28:07 +000041 >>> print(type(defaultdict)) # its metatype
Benjamin Petersonab078e92016-07-13 21:13:29 -070042 <class 'type'>
Tim Peters95c99e52001-09-03 01:24:30 +000043 >>> a = defaultdict(default=0.0) # create an instance
Georg Brandl88fc6642007-02-09 21:28:07 +000044 >>> print(a) # show the instance
Tim Peters95c99e52001-09-03 01:24:30 +000045 {}
Georg Brandl88fc6642007-02-09 21:28:07 +000046 >>> print(type(a)) # show its type
Benjamin Petersonab078e92016-07-13 21:13:29 -070047 <class 'test.test_descrtut.defaultdict'>
Georg Brandl88fc6642007-02-09 21:28:07 +000048 >>> print(a.__class__) # show its class
Benjamin Petersonab078e92016-07-13 21:13:29 -070049 <class 'test.test_descrtut.defaultdict'>
Georg Brandl88fc6642007-02-09 21:28:07 +000050 >>> print(type(a) is a.__class__) # its type is its class
Guido van Rossum77f6a652002-04-03 22:41:51 +000051 True
Tim Peters95c99e52001-09-03 01:24:30 +000052 >>> a[1] = 3.25 # modify the instance
Georg Brandl88fc6642007-02-09 21:28:07 +000053 >>> print(a) # show the new value
Tim Peters95c99e52001-09-03 01:24:30 +000054 {1: 3.25}
Georg Brandl88fc6642007-02-09 21:28:07 +000055 >>> print(a[1]) # show the new item
Tim Peters95c99e52001-09-03 01:24:30 +000056 3.25
Mark Dickinson934896d2009-02-21 20:59:32 +000057 >>> print(a[0]) # a non-existent item
Tim Peters95c99e52001-09-03 01:24:30 +000058 0.0
Tim Petersa427a2b2001-10-29 22:25:45 +000059 >>> a.merge({1:100, 2:200}) # use a dict method
Georg Brandl88fc6642007-02-09 21:28:07 +000060 >>> print(sortdict(a)) # show the result
Tim Peters95c99e52001-09-03 01:24:30 +000061 {1: 3.25, 2: 200}
62 >>>
63
64We can also use the new type in contexts where classic only allows "real"
65dictionaries, such as the locals/globals dictionaries for the exec
66statement or the built-in function eval():
67
Guido van Rossum7131f842007-02-09 20:13:25 +000068 >>> print(sorted(a.keys()))
Tim Peters95c99e52001-09-03 01:24:30 +000069 [1, 2]
Georg Brandl88fc6642007-02-09 21:28:07 +000070 >>> a['print'] = print # need the print function here
71 >>> exec("x = 3; print(x)", a)
Tim Peters95c99e52001-09-03 01:24:30 +000072 3
Guido van Rossum7131f842007-02-09 20:13:25 +000073 >>> print(sorted(a.keys(), key=lambda x: (str(type(x)), x)))
Georg Brandl88fc6642007-02-09 21:28:07 +000074 [1, 2, '__builtins__', 'print', 'x']
Guido van Rossum7131f842007-02-09 20:13:25 +000075 >>> print(a['x'])
Tim Peters95c99e52001-09-03 01:24:30 +000076 3
77 >>>
78
Tim Peters95c99e52001-09-03 01:24:30 +000079Now I'll show that defaultdict instances have dynamic instance variables,
80just like classic classes:
81
82 >>> a.default = -1
Guido van Rossum7131f842007-02-09 20:13:25 +000083 >>> print(a["noway"])
Tim Peters95c99e52001-09-03 01:24:30 +000084 -1
85 >>> a.default = -1000
Guido van Rossum7131f842007-02-09 20:13:25 +000086 >>> print(a["noway"])
Tim Peters95c99e52001-09-03 01:24:30 +000087 -1000
Tim Peters5d2b77c2001-09-03 05:47:38 +000088 >>> 'default' in dir(a)
Guido van Rossum77f6a652002-04-03 22:41:51 +000089 True
Tim Peters95c99e52001-09-03 01:24:30 +000090 >>> a.x1 = 100
91 >>> a.x2 = 200
Guido van Rossum7131f842007-02-09 20:13:25 +000092 >>> print(a.x1)
Tim Peters95c99e52001-09-03 01:24:30 +000093 100
Tim Peters5d2b77c2001-09-03 05:47:38 +000094 >>> d = dir(a)
95 >>> 'default' in d and 'x1' in d and 'x2' in d
Guido van Rossum77f6a652002-04-03 22:41:51 +000096 True
Guido van Rossum7131f842007-02-09 20:13:25 +000097 >>> print(sortdict(a.__dict__))
Tim Peterse2052ab2003-02-18 16:54:41 +000098 {'default': -1000, 'x1': 100, 'x2': 200}
Tim Peters95c99e52001-09-03 01:24:30 +000099 >>>
100"""
101
Tim Petersa427a2b2001-10-29 22:25:45 +0000102class defaultdict2(dict):
Tim Peters95c99e52001-09-03 01:24:30 +0000103 __slots__ = ['default']
104
105 def __init__(self, default=None):
Tim Petersa427a2b2001-10-29 22:25:45 +0000106 dict.__init__(self)
Tim Peters95c99e52001-09-03 01:24:30 +0000107 self.default = default
108
109 def __getitem__(self, key):
110 try:
Tim Petersa427a2b2001-10-29 22:25:45 +0000111 return dict.__getitem__(self, key)
Tim Peters95c99e52001-09-03 01:24:30 +0000112 except KeyError:
113 return self.default
114
115 def get(self, key, *args):
116 if not args:
117 args = (self.default,)
Tim Petersa427a2b2001-10-29 22:25:45 +0000118 return dict.get(self, key, *args)
Tim Peters95c99e52001-09-03 01:24:30 +0000119
120 def merge(self, other):
121 for key in other:
122 if key not in self:
123 self[key] = other[key]
124
125test_2 = """
126
127The __slots__ declaration takes a list of instance variables, and reserves
128space for exactly these in the instance. When __slots__ is used, other
129instance variables cannot be assigned to:
130
131 >>> a = defaultdict2(default=0.0)
132 >>> a[1]
133 0.0
134 >>> a.default = -1
135 >>> a[1]
136 -1
137 >>> a.x1 = 1
138 Traceback (most recent call last):
139 File "<stdin>", line 1, in ?
140 AttributeError: 'defaultdict2' object has no attribute 'x1'
141 >>>
142
143"""
144
145test_3 = """
146
147Introspecting instances of built-in types
148
149For instance of built-in types, x.__class__ is now the same as type(x):
150
151 >>> type([])
Benjamin Petersonab078e92016-07-13 21:13:29 -0700152 <class 'list'>
Tim Peters95c99e52001-09-03 01:24:30 +0000153 >>> [].__class__
Benjamin Petersonab078e92016-07-13 21:13:29 -0700154 <class 'list'>
Tim Peters95c99e52001-09-03 01:24:30 +0000155 >>> list
Benjamin Petersonab078e92016-07-13 21:13:29 -0700156 <class 'list'>
Tim Peters95c99e52001-09-03 01:24:30 +0000157 >>> isinstance([], list)
Guido van Rossum77f6a652002-04-03 22:41:51 +0000158 True
Tim Petersa427a2b2001-10-29 22:25:45 +0000159 >>> isinstance([], dict)
Guido van Rossum77f6a652002-04-03 22:41:51 +0000160 False
Tim Peters95c99e52001-09-03 01:24:30 +0000161 >>> isinstance([], object)
Guido van Rossum77f6a652002-04-03 22:41:51 +0000162 True
Tim Peters95c99e52001-09-03 01:24:30 +0000163 >>>
164
Neal Norwitz8dfc4a92007-08-11 06:39:53 +0000165You can get the information from the list type:
Tim Peters95c99e52001-09-03 01:24:30 +0000166
167 >>> pprint.pprint(dir(list)) # like list.__dict__.keys(), but sorted
168 ['__add__',
169 '__class__',
Guido van Rossum48b069a2020-04-07 09:50:06 -0700170 '__class_getitem__',
Tim Peters95c99e52001-09-03 01:24:30 +0000171 '__contains__',
172 '__delattr__',
173 '__delitem__',
Benjamin Peterson82b00c12011-05-24 11:09:06 -0500174 '__dir__',
Tim Peters80440552002-02-19 04:25:19 +0000175 '__doc__',
Tim Peters95c99e52001-09-03 01:24:30 +0000176 '__eq__',
Eric Smith8c663262007-08-25 02:26:07 +0000177 '__format__',
Tim Peters95c99e52001-09-03 01:24:30 +0000178 '__ge__',
Guido van Rossum867a8d22001-09-21 19:29:08 +0000179 '__getattribute__',
Tim Peters95c99e52001-09-03 01:24:30 +0000180 '__getitem__',
Tim Peters95c99e52001-09-03 01:24:30 +0000181 '__gt__',
182 '__hash__',
183 '__iadd__',
184 '__imul__',
185 '__init__',
Nick Coghland78448e2016-07-30 16:26:03 +1000186 '__init_subclass__',
Raymond Hettinger14bd6de2002-05-31 21:40:38 +0000187 '__iter__',
Tim Peters95c99e52001-09-03 01:24:30 +0000188 '__le__',
189 '__len__',
190 '__lt__',
191 '__mul__',
192 '__ne__',
193 '__new__',
Guido van Rossum3926a632001-09-25 16:25:58 +0000194 '__reduce__',
Guido van Rossumc53f0092003-02-18 22:05:12 +0000195 '__reduce_ex__',
Tim Peters95c99e52001-09-03 01:24:30 +0000196 '__repr__',
Raymond Hettingeraf28e4b2003-11-08 12:39:53 +0000197 '__reversed__',
Tim Peters95c99e52001-09-03 01:24:30 +0000198 '__rmul__',
199 '__setattr__',
200 '__setitem__',
Martin v. Löwis00709aa2008-06-04 14:18:43 +0000201 '__sizeof__',
Tim Peters95c99e52001-09-03 01:24:30 +0000202 '__str__',
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000203 '__subclasshook__',
Tim Peters95c99e52001-09-03 01:24:30 +0000204 'append',
Eli Benderskycbbaa962011-02-25 05:47:53 +0000205 'clear',
206 'copy',
Tim Peters95c99e52001-09-03 01:24:30 +0000207 'count',
208 'extend',
209 'index',
210 'insert',
211 'pop',
212 'remove',
213 'reverse',
Raymond Hettinger64958a12003-12-17 20:43:33 +0000214 'sort']
Tim Peters95c99e52001-09-03 01:24:30 +0000215
216The new introspection API gives more information than the old one: in
217addition to the regular methods, it also shows the methods that are
218normally invoked through special notations, e.g. __iadd__ (+=), __len__
219(len), __ne__ (!=). You can invoke any method from this list directly:
220
221 >>> a = ['tic', 'tac']
222 >>> list.__len__(a) # same as len(a)
223 2
224 >>> a.__len__() # ditto
225 2
226 >>> list.append(a, 'toe') # same as a.append('toe')
227 >>> a
228 ['tic', 'tac', 'toe']
229 >>>
230
231This is just like it is for user-defined classes.
232"""
233
234test_4 = """
235
236Static methods and class methods
237
238The new introspection API makes it possible to add static methods and class
239methods. Static methods are easy to describe: they behave pretty much like
240static methods in C++ or Java. Here's an example:
241
242 >>> class C:
Guido van Rossumd8faa362007-04-27 19:54:29 +0000243 ...
Guido van Rossum5a8a0372005-01-16 00:25:31 +0000244 ... @staticmethod
Tim Peters95c99e52001-09-03 01:24:30 +0000245 ... def foo(x, y):
Guido van Rossum7131f842007-02-09 20:13:25 +0000246 ... print("staticmethod", x, y)
Tim Peters95c99e52001-09-03 01:24:30 +0000247
248 >>> C.foo(1, 2)
249 staticmethod 1 2
250 >>> c = C()
251 >>> c.foo(1, 2)
252 staticmethod 1 2
253
254Class methods use a similar pattern to declare methods that receive an
255implicit first argument that is the *class* for which they are invoked.
256
257 >>> class C:
Guido van Rossum5a8a0372005-01-16 00:25:31 +0000258 ... @classmethod
Tim Peters95c99e52001-09-03 01:24:30 +0000259 ... def foo(cls, y):
Guido van Rossum7131f842007-02-09 20:13:25 +0000260 ... print("classmethod", cls, y)
Tim Peters95c99e52001-09-03 01:24:30 +0000261
262 >>> C.foo(1)
Benjamin Petersonab078e92016-07-13 21:13:29 -0700263 classmethod <class 'test.test_descrtut.C'> 1
Tim Peters95c99e52001-09-03 01:24:30 +0000264 >>> c = C()
265 >>> c.foo(1)
Benjamin Petersonab078e92016-07-13 21:13:29 -0700266 classmethod <class 'test.test_descrtut.C'> 1
Tim Peters95c99e52001-09-03 01:24:30 +0000267
268 >>> class D(C):
269 ... pass
270
271 >>> D.foo(1)
Benjamin Petersonab078e92016-07-13 21:13:29 -0700272 classmethod <class 'test.test_descrtut.D'> 1
Tim Peters95c99e52001-09-03 01:24:30 +0000273 >>> d = D()
274 >>> d.foo(1)
Benjamin Petersonab078e92016-07-13 21:13:29 -0700275 classmethod <class 'test.test_descrtut.D'> 1
Tim Peters95c99e52001-09-03 01:24:30 +0000276
277This prints "classmethod __main__.D 1" both times; in other words, the
278class passed as the first argument of foo() is the class involved in the
279call, not the class involved in the definition of foo().
280
281But notice this:
282
283 >>> class E(C):
Guido van Rossum5a8a0372005-01-16 00:25:31 +0000284 ... @classmethod
Tim Peters95c99e52001-09-03 01:24:30 +0000285 ... def foo(cls, y): # override C.foo
Guido van Rossum7131f842007-02-09 20:13:25 +0000286 ... print("E.foo() called")
Tim Peters95c99e52001-09-03 01:24:30 +0000287 ... C.foo(y)
Tim Peters95c99e52001-09-03 01:24:30 +0000288
289 >>> E.foo(1)
290 E.foo() called
Benjamin Petersonab078e92016-07-13 21:13:29 -0700291 classmethod <class 'test.test_descrtut.C'> 1
Tim Peters95c99e52001-09-03 01:24:30 +0000292 >>> e = E()
293 >>> e.foo(1)
294 E.foo() called
Benjamin Petersonab078e92016-07-13 21:13:29 -0700295 classmethod <class 'test.test_descrtut.C'> 1
Tim Peters95c99e52001-09-03 01:24:30 +0000296
297In this example, the call to C.foo() from E.foo() will see class C as its
298first argument, not class E. This is to be expected, since the call
299specifies the class C. But it stresses the difference between these class
300methods and methods defined in metaclasses (where an upcall to a metamethod
301would pass the target class as an explicit first argument).
302"""
303
304test_5 = """
305
306Attributes defined by get/set methods
307
308
Guido van Rossum8bce4ac2001-09-06 21:56:42 +0000309 >>> class property(object):
Tim Peters95c99e52001-09-03 01:24:30 +0000310 ...
311 ... def __init__(self, get, set=None):
312 ... self.__get = get
313 ... self.__set = set
314 ...
315 ... def __get__(self, inst, type=None):
316 ... return self.__get(inst)
317 ...
318 ... def __set__(self, inst, value):
319 ... if self.__set is None:
Collin Winter3add4d72007-08-29 23:37:32 +0000320 ... raise AttributeError("this attribute is read-only")
Tim Peters95c99e52001-09-03 01:24:30 +0000321 ... return self.__set(inst, value)
322
323Now let's define a class with an attribute x defined by a pair of methods,
Terry Jan Reedyc30b7b12013-03-11 17:57:08 -0400324getx() and setx():
Tim Peters95c99e52001-09-03 01:24:30 +0000325
326 >>> class C(object):
327 ...
328 ... def __init__(self):
329 ... self.__x = 0
330 ...
331 ... def getx(self):
332 ... return self.__x
333 ...
334 ... def setx(self, x):
335 ... if x < 0: x = 0
336 ... self.__x = x
337 ...
Guido van Rossum8bce4ac2001-09-06 21:56:42 +0000338 ... x = property(getx, setx)
Tim Peters95c99e52001-09-03 01:24:30 +0000339
340Here's a small demonstration:
341
342 >>> a = C()
343 >>> a.x = 10
Guido van Rossum7131f842007-02-09 20:13:25 +0000344 >>> print(a.x)
Tim Peters95c99e52001-09-03 01:24:30 +0000345 10
346 >>> a.x = -10
Guido van Rossum7131f842007-02-09 20:13:25 +0000347 >>> print(a.x)
Tim Peters95c99e52001-09-03 01:24:30 +0000348 0
349 >>>
350
Guido van Rossum8bce4ac2001-09-06 21:56:42 +0000351Hmm -- property is builtin now, so let's try it that way too.
Tim Peters95c99e52001-09-03 01:24:30 +0000352
Guido van Rossum8bce4ac2001-09-06 21:56:42 +0000353 >>> del property # unmask the builtin
354 >>> property
Benjamin Petersonab078e92016-07-13 21:13:29 -0700355 <class 'property'>
Tim Peters95c99e52001-09-03 01:24:30 +0000356
357 >>> class C(object):
358 ... def __init__(self):
359 ... self.__x = 0
360 ... def getx(self):
361 ... return self.__x
362 ... def setx(self, x):
363 ... if x < 0: x = 0
364 ... self.__x = x
Guido van Rossum8bce4ac2001-09-06 21:56:42 +0000365 ... x = property(getx, setx)
Tim Peters95c99e52001-09-03 01:24:30 +0000366
367
368 >>> a = C()
369 >>> a.x = 10
Guido van Rossum7131f842007-02-09 20:13:25 +0000370 >>> print(a.x)
Tim Peters95c99e52001-09-03 01:24:30 +0000371 10
372 >>> a.x = -10
Guido van Rossum7131f842007-02-09 20:13:25 +0000373 >>> print(a.x)
Tim Peters95c99e52001-09-03 01:24:30 +0000374 0
375 >>>
376"""
377
378test_6 = """
379
380Method resolution order
381
382This example is implicit in the writeup.
383
Thomas Wouters28bc7682006-04-15 09:03:16 +0000384>>> class A: # implicit new-style class
Tim Peters95c99e52001-09-03 01:24:30 +0000385... def save(self):
Guido van Rossum7131f842007-02-09 20:13:25 +0000386... print("called A.save()")
Tim Peters95c99e52001-09-03 01:24:30 +0000387>>> class B(A):
388... pass
389>>> class C(A):
390... def save(self):
Guido van Rossum7131f842007-02-09 20:13:25 +0000391... print("called C.save()")
Tim Peters95c99e52001-09-03 01:24:30 +0000392>>> class D(B, C):
393... pass
394
395>>> D().save()
Thomas Wouters28bc7682006-04-15 09:03:16 +0000396called C.save()
Tim Peters95c99e52001-09-03 01:24:30 +0000397
Thomas Wouters28bc7682006-04-15 09:03:16 +0000398>>> class A(object): # explicit new-style class
Tim Peters95c99e52001-09-03 01:24:30 +0000399... def save(self):
Guido van Rossum7131f842007-02-09 20:13:25 +0000400... print("called A.save()")
Tim Peters95c99e52001-09-03 01:24:30 +0000401>>> class B(A):
402... pass
403>>> class C(A):
404... def save(self):
Guido van Rossum7131f842007-02-09 20:13:25 +0000405... print("called C.save()")
Tim Peters95c99e52001-09-03 01:24:30 +0000406>>> class D(B, C):
407... pass
408
409>>> D().save()
410called C.save()
411"""
412
413class A(object):
414 def m(self):
415 return "A"
416
417class B(A):
418 def m(self):
419 return "B" + super(B, self).m()
420
421class C(A):
422 def m(self):
423 return "C" + super(C, self).m()
424
425class D(C, B):
426 def m(self):
427 return "D" + super(D, self).m()
428
429
430test_7 = """
431
432Cooperative methods and "super"
433
Guido van Rossum7131f842007-02-09 20:13:25 +0000434>>> print(D().m()) # "DCBA"
Tim Peters95c99e52001-09-03 01:24:30 +0000435DCBA
436"""
437
438test_8 = """
439
440Backwards incompatibilities
441
442>>> class A:
443... def foo(self):
Guido van Rossum7131f842007-02-09 20:13:25 +0000444... print("called A.foo()")
Tim Peters95c99e52001-09-03 01:24:30 +0000445
446>>> class B(A):
447... pass
448
449>>> class C(A):
450... def foo(self):
451... B.foo(self)
452
453>>> C().foo()
Christian Heimes4a22b5d2007-11-25 09:39:14 +0000454called A.foo()
Tim Peters95c99e52001-09-03 01:24:30 +0000455
456>>> class C(A):
457... def foo(self):
458... A.foo(self)
459>>> C().foo()
460called A.foo()
461"""
462
463__test__ = {"tut1": test_1,
464 "tut2": test_2,
465 "tut3": test_3,
466 "tut4": test_4,
467 "tut5": test_5,
468 "tut6": test_6,
469 "tut7": test_7,
470 "tut8": test_8}
471
472# Magic test name that regrtest.py invokes *after* importing this module.
473# This worms around a bootstrap problem.
474# Note that doctest and regrtest both look in sys.argv for a "-v" argument,
475# so this works as expected in both ways of running regrtest.
Tim Petersa0a62222001-09-09 06:12:01 +0000476def test_main(verbose=None):
477 # Obscure: import this module as test.test_descrtut instead of as
478 # plain test_descrtut because the name of this module works its way
479 # into the doctest examples, and unless the full test.test_descrtut
480 # business is used the name can change depending on how the test is
481 # invoked.
Benjamin Petersonee8712c2008-05-20 21:35:26 +0000482 from test import support, test_descrtut
Benjamin Petersonab078e92016-07-13 21:13:29 -0700483 support.run_doctest(test_descrtut, verbose)
Tim Peters95c99e52001-09-03 01:24:30 +0000484
485# This part isn't needed for regrtest, but for running the test directly.
486if __name__ == "__main__":
Tim Petersa0a62222001-09-09 06:12:01 +0000487 test_main(1)