- Notifications
You must be signed in to change notification settings - Fork 54
/
Copy pathWriting_Good_Code.html
1029 lines (921 loc) · 114 KB
/
Writing_Good_Code.html
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
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<htmlclass="writer-html5" lang="en" >
<head>
<metacharset="utf-8" /><metacontent="Topic: Writing good code, Difficulty: Easy, Category: Section" name="description" />
<metacontent="pep8, code style, lint, format, best practices, type hint, documentation, numpydoc, sphinx, typing, annotation, whitespace" name="keywords" />
<metaname="viewport" content="width=device-width, initial-scale=1.0" />
<title>Writing Good Code — Python Like You Mean It</title>
<linkrel="stylesheet" href="../_static/pygments.css" type="text/css" />
<linkrel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<linkrel="stylesheet" href="../_static/my_theme.css" type="text/css" />
<!--[if lt IE 9]>
<script src="../_static/js/html5shiv.min.js"></script>
<![endif]-->
<scriptdata-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
<scriptsrc="../_static/jquery.js"></script>
<scriptsrc="../_static/underscore.js"></script>
<scriptsrc="../_static/doctools.js"></script>
<scriptasync="async" src="https://www.googletagmanager.com/gtag/js?id=UA-115029372-1"></script>
<scriptsrc="../_static/gtag.js"></script>
<scriptcrossorigin="anonymous" integrity="sha256-Ae2Vz/4ePdIu6ZyI/5ZGsYnb+m0JlOmKPjt6XZ9JJkA=" src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"></script>
<script>window.MathJax={"tex": {"inlineMath": [["$","$"],["\\(","\\)"]],"processEscapes": true},"options": {"ignoreHtmlClass": "tex2jax_ignore|mathjax_ignore|document","processHtmlClass": "tex2jax_process|mathjax_process|math|output_area"}}</script>
<scriptdefer="defer" src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
<scriptsrc="../_static/js/theme.js"></script>
<linkrel="index" title="Index" href="../genindex.html" />
<linkrel="search" title="Search" href="../search.html" />
<linkrel="next" title="Matplotlib" href="Matplotlib.html" />
<linkrel="prev" title="Module 5: Odds and Ends" href="../module_5.html" />
</head>
<bodyclass="wy-body-for-nav">
<divclass="wy-grid-for-nav">
<navdata-toggle="wy-nav-shift" class="wy-nav-side">
<divclass="wy-side-scroll">
<divclass="wy-side-nav-search" >
<ahref="../index.html" class="icon icon-home"> Python Like You Mean It
</a>
<divclass="version">
1.4
</div>
<divrole="search">
<formid="rtd-search-form" class="wy-form" action="../search.html" method="get">
<inputtype="text" name="q" placeholder="Search docs" />
<inputtype="hidden" name="check_keywords" value="yes" />
<inputtype="hidden" name="area" value="default" />
</form>
</div>
</div><divclass="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<pclass="caption" role="heading"><spanclass="caption-text">Table of Contents:</span></p>
<ulclass="current">
<liclass="toctree-l1"><aclass="reference internal" href="../intro.html">Python Like You Mean It</a></li>
<liclass="toctree-l1"><aclass="reference internal" href="../module_1.html">Module 1: Getting Started with Python</a></li>
<liclass="toctree-l1"><aclass="reference internal" href="../module_2.html">Module 2: The Essentials of Python</a></li>
<liclass="toctree-l1"><aclass="reference internal" href="../module_2_problems.html">Module 2: Problems</a></li>
<liclass="toctree-l1"><aclass="reference internal" href="../module_3.html">Module 3: The Essentials of NumPy</a></li>
<liclass="toctree-l1"><aclass="reference internal" href="../module_3_problems.html">Module 3: Problems</a></li>
<liclass="toctree-l1"><aclass="reference internal" href="../module_4.html">Module 4: Object Oriented Programming</a></li>
<liclass="toctree-l1 current"><aclass="reference internal" href="../module_5.html">Module 5: Odds and Ends</a><ulclass="current">
<liclass="toctree-l2 current"><aclass="current reference internal" href="#">Writing Good Code</a><ul>
<liclass="toctree-l3"><aclass="reference internal" href="#The-PEP8-Style-Guide-to-Python-Code">The PEP8 Style Guide to Python Code</a><ul>
<liclass="toctree-l4"><aclass="reference internal" href="#Being-Pythonic">Being Pythonic</a></li>
<liclass="toctree-l4"><aclass="reference internal" href="#Naming-Conventions">Naming Conventions</a></li>
<liclass="toctree-l4"><aclass="reference internal" href="#Indentations-and-Spacing">Indentations and Spacing</a></li>
</ul>
</li>
<liclass="toctree-l3"><aclass="reference internal" href="#Type-Hinting">Type-Hinting</a><ul>
<liclass="toctree-l4"><aclass="reference internal" href="#What-is-It-Good-For?-(Absolutely-Nothing)">What is It Good For? (Absolutely Nothing)</a></li>
<liclass="toctree-l4"><aclass="reference internal" href="#Using-the-typing-Module">Using the <codeclass="docutils literal notranslate"><spanclass="pre">typing</span></code> Module</a></li>
<liclass="toctree-l4"><aclass="reference internal" href="#Writing-Good-Type-Hints-(quack-quack)">Writing Good Type-Hints (quack quack)</a></li>
</ul>
</li>
<liclass="toctree-l3"><aclass="reference internal" href="#Documentation-Styles">Documentation Styles</a><ul>
<liclass="toctree-l4"><aclass="reference internal" href="#The-NumPy-Documentation-Style">The NumPy Documentation Style</a></li>
<liclass="toctree-l4"><aclass="reference internal" href="#The-Google-Documentation-Style">The Google Documentation Style</a></li>
</ul>
</li>
<liclass="toctree-l3"><aclass="reference internal" href="#Links-to-Official-Documentation">Links to Official Documentation</a></li>
<liclass="toctree-l3"><aclass="reference internal" href="#Reading-Comprehension-Solutions">Reading Comprehension Solutions</a></li>
</ul>
</li>
<liclass="toctree-l2"><aclass="reference internal" href="Matplotlib.html">Matplotlib</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="WorkingWithFiles.html">Working with Files</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="Modules_and_Packages.html">Import: Modules and Packages</a></li>
</ul>
</li>
<liclass="toctree-l1"><aclass="reference internal" href="../changes.html">Changelog</a></li>
</ul>
</div>
</div>
</nav>
<sectiondata-toggle="wy-nav-shift" class="wy-nav-content-wrap"><navclass="wy-nav-top" aria-label="Mobile navigation menu" >
<idata-toggle="wy-nav-top" class="fa fa-bars"></i>
<ahref="../index.html">Python Like You Mean It</a>
</nav>
<divclass="wy-nav-content">
<divclass="rst-content">
<divrole="navigation" aria-label="Page navigation">
<ulclass="wy-breadcrumbs">
<li><ahref="../index.html" class="icon icon-home"></a> »</li>
<li><ahref="../module_5.html">Module 5: Odds and Ends</a> »</li>
<li>Writing Good Code</li>
<liclass="wy-breadcrumbs-aside">
<ahref="../_sources/Module5_OddsAndEnds/Writing_Good_Code.md.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<divrole="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<divitemprop="articleBody">
<style>
/* CSS overrides for sphinx_rtd_theme */
/* 24px margin */
.nbinput.nblast.container,
.nboutput.nblast.container {
margin-bottom:19px; /* padding has already 5px */
}
/* ... except between code cells! */
.nblast.container+ .nbinput.container {
margin-top:-19px;
}
.admonition>p:before {
margin-right:4px; /* make room for the exclamation icon */
}
/* Fix math alignment, see https://github.com/rtfd/sphinx_rtd_theme/pull/686 */
.math {
text-align: unset;
}
</style>
<divclass="section" id="Writing-Good-Code">
<h1>Writing Good Code<aclass="headerlink" href="#Writing-Good-Code" title="Permalink to this headline"></a></h1>
<p>Throughout PLYMI we have been concerned with learning the rules for writing valid Python code. That is, we have taken care to ensure that our computers can understand the instructions that we have written for them. Here, we will discuss methods for making our code easier for <em>humans</em> to understand. Specifically, we will study:</p>
<ulclass="simple">
<li><p>“PEP8”: the official style guide for Python code.</p></li>
<li><p>Python’s system for adding so-called “type hints” to functions.</p></li>
<li><p>Formal documentation specifications such as NumPy docs and Napolean docs.</p></li>
</ul>
<p>The immediate purpose of discussing these items is that they will help us write code that is easy to understand and maintain. In the long term, they will serve to make our projects long-lived and useful to many more people. It can be surprising to see how quickly a code base can atrophy, becoming opaque and unusable even to its creator, when it wasn’t designed with a sufficient attention to detail and documentation.</p>
<p>It is difficult to overstate the importance of this material.</p>
<divclass="section" id="The-PEP8-Style-Guide-to-Python-Code">
<h2>The PEP8 Style Guide to Python Code<aclass="headerlink" href="#The-PEP8-Style-Guide-to-Python-Code" title="Permalink to this headline"></a></h2>
<divclass="admonition warning">
<pclass="admonition-title fa fa-exclamation-circle"><strong>What is a PEP?</strong></p>
<p>We will be referencing several “PEPs” in this section. PEP stands for Python Enhancement Proposal. Any fundamental changes to the core Python language, the CPython interpreter, or the modules in Python’s standard library must first be submitted as a PEP, which goes through an approval process. You can read more about the purposes and guidelines of PEPs <aclass="reference external" href="https://www.python.org/dev/peps/pep-0001/">here</a>. The complete index of PEPs is available <aclass="reference external" href="https://www.python.org/dev/peps/">here</a>.</p>
</div>
<p><aclass="reference external" href="https://www.python.org/dev/peps/pep-0008/#code-lay-out">PEP 8</a> is a design document that specifies a coherent code style guide for the Python community.. It touches on a wide array of “dos” and “don’ts” when making style decision in your code. Many of these items are exceedingly simple. For example, PEP 8 calls for the inclusion of a single whitespace around binary mathematical operators; e.g.:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Do:</span>
<spanclass="n">x</span><spanclass="o">=</span><spanclass="n">x</span><spanclass="o">+</span><spanclass="mi">1</span>
<spanclass="c1"># Don't:</span>
<spanclass="n">x</span><spanclass="o">=</span><spanclass="n">x</span><spanclass="o">+</span><spanclass="mi">1</span>
</pre></div>
</div>
<p>The biggest impact that this document has is that it guides Python users to write similar-looking code. Thus, writing code that adheres to PEP8 will ensure your code is easy for others to read, and vice versa. Note that the code you have encountered throughout PLYMI adheres to this style guide.</p>
<p>We will make salient some of the PEP8 guidelines that are most pertinent to the variety of code that you have encountered in your reading thus far. That being said, you should take the time to read through <aclass="reference external" href="https://www.python.org/dev/peps/pep-0008/#code-lay-out">PEP 8 in full</a>, and consult it regularly when you write code. It won’t take long for you to internalize most of its guidelines. Lastly, note that many
<aclass="reference external" href="https://www.pythonlikeyoumeanit.com/Module1_GettingStartedWithPython/Getting_Started_With_IDEs_and_Notebooks.html">IDEs</a> have have tools called “linters” that will parse your code and warn you when your code is in violation of PEP8’s guidelines. This is an excellent mechanism for ensuring that your code adheres to this style specification.</p>
<divclass="section" id="Being-Pythonic">
<h3>Being Pythonic<aclass="headerlink" href="#Being-Pythonic" title="Permalink to this headline"></a></h3>
<p>We will being by studying some guidelines for writing idiomatic Python code. That is, these guide us to follow the syntax that the creators of Python intended for us to use.</p>
<p>For instance, always leverage the negated operators <codeclass="docutils literal notranslate"><spanclass="pre">is</span><spanclass="pre">not</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">not</span><spanclass="pre">in</span></code>. For example <codeclass="docutils literal notranslate"><spanclass="pre">not</span><spanclass="pre">x</span><spanclass="pre">is</span><spanclass="pre">None</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">x</span><spanclass="pre">is</span><spanclass="pre">not</span><spanclass="pre">None</span></code> are functionally equivalent, but the latter is clearly preferable as it matches our native grammar.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Do:</span>
<spanclass="n">x</span><spanclass="ow">not</span><spanclass="ow">in</span><spanclass="n">collection</span>
<spanclass="c1"># Don't</span>
<spanclass="ow">not</span><spanclass="n">x</span><spanclass="ow">in</span><spanclass="n">collections</span>
<spanclass="c1"># Do:</span>
<spanclass="n">x</span><spanclass="ow">is</span><spanclass="ow">not</span><spanclass="kc">None</span>
<spanclass="c1"># Don't</span>
<spanclass="ow">not</span><spanclass="n">x</span><spanclass="ow">is</span><spanclass="kc">None</span>
</pre></div>
</div>
<p>Do not use parentheses to create unnecessary closures. Parentheses should be used for specifying function signatures, calling objects (e.g. calling a function), associating mathematical operations, defining generator-expressions, and grouping long multi-line expressions.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Do:</span>
<spanclass="k">if</span><spanclass="n">x</span><spanclass="o">></span><spanclass="mi">2</span><spanclass="p">:</span>
<spanclass="n">x</span><spanclass="o">+=</span><spanclass="mi">1</span>
<spanclass="c1"># Don't:</span>
<spanclass="k">if</span><spanclass="p">(</span><spanclass="n">x</span><spanclass="o">></span><spanclass="mi">2</span><spanclass="p">):</span>
<spanclass="n">x</span><spanclass="o">+=</span><spanclass="mi">1</span>
<spanclass="c1"># Do</span>
<spanclass="k">if</span><spanclass="p">(</span><spanclass="n">long_variable_name</span><spanclass="ow">in</span><spanclass="n">a_long_list_name</span>
<spanclass="ow">and</span><spanclass="n">long_variable_name</span><spanclass="ow">not</span><spanclass="ow">in</span><spanclass="n">another_long_name</span><spanclass="p">):</span>
<spanclass="n">x</span><spanclass="o">+=</span><spanclass="mi">1</span>
<spanclass="c1"># Don't</span>
<spanclass="k">if</span><spanclass="n">long_variable_name</span><spanclass="ow">in</span><spanclass="n">a_long_list_name</span><spanclass="ow">and</span><spanclass="n">long_variable_name</span><spanclass="ow">not</span><spanclass="ow">in</span><spanclass="n">another_long_name</span><spanclass="p">:</span>
<spanclass="n">x</span><spanclass="o">+=</span><spanclass="mi">1</span>
<spanclass="c1"># Do:</span>
<spanclass="k">for</span><spanclass="n">i</span><spanclass="ow">in</span><spanclass="n">numbers</span><spanclass="p">:</span>
<spanclass="n">x</span><spanclass="o">.</span><spanclass="n">append</span><spanclass="p">(</span><spanclass="n">i</span><spanclass="o">**</span><spanclass="mi">2</span><spanclass="p">)</span>
<spanclass="c1"># Don't:</span>
<spanclass="k">for</span><spanclass="n">i</span><spanclass="ow">in</span><spanclass="n">numbers</span><spanclass="p">:(</span>
<spanclass="n">x</span><spanclass="o">.</span><spanclass="n">append</span><spanclass="p">(</span><spanclass="n">i</span><spanclass="o">**</span><spanclass="mi">2</span><spanclass="p">)</span>
<spanclass="p">)</span>
</pre></div>
</div>
<p>Finally, make use of <aclass="reference external" href="https://www.pythonlikeyoumeanit.com/Module2_EssentialsOfPython/ConditionalStatements.html#bool-and-Truth-Values-of-Non-Boolean-Objects">boolean values for non-boolean objects</a> in conditional expressions. For example, you can rely on the fact that empty sequence-objects will evaluate to <codeclass="docutils literal notranslate"><spanclass="pre">False</span></code> in conditional statements.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Do:</span>
<spanclass="k">if</span><spanclass="n">list_of_names</span><spanclass="p">:</span>
<spanclass="n">x</span><spanclass="o">+=</span><spanclass="mi">1</span>
<spanclass="c1"># Don't:</span>
<spanclass="k">if</span><spanclass="nb">len</span><spanclass="p">(</span><spanclass="n">list_of_names</span><spanclass="p">)</span><spanclass="o">></span><spanclass="mi">0</span><spanclass="p">:</span>
<spanclass="n">x</span><spanclass="o">+=</span><spanclass="mi">1</span>
<spanclass="c1"># Do:</span>
<spanclass="n">result</span><spanclass="o">=</span><spanclass="s2">"on"</span><spanclass="k">if</span><spanclass="n">integer_flag</span><spanclass="k">else</span><spanclass="s2">"off</span>
<spanclass="c1"># Don't:</span>
<spanclass="n">result</span><spanclass="o">=</span><spanclass="s2">"on"</span><spanclass="k">if</span><spanclass="n">integer_flag</span><spanclass="o">!=</span><spanclass="mi">0</span><spanclass="k">else</span><spanclass="s2">"off</span>
</pre></div>
</div>
</div>
<divclass="section" id="Naming-Conventions">
<h3>Naming Conventions<aclass="headerlink" href="#Naming-Conventions" title="Permalink to this headline"></a></h3>
<p>Class names should use the <codeclass="docutils literal notranslate"><spanclass="pre">CamelCase</span></code> (aka <codeclass="docutils literal notranslate"><spanclass="pre">CapWords</span></code>) formatting convention, whereas functions and variables should use all-lowercase characters in their names. Underscores can be used in longer lowercased names to make them easier to read (i.e. <codeclass="docutils literal notranslate"><spanclass="pre">snake_case</span></code>).</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># naming conventions for classes</span>
<spanclass="c1"># Do:</span>
<spanclass="k">class</span><spanclass="nc">ShoppingList</span><spanclass="p">:</span>
<spanclass="k">pass</span>
<spanclass="c1"># Don't:</span>
<spanclass="k">class</span><spanclass="nc">shoppingList</span><spanclass="p">:</span>
<spanclass="k">pass</span>
</pre></div>
</div>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># naming conventions for local variables and functions</span>
<spanclass="c1"># Do:</span>
<spanclass="n">list_of_students</span><spanclass="o">=</span><spanclass="p">[</span><spanclass="s2">"Alyosha"</span><spanclass="p">,</span><spanclass="s2">"Biff"</span><spanclass="p">,</span><spanclass="s2">"Celine"</span><spanclass="p">]</span>
<spanclass="k">def</span><spanclass="nf">rotate_image</span><spanclass="p">(</span><spanclass="n">image</span><spanclass="p">):</span>
<spanclass="k">pass</span>
<spanclass="c1"># Don't</span>
<spanclass="n">ListOfStudents</span><spanclass="o">=</span><spanclass="p">[</span><spanclass="s2">"Shmangela"</span><spanclass="p">,</span><spanclass="s2">"Shmonathan"</span><spanclass="p">]</span>
<spanclass="k">def</span><spanclass="nf">rotateimage</span><spanclass="p">(</span><spanclass="n">image</span><spanclass="p">):</span>
<spanclass="k">pass</span>
</pre></div>
</div>
<p>To be clear, there is nothing fundamentally correct about using <codeclass="docutils literal notranslate"><spanclass="pre">CamelCasing</span></code> for class names and <codeclass="docutils literal notranslate"><spanclass="pre">snake_casing</span></code> for functions and variable names. That being said, most Python users expect code to adhere to these conventions and will struggle to understand and use your code if you do not adhere to them.</p>
<p>Constants - variables whose values are not to be changed anywhere within the code - should be specified using ALL_CAPS. Underscores can be used for improving readability.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># naming conventions for constants</span>
<spanclass="c1"># Do:</span>
<spanclass="n">BOILING_POINT</span><spanclass="o">=</span><spanclass="mi">100</span><spanclass="c1"># celsius</span>
<spanclass="c1"># Don't:</span>
<spanclass="n">boiling_point</span><spanclass="o">=</span><spanclass="mi">100</span><spanclass="c1"># celsius</span>
</pre></div>
</div>
<p>Variables that are only to be used internally within the code by developers can be identified using a leading underscore. For example, if you encounter the line of code <codeclass="docutils literal notranslate"><spanclass="pre">_use_gpu</span><spanclass="pre">=</span><spanclass="pre">True</span></code>, this means that the variable <codeclass="docutils literal notranslate"><spanclass="pre">_use_gpu</span></code> is only meant to be viewed and edited by the people who are actually writing the code. Note that this variable will not behave differently from <codeclass="docutils literal notranslate"><spanclass="pre">use_gpu</span></code> - the leading underscore is simply a visual indicator and nothing more.</p>
<p>You can use a trailing underscore when your variable name would otherwise conflict with terms reserved by Python. For example you cannot name a variable <codeclass="docutils literal notranslate"><spanclass="pre">class</span></code>, as this term is reserved by Python for defining a new class-object. Instead you could name the variable <codeclass="docutils literal notranslate"><spanclass="pre">class_</span></code>. This should be used only sparingly.</p>
<p>Paramount to all of this is that variables are given <em>descriptive</em> names.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Do:</span>
<spanclass="k">for</span><spanclass="n">temperature</span><spanclass="ow">in</span><spanclass="n">list_of_temperatures</span><spanclass="p">:</span>
<spanclass="n">pressure</span><spanclass="o">=</span><spanclass="n">gauge</span><spanclass="p">(</span><spanclass="n">temperature</span><spanclass="p">)</span>
<spanclass="c1"># Don't:</span>
<spanclass="k">for</span><spanclass="n">thing</span><spanclass="ow">in</span><spanclass="n">x</span><spanclass="p">:</span>
<spanclass="n">thingthing</span><spanclass="o">=</span><spanclass="n">f</span><spanclass="p">(</span><spanclass="n">thing</span><spanclass="p">)</span>
<spanclass="c1"># No this is not an exaggeration.</span>
<spanclass="c1"># I have really seen code like this.</span>
</pre></div>
</div>
</div>
<divclass="section" id="Indentations-and-Spacing">
<h3>Indentations and Spacing<aclass="headerlink" href="#Indentations-and-Spacing" title="Permalink to this headline"></a></h3>
<p>You should use spaces, not tabs, when creating indentations.</p>
<p><aclass="reference external" href="https://www.pythonlikeyoumeanit.com/Module2_EssentialsOfPython/Introduction.html#Python-Uses-Whitespace-to-Delimit-Scope">Scope-delimiting indentations</a> should always consist of four spaces.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># using four spaces to delimit scope</span>
<spanclass="c1"># Do:</span>
<spanclass="k">if</span><spanclass="n">x</span><spanclass="o">></span><spanclass="mi">0</span><spanclass="p">:</span>
<spanclass="n">x</span><spanclass="o">=</span><spanclass="mi">2</span><spanclass="c1"># indented by four spaces</span>
<spanclass="c1"># Don't:</span>
<spanclass="k">if</span><spanclass="n">x</span><spanclass="o">></span><spanclass="mi">0</span><spanclass="p">:</span>
<spanclass="n">x</span><spanclass="o">=</span><spanclass="mi">2</span><spanclass="c1"># indented by not-four spaces</span>
</pre></div>
</div>
<p>Use hanging indentations to wrap a long line of code over two or more lines. That being said, you should ensure that contents within parentheses or brackets are aligned vertically:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Using hanging indents to manage long lines of code</span>
<spanclass="c1"># Do: use whitespace to align multi-line arguments in</span>
<spanclass="c1"># a function signature</span>
<spanclass="k">if</span><spanclass="nb">isinstance</span><spanclass="p">(</span><spanclass="n">item</span><spanclass="p">,</span><spanclass="nb">str</span><spanclass="p">):</span>
<spanclass="n">output</span><spanclass="o">=</span><spanclass="n">some_long_function_name</span><spanclass="p">(</span><spanclass="n">arg1</span><spanclass="p">,</span><spanclass="n">arg2</span><spanclass="p">,</span><spanclass="n">arg3</span><spanclass="p">,</span>
<spanclass="n">arg4</span><spanclass="p">,</span><spanclass="n">arg5</span><spanclass="p">,</span><spanclass="n">arg6</span><spanclass="p">)</span>
<spanclass="c1"># Don't:</span>
<spanclass="k">if</span><spanclass="nb">isinstance</span><spanclass="p">(</span><spanclass="n">item</span><spanclass="p">,</span><spanclass="nb">str</span><spanclass="p">):</span>
<spanclass="n">output</span><spanclass="o">=</span><spanclass="n">some_long_function_name</span><spanclass="p">(</span><spanclass="n">arg1</span><spanclass="p">,</span><spanclass="n">arg2</span><spanclass="p">,</span><spanclass="n">arg3</span><spanclass="p">,</span>
<spanclass="n">arg4</span><spanclass="p">,</span><spanclass="n">arg5</span><spanclass="p">,</span><spanclass="n">arg6</span><spanclass="p">)</span>
<spanclass="c1"># Do:</span>
<spanclass="n">grocery_list</span><spanclass="o">=</span><spanclass="p">{</span><spanclass="s2">"apple"</span><spanclass="p">:</span><spanclass="mi">2</span><spanclass="p">,</span><spanclass="s2">"banana"</span><spanclass="p">:</span><spanclass="mi">10</span><spanclass="p">,</span><spanclass="s2">"chocolate"</span><spanclass="p">:</span><spanclass="mf">1e34</span><spanclass="p">,</span>
<spanclass="s2">"toothpaste"</span><spanclass="p">:</span><spanclass="mi">1</span><spanclass="p">,</span><spanclass="s2">"shampoo"</span><spanclass="p">:</span><spanclass="mi">1</span><spanclass="p">}</span>
<spanclass="c1"># Don't: second line is under-indented</span>
<spanclass="n">grocery_list</span><spanclass="o">=</span><spanclass="p">{</span><spanclass="s2">"apple"</span><spanclass="p">:</span><spanclass="mi">2</span><spanclass="p">,</span><spanclass="s2">"banana"</span><spanclass="p">:</span><spanclass="mi">10</span><spanclass="p">,</span><spanclass="s2">"chocolate"</span><spanclass="p">:</span><spanclass="mf">1e34</span><spanclass="p">,</span>
<spanclass="s2">"toothpaste"</span><spanclass="p">:</span><spanclass="mi">1</span><spanclass="p">,</span><spanclass="s2">"shampoo"</span><spanclass="p">:</span><spanclass="mi">1</span><spanclass="p">}</span>
<spanclass="c1"># Do</span>
<spanclass="n">x</span><spanclass="o">=</span><spanclass="p">[[</span><spanclass="n">i</span><spanclass="o">**</span><spanclass="mi">2</span><spanclass="k">for</span><spanclass="n">i</span><spanclass="ow">in</span><spanclass="n">list_of_ages</span><spanclass="k">if</span><spanclass="n">i</span><spanclass="o">></span><spanclass="mi">10</span><spanclass="p">]</span>
<spanclass="k">for</span><spanclass="n">list_of_ages</span><spanclass="ow">in</span><spanclass="n">database</span><spanclass="p">]</span>
<spanclass="c1"># Don't: second line is over-indented</span>
<spanclass="n">x</span><spanclass="o">=</span><spanclass="p">[[</span><spanclass="n">i</span><spanclass="o">**</span><spanclass="mi">2</span><spanclass="k">for</span><spanclass="n">i</span><spanclass="ow">in</span><spanclass="n">list_of_ages</span><spanclass="k">if</span><spanclass="n">i</span><spanclass="o">></span><spanclass="mi">10</span><spanclass="p">]</span>
<spanclass="k">for</span><spanclass="n">list_of_ages</span><spanclass="ow">in</span><spanclass="n">database</span><spanclass="p">]</span>
</pre></div>
</div>
<p>Function and class definitions should be separated by two blank lines:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># separating function and class definitions using two blank lines</span>
<spanclass="c1"># Do:</span>
<spanclass="k">def</span><spanclass="nf">func_a</span><spanclass="p">():</span>
<spanclass="sd">"""I am function a"""</span>
<spanclass="k">return</span><spanclass="mi">1</span>
<spanclass="k">def</span><spanclass="nf">func_b</span><spanclass="p">():</span><spanclass="c1"># separated from func_a by two blank lines</span>
<spanclass="sd">"""I am function b"""</span>
<spanclass="k">return</span><spanclass="mi">2</span>
<spanclass="c1"># Don't:</span>
<spanclass="k">def</span><spanclass="nf">func_c</span><spanclass="p">():</span>
<spanclass="sd">"""I am function c"""</span>
<spanclass="k">return</span><spanclass="mi">1</span>
<spanclass="k">def</span><spanclass="nf">func_d</span><spanclass="p">():</span><spanclass="c1"># separated from func_c by one blank line</span>
<spanclass="sd">"""I am function d"""</span>
<spanclass="k">return</span><spanclass="mi">2</span>
</pre></div>
</div>
<p>Default-values for arguments in functions should be specified without any surrounding whitespace. This also holds when calling a function using a named argument.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># default values should not have whitespace around them</span>
<spanclass="c1"># Do:</span>
<spanclass="k">def</span><spanclass="nf">func</span><spanclass="p">(</span><spanclass="n">x</span><spanclass="p">,</span><spanclass="n">y</span><spanclass="o">=</span><spanclass="mi">2</span><spanclass="p">):</span>
<spanclass="k">return</span><spanclass="n">x</span><spanclass="o">+</span><spanclass="n">y</span>
<spanclass="c1"># Don't:</span>
<spanclass="k">def</span><spanclass="nf">func</span><spanclass="p">(</span><spanclass="n">x</span><spanclass="p">,</span><spanclass="n">y</span><spanclass="o">=</span><spanclass="mi">2</span><spanclass="p">):</span>
<spanclass="k">return</span><spanclass="n">x</span><spanclass="o">+</span><spanclass="n">y</span>
<spanclass="c1"># Do:</span>
<spanclass="n">grade</span><spanclass="o">=</span><spanclass="n">grade_lookup</span><spanclass="p">(</span><spanclass="n">name</span><spanclass="o">=</span><spanclass="s2">"Ryan"</span><spanclass="p">)</span>
<spanclass="c1"># Don't:</span>
<spanclass="n">grade</span><spanclass="o">=</span><spanclass="n">grade_lookup</span><spanclass="p">(</span><spanclass="n">name</span><spanclass="o">=</span><spanclass="s2">"Ryan"</span><spanclass="p">)</span>
</pre></div>
</div>
<p>As in written English, commas and colons should both follow a non-space character and should be followed by a whitespace. An exception to this is when there is a trailing comma/colon at the end of the line of code, or when a colon is used in a slice.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># a comma/colon should be followed by a whitespace</span>
<spanclass="c1"># Do:</span>
<spanclass="n">x</span><spanclass="o">=</span><spanclass="p">(</span><spanclass="mi">1</span><spanclass="p">,</span><spanclass="mi">2</span><spanclass="p">,</span><spanclass="mi">3</span><spanclass="p">)</span>
<spanclass="c1"># Don't</span>
<spanclass="n">x</span><spanclass="o">=</span><spanclass="p">(</span><spanclass="mi">1</span><spanclass="p">,</span><spanclass="mi">2</span><spanclass="p">,</span><spanclass="mi">3</span><spanclass="p">)</span>
<spanclass="n">x</span><spanclass="o">=</span><spanclass="p">(</span><spanclass="mi">1</span><spanclass="p">,</span><spanclass="mi">2</span><spanclass="p">,</span><spanclass="mi">3</span><spanclass="p">)</span>
<spanclass="c1"># Do:</span>
<spanclass="n">x</span><spanclass="o">=</span><spanclass="p">{</span><spanclass="mi">1</span><spanclass="p">:</span><spanclass="s2">"a"</span><spanclass="p">,</span><spanclass="mi">2</span><spanclass="p">:</span><spanclass="s2">"b"</span><spanclass="p">,</span><spanclass="mi">3</span><spanclass="p">:</span><spanclass="s2">"c"</span><spanclass="p">}</span>
<spanclass="c1"># Don't:</span>
<spanclass="n">x</span><spanclass="o">=</span><spanclass="p">{</span><spanclass="mi">1</span><spanclass="p">:</span><spanclass="s2">"a"</span><spanclass="p">,</span><spanclass="mi">2</span><spanclass="p">:</span><spanclass="s2">"b"</span><spanclass="p">,</span><spanclass="mi">3</span><spanclass="p">:</span><spanclass="s2">"c"</span><spanclass="p">}</span>
<spanclass="n">x</span><spanclass="o">=</span><spanclass="p">{</span><spanclass="mi">1</span><spanclass="p">:</span><spanclass="s2">"a"</span><spanclass="p">,</span><spanclass="mi">2</span><spanclass="p">:</span><spanclass="s2">"b"</span><spanclass="p">,</span><spanclass="mi">3</span><spanclass="p">:</span><spanclass="s2">"c"</span><spanclass="p">}</span>
<spanclass="c1"># Do:</span>
<spanclass="c1"># (1,) is a tuple containing the integer 1.</span>
<spanclass="c1"># Recall that (1) is the same as 1. The</span>
<spanclass="c1"># trailing comma is necessary for it to</span>
<spanclass="c1"># be treated as a tuple.</span>
<spanclass="n">x</span><spanclass="o">=</span><spanclass="p">(</span><spanclass="mi">1</span><spanclass="p">,)</span>
<spanclass="c1"># Don't:</span>
<spanclass="n">x</span><spanclass="o">=</span><spanclass="p">(</span><spanclass="mi">1</span><spanclass="p">,</span><spanclass="p">)</span>
<spanclass="c1"># Do:</span>
<spanclass="c1"># a simple slice should not contain whitespaces</span>
<spanclass="n">sublist</span><spanclass="o">=</span><spanclass="n">x</span><spanclass="p">[</span><spanclass="mi">1</span><spanclass="p">:</span><spanclass="mi">4</span><spanclass="p">]</span>
<spanclass="c1"># Don't:</span>
<spanclass="n">sublist</span><spanclass="o">=</span><spanclass="n">x</span><spanclass="p">[</span><spanclass="mi">1</span><spanclass="p">:</span><spanclass="mi">4</span><spanclass="p">]</span>
</pre></div>
</div>
<p>To conclude, consider that simply knowing that there exists a Python style guide, and that it is named PEP8, is the most important thing to take away from this section. Previously, you may not have even thought to search for such a document. That you consult PEP8 when you have code-style questions is the most important outcome here.</p>
<divclass="admonition warning">
<pclass="admonition-title fa fa-exclamation-circle"><strong>Automating Style:</strong></p>
<p>Although adhering to a clear and consistent style is critical for writing “good code,” enforcing such standards can be tedious and labor-intensive. This is especially true when you begin collaborating with others and working on large projects. Fortunately, several powerful tools exist that can help us automate good code styling.</p>
<ulclass="simple">
<li><p><aclass="reference external" href="https://github.com/PyCQA/flake8">flake8</a>: Analyzes your code to enforce the PEP8 standards and to catch bad code patterns, such as unused variables.</p>
<ul>
<li><p>IDEs like Visual Studio Code and PyCharm will automatically configure themselves to run flake8 or comparable <aclass="reference external" href="https://en.wikipedia.org/wiki/Lint_(software)">linters</a> on your code. They will add visual marks to your code to highlight problematic sections of code. This tool can also be run from the command line, or be configured to run automatically with other IDEs and text editors.</p></li>
</ul>
</li>
<li><p><aclass="reference external" href="https://isort.readthedocs.io/en/latest/">isort</a>: <em>“I sort your Python imports so you don’t have to”</em></p>
<ul>
<li><p>As promised, this tool manages the unruly stack of import statements that quickly accrue at the top of our code. It will sort import statements alphabetically, and will group them in accordance with PEP8.</p></li>
</ul>
</li>
<li><p><aclass="reference external" href="https://black.readthedocs.io/en/stable/">black</a>: <em>“Any code style you like, as long as it is black”</em></p>
<ul>
<li><p>Black is an uncompromising code formatter. You need not spend time formatting code correctly if you run black - it will format your code the same way every time. While this will take care of managing things like line-breaks, indentation, spacing, and brackets for you, it is still your responsibility to <aclass="reference external" href="https://www.pythonlikeyoumeanit.com/Module5_OddsAndEnds/Writing_Good_Code.html#Being-Pythonic">write code that is Pythonic</a> and to <aclass="reference external" href="https://www.pythonlikeyoumeanit.com/Module5_OddsAndEnds/Writing_Good_Code.html#Naming-Conventions">use good naming
conventions</a>.</p></li>
</ul>
</li>
</ul>
<p>It is useful to know that these tools exist; consider integrating them into your workflow as you become an increasingly-prolific “Pythoneer”.</p>
</div>
<divclass="admonition note">
<pclass="admonition-title fa fa-exclamation-circle"><strong>Takeaway:</strong></p>
<p><aclass="reference external" href="https://www.python.org/dev/peps/pep-0008/#code-lay-out">PEP8</a> is a design document for the Python community that specifies a coherent style guide for writing Python code. Adhering to this style guide will help to ensure that you write clean code that is organized in a consistent manner across projects. Furthermore, those who abide by PEP8 will find it easier to navigate other PEP8-adherent code bases.</p>
</div>
</div>
</div>
<divclass="section" id="Type-Hinting">
<h2>Type-Hinting<aclass="headerlink" href="#Type-Hinting" title="Permalink to this headline"></a></h2>
<p>Type hinting is a syntax that was introduced in Python 3.5 (via <aclass="reference external" href="https://www.python.org/dev/peps/pep-0484/">PEP 484</a>), which permits users to annotate their function definitions to indicate the object-types of a function’s inputs and outputs. For example, let’s define a function that counts the number of vowels in a string and annotate the function signature with type-hints.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># A function signature that has been annotated with type-hints</span>
<spanclass="k">def</span><spanclass="nf">count_vowels</span><spanclass="p">(</span><spanclass="n">x</span><spanclass="p">:</span><spanclass="nb">str</span><spanclass="p">)</span><spanclass="o">-></span><spanclass="nb">int</span><spanclass="p">:</span>
<spanclass="sd">"""Returns the number of vowels contained in `in_string`"""</span>
<spanclass="n">vowels</span><spanclass="o">=</span><spanclass="nb">set</span><spanclass="p">(</span><spanclass="s2">"aeiouAEIOU"</span><spanclass="p">)</span>
<spanclass="k">return</span><spanclass="nb">sum</span><spanclass="p">(</span><spanclass="mi">1</span><spanclass="k">for</span><spanclass="n">char</span><spanclass="ow">in</span><spanclass="n">x</span><spanclass="k">if</span><spanclass="n">char</span><spanclass="ow">in</span><spanclass="n">vowels</span><spanclass="p">)</span>
</pre></div>
</div>
<p>Here, we have “hinted” that <codeclass="docutils literal notranslate"><spanclass="pre">x</span></code> should be passed a string-type object, and that the function will return an integer-type object. The general form of an annotated function, with an arbitrary number of <aclass="reference external" href="https://www.pythonlikeyoumeanit.com/Module2_EssentialsOfPython/Functions.html#Arguments">positional arguments</a> and <aclass="reference external" href="https://www.pythonlikeyoumeanit.com/Module2_EssentialsOfPython/Functions.html#Default-Valued-Arguments">default-valued arguments</a> is as follows:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>def func_name(arg: <type>, [...], kwarg: <type> = <value>, [...])) -> <type>:
</pre></div>
</div>
<p>See that each argument name is followed by a colon and the type-object that serves as the type-hint. The return type of the function comes after the closing parenthesis of the signature; it is preceded by the arrow <codeclass="docutils literal notranslate"><spanclass="pre">-></span></code> and is followed by the colon that ends the function signature. The same syntax can be used to annotate methods in a class definition.</p>
<p>Let’s modify <codeclass="docutils literal notranslate"><spanclass="pre">count_vowels</span></code> and add a default-valued argument that permits users to optionally include ‘y’ as a vowel.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Type-hinting a default-valued argument</span>
<spanclass="k">def</span><spanclass="nf">count_vowels</span><spanclass="p">(</span><spanclass="n">x</span><spanclass="p">:</span><spanclass="nb">str</span><spanclass="p">,</span><spanclass="n">include_y</span><spanclass="p">:</span><spanclass="nb">bool</span><spanclass="o">=</span><spanclass="kc">False</span><spanclass="p">)</span><spanclass="o">-></span><spanclass="nb">int</span><spanclass="p">:</span>
<spanclass="sd">"""Returns the number of vowels contained in `in_string`"""</span>
<spanclass="n">vowels</span><spanclass="o">=</span><spanclass="nb">set</span><spanclass="p">(</span><spanclass="s2">"aeiouAEIOU"</span><spanclass="p">)</span>
<spanclass="k">if</span><spanclass="n">include_y</span><spanclass="p">:</span>
<spanclass="n">vowels</span><spanclass="o">.</span><spanclass="n">update</span><spanclass="p">(</span><spanclass="s2">"yY"</span><spanclass="p">)</span>
<spanclass="k">return</span><spanclass="nb">sum</span><spanclass="p">(</span><spanclass="mi">1</span><spanclass="k">for</span><spanclass="n">char</span><spanclass="ow">in</span><spanclass="n">x</span><spanclass="k">if</span><spanclass="n">char</span><spanclass="ow">in</span><spanclass="n">vowels</span><spanclass="p">)</span>
</pre></div>
</div>
<p>Here, we have hinted that <codeclass="docutils literal notranslate"><spanclass="pre">include_y</span></code> is expected to be passed a boolean-type object, and that it has a default value of <codeclass="docutils literal notranslate"><spanclass="pre">False</span></code>. It is important to take some time to grow accustomed to seeing the form <codeclass="docutils literal notranslate"><spanclass="pre">include_y:</span><spanclass="pre">bool</span><spanclass="pre">=</span><spanclass="pre">False</span></code>. This can be difficult to parse at first. Keep in mind that <codeclass="docutils literal notranslate"><spanclass="pre">:</span><spanclass="pre">bool</span></code> is the type-hint here and <codeclass="docutils literal notranslate"><spanclass="pre">=</span><spanclass="pre">False</span></code> specifies the default argument. The ordering of these statements are <em>not</em> interchangeable - a type-hint must immediately follow the variable name.</p>
<p>Python 3.6, via <aclass="reference external" href="https://www.python.org/dev/peps/pep-0526/">PEP 526</a>, introduced a syntax for annotating standalone variables in your code. For example, suppose that you are initializing a list in your code that will store even numbers. You can annotate this variable as:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># annotating a variable with a type-hint</span>
<spanclass="kn">from</span><spanclass="nn">typing</span><spanclass="kn">import</span><spanclass="n">List</span><spanclass="p">,</span><spanclass="n">Set</span>
<spanclass="n">names</span><spanclass="p">:</span><spanclass="n">Set</span><spanclass="p">[</span><spanclass="nb">str</span><spanclass="p">]</span><spanclass="o">=</span><spanclass="p">[]</span>
<spanclass="n">odd_numbers</span><spanclass="p">:</span><spanclass="n">List</span><spanclass="p">[</span><spanclass="nb">int</span><spanclass="p">]</span><spanclass="o">=</span><spanclass="p">[]</span>
</pre></div>
</div>
<p>this permits us to document that the empty list will be used to store integers. You can also annotate a variable without providing an initial value.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># annotating a variable, without providing a value</span>
<spanclass="n">max_num</span><spanclass="p">:</span><spanclass="nb">int</span>
</pre></div>
</div>
<p>Note that this variable-annotation syntax is <em>not</em> valid for versions of Python earlier than Python 3.6, and the function-annotation syntax is not valid for versions prior to Python 3.5. A formal theory of type-hinting is discussed in <aclass="reference external" href="https://www.python.org/dev/peps/pep-0483/">PEP 483</a>.</p>
<divclass="section" id="What-is-It-Good-For?-(Absolutely-Nothing)">
<h3>What is It Good For? (Absolutely Nothing)<aclass="headerlink" href="#What-is-It-Good-For?-(Absolutely-Nothing)" title="Permalink to this headline"></a></h3>
<p>As far as the Python interpreter is concerned, <strong>type-hints have no impact on your code other than adding documentation</strong>. That is, Python <strong>will not enforce any type-checking based on your type-hints</strong>. This is in stark contrast to strongly-typed languages, like C++, where you are required specify input and output types for a function as constraints that are strictly enforced by the compiler.</p>
<p>Indeed, in Python we are free to pass whatever we want to our function regardless of its annotated type-hints. Let’s pass an empty list, instead of a string, to the <codeclass="docutils literal notranslate"><spanclass="pre">count_vowels</span></code> function that we defined above.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Type-hints do not actually enforce type-checking.</span>
<spanclass="c1"># Here we pass an empty list instead of a string without</span>
<spanclass="c1"># any warnings/errors being raised</span>
<spanclass="o">>>></span><spanclass="n">count_vowels</span><spanclass="p">([])</span>
<spanclass="mi">0</span>
</pre></div>
</div>
<p>See that our function pays no notice to the fact that we violated our type-hint, which suggests that we will be passing in a string. It happily loops over the empty list and sums over zeros entries, thus the function returns <codeclass="docutils literal notranslate"><spanclass="pre">0</span></code>. This is why these annotations are merely called type <em>hints</em>, and not type <em>requirements</em>.</p>
<p>While the CPython interpreter will never require or enforce type-hints during the lifetime of Python 3, there are 3rd party libraries and tooling that makes keen use of these annotations. <em>It is these 3rd-party capabilities that make type-hinting worth using</em>. <aclass="reference external" href="https://www.pythonlikeyoumeanit.com/Module1_GettingStartedWithPython/Getting_Started_With_IDEs_and_Notebooks.html">IDEs like PyCharm and VSCode</a> can leverage type hints to great effect. They will warn you when you pass objects to your
function that do not abide by the type hints, and they will also leverage these annotations to keep track of the objects that are returned by the function.</p>
<p>For example, suppose that we are using the <codeclass="docutils literal notranslate"><spanclass="pre">count_vowels</span></code> function in a library of code that we are developing, and we mistakenly think that the output of this function is a string that we want to capitalize. Our IDE will see that we are trying to capitalize an integer and will thus warn us:</p>
<p><imgalt="PyCharm uses type-hints to check our code for consistency" src="../_images/pycharm1.png" /></p>
<p>This saves us the trouble of having to run our code, hit an error, read through the stack trace, and debug our mistake. Instead, we immediately see our inconsistency get flagged. In fact, we probably never would have even made the mistake at all, as our IDE would have shown a list of integer-methods for us to choose from, and not string-methods. Type-hints would have likely alerted us to our misapprehension.</p>
<p>It does not take long to experience the benefits of type-hinting through your IDE. This both accelerates your coding by informing you of the object types that you are working with on the fly, and helps to expose oversights in your code as soon as they are made.</p>
<p>Finally, it is also worthwhile to highlight two projects, <aclass="reference external" href="http://mypy-lang.org/">mypy</a> and <aclass="reference external" href="https://github.com/microsoft/pyright">pyright</a>, which are used to perform static type-checking on your code based on your type-hints. That is, mypy and pyright will both automatically traverse your code and find potential bugs by identifying type conflicts in your code (e.g. trying to capitalize an integer) by checking their annotated and inferred types. These tools are especially useful for
large-scale code bases. Companies like Dropbox and Microsoft make keen use of static type-checking to identify inconsistencies in their code without having to hit runtime errors. Keep mypy, pyright, and other type-checking utilities in mind as you mature as a Python developer and find yourself working on projects of growing complexity. If you are using <aclass="reference external" href="https://www.pythonlikeyoumeanit.com/Module1_GettingStartedWithPython/Getting_Started_With_IDEs_and_Notebooks.html">VSCode as your IDE</a>, you
can install the <aclass="reference external" href="https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance">PyLance VSCode extension</a> to leverage pyright’s type checking within your IDE.</p>
<divclass="admonition note">
<pclass="admonition-title fa fa-exclamation-circle"><strong>Reading Comprehension: Type-Assisted Code Completion</strong></p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">jedi</span></code> package, which is installed by default alongside Jupyter and IPython, enables type-informed code completion. This means that we can benefit from type-hints even when we are working in a Jupyter notebook!</p>
<p>In a Jupyter notebook, write the following type-annotated signature for a function: <codeclass="docutils literal notranslate"><spanclass="pre">def</span><spanclass="pre">f(x:</span><spanclass="pre">str):</span></code>. Now in the body of the function (i.e. on the next line, and indented inwards), try typing <codeclass="docutils literal notranslate"><spanclass="pre">x.</span></code> and then hit <codeclass="docutils literal notranslate"><spanclass="pre"><TAB></span></code>.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="k">def</span><spanclass="nf">f</span><spanclass="p">(</span><spanclass="n">x</span><spanclass="p">:</span><spanclass="nb">str</span><spanclass="p">):</span>
<spanclass="n">x</span><spanclass="o">.</span><spanclass="c1">#hit <TAB> here</span>
</pre></div>
</div>
<p>You should see a list of methods appear for <codeclass="docutils literal notranslate"><spanclass="pre">x</span></code>. What are the first three methods that appear? Do these make sense based on the annotation associated with <codeclass="docutils literal notranslate"><spanclass="pre">x</span></code>? Now change the annotation for <codeclass="docutils literal notranslate"><spanclass="pre">x</span></code> to be <codeclass="docutils literal notranslate"><spanclass="pre">list</span></code> and trigger the auto-completion in the editor again; do you see an updated list of methods?</p>
</div>
<divclass="admonition note">
<pclass="admonition-title fa fa-exclamation-circle"><strong>Takeaway:</strong></p>
<p>There is a simple syntax for annotating functions, class-methods, and variables with type-hints; this is a formal mechanism for documenting the types of objects that are expected as inputs to the function, as well as the return type of the function. It is critical to note that that type-hints are <em>never</em> enforced by Python - they only serve as a form of documentation.</p>
<p>That being said, IDEs have powerful abilities to inspect type-hints and to highlight potential inconsistencies in your code. These capabilities can greatly facilitate your code-development. There are also third-party libraries like <aclass="reference external" href="http://mypy-lang.org/">mypy</a> and <aclass="reference external" href="https://github.com/microsoft/pyright">pyright</a> that can be used to provide more rigorous type enforcement in your code.</p>
</div>
</div>
<divclass="section" id="Using-the-typing-Module">
<h3>Using the <codeclass="docutils literal notranslate"><spanclass="pre">typing</span></code> Module<aclass="headerlink" href="#Using-the-typing-Module" title="Permalink to this headline"></a></h3>
<p>Although we can use Python’s built-in type objects (e.g. <codeclass="docutils literal notranslate"><spanclass="pre">list</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">dict</span></code>) for type-hinting, the standard library’s <aclass="reference external" href="https://docs.python.org/3/library/typing.html">typing</a> module provides objects that are used to form more descriptive hints. For example, suppose that we want to write a function that takes in a list of integers as an input. Using the built-in <codeclass="docutils literal notranslate"><spanclass="pre">list</span></code> object for our type-hint prevents us from indicating that the list should house integers. Using <codeclass="docutils literal notranslate"><spanclass="pre">typing.List</span></code>, on the
other hand, supports a richer syntax for type-hinting: <codeclass="docutils literal notranslate"><spanclass="pre">typing.List[int]</span></code> specifies “a list of integers.” Familiarizing yourself with the <codeclass="docutils literal notranslate"><spanclass="pre">typing</span></code> module is the first step to writing good type hints.</p>
<p>The following is a summary some of the most critical members of the <codeclass="docutils literal notranslate"><spanclass="pre">typing</span></code> module, along with examples for using them.</p>
<divclass="section" id="Any">
<h4><codeclass="docutils literal notranslate"><spanclass="pre">Any</span></code><aclass="headerlink" href="#Any" title="Permalink to this headline"></a></h4>
<ulclass="simple">
<li><p><strong>What it hints:</strong> Any type of object</p></li>
</ul>
</div>
<divclass="section" id="Union[<type>,-<type>]">
<h4><codeclass="docutils literal notranslate"><spanclass="pre">Union[<type>,</span><spanclass="pre"><type>]</span></code><aclass="headerlink" href="#Union[<type>,-<type>]" title="Permalink to this headline"></a></h4>
<ulclass="simple">
<li><p><strong>What it hints:</strong> Either of two types of objects</p></li>
<li><p><strong>Examples:</strong> Hint an integer or a boolean: <codeclass="docutils literal notranslate"><spanclass="pre">Union[int,</span><spanclass="pre">bool]</span></code></p></li>
</ul>
</div>
<divclass="section" id="Optional[<type>]">
<h4><codeclass="docutils literal notranslate"><spanclass="pre">Optional[<type>]</span></code><aclass="headerlink" href="#Optional[<type>]" title="Permalink to this headline"></a></h4>
<ulclass="simple">
<li><p><strong>What it hints:</strong> Either <codeclass="docutils literal notranslate"><spanclass="pre"><type></span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code>, with <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code> as the default</p></li>
<li><p><strong>Examples:</strong> Hint an object that is <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code> by default, but will be a string otherwise: <codeclass="docutils literal notranslate"><spanclass="pre">Optional[str]</span></code></p></li>
</ul>
</div>
<divclass="section" id="None">
<h4><codeclass="docutils literal notranslate"><spanclass="pre">None</span></code><aclass="headerlink" href="#None" title="Permalink to this headline"></a></h4>
<ulclass="simple">
<li><p><strong>What it hints:</strong> Simply the object <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code></p></li>
</ul>
</div>
<divclass="section" id="List[<type>]">
<h4><codeclass="docutils literal notranslate"><spanclass="pre">List[<type>]</span></code><aclass="headerlink" href="#List[<type>]" title="Permalink to this headline"></a></h4>
<ulclass="simple">
<li><p><strong>What it hints:</strong> A list containing an arbitrary number of objects of a given type</p></li>
<li><p><strong>Examples:</strong></p>
<ul>
<li><p>Hint a list of strings: <codeclass="docutils literal notranslate"><spanclass="pre">List[str]</span></code></p></li>
<li><p>Hint a list of strings and integers: <codeclass="docutils literal notranslate"><spanclass="pre">List[Union[str,</span><spanclass="pre">int]]</span></code></p></li>
<li><p>Hint a list of lists of anything: <codeclass="docutils literal notranslate"><spanclass="pre">List[List[Any]]</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">List[List]</span></code></p></li>
</ul>
</li>
</ul>
</div>
<divclass="section" id="Tuple[<type>,-...]">
<h4><codeclass="docutils literal notranslate"><spanclass="pre">Tuple[<type>,</span><spanclass="pre">...]</span></code><aclass="headerlink" href="#Tuple[<type>,-...]" title="Permalink to this headline"></a></h4>
<ulclass="simple">
<li><p><strong>What it hints:</strong> A tuple containing a specific number of objects of the specified types. <codeclass="docutils literal notranslate"><spanclass="pre">...</span></code> can be used to indicate an arbitrary number of objects in the tuple</p></li>
<li><p><strong>Examples:</strong></p>
<ul>
<li><p>Hint a tuple containing one string and one boolean: <codeclass="docutils literal notranslate"><spanclass="pre">Tuple[str,</span><spanclass="pre">bool]</span></code></p></li>
<li><p>Hint a tuple containing an arbitrary number of integers: <codeclass="docutils literal notranslate"><spanclass="pre">Tuple[int,</span><spanclass="pre">...]</span></code></p></li>
</ul>
</li>
</ul>
</div>
<divclass="section" id="Set[<type>]">
<h4><codeclass="docutils literal notranslate"><spanclass="pre">Set[<type>]</span></code><aclass="headerlink" href="#Set[<type>]" title="Permalink to this headline"></a></h4>
<ulclass="simple">
<li><p><strong>What it hints:</strong> A set containing an arbitrary number of objects of a given type</p></li>
<li><p><strong>Examples:</strong></p>
<ul>
<li><p>Hint a set of floats: <codeclass="docutils literal notranslate"><spanclass="pre">Set[float]</span></code></p></li>
<li><p>Hint a set of tuples (each containing two integers): <codeclass="docutils literal notranslate"><spanclass="pre">Set[Tuple[int,</span><spanclass="pre">int]]</span></code></p></li>
</ul>
</li>
</ul>
</div>
<divclass="section" id="Dict[<key-type>,-<value-type>]">
<h4><codeclass="docutils literal notranslate"><spanclass="pre">Dict[<key-type>,</span><spanclass="pre"><value-type>]</span></code><aclass="headerlink" href="#Dict[<key-type>,-<value-type>]" title="Permalink to this headline"></a></h4>
<ulclass="simple">
<li><p><strong>What it hints:</strong> A dictionary that maps keys of a given type to values of a given type</p></li>
<li><p><strong>Examples:</strong></p>
<ul>
<li><p>Hint a dictionary that maps strings to integers: <codeclass="docutils literal notranslate"><spanclass="pre">Dict[str,</span><spanclass="pre">int]</span></code></p></li>
<li><p>Hint a dictionary that maps any hashable to booleans: <codeclass="docutils literal notranslate"><spanclass="pre">Dict[Hashable,</span><spanclass="pre">bool]</span></code>|</p></li>
</ul>
</li>
</ul>
</div>
<divclass="section" id="Callable[[<arg-type>],-<output-type>]">
<h4><codeclass="docutils literal notranslate"><spanclass="pre">Callable[[<arg-type>],</span><spanclass="pre"><output-type>]</span></code><aclass="headerlink" href="#Callable[[<arg-type>],-<output-type>]" title="Permalink to this headline"></a></h4>
<ulclass="simple">
<li><p><strong>What it hints:</strong> A callable (e.g. a function or a method) that takes in arguments of specified types and returns the specified type</p></li>
<li><p><strong>Examples:</strong></p>
<ul>
<li><p>Hint a function that takes in a string and an integer and returns <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code>: <codeclass="docutils literal notranslate"><spanclass="pre">Callable[[str,</span><spanclass="pre">int],</span><spanclass="pre">None]</span></code></p></li>
<li><p>Hint a method that accepts arbitrary arguments and returns a boolean: <codeclass="docutils literal notranslate"><spanclass="pre">Callable[...,</span><spanclass="pre">bool]</span></code></p></li>
</ul>
</li>
</ul>
</div>
<divclass="section" id="Literal[<value>,-...]">
<h4><codeclass="docutils literal notranslate"><spanclass="pre">Literal[<value>,</span><spanclass="pre">...]</span></code><aclass="headerlink" href="#Literal[<value>,-...]" title="Permalink to this headline"></a></h4>
<ulclass="simple">
<li><p><strong>What it hints:</strong> That the variable will be passed one of the exact values</p></li>
<li><p><strong>Examples:</strong></p>
<ul>
<li><p>Hint that a variable that will be the integer <codeclass="docutils literal notranslate"><spanclass="pre">1</span></code>: <codeclass="docutils literal notranslate"><spanclass="pre">Literal[1]</span></code></p></li>
<li><p>Hint that a variable that will be the either the string <codeclass="docutils literal notranslate"><spanclass="pre">"sum"</span></code> or the string <codeclass="docutils literal notranslate"><spanclass="pre">"mean"</span></code>: <codeclass="docutils literal notranslate"><spanclass="pre">Literal["sum",</span><spanclass="pre">"mean"]</span></code></p></li>
<li><p>Hint that a variable that will be either the list <codeclass="docutils literal notranslate"><spanclass="pre">[1,</span><spanclass="pre">2]</span></code> or the string <codeclass="docutils literal notranslate"><spanclass="pre">"abc"</span></code>: <codeclass="docutils literal notranslate"><spanclass="pre">Literal[[1,</span><spanclass="pre">2],</span><spanclass="pre">"abc"]</span></code></p></li>
</ul>
</li>
<li><p><strong>Compatibility Note:</strong> The <codeclass="docutils literal notranslate"><spanclass="pre">Literal</span></code> type-hint was introduced in Python 3.8 - it is not available in earlier versions of Python.</p></li>
</ul>
<p>Let’s take, for example, a function that takes in:</p>
<ulclass="simple">
<li><p>a dictionary of student grades, which maps names (strings) to grades (list of floats)</p></li>
<li><p>a custom function for computing statistics over a list of numbers</p></li>
<li><p>a list of names of students for whom we want to compute statistics, whose default is all students</p></li>
</ul>
<p>and returns a list of tuples, with each tuple containing a student’s name and their stat.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="kn">from</span><spanclass="nn">typing</span><spanclass="kn">import</span><spanclass="n">Dict</span><spanclass="p">,</span><spanclass="n">Callable</span><spanclass="p">,</span><spanclass="n">Optional</span><spanclass="p">,</span><spanclass="n">List</span><spanclass="p">,</span><spanclass="n">Tuple</span><spanclass="p">,</span><spanclass="n">Any</span>
<spanclass="k">def</span><spanclass="nf">compute_student_stats</span><spanclass="p">(</span><spanclass="n">grade_book</span><spanclass="p">:</span><spanclass="n">Dict</span><spanclass="p">[</span><spanclass="nb">str</span><spanclass="p">,</span><spanclass="n">List</span><spanclass="p">[</span><spanclass="nb">float</span><spanclass="p">]],</span>
<spanclass="n">stat_function</span><spanclass="p">:</span><spanclass="n">Callable</span><spanclass="p">[[</span><spanclass="n">List</span><spanclass="p">[</span><spanclass="nb">float</span><spanclass="p">]],</span><spanclass="n">Any</span><spanclass="p">],</span>
<spanclass="n">student_list</span><spanclass="p">:</span><spanclass="n">Optional</span><spanclass="p">[</span><spanclass="n">List</span><spanclass="p">[</span><spanclass="nb">str</span><spanclass="p">]]</span><spanclass="o">=</span><spanclass="kc">None</span><spanclass="p">)</span><spanclass="o">-></span><spanclass="n">List</span><spanclass="p">[</span><spanclass="n">Tuple</span><spanclass="p">[</span><spanclass="nb">str</span><spanclass="p">,</span><spanclass="n">Any</span><spanclass="p">]]:</span>
<spanclass="sd">"""Computes custom statistics over student's grades.</span>
<spanclass="sd"> Parameters</span>
<spanclass="sd"> ----------</span>
<spanclass="sd"> grade_book : Dict[str, List[float]]</span>
<spanclass="sd"> The dictionary (name -> grades) of all of the students' grades.</span>
<spanclass="sd"> stat_function: Callable[[List[float]], Any]</span>
<spanclass="sd"> The function used to compute statistics over each student's grades.</span>
<spanclass="sd"> student_list : Optional[List[str]]</span>
<spanclass="sd"> A list of names of the students for whom statistics will be computed.</span>
<spanclass="sd"> By default, statistics will be computed for all students in the gradebook.</span>
<spanclass="sd"> Returns</span>
<spanclass="sd"> -------</span>
<spanclass="sd"> List[Tuple[str, Any]]</span>
<spanclass="sd"> The name-stats tuple pair for each specified student.</span>
<spanclass="sd"> """</span>
<spanclass="k">if</span><spanclass="n">student_list</span><spanclass="ow">is</span><spanclass="kc">None</span><spanclass="p">:</span><spanclass="c1"># default to all-students</span>
<spanclass="n">student_list</span><spanclass="o">=</span><spanclass="nb">sorted</span><spanclass="p">(</span><spanclass="n">grade_book</span><spanclass="p">)</span><spanclass="c1"># iterates over the dictionary's keys</span>
<spanclass="k">return</span><spanclass="p">[(</span><spanclass="n">name</span><spanclass="p">,</span><spanclass="n">stat_function</span><spanclass="p">(</span><spanclass="n">grade_book</span><spanclass="p">[</span><spanclass="n">name</span><spanclass="p">]))</span><spanclass="k">for</span><spanclass="n">name</span><spanclass="ow">in</span><spanclass="n">student_list</span><spanclass="p">]</span>
</pre></div>
</div>
<p>(Note that we have also included a detailed NumPy-style docstring; we will discuss this documentation style in detail in the following subsection).</p>
<p>There are a few details to take note of here. First, see that we need not make any assumptions about what type of object is returned by <codeclass="docutils literal notranslate"><spanclass="pre">stat_function</span></code>. It might return the mean-value as a single floating point number, or perhaps a tuple of the mean, median, and mode, etc. Thus we document its output type as <codeclass="docutils literal notranslate"><spanclass="pre">Any</span></code>; this is reflected in our function’s return type as well: <codeclass="docutils literal notranslate"><spanclass="pre">List[Tuple[str,</span><spanclass="pre">Any]]</span></code>. As we will discuss shortly, it is prudent to be discerning but general in one’s type-hints.
Next, note that <codeclass="docutils literal notranslate"><spanclass="pre">Optional[List[str]]</span></code> is used to indicate that the default-value of <codeclass="docutils literal notranslate"><spanclass="pre">student_list</span></code> is <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code>, but that we can otherwise pass it a list-of-strings. This is cleaner to read than the equivalent hint <codeclass="docutils literal notranslate"><spanclass="pre">Union[None,</span><spanclass="pre">List[str]]</span></code> and it indicates that <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code> is indeed the default-value.</p>
<p>In the case that you have <aclass="reference external" href="http://www.pythonlikeyoumeanit.com/module_4.html">defined your own type (akaclass)</a>, you can simply provide the resulting class object in an annotation. This type-hints that a variable is expected to be an <em>instance</em> of that type. If, instead, you have the rare case of hinting that the class object itself (not an instance of the class) is expected, you can use <codeclass="docutils literal notranslate"><spanclass="pre">typing.Type</span></code> to indicate this.</p>
<p>Let’s write a silly example to demonstrate these points. We will define our own <codeclass="docutils literal notranslate"><spanclass="pre">Dog</span></code> class, and will write a function that expects the <codeclass="docutils literal notranslate"><spanclass="pre">Dog</span></code> class-object itself (type-hinted as <codeclass="docutils literal notranslate"><spanclass="pre">Type[Dog]</span></code>). The function will create several <em>instances</em> of the <codeclass="docutils literal notranslate"><spanclass="pre">Dog</span></code> class (type-hinted simply as <codeclass="docutils literal notranslate"><spanclass="pre">Dog</span></code>), and will return them in a list.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># type-hinting a custom class</span>
<spanclass="kn">from</span><spanclass="nn">typing</span><spanclass="kn">import</span><spanclass="n">List</span><spanclass="p">,</span><spanclass="n">Type</span>
<spanclass="k">class</span><spanclass="nc">Dog</span><spanclass="p">:</span>
<spanclass="k">def</span><spanclass="fm">__init__</span><spanclass="p">(</span><spanclass="bp">self</span><spanclass="p">,</span><spanclass="n">name</span><spanclass="p">):</span>
<spanclass="bp">self</span><spanclass="o">.</span><spanclass="n">name</span><spanclass="o">=</span><spanclass="n">name</span>
<spanclass="c1"># cls is expected to be the class-object, `Dog`, itself</span>
<spanclass="c1"># This function returns a list of instances of the `Dog` type</span>
<spanclass="k">def</span><spanclass="nf">list_famous_dogs</span><spanclass="p">(</span><spanclass="bp">cls</span><spanclass="p">:</span><spanclass="n">Type</span><spanclass="p">[</span><spanclass="n">Dog</span><spanclass="p">])</span><spanclass="o">-></span><spanclass="n">List</span><spanclass="p">[</span><spanclass="n">Dog</span><spanclass="p">]:</span>
<spanclass="k">return</span><spanclass="p">[</span><spanclass="bp">cls</span><spanclass="p">(</span><spanclass="n">name</span><spanclass="p">)</span><spanclass="k">for</span><spanclass="n">name</span><spanclass="ow">in</span><spanclass="p">[</span><spanclass="s2">"Lassie"</span><spanclass="p">,</span><spanclass="s2">"Shadow"</span><spanclass="p">,</span><spanclass="s2">"Air Bud"</span><spanclass="p">]]</span>
</pre></div>
</div>
<p>You can also create a <aclass="reference external" href="https://docs.python.org/3/library/typing.html#type-aliases">type alias</a>, which you can define in your code and use in your annotations. For example, if you will regularly be passing around a tuple containing five <codeclass="docutils literal notranslate"><spanclass="pre">Dog</span></code>-instances, you can define an alias to help make your type-hints more succinct:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># creating an alias for a type</span>
<spanclass="n">Pack</span><spanclass="o">=</span><spanclass="n">Tuple</span><spanclass="p">[</span><spanclass="n">Dog</span><spanclass="p">,</span><spanclass="n">Dog</span><spanclass="p">,</span><spanclass="n">Dog</span><spanclass="p">,</span><spanclass="n">Dog</span><spanclass="p">,</span><spanclass="n">Dog</span><spanclass="p">]</span>
<spanclass="k">def</span><spanclass="nf">find_alpha</span><spanclass="p">(</span><spanclass="n">dogs</span><spanclass="p">:</span><spanclass="n">Pack</span><spanclass="p">)</span><spanclass="o">-></span><spanclass="n">Dog</span><spanclass="p">:</span>
<spanclass="o">...</span>
</pre></div>
</div>
<p>Object types defined in 3rd-party libraries, e.g. NumPy’s <aclass="reference external" href="https://www.pythonlikeyoumeanit.com/Module3_IntroducingNumpy/IntroducingTheNDarray.html">ndarray</a> behave no differently from our own custom custom classes; simply provide the <aclass="reference external" href="https://www.pythonlikeyoumeanit.com/Module4_OOP/ClassDefinition.html#Defining-a-New-Class-of-Object">class object</a> in the type-hint annotation:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># type-hinting an nd-array from numpy</span>
<spanclass="kn">import</span><spanclass="nn">numpy</span><spanclass="k">as</span><spanclass="nn">np</span>
<spanclass="k">def</span><spanclass="nf">custom_dot_product</span><spanclass="p">(</span><spanclass="n">x</span><spanclass="p">:</span><spanclass="n">np</span><spanclass="o">.</span><spanclass="n">ndarray</span><spanclass="p">,</span><spanclass="n">y</span><spanclass="p">:</span><spanclass="n">np</span><spanclass="o">.</span><spanclass="n">ndarray</span><spanclass="p">)</span><spanclass="o">-></span><spanclass="nb">float</span><spanclass="p">:</span>
<spanclass="k">return</span><spanclass="nb">float</span><spanclass="p">(</span><spanclass="n">np</span><spanclass="o">.</span><spanclass="n">sum</span><spanclass="p">(</span><spanclass="n">x</span><spanclass="o">*</span><spanclass="n">y</span><spanclass="p">))</span>
</pre></div>
</div>
<p>Eventually, popular 3rd party libraries like NumPy will contribute their own typing modules so that you can provide higher-fidelity hints that indicate things like data-type and array-shape. NumPy developers <aclass="reference external" href="https://github.com/numpy/numpy/issues/7370">are currently working on this</a>.</p>
<divclass="admonition note">
<pclass="admonition-title fa fa-exclamation-circle"><strong>Takeaway:</strong></p>
<p>Python’s <codeclass="docutils literal notranslate"><spanclass="pre">typing</span></code> module contains objects that are used to create descriptive type-hints. For example, whereas <codeclass="docutils literal notranslate"><spanclass="pre">list</span></code> can only be used to type-hint a list, <codeclass="docutils literal notranslate"><spanclass="pre">typing.List[str]</span></code> describes a list-of-strings. These can also be used to create concise aliases for convoluted type-hints that will be used frequently throughout your code.</p>
<p>In general, a <aclass="reference external" href="https://www.pythonlikeyoumeanit.com/Module4_OOP/ClassDefinition.html#Defining-a-New-Class-of-Object">class object</a> can be used for type-hinting, and it indicates that a variable should be an <em>instance</em> of that class. For example, <codeclass="docutils literal notranslate"><spanclass="pre">numpy.ndarray</span></code> hints that a variable should be passed an instance of the nd-array class.</p>
</div>
</div>
</div>
<divclass="section" id="Writing-Good-Type-Hints-(quack-quack)">
<h3>Writing Good Type-Hints (quack quack)<aclass="headerlink" href="#Writing-Good-Type-Hints-(quack-quack)" title="Permalink to this headline"></a></h3>
<p>You should strive to write type-hints that pass <aclass="reference external" href="https://en.wikipedia.org/wiki/Duck_test">the duck test</a>: if your function is expecting a duck then hint for something that walks like a duck, quacks like a duck, etc. This will help you avoid writing type-hints that are overly narrow, and which are ultimately non-Pythonic in their strictness.</p>
<p>To be more concrete, let’s revisit our <codeclass="docutils literal notranslate"><spanclass="pre">count_vowels</span></code> function:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="k">def</span><spanclass="nf">count_vowels</span><spanclass="p">(</span><spanclass="n">x</span><spanclass="p">:</span><spanclass="nb">str</span><spanclass="p">,</span><spanclass="n">include_y</span><spanclass="p">:</span><spanclass="nb">bool</span><spanclass="o">=</span><spanclass="kc">False</span><spanclass="p">)</span><spanclass="o">-></span><spanclass="nb">int</span><spanclass="p">:</span>
<spanclass="sd">"""Returns the number of vowels contained in `in_string`"""</span>
<spanclass="n">vowels</span><spanclass="o">=</span><spanclass="nb">set</span><spanclass="p">(</span><spanclass="s2">"aeiouAEIOU"</span><spanclass="p">)</span>
<spanclass="k">if</span><spanclass="n">include_y</span><spanclass="p">:</span>
<spanclass="n">vowels</span><spanclass="o">.</span><spanclass="n">update</span><spanclass="p">(</span><spanclass="s2">"yY"</span><spanclass="p">)</span>
<spanclass="k">return</span><spanclass="nb">sum</span><spanclass="p">(</span><spanclass="mi">1</span><spanclass="k">for</span><spanclass="n">char</span><spanclass="ow">in</span><spanclass="n">x</span><spanclass="k">if</span><spanclass="n">char</span><spanclass="ow">in</span><spanclass="n">vowels</span><spanclass="p">)</span>
</pre></div>
</div>
<p>Look carefully at how <codeclass="docutils literal notranslate"><spanclass="pre">x</span></code> is used in this function. We simply iterate over <codeclass="docutils literal notranslate"><spanclass="pre">x</span></code> in a for-loop - there is nothing string-specific about this. We could pass a string, a tuple, a list, or anything that supports iteration to this function, and it will happily count the vowels in <codeclass="docutils literal notranslate"><spanclass="pre">x</span></code>:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># `count_vowels` can operate on any iterable of strings</span>
<spanclass="o">>>></span><spanclass="n">count_vowels</span><spanclass="p">(</span><spanclass="s2">"apple"</span><spanclass="p">)</span>
<spanclass="mi">2</span>
<spanclass="o">>>></span><spanclass="n">count_vowels</span><spanclass="p">([</span><spanclass="s1">'a'</span><spanclass="p">,</span><spanclass="s1">'p'</span><spanclass="p">,</span><spanclass="s1">'p'</span><spanclass="p">,</span><spanclass="s1">'l'</span><spanclass="p">,</span><spanclass="s1">'e'</span><spanclass="p">])</span>
<spanclass="mi">2</span>
<spanclass="o">>>></span><spanclass="n">count_vowels</span><spanclass="p">((</span><spanclass="s1">'a'</span><spanclass="p">,</span><spanclass="s1">'p'</span><spanclass="p">,</span><spanclass="s1">'p'</span><spanclass="p">,</span><spanclass="s1">'l'</span><spanclass="p">,</span><spanclass="s1">'e'</span><spanclass="p">))</span>
<spanclass="mi">2</span>
<spanclass="o">>>></span><spanclass="n">count_vowels</span><spanclass="p">({</span><spanclass="s1">'a'</span><spanclass="p">,</span><spanclass="s1">'p'</span><spanclass="p">,</span><spanclass="s1">'p'</span><spanclass="p">,</span><spanclass="s1">'l'</span><spanclass="p">,</span><spanclass="s1">'e'</span><spanclass="p">})</span>
<spanclass="mi">2</span>
</pre></div>
</div>
<p>It is over-restrictive and un-Pythonic to type-hint <codeclass="docutils literal notranslate"><spanclass="pre">x</span></code> as <codeclass="docutils literal notranslate"><spanclass="pre">str</span></code>. Let’s make our type-hint more accommodating.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">typing</span></code> module provides a so-called <aclass="reference external" href="https://docs.python.org/3/glossary.html#term-abstract-base-class">abstract base class</a>, <codeclass="docutils literal notranslate"><spanclass="pre">Iterable</span></code>, which is a generic type for any class that supports iteration. Thus we can improve our type-hint by making it more general. This encapsulates all of the above use-cases that we demonstrated.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="kn">from</span><spanclass="nn">typing</span><spanclass="kn">import</span><spanclass="n">Iterable</span>
<spanclass="k">def</span><spanclass="nf">count_vowels</span><spanclass="p">(</span><spanclass="n">x</span><spanclass="p">:</span><spanclass="n">Iterable</span><spanclass="p">[</span><spanclass="nb">str</span><spanclass="p">],</span><spanclass="n">include_y</span><spanclass="p">:</span><spanclass="nb">bool</span><spanclass="o">=</span><spanclass="kc">False</span><spanclass="p">)</span><spanclass="o">-></span><spanclass="nb">int</span><spanclass="p">:</span>
<spanclass="sd">"""Returns the number of vowels contained in `in_string`"""</span>
<spanclass="n">vowels</span><spanclass="o">=</span><spanclass="nb">set</span><spanclass="p">(</span><spanclass="s2">"aeiouAEIOU"</span><spanclass="p">)</span>
<spanclass="k">if</span><spanclass="n">include_y</span><spanclass="p">:</span>
<spanclass="n">vowels</span><spanclass="o">.</span><spanclass="n">update</span><spanclass="p">(</span><spanclass="s2">"yY"</span><spanclass="p">)</span>
<spanclass="k">return</span><spanclass="nb">sum</span><spanclass="p">(</span><spanclass="mi">1</span><spanclass="k">for</span><spanclass="n">char</span><spanclass="ow">in</span><spanclass="n">x</span><spanclass="k">if</span><spanclass="n">char</span><spanclass="ow">in</span><spanclass="n">vowels</span><spanclass="p">)</span>
</pre></div>
</div>
<p>(To be completely general, we could have hinted <codeclass="docutils literal notranslate"><spanclass="pre">Iterable[Hashable]</span></code>, as we are relying on the entries of <codeclass="docutils literal notranslate"><spanclass="pre">x</span></code> to be hashable to check for their membership in the <aclass="reference external" href="http://www.pythonlikeyoumeanit.com/Module2_EssentialsOfPython/DataStructures_III_Sets_and_More.html#The-%E2%80%9CSet%E2%80%9D-Data-Structure">set</a> of vowels. It is up to you to determine how abstract you want your ducks to be.)</p>
<p>It is is important to review the <aclass="reference external" href="https://docs.python.org/3/library/collections.abc.html#collections-abstract-base-classes">abstract base classes (abc’s) for Python’s collections</a> (yes, I am encouraging you to learn your abc’s). This will help you classify categories of types generally, based on their <aclass="reference external" href="http://www.pythonlikeyoumeanit.com/Module4_OOP/Special_Methods.html">special methods</a>. Two of the most common abc’s are <codeclass="docutils literal notranslate"><spanclass="pre">Iterable</span></code>: any class that supports the iteration protocol, and
<codeclass="docutils literal notranslate"><spanclass="pre">Sequence</span></code>: any collection that has a length (via <codeclass="docutils literal notranslate"><spanclass="pre">__len__</span></code>) and supports the get-item syntax (via <codeclass="docutils literal notranslate"><spanclass="pre">__getitem__</span></code>).</p>
<divclass="admonition note">
<pclass="admonition-title fa fa-exclamation-circle"><strong>Reading Comprehension: Type Hinting</strong></p>
<p>Read through the following function and annotate its signature with type-hints. Try to make your type-hints sufficiently general here.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="k">def</span><spanclass="nf">get_first_and_last</span><spanclass="p">(</span><spanclass="n">x</span><spanclass="p">):</span>
<spanclass="sd">"""Returns the first and last elements of `x`. `x` is</span>
<spanclass="sd"> assumed to be non-empty</span>
<spanclass="sd"> """</span>
<spanclass="k">return</span><spanclass="p">(</span><spanclass="n">x</span><spanclass="p">[</span><spanclass="mi">0</span><spanclass="p">],</span><spanclass="n">x</span><spanclass="p">[</span><spanclass="o">-</span><spanclass="mi">1</span><spanclass="p">])</span>
</pre></div>
</div>
<p>Here are some examples of this function in action. Be sure that your type-hint captures all of this diversity.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="gp">>>> </span><spanclass="n">get_first_and_last</span><spanclass="p">(</span><spanclass="s2">"hello"</span><spanclass="p">)</span>
<spanclass="go">('h', 'o')</span>
<spanclass="gp">>>> </span><spanclass="n">get_first_and_last</span><spanclass="p">([</span><spanclass="mi">0</span><spanclass="p">,</span><spanclass="mi">1</span><spanclass="p">,</span><spanclass="mi">2</span><spanclass="p">,</span><spanclass="mi">3</span><spanclass="p">])</span>
<spanclass="go">(0, 3)</span>
<spanclass="gp">>>> </span><spanclass="n">get_first_and_last</span><spanclass="p">((</span><spanclass="kc">True</span><spanclass="p">,</span><spanclass="kc">False</span><spanclass="p">))</span>
<spanclass="go">(True, False)</span>
</pre></div>
</div>
</div>
<divclass="admonition note">
<pclass="admonition-title fa fa-exclamation-circle"><strong>Takeaway:</strong></p>
<p>It is un-Pythonic to be overly strict when type hinting. Python handles typing flexibly - it uses <aclass="reference external" href="https://en.wikipedia.org/wiki/Duck_typing">duck typing</a> - and our type hints should follow suit. Rely on abstract base classes when possible to provide the appropriate guidelines for a particular variable type.</p>
</div>
</div>
</div>
<divclass="section" id="Documentation-Styles">
<h2>Documentation Styles<aclass="headerlink" href="#Documentation-Styles" title="Permalink to this headline"></a></h2>
<p><aclass="reference external" href="https://twitter.com/nulhom?lang=en">Davis King</a>, a prolific and talented open source developer, is the creator of the <aclass="reference external" href="http://dlib.net/">dlib C++ library</a>. Among the library’s major features, like machine learning algorithms, Davis lists its <em>documentation</em> as the first and foremost feature. In fact, he says about dlib:</p>
<blockquote>
<div><p><em>I consider the documentation to be the most important part of the library.</em> So if you find anything that isn’t documented, isn’t clear, or has out of date documentation, tell me and I will fix it.</p>
</div></blockquote>
<p>There is great wisdom in placing such a high value on documentation. In this section, we will learn about two popular docstring-style specifications for Python: the NumPy specification and the Google specification. Both of these are rich extensions of the rudimentary docstring conventions that are proposed in <aclass="reference external" href="https://www.python.org/dev/peps/pep-0257/">PEP 257</a>, and, critically, they both place an emphasis on documenting the variable types.</p>
<p>PLYMI uses Numpy-style docstrings throughout most of the text (except for when we are trying to keep the functions brief). This is ultimately just a choice of style/aesthetics. Ultimately, the critical takeaway here is to <strong>pick a documentation style, learn it, and stick to it faithfully</strong>. Once again, it is hard to overstate how important it is to anchor your code with clear and consistent documentation. It will aid you in your code-writing process, it will enable users to adopt and perhaps
contribute to your code, and it will ensure longevity for your hard work.</p>
<divclass="section" id="The-NumPy-Documentation-Style">
<h3>The NumPy Documentation Style<aclass="headerlink" href="#The-NumPy-Documentation-Style" title="Permalink to this headline"></a></h3>
<p>The NumPy documentation style is specified in full <aclass="reference external" href="https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard">here</a>. It is strongly recommended that you read through it in full. There are details in the specification that we will pass over here for the sake of simplicity and to avoid rewriting their specification. We will focus on the guidelines for documenting functions, but note that they specify rules for documenting
<aclass="reference external" href="https://www.pythonlikeyoumeanit.com/module_4.html">classes</a> and <aclass="reference external" href="https://www.pythonlikeyoumeanit.com/Module5_OddsAndEnds/Modules_and_Packages.html#Modules">modules</a>.</p>
<p>A function’s docstring is divided up into several sections. Most of these sections are delimited with a header, e.g. “Parameters”, followed by a horizontal line of dashes:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>Parameters
----------
</pre></div>
</div>
<p>A docstring should at least consist of:</p>
<ulclass="simple">
<li><p>A succinct, single-line description of the function.</p></li>
<li><p>An extended summary of the function, which provides a more verbose description of things.</p></li>
<li><p>A <codeclass="docutils literal notranslate"><spanclass="pre">Parameters</span></code> section, which details the types of the input parameters along with descriptions of them. (This section is not necessary if your function is parameterless).</p></li>
<li><p>A <codeclass="docutils literal notranslate"><spanclass="pre">Returns</span></code> section (or <codeclass="docutils literal notranslate"><spanclass="pre">Yields</span></code> for a generator), which details the object that is returned by the function. (This is not necessary if your function always returns <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code>).</p></li>
</ul>
<p>There are additional, optional sections that can be used to improve your documentation:</p>
<ulclass="simple">
<li><p>A <codeclass="docutils literal notranslate"><spanclass="pre">Notes</span></code> section, which can be used to discuss tertiary details of the function, such as a description of the algorithm that was used. You can also include mathematical formulae here, and cite primary materials</p></li>
<li><p>A <codeclass="docutils literal notranslate"><spanclass="pre">References</span></code> section, used to document any works that were cited in the “Notes” section. It is not very common to need to reference primary sources in your docstrings.</p></li>
<li><p>An <codeclass="docutils literal notranslate"><spanclass="pre">Examples</span></code> section, which contains console-style code, similar to the code snippets that you see in PLYMI, for using your function.</p></li>
</ul>
<p>There are additional, more obscure or technical sections that you can read about in the formal specification.</p>
<p>The following function has a docstring that exemplifies all of these sections.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="k">def</span><spanclass="nf">pairwise_dists</span><spanclass="p">(</span><spanclass="n">x</span><spanclass="p">:</span><spanclass="n">np</span><spanclass="o">.</span><spanclass="n">ndarray</span><spanclass="p">,</span><spanclass="n">y</span><spanclass="p">:</span><spanclass="n">np</span><spanclass="o">.</span><spanclass="n">ndarray</span><spanclass="p">)</span><spanclass="o">-></span><spanclass="n">np</span><spanclass="o">.</span><spanclass="n">ndarray</span><spanclass="p">:</span>
<spanclass="sd">"""Computes pairwise distances between the rows of ``x`` and ``y``.</span>
<spanclass="sd"> Returns the shape-(M, N) array of Euclidean distances between</span>
<spanclass="sd"> the M rows of ``x`` and the N rows of ``y``.</span>
<spanclass="sd"> Parameters</span>
<spanclass="sd"> ----------</span>
<spanclass="sd"> x : numpy.ndarray, shape=(M, D)</span>
<spanclass="sd"> An optional description of ``x``</span>
<spanclass="sd"> y : numpy.ndarray, shape=(N, D)</span>
<spanclass="sd"> An optional description of ``y``</span>
<spanclass="sd"> Returns</span>
<spanclass="sd"> -------</span>
<spanclass="sd"> numpy.ndarray, shape=(M, N)</span>
<spanclass="sd"> The pairwise distances</span>
<spanclass="sd"> Notes</span>
<spanclass="sd"> -----</span>
<spanclass="sd"> This function uses the memory-efficient vectorized implementation that</span>
<spanclass="sd"> is detailed in [1]_.</span>
<spanclass="sd"> References</span>
<spanclass="sd"> ----------</span>
<spanclass="sd"> .. [1] Soklaski, R. (2019, Jan 21). Array Broadcasting.</span>
<spanclass="sd"> Retrieved from https://www.pythonlikeyoumeanit.com</span>
<spanclass="sd"> Examples</span>
<spanclass="sd"> --------</span>
<spanclass="sd"> Compute the pairwise distances between the rows of a shape-(3, 3) array</span>
<spanclass="sd"> with the rows of a shape-(2, 3) array.</span>
<spanclass="sd"> >>> import numpy as np</span>
<spanclass="sd"> >>> x = np.array([[1., 2., 3.],</span>
<spanclass="sd"> ... [4., 5., 6.],</span>
<spanclass="sd"> ... [7., 8., 9.]])</span>
<spanclass="sd"> >>> y = np.array([[1., 2., 3.],</span>
<spanclass="sd"> ... [4., 5., 6.]])</span>
<spanclass="sd"> >>> pairwise_dists(x, y)</span>
<spanclass="sd"> array([[ 0. , 5.19615242],</span>
<spanclass="sd"> [ 5.19615242, 0. ],</span>
<spanclass="sd"> [10.39230485, 5.19615242]])</span>
<spanclass="sd"> """</span>
<spanclass="o">...</span>
</pre></div>
</div>
<p>See that we specify <strong>type information</strong> in the <codeclass="docutils literal notranslate"><spanclass="pre">Parameters</span></code> and the <codeclass="docutils literal notranslate"><spanclass="pre">Returns</span></code> section of the docstring, even though it is redundant with the function signature’s type-hints - it is useful to have this information in the docstring too. This is a good place to embellish the type information with pertinent information that is not conveyed by the formal type-hints. For example, we added shape information alongside the types in these sections.</p>
<p>Variable names should be referenced using double back-ticks within the docstring; e.g. ``x``. It should also be noted that that including an <codeclass="docutils literal notranslate"><spanclass="pre">Examples</span></code> section is very useful for creating high-quality documentation. It is recommended that you include examples liberally throughout your code.</p>
<p>Here is another example docstring that adheres to the NumPy-style, one without a <codeclass="docutils literal notranslate"><spanclass="pre">Notes</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">References</span></code> section:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="k">def</span><spanclass="nf">compute_student_stats</span><spanclass="p">(</span><spanclass="n">grade_book</span><spanclass="p">:</span><spanclass="n">Dict</span><spanclass="p">[</span><spanclass="nb">str</span><spanclass="p">,</span><spanclass="n">Iterable</span><spanclass="p">[</span><spanclass="nb">float</span><spanclass="p">]],</span>
<spanclass="n">stat_function</span><spanclass="p">:</span><spanclass="n">Callable</span><spanclass="p">[[</span><spanclass="n">Iterable</span><spanclass="p">[</span><spanclass="nb">float</span><spanclass="p">]],</span><spanclass="n">Any</span><spanclass="p">],</span>
<spanclass="n">student_list</span><spanclass="p">:</span><spanclass="n">Optional</span><spanclass="p">[</span><spanclass="n">List</span><spanclass="p">[</span><spanclass="nb">str</span><spanclass="p">]]</span><spanclass="o">=</span><spanclass="kc">None</span><spanclass="p">)</span><spanclass="o">-></span><spanclass="n">List</span><spanclass="p">[</span><spanclass="n">Tuple</span><spanclass="p">[</span><spanclass="nb">str</span><spanclass="p">,</span><spanclass="n">Any</span><spanclass="p">]]:</span>
<spanclass="sd">"""Computes custom statistics over students' grades.</span>
<spanclass="sd"> Applies ``stat_func`` over a list of each student's grades,</span>
<spanclass="sd"> and accumulates name-stat tuple pairs in a list.</span>
<spanclass="sd"> Parameters</span>
<spanclass="sd"> ----------</span>
<spanclass="sd"> grade_book : Dict[str, List[float]]</span>
<spanclass="sd"> The dictionary (name -> grades) of all of the students'</span>
<spanclass="sd"> grades.</span>
<spanclass="sd"> stat_function: Callable[[Iterable[float]], Any]</span>
<spanclass="sd"> The function used to compute statistics over each student's</span>
<spanclass="sd"> grades.</span>
<spanclass="sd"> student_list : Optional[List[str]]</span>
<spanclass="sd"> A list of names of the students for whom statistics will be</span>
<spanclass="sd"> computed. By default, statistics will be computed for all</span>
<spanclass="sd"> students in the grade book.</span>
<spanclass="sd"> Returns</span>
<spanclass="sd"> -------</span>
<spanclass="sd"> List[Tuple[str, Any]]</span>
<spanclass="sd"> The name-stats tuple pair for each specified student.</span>
<spanclass="sd"> Examples</span>
<spanclass="sd"> --------</span>
<spanclass="sd"> >>> from statistics import mean</span>
<spanclass="sd"> >>> grade_book = dict(Bruce=[90., 82., 92.], Courtney=[100., 85., 78.])</span>
<spanclass="sd"> >>> compute_student_stats(grade_book, stat_function=mean)</span>
<spanclass="sd"> [('Bruce', 88.0), ('Courtney', 87.66666666666667)]</span>
<spanclass="sd"> """</span>
<spanclass="o">...</span>
</pre></div>
</div>
</div>
<divclass="section" id="The-Google-Documentation-Style">
<h3>The Google Documentation Style<aclass="headerlink" href="#The-Google-Documentation-Style" title="Permalink to this headline"></a></h3>
<p>The Google documentation style is specified in full <aclass="reference external" href="https://github.com/google/styleguide/blob/gh-pages/pyguide.md#doc-function-args">here</a>; it is part of the complete <aclass="reference external" href="https://github.com/google/styleguide/blob/gh-pages/pyguide.md#google-python-style-guide">Google Python style guide</a>. The docstring style specified here is quite succinct in comparison to the NumPy spec. It consists of the following sections:</p>
<ulclass="simple">
<li><p>A succinct, single-line description of the function.</p></li>
<li><p>An extended summary of the function, which provides a more verbose description of things.</p></li>
<li><p>An <codeclass="docutils literal notranslate"><spanclass="pre">Args</span></code> section, which details the types of the input parameters along with descriptions of them. (This section is not necessary if your function is parameterless).</p></li>
<li><p>A <codeclass="docutils literal notranslate"><spanclass="pre">Returns</span></code> section (or <codeclass="docutils literal notranslate"><spanclass="pre">Yields</span></code> for a generator), which details the object that is returned by the function. (This is not necessary if your function always returns <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code>).</p></li>
</ul>
<p>There is also a <codeclass="docutils literal notranslate"><spanclass="pre">Raises</span></code> section in the case that your function raises exceptions under known conditions.</p>
<p>Let’s reproduce the docstrings for <codeclass="docutils literal notranslate"><spanclass="pre">pairwise_dists</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">compute_student_stats</span></code> using the Google style.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="k">def</span><spanclass="nf">pairwise_dists</span><spanclass="p">(</span><spanclass="n">x</span><spanclass="p">:</span><spanclass="n">np</span><spanclass="o">.</span><spanclass="n">ndarray</span><spanclass="p">,</span><spanclass="n">y</span><spanclass="p">:</span><spanclass="n">np</span><spanclass="o">.</span><spanclass="n">ndarray</span><spanclass="p">)</span><spanclass="o">-></span><spanclass="n">np</span><spanclass="o">.</span><spanclass="n">ndarray</span><spanclass="p">:</span>
<spanclass="sd">"""Computes pairwise distances between the rows of ``x`` and ``y``.</span>
<spanclass="sd"> Returns the shape-(M, N) array of Euclidean distances between</span>
<spanclass="sd"> the M rows of ``x`` and the N rows of ``y``.</span>
<spanclass="sd"> Args:</span>
<spanclass="sd"> x (numpy.ndarray) : A shape-(M, D) array</span>
<spanclass="sd"> y (numpy.ndarray) : A shape-(N, D) array</span>
<spanclass="sd"> Returns:</span>
<spanclass="sd"> (numpy.ndarray): A shape-(M, N) array of the pairwise distances</span>
<spanclass="sd"> """</span>
<spanclass="o">...</span>
</pre></div>
</div>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="k">def</span><spanclass="nf">compute_student_stats</span><spanclass="p">(</span><spanclass="n">grade_book</span><spanclass="p">:</span><spanclass="n">Dict</span><spanclass="p">[</span><spanclass="nb">str</span><spanclass="p">,</span><spanclass="n">Iterable</span><spanclass="p">[</span><spanclass="nb">float</span><spanclass="p">]],</span>
<spanclass="n">stat_function</span><spanclass="p">:</span><spanclass="n">Callable</span><spanclass="p">[[</span><spanclass="n">Iterable</span><spanclass="p">[</span><spanclass="nb">float</span><spanclass="p">]],</span><spanclass="n">Any</span><spanclass="p">],</span>
<spanclass="n">student_list</span><spanclass="p">:</span><spanclass="n">Optional</span><spanclass="p">[</span><spanclass="n">List</span><spanclass="p">[</span><spanclass="nb">str</span><spanclass="p">]]</span><spanclass="o">=</span><spanclass="kc">None</span><spanclass="p">)</span><spanclass="o">-></span><spanclass="n">List</span><spanclass="p">[</span><spanclass="n">Tuple</span><spanclass="p">[</span><spanclass="nb">str</span><spanclass="p">,</span><spanclass="n">Any</span><spanclass="p">]]:</span>
<spanclass="sd">"""Computes custom statistics over students' grades.</span>
<spanclass="sd"> Applies ``stat_func`` over a list of each student's grades,</span>
<spanclass="sd"> and accumulates name-stat tuple pairs in a list.</span>
<spanclass="sd"> Args:</span>
<spanclass="sd"> grade_book (Dict[str, List[float]]): The dictionary</span>
<spanclass="sd"> (name -> grades) of all of the students' grades.</span>
<spanclass="sd"> stat_function (Callable[[Iterable[float]], Any]): The</span>
<spanclass="sd"> function used to compute statistics over each</span>
<spanclass="sd"> student's grades.</span>
<spanclass="sd"> student_list (Optional[List[str]]): A list of names of</span>
<spanclass="sd"> the students for whom statistics will be computed.</span>
<spanclass="sd"> By default, statistics will be computed for all</span>
<spanclass="sd"> students in the grade book.</span>
<spanclass="sd"> Returns</span>
<spanclass="sd"> (List[Tuple[str, Any]]): The name-stats tuple pair for each</span>
<spanclass="sd"> specified student.</span>
<spanclass="sd"> """</span>
<spanclass="o">...</span>
</pre></div>
</div>
<p>See that this style produces docstrings that are succinct, but are sometimes crowded horizontally given the successive levels of indentation within each docstring-section.</p>
<p>It must also be noted that the <aclass="reference external" href="https://sphinxcontrib-napoleon.readthedocs.io/en/latest/index.html#napoleon-marching-toward-legible-docstrings">Napolean project</a>, which facilitates the automated generation of HTML documentation-pages from Python docstrings, has extended the Google specification to match the sections of the NumPy style. The Napolean version of the NumPy and Google docstring styles can be found <aclass="reference external" href="https://sphinxcontrib-napoleon.readthedocs.io/en/latest/index.html#id1">here</a>.
This resource also includes useful examples of docstrings for modules and classes.</p>
<divclass="admonition note">
<pclass="admonition-title fa fa-exclamation-circle"><strong>Takeaway:</strong></p>
<p>Take some time to review the NumPy and Google docstring specifications, pick one, and stick to it faithfully when documenting your code. If you plan to code with others, find out if they have already chosen a documentation style.</p>
</div>
<divclass="admonition warning">
<pclass="admonition-title fa fa-exclamation-circle"><strong>Documentation Tools:</strong></p>
<p><aclass="reference external" href="http://www.sphinx-doc.org/en/master/">Sphinx</a> is a popular and hugely-powerful tool that will render documentation for your project in HTML by parsing the docstrings that are in your code. Python, NumPy, and almost all major 3rd party Python libraries use Sphinx to publish their documentation pages. <aclass="reference external" href="https://sphinxcontrib-napoleon.readthedocs.io/en/latest/index.html#napoleon-marching-toward-legible-docstrings">Napolean</a> and <aclass="reference external" href="https://github.com/numpy/numpydoc">numpydoc</a> are Sphinx
extensions that allows Sphinx to parse and nicely render docstrings that adhere to the NumPy and Google docstring specifications.</p>
<p><aclass="reference external" href="https://github.com/meowklaski/custom_inherit">custom_inherit</a> is a lightweight tool for <aclass="reference external" href="http://www.pythonlikeyoumeanit.com/Module4_OOP/Inheritance.html">inheriting</a> and merging docstrings. It provides rich support for merging the various sections of docstrings, and supports NumPy and Google-style docstrings natively. It also supports custom documentation styles.</p>
</div>
</div>
</div>
<divclass="section" id="Links-to-Official-Documentation">
<h2>Links to Official Documentation<aclass="headerlink" href="#Links-to-Official-Documentation" title="Permalink to this headline"></a></h2>
<ulclass="simple">
<li><p><aclass="reference external" href="https://www.python.org/dev/peps/">PEP 0: Index of Python Enhancement Proposals</a></p></li>
<li><p><aclass="reference external" href="https://www.python.org/dev/peps/pep-0001/">PEP 1: Purpose and Guidelines</a></p></li>
<li><p><aclass="reference external" href="https://www.python.org/dev/peps/pep-0008">PEP 8: Style Guide for Python Code</a></p></li>
<li><p><aclass="reference external" href="https://www.python.org/dev/peps/pep-0483/">PEP 483: The Theory of Type Hints</a></p></li>
<li><p><aclass="reference external" href="https://www.python.org/dev/peps/pep-0484/">PEP 484: Type-Hinting</a></p></li>
<li><p><aclass="reference external" href="https://www.python.org/dev/peps/pep-0526/">PEP 526: Syntax for Variable Annotations</a></p></li>
<li><p><aclass="reference external" href="https://docs.python.org/3/library/typing.html">The standard library’s typing module</a></p></li>
<li><p><aclass="reference external" href="https://docs.python.org/3/glossary.html#term-abstract-base-class">Definition: abstract base class</a></p></li>
<li><p><aclass="reference external" href="https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard">NumPy Documentation Specification</a></p></li>
<li><p><aclass="reference external" href="https://github.com/google/styleguide/blob/gh-pages/pyguide.md#doc-function-args">Google Documentation Specification</a></p></li>
<li><p><aclass="reference external" href="https://sphinxcontrib-napoleon.readthedocs.io/en/latest/index.html#">Napolean: Marching Towards Legible Docstrings</a></p></li>
</ul>
</div>
<divclass="section" id="Reading-Comprehension-Solutions">
<h2>Reading Comprehension Solutions<aclass="headerlink" href="#Reading-Comprehension-Solutions" title="Permalink to this headline"></a></h2>
<p><strong>Type-Assisted Code Completion: Solution</strong></p>
<p>The tab-completion reveals methods like “capitalize”, “casefold”, and “center” – all of which are string methods. These are made available despite the fact that <codeclass="docutils literal notranslate"><spanclass="pre">x</span></code> did not yet refer to a specific string. Instead, the type-hint was able to tell the editor that <codeclass="docutils literal notranslate"><spanclass="pre">x</span></code><em>will</em> refer to a string, and this was enough to inform these type completions.</p>
<p>Revising the type-annotation for <codeclass="docutils literal notranslate"><spanclass="pre">x</span></code> to be <codeclass="docutils literal notranslate"><spanclass="pre">list</span></code> affects the auto-completion options accordingly: the editor will now suggest list methods like “append”, “clear”, and “copy”.</p>
<p><strong>Type Hinting: Solution</strong></p>
<p>The following is a well-annotated version of <codeclass="docutils literal notranslate"><spanclass="pre">get_first_and_last</span></code>:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="kn">from</span><spanclass="nn">typing</span><spanclass="kn">import</span><spanclass="n">Sequence</span><spanclass="p">,</span><spanclass="n">Tuple</span><spanclass="p">,</span><spanclass="n">Any</span>
<spanclass="k">def</span><spanclass="nf">get_first_and_last</span><spanclass="p">(</span><spanclass="n">x</span><spanclass="p">:</span><spanclass="n">Sequence</span><spanclass="p">[</span><spanclass="n">Any</span><spanclass="p">])</span><spanclass="o">-></span><spanclass="n">Tuple</span><spanclass="p">[</span><spanclass="n">Any</span><spanclass="p">,</span><spanclass="n">Any</span><spanclass="p">]:</span>
<spanclass="sd">"""Returns the first and last elements of `x`. `x` is</span>
<spanclass="sd"> assumed to be non-empty</span>
<spanclass="sd"> """</span>
<spanclass="k">return</span><spanclass="p">(</span><spanclass="n">x</span><spanclass="p">[</span><spanclass="mi">0</span><spanclass="p">],</span><spanclass="n">x</span><spanclass="p">[</span><spanclass="o">-</span><spanclass="mi">1</span><spanclass="p">])</span>
</pre></div>
</div>
<p>This function only requires that <codeclass="docutils literal notranslate"><spanclass="pre">x</span></code> can be indexed into. Referring to the <aclass="reference external" href="https://docs.python.org/3/library/collections.abc.html#collections-abstract-base-classes">abc’s for Python’s collections</a>, <codeclass="docutils literal notranslate"><spanclass="pre">Sequence</span></code> is the simplest abstract base class that supports the <codeclass="docutils literal notranslate"><spanclass="pre">__getitem__</span></code> syntax. Indeed, this was a trait characteristic that we saw for all of <aclass="reference external" href="https://www.pythonlikeyoumeanit.com/Module2_EssentialsOfPython/SequenceTypes.html">Python’s sequence types</a>. Lastly, note that we make no
assumptions about the contents of <codeclass="docutils literal notranslate"><spanclass="pre">x</span></code>, thus we use the generic <codeclass="docutils literal notranslate"><spanclass="pre">Any</span></code> type.</p>
</div>
</div>
</div>
</div>
