forked from UWPCE-PythonCert/ProgrammingInPython
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathSpecialMethodsAndProtocols.html
More file actions
447 lines (413 loc) · 44.8 KB
/
Copy pathSpecialMethodsAndProtocols.html
File metadata and controls
447 lines (413 loc) · 44.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Special Methods & Protocols — Programming in Python 8.0 documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" />
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=bb3927b2"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script async="async" src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
<script src="../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Circle Class Exercise" href="../exercises/circle/circle_class.html" />
<link rel="prev" title="Static and Class Methods" href="StaticAndClassMethods.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" style="background: #4b2e83" >
<a href="../index.html">
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Topics in the Program</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../topics/01-setting_up/index.html">1. Setting up your Environment</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/02-basic_python/index.html">2. Basic Python</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/03-recursion_booleans/index.html">3. Booleans and Recursion</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/04-sequences_iteration/index.html">4. Sequences and Iteration</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/05-text_handling/index.html">5. Basic Text Handling</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/06-exceptions/index.html">6. Exception Handling</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/07-unit_testing/index.html">7. Unit Testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/08-dicts_sets/index.html">8. Dictionaries and Sets</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/09-files/index.html">9. File Handling</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/10-modules_packages/index.html">10. Modules and Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/11-argument_passing/index.html">11. Advanced Argument Passing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/12-comprehensions/index.html">12. Comprehensions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/13-intro_oo/index.html">13. Intro to Object Oriented Programing</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../topics/14-magic_methods/index.html">14. Properties and Magic Methods</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="Properties.html">Properties</a></li>
<li class="toctree-l2"><a class="reference internal" href="StaticAndClassMethods.html">Static and Class Methods</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Special Methods & Protocols</a></li>
<li class="toctree-l2"><a class="reference internal" href="../exercises/circle/circle_class.html">Circle Class Exercise</a></li>
<li class="toctree-l2"><a class="reference internal" href="../exercises/sparse_array.html">Sparse Array Exercise</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../topics/15-subclassing/index.html">15. Subclassing and Inheritance</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/16-multiple_inheritance/index.html">16. Multiple Inheritance</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/17-functional_programming/index.html">17. Introduction to Functional Programming</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/18-advanced_testing/index.html">18. Advanced Testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/99-extras/index.html">19. Extra Topics</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #4b2e83" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">Programming in Python</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content style-external-links">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="../topics/14-magic_methods/index.html"><span class="section-number">14. </span>Properties and Magic Methods</a></li>
<li class="breadcrumb-item active">Special Methods & Protocols</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/modules/SpecialMethodsAndProtocols.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul><div class="rst-breadcrumbs-buttons" role="navigation" aria-label="Sequential page navigation">
<a href="StaticAndClassMethods.html" class="btn btn-neutral float-left" title="Static and Class Methods" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="../exercises/circle/circle_class.html" class="btn btn-neutral float-right" title="Circle Class Exercise" accesskey="n">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="special-methods-protocols">
<span id="special-methods"></span><h1>Special Methods & Protocols<a class="headerlink" href="#special-methods-protocols" title="Link to this heading"></a></h1>
<p>Special methods (also called <em>magic</em> methods) are the secret sauce to Python’s duck typing.</p>
<p>Defining the appropriate special methods in your classes is how you make your class act like the standard classes.</p>
<section id="what-s-in-a-name">
<h2>What’s in a Name?<a class="headerlink" href="#what-s-in-a-name" title="Link to this heading"></a></h2>
<p>We’ve seen at least one special method so far:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="fm">__init__</span>
</pre></div>
</div>
<p>It’s all in the double underscores…</p>
<p>Pronounced “dunder”</p>
<p>try: <code class="docutils literal notranslate"><span class="pre">dir(2)</span></code> or <code class="docutils literal notranslate"><span class="pre">dir(list)</span></code></p>
</section>
<section id="generally-useful-special-methods">
<h2>Generally Useful Special Methods<a class="headerlink" href="#generally-useful-special-methods" title="Link to this heading"></a></h2>
<p>Most classes should at least have these special methods:</p>
<dl>
<dt><code class="docutils literal notranslate"><span class="pre">object.__str__</span></code>:</dt><dd><p>Called by the str() built-in function and by the print function to compute
the <em>informal</em> string representation of an object.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">object.__repr__</span></code>:</dt><dd><p>Called by the repr() built-in function to compute the <em>official</em> string representation of an object.</p>
<p>Ideally: <code class="docutils literal notranslate"><span class="pre">eval(</span> <span class="pre">repr(something)</span> <span class="pre">)</span> <span class="pre">==</span> <span class="pre">something</span></code></p>
<p>This means that the “repr” is what you type to create the object. In practice, this is impractical for complex objects… but it is still a more “formal” form.</p>
<p>Note that if you don’t define a <code class="docutils literal notranslate"><span class="pre">__str__</span></code> method, then the <code class="docutils literal notranslate"><span class="pre">__repr__</span></code> will be used. And the base class (<code class="docutils literal notranslate"><span class="pre">object</span></code>) has a <code class="docutils literal notranslate"><span class="pre">__repr__</span></code> defined, so every class automatically gets one – but it’s ugly :-)</p>
</dd>
</dl>
</section>
<section id="protocols">
<h2>Protocols<a class="headerlink" href="#protocols" title="Link to this heading"></a></h2>
<p>The set of special methods needed to emulate a particular type of Python object is called a <em>protocol</em>.</p>
<p>Your classes can “become” like Python built-in classes by implementing the methods in a given protocol.</p>
<p>Remember, these are more <em>guidelines</em> than laws. Implement only what you need.</p>
</section>
<section id="the-numerics-protocol">
<h2>The Numerics Protocol<a class="headerlink" href="#the-numerics-protocol" title="Link to this heading"></a></h2>
<p>Do you want your class to behave like a number? Implement these methods:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="nb">object</span><span class="o">.</span><span class="fm">__add__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>
<span class="nb">object</span><span class="o">.</span><span class="fm">__sub__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>
<span class="nb">object</span><span class="o">.</span><span class="fm">__mul__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>
<span class="nb">object</span><span class="o">.</span><span class="fm">__matmul__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>
<span class="nb">object</span><span class="o">.</span><span class="fm">__truediv__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>
<span class="nb">object</span><span class="o">.</span><span class="fm">__floordiv__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>
<span class="nb">object</span><span class="o">.</span><span class="fm">__mod__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>
<span class="nb">object</span><span class="o">.</span><span class="fm">__divmod__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>
<span class="nb">object</span><span class="o">.</span><span class="fm">__pow__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">[,</span> <span class="n">modulo</span><span class="p">])</span>
<span class="nb">object</span><span class="o">.</span><span class="fm">__lshift__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>
<span class="nb">object</span><span class="o">.</span><span class="fm">__rshift__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>
<span class="nb">object</span><span class="o">.</span><span class="fm">__and__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>
<span class="nb">object</span><span class="o">.</span><span class="fm">__xor__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>
<span class="nb">object</span><span class="o">.</span><span class="fm">__or__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>
</pre></div>
</div>
<p>(or the fraction you actually need).</p>
</section>
<section id="operator-overloading">
<h2>Operator Overloading<a class="headerlink" href="#operator-overloading" title="Link to this heading"></a></h2>
<p>Most of the previous examples map to “operators”: <code class="docutils literal notranslate"><span class="pre">+,</span> <span class="pre">-</span> <span class="pre">,</span> <span class="pre">*,</span> <span class="pre">//,</span> <span class="pre">/,</span> <span class="pre">%</span></code> etc. This is often known as “operator overloading”, as you are redefining what the operators mean for that specific type.</p>
<p>Note that you can define these operators to do ANYTHING you want – but it is a really good idea to only define them to mean something that makes sense in the usual way.</p>
<p>One interesting exception to this rule is the <code class="docutils literal notranslate"><span class="pre">pathlib.Path</span></code> class, that has defined <code class="docutils literal notranslate"><span class="pre">__truediv__</span></code> to mean path concatenation:</p>
<div class="highlight-ipython notranslate"><div class="highlight"><pre><span></span><span class="gp">In [19]: </span><span class="kn">import</span><span class="w"> </span><span class="nn">pathlib</span>
<span class="gp">In [20]: </span><span class="n">p1</span> <span class="o">=</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="o">.</span><span class="n">cwd</span><span class="p">()</span>
<span class="gp">In [21]: </span><span class="n">p1</span>
<span class="gh">Out[21]: </span><span class="go">PosixPath('/Users/Chris/PythonStuff/UWPCE/PythonCertDevel')</span>
<span class="gp">In [22]: </span><span class="n">p1</span> <span class="o">/</span> <span class="s2">"a_filename"</span>
<span class="gh">Out[22]: </span><span class="go">PosixPath('/Users/Chris/PythonStuff/UWPCE/PythonCertDevel/a_filename')</span>
</pre></div>
</div>
<p>While this is not division in any sense, the slash <em>is</em> used as a path separator – so this does make intuitive sense. At least to me – I think it’s pretty cool.</p>
</section>
<section id="comparing">
<h2>Comparing<a class="headerlink" href="#comparing" title="Link to this heading"></a></h2>
<p>If you want your objects to be comparable:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">A</span> <span class="o">></span> <span class="n">B</span>
<span class="n">A</span> <span class="o"><</span> <span class="n">B</span>
<span class="n">A</span> <span class="o">>=</span> <span class="n">B</span>
</pre></div>
</div>
<p>etc…</p>
<p>There is a full set of magic methods you can use to override the “comparison operators”</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="fm">__lt__</span> <span class="p">:</span> <span class="o"><</span> <span class="p">(</span><span class="n">less</span> <span class="n">than</span><span class="p">)</span>
<span class="fm">__le__</span> <span class="p">:</span> <span class="o"><=</span> <span class="p">(</span><span class="n">less</span> <span class="n">than</span> <span class="ow">or</span> <span class="n">equal</span><span class="p">)</span>
<span class="fm">__eq__</span> <span class="p">:</span> <span class="o">==</span> <span class="p">(</span><span class="n">equal</span><span class="p">)</span>
<span class="fm">__ge__</span> <span class="p">:</span> <span class="o">>=</span> <span class="p">(</span><span class="n">greater</span> <span class="n">than</span> <span class="ow">or</span> <span class="n">equal</span><span class="p">)</span>
<span class="fm">__gt__</span> <span class="p">:</span> <span class="o">></span> <span class="p">(</span><span class="n">greater</span> <span class="n">than</span><span class="p">)</span>
<span class="fm">__ne__</span> <span class="p">:</span> <span class="o">!=</span> <span class="p">(</span><span class="ow">not</span> <span class="n">equal</span><span class="p">)</span>
</pre></div>
</div>
<p>These are known as the “rich comparison” operators, as they allow fuller featured comparisons. In particular, they are used by numpy to provide “element-wise” comparison – that is, comparing two arrays yields an array of results, rather than a single result:</p>
<div class="highlight-ipython notranslate"><div class="highlight"><pre><span></span><span class="gp">In [26]: </span><span class="kn">import</span><span class="w"> </span><span class="nn">numpy</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nn">np</span>
<span class="gp">In [27]: </span><span class="n">arr1</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mi">5</span><span class="p">,</span><span class="mi">6</span><span class="p">,</span><span class="mi">7</span><span class="p">,</span><span class="mi">8</span><span class="p">,</span><span class="mi">9</span><span class="p">])</span>
<span class="gp">In [28]: </span><span class="n">arr2</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">9</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">6</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">6</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">9</span><span class="p">])</span>
<span class="gp">In [29]: </span><span class="n">arr1</span> <span class="o">></span> <span class="n">arr2</span>
<span class="gh">Out[29]: </span><span class="go">array([False, True, False, True, True, True, False], dtype=bool)</span>
<span class="gp">In [30]: </span><span class="n">arr1</span> <span class="o">==</span> <span class="n">arr2</span>
<span class="gh">Out[30]: </span><span class="go">array([False, False, False, False, False, False, True], dtype=bool)</span>
</pre></div>
</div>
<p>This is just one example – the point is that for your particular class, you can define these comparisons however you want.</p>
</section>
<section id="total-ordering">
<h2>Total Ordering<a class="headerlink" href="#total-ordering" title="Link to this heading"></a></h2>
<p>You may notice that those operators are kind of redundant – if <code class="docutils literal notranslate"><span class="pre">A</span> <span class="pre">></span> <span class="pre">B</span> <span class="pre">is</span> <span class="pre">True</span></code> then we know that <code class="docutils literal notranslate"><span class="pre">A</span> <span class="pre"><</span> <span class="pre">B</span> <span class="pre">is</span> <span class="pre">False</span></code> and <code class="docutils literal notranslate"><span class="pre">A</span> <span class="pre"><=</span> <span class="pre">B</span> <span class="pre">is</span> <span class="pre">False</span></code>.</p>
<p>In fact, there is a mathematical / computer science concept known as “Total Order”: (<a class="reference external" href="https://en.wikipedia.org/wiki/Total_order">https://en.wikipedia.org/wiki/Total_order</a>), which strictly defines “well behaved” objects in this regard.</p>
<p>There may be some special cases, where these rules may not apply for your classes (though I can’t think of any :-) ), but for the most part, you want your classes, if they support comparisons at all, to be well behaved, or “total ordered”.</p>
<p>Because this is the common case, Python comes with a nifty utility that implements total ordering for you:</p>
<p><a class="reference external" href="https://docs.python.org/3.6/library/functools.html#functools.total_ordering">https://docs.python.org/3.6/library/functools.html#functools.total_ordering</a></p>
<p>It can be found in the functools module, and allows you to specify __eq__ and only one of: <code class="docutils literal notranslate"><span class="pre">__lt__()</span></code>, <code class="docutils literal notranslate"><span class="pre">__le__()</span></code>, <code class="docutils literal notranslate"><span class="pre">__gt__()</span></code>, or <code class="docutils literal notranslate"><span class="pre">__ge__()</span></code>. It will then fill in the others for you.</p>
<p>Note: if you define only one, it should be <code class="docutils literal notranslate"><span class="pre">__lt__</span></code>, because this is the one used for sorting (see below for more about that).</p>
<p>Here is the truncated example from the docs:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="nd">@total_ordering</span>
<span class="k">class</span><span class="w"> </span><span class="nc">Student</span><span class="p">:</span>
<span class="k">def</span><span class="w"> </span><span class="fm">__eq__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
<span class="k">return</span> <span class="p">((</span><span class="bp">self</span><span class="o">.</span><span class="n">lastname</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="bp">self</span><span class="o">.</span><span class="n">firstname</span><span class="o">.</span><span class="n">lower</span><span class="p">())</span> <span class="o">==</span>
<span class="p">(</span><span class="n">other</span><span class="o">.</span><span class="n">lastname</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="n">other</span><span class="o">.</span><span class="n">firstname</span><span class="o">.</span><span class="n">lower</span><span class="p">()))</span>
<span class="k">def</span><span class="w"> </span><span class="fm">__lt__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
<span class="k">return</span> <span class="p">((</span><span class="bp">self</span><span class="o">.</span><span class="n">lastname</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="bp">self</span><span class="o">.</span><span class="n">firstname</span><span class="o">.</span><span class="n">lower</span><span class="p">())</span> <span class="o"><</span>
<span class="p">(</span><span class="n">other</span><span class="o">.</span><span class="n">lastname</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="n">other</span><span class="o">.</span><span class="n">firstname</span><span class="o">.</span><span class="n">lower</span><span class="p">()))</span>
</pre></div>
</div>
<p>Note that this makes it a lot easier than implementing all six comparison operators. However, if you read the doc, it lets you know that <code class="docutils literal notranslate"><span class="pre">total_ordering</span></code> has poor performance – it is doing extra method call re-direction when the operators are used. If performance matters to your use case (and it probably doesn’t), you need to write all six comparison dunders.</p>
</section>
<section id="sorting">
<h2>Sorting<a class="headerlink" href="#sorting" title="Link to this heading"></a></h2>
<p>Python has a handful of sorting methods built in:</p>
<p><code class="docutils literal notranslate"><span class="pre">list.sort()</span></code> – for sorting a list in place.
<code class="docutils literal notranslate"><span class="pre">sorted(iterable)</span></code> – for creating a sorted copy of an iterable (sequence).</p>
<p>And a couple of more obscure ones.</p>
<p>In order for your custom objects to be sortable, they need the <code class="docutils literal notranslate"><span class="pre">__lt__</span></code> (less than) magic method defined – that’s about it.</p>
<p>So if you are using the <code class="docutils literal notranslate"><span class="pre">total_ordering</span></code> decorator, it’s best to define <code class="docutils literal notranslate"><span class="pre">__eq__</span></code> and <code class="docutils literal notranslate"><span class="pre">__lt__</span></code> – that way sorting will be able to use a “native” method for sorting, and maybe get better performance.</p>
</section>
<section id="sort-key-methods">
<h2>Sort key methods<a class="headerlink" href="#sort-key-methods" title="Link to this heading"></a></h2>
<p>By default, the sorting methods use <code class="docutils literal notranslate"><span class="pre">__lt__</span></code> for comparison, and that algorithm calls <code class="docutils literal notranslate"><span class="pre">__lt__</span></code> O(n log(n)) times. But if you pass a “key” function in to the sort call:</p>
<p><code class="docutils literal notranslate"><span class="pre">a_list.sort(key=key_fun)</span></code></p>
<p>then the key_fun is only called n times, and if the key returns a simple type, like an integer or float, then the sorting will be faster.</p>
<p>So it often helps to provide a sort_key() method on your class, so it can be passed in to the sort methods:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">Simple</span><span class="p">:</span>
<span class="w"> </span><span class="sd">"""</span>
<span class="sd"> simple class to demonstrate a simple sorting key method</span>
<span class="sd"> """</span>
<span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">val</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">val</span> <span class="o">=</span> <span class="n">val</span>
<span class="k">def</span><span class="w"> </span><span class="nf">sort_key</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">val</span>
</pre></div>
</div>
<p>And to use it:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">list_of_Simple_objects</span><span class="o">.</span><span class="n">sort</span><span class="p">(</span><span class="n">key</span><span class="o">=</span><span class="n">Simple</span><span class="o">.</span><span class="n">sort_key</span><span class="p">)</span>
</pre></div>
</div>
<p>See: <a class="reference download internal" download="" href="../_downloads/399e36e44f4ba5aec7db0351a5f6802e/sort_key.py"><code class="xref download docutils literal notranslate"><span class="pre">sort_key.py</span></code></a> for a complete example with timing. Here is an example of running it:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Timing</span> <span class="k">for</span> <span class="mi">10000</span> <span class="n">items</span>
<span class="n">regular</span> <span class="n">sort</span> <span class="n">took</span><span class="p">:</span> <span class="mf">0.04288</span><span class="n">s</span>
<span class="n">key</span> <span class="n">sort</span> <span class="n">took</span><span class="p">:</span> <span class="mf">0.004779</span><span class="n">s</span>
<span class="n">performance</span> <span class="n">improvement</span> <span class="n">factor</span><span class="p">:</span> <span class="mf">8.9726</span>
</pre></div>
</div>
<p>So almost 9 times faster for a 10,000 item list. Pretty good, eh?</p>
</section>
<section id="an-example">
<h2>An Example<a class="headerlink" href="#an-example" title="Link to this heading"></a></h2>
<p>Each of these methods supports a common Python operation.</p>
<p>For example, to make ‘+’ work with a sequence type in a vector-like fashion,
implement <code class="docutils literal notranslate"><span class="pre">__add__</span></code>:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="fm">__add__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">v</span><span class="p">):</span>
<span class="w"> </span><span class="sd">"""return the element-wise vector sum of self and v</span>
<span class="sd"> """</span>
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">==</span> <span class="nb">len</span><span class="p">(</span><span class="n">v</span><span class="p">)</span>
<span class="k">return</span> <span class="n">vector</span><span class="p">([</span><span class="n">x1</span> <span class="o">+</span> <span class="n">x2</span> <span class="k">for</span> <span class="n">x1</span><span class="p">,</span> <span class="n">x2</span> <span class="ow">in</span> <span class="nb">zip</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">v</span><span class="p">)])</span>
</pre></div>
</div>
<p>[a slightly more complete example may be seen here <a class="reference download internal" download="" href="../_downloads/1a51769567a10ff0d20491c9117ad604/vector.py"><code class="xref download docutils literal notranslate"><span class="pre">vector.py</span></code></a>]</p>
<section id="emulating-standard-types">
<h3>Emulating Standard types<a class="headerlink" href="#emulating-standard-types" title="Link to this heading"></a></h3>
<p>Making your classes behave like the built-ins.</p>
</section>
</section>
<section id="the-container-protocol">
<h2>The Container Protocol<a class="headerlink" href="#the-container-protocol" title="Link to this heading"></a></h2>
<p>Want to make a container type? Here’s what you need:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="nb">object</span><span class="o">.</span><span class="fm">__len__</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
<span class="nb">object</span><span class="o">.</span><span class="fm">__getitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="p">)</span>
<span class="nb">object</span><span class="o">.</span><span class="fm">__setitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>
<span class="nb">object</span><span class="o">.</span><span class="fm">__delitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="p">)</span>
<span class="nb">object</span><span class="o">.</span><span class="fm">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
<span class="nb">object</span><span class="o">.</span><span class="fm">__reversed__</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
<span class="nb">object</span><span class="o">.</span><span class="fm">__contains__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">item</span><span class="p">)</span>
<span class="nb">object</span><span class="o">.</span><span class="fm">__index__</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">__len__</span></code> is called when len(object) is called.</p>
<p><code class="docutils literal notranslate"><span class="pre">__reversed__</span></code> is called when reversed(object) is called.</p>
<p><code class="docutils literal notranslate"><span class="pre">__contains__</span></code> is called with <code class="docutils literal notranslate"><span class="pre">in</span></code> is used: <code class="docutils literal notranslate"><span class="pre">something</span> <span class="pre">in</span> <span class="pre">object</span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">__iter__</span></code> is used for iteration – called when in a for loop.</p>
<p><code class="docutils literal notranslate"><span class="pre">__index__</span></code> is used to convert the object into an integer for indexing. So you don’t define this in a container type but rather define it for a type so it can be used as an index. If you have a class that could reasonably be interpreted as an index, you should define this. It should return an integer. This was added to support multiple integer types for numpy.</p>
</section>
<section id="indexing-and-slicing">
<h2>Indexing and Slicing<a class="headerlink" href="#indexing-and-slicing" title="Link to this heading"></a></h2>
<p><code class="docutils literal notranslate"><span class="pre">__getitem__</span></code> and <code class="docutils literal notranslate"><span class="pre">set__item__</span></code> are used when indexing:</p>
<p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">=</span> <span class="pre">object[i]</span></code> calls <code class="docutils literal notranslate"><span class="pre">__getitem__</span></code>, and <code class="docutils literal notranslate"><span class="pre">object[i]</span> <span class="pre">=</span> <span class="pre">something</span></code> calls <code class="docutils literal notranslate"><span class="pre">__setitem__</span></code>.</p>
<p>But indexing is pretty complex in python. There is simple indexing: <code class="docutils literal notranslate"><span class="pre">object[i]</span></code>, but there is also slicing: <code class="docutils literal notranslate"><span class="pre">object[i:j:skip]</span></code></p>
<p>When you implement <code class="docutils literal notranslate"><span class="pre">__getitem__(self,</span> <span class="pre">index)</span></code>, <code class="docutils literal notranslate"><span class="pre">index</span></code> will simply be the index if it’s a simple index, but if it’s slicing, it will be a <code class="docutils literal notranslate"><span class="pre">slice</span></code> object. Python also supports multiple slices:</p>
<p><code class="docutils literal notranslate"><span class="pre">object[a:b,c:d]</span></code></p>
<p>These are used in numpy to support multi-dimensional arrays, for instance.</p>
<p>In this case, a tuple of slice objects is passed in.</p>
<p>See: <a class="reference download internal" download="" href="../_downloads/56c8a64286905e2661129d04085c7408/index_slicing.py"><code class="xref download docutils literal notranslate"><span class="pre">index_slicing.py</span></code></a></p>
</section>
<section id="callable-classes">
<h2>Callable classes<a class="headerlink" href="#callable-classes" title="Link to this heading"></a></h2>
<p>We’ve been using functions a lot:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">my_fun</span><span class="p">(</span><span class="n">something</span><span class="p">):</span>
<span class="n">do_something</span>
<span class="o">...</span>
<span class="k">return</span> <span class="n">something</span>
</pre></div>
</div>
<p>And then we can call it:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">result</span> <span class="o">=</span> <span class="n">my_fun</span><span class="p">(</span><span class="n">some_arguments</span><span class="p">)</span>
</pre></div>
</div>
<p>But what if we need to store some data to know how to evaluate that function?</p>
<p>Example: a function that computes a quadratic function:</p>
<div class="math notranslate nohighlight">
\[y = a x^2 + bx + c\]</div>
<p>You could pass in a, b and c each time:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">quadratic</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">,</span> <span class="n">c</span><span class="p">):</span>
<span class="k">return</span> <span class="n">a</span> <span class="o">*</span> <span class="n">x</span><span class="o">**</span><span class="mi">2</span> <span class="o">+</span> <span class="n">b</span> <span class="o">*</span> <span class="n">x</span> <span class="o">+</span> <span class="n">c</span>
</pre></div>
</div>
<p>But what if you are using the same a, b, and c numerous times?</p>
<p>Or what if you need to pass this in to something
(like map) that requires a function that takes a single argument?</p>
</section>
<section id="callables">
<h2>“Callables”<a class="headerlink" href="#callables" title="Link to this heading"></a></h2>
<p>Various places in Python expect a “callable” – something that you can
call like a function:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">a_result</span> <span class="o">=</span> <span class="n">something</span><span class="p">(</span><span class="n">some_arguments</span><span class="p">)</span>
</pre></div>
</div>
<p>“Something” in this case is often a function, but can be anything else
that is “callable”.</p>
<p>What have we been introduced to recently that is “callable”, but not a
function object?</p>
</section>
<section id="custom-callable-objects">
<h2>Custom callable objects<a class="headerlink" href="#custom-callable-objects" title="Link to this heading"></a></h2>
<p>The trick is one of Python’s “magic methods”</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="fm">__call__</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
</pre></div>
</div>
<p>If you define a <code class="docutils literal notranslate"><span class="pre">__call__</span></code> method in your class, it will be used when
code “calls” an instance of your class:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">Callable</span><span class="p">:</span>
<span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">.....</span><span class="p">)</span>
<span class="n">some_initilization</span>
<span class="k">def</span><span class="w"> </span><span class="fm">__call__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">some_parameters</span><span class="p">)</span>
</pre></div>
</div>
<p>Then you can do:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">callable_instance</span> <span class="o">=</span> <span class="n">Callable</span><span class="p">(</span><span class="n">some_arguments</span><span class="p">)</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">callable_instance</span><span class="p">(</span><span class="n">some_arguments</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="callable-example">
<h2>Callable example<a class="headerlink" href="#callable-example" title="Link to this heading"></a></h2>
<p>An example of writing a callable class:</p>
<p>Write a class for a quadratic equation.</p>
<ul class="simple">
<li><p>The initializer for that class should take the parameters: <code class="docutils literal notranslate"><span class="pre">a,</span> <span class="pre">b,</span> <span class="pre">c</span></code></p></li>
<li><p>It should store those parameters as attributes.</p></li>
<li><p>The resulting instance should evaluate the function when called, and return the result:</p></li>
</ul>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">my_quad</span> <span class="o">=</span> <span class="n">Quadratic</span><span class="p">(</span><span class="n">a</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">b</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span> <span class="n">c</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="n">my_quad</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
</pre></div>
</div>
<p>Here’s one way to do that:
<a class="reference download internal" download="" href="../_downloads/09156b87264df3eed45e647a1081ff51/quadratic.py"><code class="xref download docutils literal notranslate"><span class="pre">quadratic.py</span></code></a></p>
</section>
<section id="protocols-in-summary">
<h2>Protocols in Summary<a class="headerlink" href="#protocols-in-summary" title="Link to this heading"></a></h2>
<p>Use special methods when you want your class to act like a “standard” type or class in some way.</p>
<p>Look up the special methods you need and define them (and only the ones you need).</p>
<p>There’s more to read about the details of implementing these methods:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://docs.python.org/3.8/reference/datamodel.html#special-method-names">https://docs.python.org/3.8/reference/datamodel.html#special-method-names</a></p></li>
</ul>
</section>
<section id="references">
<h2>References<a class="headerlink" href="#references" title="Link to this heading"></a></h2>
<p>Here is a good reference for magic methods:</p>
<p><a class="reference external" href="http://minhhh.github.io/posts/a-guide-to-pythons-magic-methods">http://minhhh.github.io/posts/a-guide-to-pythons-magic-methods</a></p>
<p>And with a bit more explanation:</p>
<p><a class="reference external" href="https://www.python-course.eu/python3_magic_methods.php">https://www.python-course.eu/python3_magic_methods.php</a></p>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="StaticAndClassMethods.html" class="btn btn-neutral float-left" title="Static and Class Methods" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="../exercises/circle/circle_class.html" class="btn btn-neutral float-right" title="Circle Class Exercise" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2025, Natasha Aleksandrova, Christopher Barker, Brian Dorsey, Cris Ewing, Christy Heaton, Jon Jacky, Maria McKinley, Andy Miles, Rick Riehle, Joseph Schilz, Joseph Sheedy, Hosung Song. Creative Commons Attribution-ShareAlike 4.0 license.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>