source: documentation/coding_standards/Style Guide for Python Code, GA version.htm @ 3031

Last change on this file since 3031 was 2419, checked in by sexton, 19 years ago

Doing action item from Wed 15 Feb meeting (adding FIXME to style guide)
File size: 84.5 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3c.org/TR/1999/REC-html401-19991224/loose.dtd">
2<!-- saved from url=(0110)file://V:\1\cit\risk_assessment_methods_project\inundation\sandpits\onielsen\anuga\documentation\pep-0008.html -->
3<html xmlns:v="urn:schemas-microsoft-com:vml"
4xmlns:o="urn:schemas-microsoft-com:office:office"
5xmlns:w="urn:schemas-microsoft-com:office:word"
6xmlns:st1="urn:schemas-microsoft-com:office:smarttags"
7xmlns="http://www.w3.org/TR/REC-html40">
8
9<head>
10<meta http-equiv=Content-Type content="text/html; charset=windows-1252">
11<meta name=ProgId content=Word.Document>
12<meta name=Generator content="Microsoft Word 10">
13<meta name=Originator content="Microsoft Word 10">
14<link rel=File-List
15href="Style%20Guide%20for%20Python%20Code,%20GA%20version_files/filelist.xml">
16<link rel=Edit-Time-Data
17href="Style%20Guide%20for%20Python%20Code,%20GA%20version_files/editdata.mso">
18<!--[if !mso]>
19<style>
20v\:* {behavior:url(#default#VML);}
21o\:* {behavior:url(#default#VML);}
22w\:* {behavior:url(#default#VML);}
23.shape {behavior:url(#default#VML);}
24</style>
25<![endif]-->
26<title>PEP 8 -- Style Guide for Python Code</title>
27<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
28 name="date"/>
29<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
30 name="country-region"/>
31<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
32 name="place"/>
33<!--[if gte mso 9]><xml>
34 <o:DocumentProperties>
35  <o:Author>nielsen ole</o:Author>
36  <o:LastAuthor>sexton jane</o:LastAuthor>
37  <o:Revision>3</o:Revision>
38  <o:TotalTime>45</o:TotalTime>
39  <o:Created>2006-02-16T06:00:00Z</o:Created>
40  <o:LastSaved>2006-02-16T06:02:00Z</o:LastSaved>
41  <o:Pages>1</o:Pages>
42  <o:Words>4006</o:Words>
43  <o:Characters>22839</o:Characters>
44  <o:Company>Geoscience Australia</o:Company>
45  <o:Lines>190</o:Lines>
46  <o:Paragraphs>53</o:Paragraphs>
47  <o:CharactersWithSpaces>26792</o:CharactersWithSpaces>
48  <o:Version>10.6626</o:Version>
49 </o:DocumentProperties>
50</xml><![endif]--><!--[if gte mso 9]><xml>
51 <w:WordDocument>
52  <w:SpellingState>Clean</w:SpellingState>
53  <w:GrammarState>Clean</w:GrammarState>
54  <w:BrowserLevel>MicrosoftInternetExplorer4</w:BrowserLevel>
55 </w:WordDocument>
56</xml><![endif]--><!--[if !mso]><object
57 classid="clsid:38481807-CA0E-42D2-BF39-B33AF135CC4D" id=ieooui></object>
58<style>
59st1\:*{behavior:url(#ieooui) }
60</style>
61<![endif]-->
62<link rel=Stylesheet type="text/css" media=all
63href="Style%20Guide%20for%20Python%20Code,%20GA%20version_files/style.css">
64<style>
65<!--
66 /* Style Definitions */
67 p.MsoNormal, li.MsoNormal, div.MsoNormal
68        {mso-style-parent:"";
69        margin:0cm;
70        margin-bottom:.0001pt;
71        mso-pagination:widow-orphan;
72        font-size:12.0pt;
73        font-family:"Times New Roman";
74        mso-fareast-font-family:"Times New Roman";}
75h3
76        {mso-margin-top-alt:auto;
77        margin-right:0cm;
78        mso-margin-bottom-alt:auto;
79        margin-left:0cm;
80        mso-pagination:widow-orphan;
81        mso-outline-level:3;
82        font-size:13.5pt;}
83a:link, span.MsoHyperlink
84        {color:blue;
85        text-decoration:underline;
86        text-underline:single;}
87a:visited, span.MsoHyperlinkFollowed
88        {color:blue;
89        text-decoration:underline;
90        text-underline:single;}
91pre
92        {margin:0cm;
93        margin-bottom:.0001pt;
94        mso-pagination:widow-orphan;
95        font-size:10.0pt;
96        font-family:"Courier New";
97        mso-fareast-font-family:"Times New Roman";}
98p.navigation, li.navigation, div.navigation
99        {mso-style-name:navigation;
100        mso-margin-top-alt:auto;
101        margin-right:0cm;
102        mso-margin-bottom-alt:auto;
103        margin-left:0cm;
104        mso-pagination:widow-orphan;
105        font-size:12.0pt;
106        font-family:"Times New Roman";
107        mso-fareast-font-family:"Times New Roman";}
108p.header, li.header, div.header
109        {mso-style-name:header;
110        mso-margin-bottom-alt:auto;
111        mso-pagination:widow-orphan;
112        font-size:12.0pt;
113        font-family:"Times New Roman";
114        mso-fareast-font-family:"Times New Roman";}
115p.content, li.content, div.content
116        {mso-style-name:content;
117        mso-margin-top-alt:auto;
118        mso-margin-bottom-alt:auto;
119        mso-pagination:widow-orphan;
120        font-size:12.0pt;
121        font-family:"Times New Roman";
122        mso-fareast-font-family:"Times New Roman";}
123p.navicon, li.navicon, div.navicon
124        {mso-style-name:navicon;
125        mso-margin-top-alt:auto;
126        margin-right:0cm;
127        mso-margin-bottom-alt:auto;
128        margin-left:0cm;
129        mso-pagination:widow-orphan;
130        background:#99CCFF;
131        font-size:12.0pt;
132        font-family:"Times New Roman";
133        mso-fareast-font-family:"Times New Roman";}
134p.textlinks, li.textlinks, div.textlinks
135        {mso-style-name:textlinks;
136        mso-margin-top-alt:auto;
137        margin-right:0cm;
138        mso-margin-bottom-alt:auto;
139        margin-left:0cm;
140        mso-pagination:widow-orphan;
141        background:#99CCFF;
142        font-size:12.0pt;
143        font-family:"Times New Roman";
144        mso-fareast-font-family:"Times New Roman";}
145p.navicon1, li.navicon1, div.navicon1
146        {mso-style-name:navicon1;
147        mso-margin-top-alt:auto;
148        margin-right:0cm;
149        mso-margin-bottom-alt:auto;
150        margin-left:0cm;
151        mso-pagination:widow-orphan;
152        background:#99CCFF;
153        font-size:12.0pt;
154        font-family:"Times New Roman";
155        mso-fareast-font-family:"Times New Roman";}
156p.textlinks1, li.textlinks1, div.textlinks1
157        {mso-style-name:textlinks1;
158        mso-margin-top-alt:auto;
159        margin-right:0cm;
160        mso-margin-bottom-alt:auto;
161        margin-left:0cm;
162        mso-pagination:widow-orphan;
163        background:#99CCFF;
164        font-size:12.0pt;
165        font-family:"Times New Roman";
166        mso-fareast-font-family:"Times New Roman";}
167span.SpellE
168        {mso-style-name:"";
169        mso-spl-e:yes;}
170span.GramE
171        {mso-style-name:"";
172        mso-gram-e:yes;}
173@page Section1
174        {size:595.3pt 841.9pt;
175        margin:72.0pt 90.0pt 72.0pt 90.0pt;
176        mso-header-margin:35.4pt;
177        mso-footer-margin:35.4pt;
178        mso-paper-source:0;}
179div.Section1
180        {page:Section1;}
181 /* List Definitions */
182 @list l0
183        {mso-list-id:1153451165;
184        mso-list-type:hybrid;
185        mso-list-template-ids:214334516 -1253416102 201916419 201916421 201916417 201916419 201916421 201916417 201916419 201916421;}
186@list l0:level1
187        {mso-level-start-at:5;
188        mso-level-number-format:bullet;
189        mso-level-text:-;
190        mso-level-tab-stop:42.0pt;
191        mso-level-number-position:left;
192        margin-left:42.0pt;
193        text-indent:-18.0pt;
194        font-family:"Courier New";
195        mso-fareast-font-family:"Times New Roman";
196        color:windowtext;
197        mso-ansi-font-style:normal;}
198@list l0:level2
199        {mso-level-tab-stop:72.0pt;
200        mso-level-number-position:left;
201        text-indent:-18.0pt;}
202@list l0:level3
203        {mso-level-tab-stop:108.0pt;
204        mso-level-number-position:left;
205        text-indent:-18.0pt;}
206@list l0:level4
207        {mso-level-tab-stop:144.0pt;
208        mso-level-number-position:left;
209        text-indent:-18.0pt;}
210@list l0:level5
211        {mso-level-tab-stop:180.0pt;
212        mso-level-number-position:left;
213        text-indent:-18.0pt;}
214@list l0:level6
215        {mso-level-tab-stop:216.0pt;
216        mso-level-number-position:left;
217        text-indent:-18.0pt;}
218@list l0:level7
219        {mso-level-tab-stop:252.0pt;
220        mso-level-number-position:left;
221        text-indent:-18.0pt;}
222@list l0:level8
223        {mso-level-tab-stop:288.0pt;
224        mso-level-number-position:left;
225        text-indent:-18.0pt;}
226@list l0:level9
227        {mso-level-tab-stop:324.0pt;
228        mso-level-number-position:left;
229        text-indent:-18.0pt;}
230ol
231        {margin-bottom:0cm;}
232ul
233        {margin-bottom:0cm;}
234-->
235</style>
236<!--[if gte mso 10]>
237<style>
238 /* Style Definitions */
239 table.MsoNormalTable
240        {mso-style-name:"Table Normal";
241        mso-tstyle-rowband-size:0;
242        mso-tstyle-colband-size:0;
243        mso-style-noshow:yes;
244        mso-style-parent:"";
245        mso-padding-alt:0cm 5.4pt 0cm 5.4pt;
246        mso-para-margin:0cm;
247        mso-para-margin-bottom:.0001pt;
248        mso-pagination:widow-orphan;
249        font-size:10.0pt;
250        font-family:"Times New Roman";}
251</style>
252<![endif]--><!--
253This HTML is auto-generated.  DO NOT EDIT THIS FILE!  If you are writing a new
254PEP, see http://www.python.org/peps/pep-0001.html for instructions and links
255to templates.  DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
256--><!--[if gte mso 9]><xml>
257 <o:shapedefaults v:ext="edit" spidmax="8194"/>
258</xml><![endif]--><!--[if gte mso 9]><xml>
259 <o:shapelayout v:ext="edit">
260  <o:idmap v:ext="edit" data="1"/>
261 </o:shapelayout></xml><![endif]-->
262</head>
263
264<body bgcolor=white lang=EN-AU link=blue vlink=blue style='tab-interval:36.0pt'>
265
266<div class=Section1>
267
268<table class=MsoNormalTable border=0 cellspacing=0 cellpadding=0 width="100%"
269 style='width:100.0%;mso-cellspacing:0cm;background:#99CCFF;mso-padding-alt:
270 0cm 0cm 0cm 0cm'>
271 <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes;height:26.25pt'>
272  <td width="100%" style='width:100.0%;padding:0cm 0cm 0cm 0cm;height:26.25pt'>
273  <p class=MsoNormal><a href="http://www.python.org/" title="Python Home Page"><span
274  style='text-decoration:none;text-underline:none'><img border=0 width=150
275  height=35 id="_x0000_i1025"
276  src="Style%20Guide%20for%20Python%20Code,%20GA%20version_files/PyBanner040.gif"
277  alt="[Python]"></span></a></p>
278  </td>
279  <td width="100%" style='width:100.0%;padding:0cm 0cm 0cm 12.0pt;height:26.25pt'>
280  <p class=MsoNormal>[<b><a href="http://www.python.org/">Python Home</a></b>]
281  [<b><a href="http://www.python.org/peps/">PEP Index</a></b>] [<b><a
282  href="http://www.python.org/peps/pep-0008.txt">PEP Source</a></b>] </p>
283  </td>
284 </tr>
285</table>
286
287<div style='margin-left:12.0pt;margin-top:6.0pt;margin-right:12.0pt'>
288
289<p class=MsoNormal><span style='display:none;mso-hide:all'><o:p>&nbsp;</o:p></span></p>
290
291<table class=MsoNormalTable border=0 cellpadding=0 style='mso-cellspacing:1.5pt;
292 mso-padding-alt:0cm 5.4pt 0cm 5.4pt'>
293 <tr style='mso-yfti-irow:0'>
294  <td style='padding:.75pt 6.0pt .75pt .75pt'>
295  <p class=MsoNormal align=right style='text-align:right'><b><span
296  style='font-family:Arial'>PEP:&nbsp;<o:p></o:p></span></b></p>
297  </td>
298  <td style='padding:.75pt .75pt .75pt .75pt'>
299  <p class=MsoNormal>8</p>
300  </td>
301 </tr>
302 <tr style='mso-yfti-irow:1'>
303  <td style='padding:.75pt 6.0pt .75pt .75pt'>
304  <p class=MsoNormal align=right style='text-align:right'><b><span
305  style='font-family:Arial'>Title:&nbsp;<o:p></o:p></span></b></p>
306  </td>
307  <td style='padding:.75pt .75pt .75pt .75pt'>
308  <p class=MsoNormal>Style Guide for Python Code</p>
309  </td>
310 </tr>
311 <tr style='mso-yfti-irow:2'>
312  <td style='padding:.75pt 6.0pt .75pt .75pt'>
313  <p class=MsoNormal align=right style='text-align:right'><b><span
314  style='font-family:Arial'>Version:&nbsp;<o:p></o:p></span></b></p>
315  </td>
316  <td style='padding:.75pt .75pt .75pt .75pt'>
317  <p class=MsoNormal>$Revision: 1.27$ (Modified by Geoscience <st1:country-region><st1:place>Australia</st1:place></st1:country-region>)</p>
318  </td>
319 </tr>
320 <tr style='mso-yfti-irow:3'>
321  <td style='padding:.75pt 6.0pt .75pt .75pt'>
322  <p class=MsoNormal align=right style='text-align:right'><b><span
323  style='font-family:Arial'>Author:&nbsp;<o:p></o:p></span></b></p>
324  </td>
325  <td style='padding:.75pt .75pt .75pt .75pt'>
326  <p class=MsoNormal>Guido van <span class=SpellE>Rossum</span> &lt;<span
327  class=SpellE>guido</span> at python.org&gt;, Barry Warsaw &lt;<span
328  class=SpellE>barry</span> at python.org&gt;</p>
329  </td>
330 </tr>
331 <tr style='mso-yfti-irow:4'>
332  <td style='padding:.75pt 6.0pt .75pt .75pt'>
333  <p class=MsoNormal align=right style='text-align:right'><b><span
334  style='font-family:Arial'>Status:&nbsp;<o:p></o:p></span></b></p>
335  </td>
336  <td style='padding:.75pt .75pt .75pt .75pt'>
337  <p class=MsoNormal>Active</p>
338  </td>
339 </tr>
340 <tr style='mso-yfti-irow:5'>
341  <td style='padding:.75pt 6.0pt .75pt .75pt'>
342  <p class=MsoNormal align=right style='text-align:right'><b><span
343  style='font-family:Arial'>Type:&nbsp;<o:p></o:p></span></b></p>
344  </td>
345  <td style='padding:.75pt .75pt .75pt .75pt'>
346  <p class=MsoNormal>Informational</p>
347  </td>
348 </tr>
349 <tr style='mso-yfti-irow:6'>
350  <td style='padding:.75pt 6.0pt .75pt .75pt'>
351  <p class=MsoNormal align=right style='text-align:right'><b><span
352  style='font-family:Arial'>Created:&nbsp;<o:p></o:p></span></b></p>
353  </td>
354  <td style='padding:.75pt .75pt .75pt .75pt'>
355  <p class=MsoNormal><st1:date Year="2001" Day="5" Month="7">05-Jul-2001</st1:date></p>
356  </td>
357 </tr>
358 <tr style='mso-yfti-irow:7;mso-yfti-lastrow:yes'>
359  <td style='padding:.75pt 6.0pt .75pt .75pt'>
360  <p class=MsoNormal align=right style='text-align:right'><b><span
361  style='font-family:Arial'>Post-History:&nbsp;<o:p></o:p></span></b></p>
362  </td>
363  <td style='padding:.75pt .75pt .75pt .75pt'>
364  <p class=MsoNormal>Modified slightly by Ole Nielsen &lt;<span class=SpellE>Ole.Nielsen</span>
365  at <span class=SpellE>ga.gov.au</span>&gt; and Duncan Gray &lt;<span
366  class=SpellE>Duncan.gray</span> at <span class=SpellE>ga.gov.au</span>&gt;</p>
367  <p class=MsoNormal>Geoscience Australia 2005. </p>
368  <p class=MsoNormal>The GA modifications are clearly flagged using blue
369  italics and reasons outlined.</p>
370  </td>
371 </tr>
372</table>
373
374</div>
375
376<div class=MsoNormal align=center style='text-align:center'>
377
378<hr size=2 width="100%" align=center>
379
380</div>
381
382<div style='margin-left:12.0pt;margin-right:12.0pt'>
383
384<h3>Introduction</h3>
385
386<pre><span style='mso-spacerun:yes'>    </span>This document gives coding conventions for the Python code</pre><pre><span style='mso-spacerun:yes'>    </span><span
387class=GramE>comprising</span> the standard library for the main Python distribution.</pre><pre><span style='mso-spacerun:yes'>    </span>Please see the companion informational PEP describing style</pre><pre><span style='mso-spacerun:yes'>    </span><span
388class=GramE>guidelines</span> for the C code in the C implementation of Python[1].</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>This document was adapted from Guido's original Python Style</pre><pre><span style='mso-spacerun:yes'>   </span><span style='mso-spacerun:yes'> </span>Guide <span
389class=GramE>essay[</span>2], with some additions from Barry's style guide[5].</pre><pre><span style='mso-spacerun:yes'>    </span>Where there's conflict, Guido's style rules for the purposes of</pre><pre><span style='mso-spacerun:yes'>    </span><span
390class=GramE>this</span> PEP.<span style='mso-spacerun:yes'>  </span>This PEP may still be incomplete (in fact, it may never</pre><pre><span style='mso-spacerun:yes'>    </span><span
391class=GramE>be</span> finished &lt;wink&gt;).</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
392
393<h3>A Foolish Consistency is the Hobgoblin of Little Minds</h3>
394
395<pre><span style='mso-spacerun:yes'>    </span>A style guide is about consistency.<span style='mso-spacerun:yes'>  </span>Consistency with this style</pre><pre><span style='mso-spacerun:yes'>    </span><span
396class=GramE>guide</span> is important.<span style='mso-spacerun:yes'>  </span>Consistency within a project is more</pre><pre><span style='mso-spacerun:yes'>    </span><span
397class=GramE>important</span>. Consistency within one module or function is most</pre><pre><span style='mso-spacerun:yes'>    </span><span
398class=GramE>important</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>But most importantly: know when to be inconsistent -- sometimes</pre><pre><span style='mso-spacerun:yes'>    </span><span
399class=GramE>the</span> style guide just doesn't apply.<span style='mso-spacerun:yes'>  </span>When in doubt, use your best</pre><pre><span style='mso-spacerun:yes'>    </span><span
400class=GramE>judgement</span>.<span style='mso-spacerun:yes'>  </span>Look at other examples and decide what looks best.</pre><pre><span style='mso-spacerun:yes'>    </span>And don't hesitate to ask!</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Two good reasons to break a particular rule:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>(1) When applying the rule would make the code less readable, even</pre><pre><span style='mso-spacerun:yes'>        </span><span
401class=GramE>for</span> someone who is used to reading code that follows the rules.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>(2) To be consistent with surrounding code that also breaks it</pre><pre><span style='mso-spacerun:yes'>   </span><span style='mso-spacerun:yes'>     </span>(<span
402class=GramE>maybe</span> for historic reasons) -- <span class=GramE>although</span> this is also an</pre><pre><span style='mso-spacerun:yes'>        </span><span
403class=GramE>opportunity</span> to clean up someone else's mess (in true XP style).</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
404
405<h3>Code lay-out</h3>
406
407<pre><span style='mso-spacerun:yes'>  </span>Indentation</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Use the default of <span
408class=SpellE>Emacs</span>' Python-mode: 4 spaces for one</pre><pre><span style='mso-spacerun:yes'>    </span><span
409class=GramE>indentation</span> level.<span style='mso-spacerun:yes'>  </span>For really old code that you don't want to</pre><pre><span style='mso-spacerun:yes'>    </span><span
410class=GramE>mess</span> up, you can continue to use 8-space tabs.<span style='mso-spacerun:yes'>  </span><span
411class=SpellE>Emacs</span> Python-mode</pre><pre><span style='mso-spacerun:yes'>    </span><span
412class=GramE>auto-</span>detects the prevailing indentation level used in a file and</pre><pre><span style='mso-spacerun:yes'>    </span><span
413class=GramE>sets</span> its indentation parameters accordingly.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span><span
414class=GramE>Tabs or Spaces?</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Never mix tabs and spaces.<span style='mso-spacerun:yes'>  </span>The most popular way of indenting</pre><pre><span style='mso-spacerun:yes'>    </span>Python is with spaces only.<span style='mso-spacerun:yes'>  </span>The second-most popular way is with</pre><pre><span style='mso-spacerun:yes'>    </span><span
415class=GramE>tabs</span> only.<span style='mso-spacerun:yes'>  </span>Code indented with a mixture of tabs and spaces should</pre><pre><span style='mso-spacerun:yes'>    </span><span
416class=GramE>be</span> converted to using spaces exclusively.<span style='mso-spacerun:yes'>  </span>(In <span
417class=SpellE>Emacs</span>, select the</pre><pre><span style='mso-spacerun:yes'>    </span><span
418class=GramE>whole</span> buffer and hit ESC-x <span class=SpellE>untabify</span>.)<span style='mso-spacerun:yes'>  </span>When invoking the python</pre><pre><span style='mso-spacerun:yes'>    </span><span
419class=GramE>command</span> line interpreter with the -t option, it issues warnings</pre><pre><span style='mso-spacerun:yes'>    </span><span
420class=GramE>about</span> code that illegally mixes tabs and spaces.<span style='mso-spacerun:yes'>  </span>When using -<span
421class=SpellE>tt</span></pre><pre><span style='mso-spacerun:yes'>    </span><span
422class=GramE>these</span> warnings become errors.<span style='mso-spacerun:yes'>  </span>These options are highly</pre><pre><span style='mso-spacerun:yes'>    </span><span
423class=GramE>recommended</span>!</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>For new projects, spaces-only are strongly recommended over tabs.</pre><pre><span style='mso-spacerun:yes'>    </span>Most editors have features that make this easy to do.<span style='mso-spacerun:yes'>  </span>(In <span
424class=SpellE>Emacs</span>,</pre><pre><span style='mso-spacerun:yes'>    </span><span
425class=GramE>make</span> sure indent-tabs-mode is nil).</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span>Maximum Line Length</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>There are still many devices around that are limited to 80</pre><pre><span style='mso-spacerun:yes'>    </span><span
426class=GramE>character</span> lines; plus, limiting windows to 80 characters makes it</pre><pre><span style='mso-spacerun:yes'>    </span><span
427class=GramE>possible</span> to have several windows side-by-side.<span style='mso-spacerun:yes'>  </span>The default</pre><pre><span style='mso-spacerun:yes'>    </span><span
428class=GramE>wrapping</span> on such devices looks ugly.<span style='mso-spacerun:yes'>  </span>Therefore, please limit all</pre><pre><span style='mso-spacerun:yes'>    </span><span
429class=GramE>lines</span> to a maximum of 79 characters (<span class=SpellE>Emacs</span> wraps lines that are</pre><pre><span style='mso-spacerun:yes'>    </span><span
430class=GramE>exactly</span> 80 characters long).<span style='mso-spacerun:yes'>  </span>For flowing long blocks of text</pre><pre><span style='mso-spacerun:yes'>    </span>(<span
431class=SpellE>docstrings</span> or comments), limiting the length to 72 characters is</pre><pre><span style='mso-spacerun:yes'>    </span><span
432class=GramE>recommended</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>The preferred way of wrapping long lines is by using Python's</pre><pre><span style='mso-spacerun:yes'>    </span><span
433class=GramE>implied</span> line continuation inside parentheses, brackets and braces.</pre><pre><span style='mso-spacerun:yes'>    </span>If necessary, you can add an extra pair of parentheses around an</pre><pre><span style='mso-spacerun:yes'>    </span><span
434class=GramE>expression</span>, but sometimes using a backslash looks better.<span style='mso-spacerun:yes'>  </span>Make</pre><pre><span style='mso-spacerun:yes'>    </span><span
435class=GramE>sure</span> to indent the continued line appropriately.<span style='mso-spacerun:yes'>  </span><span
436class=SpellE>Emacs</span></pre><pre><span style='mso-spacerun:yes'>    </span>Python-mode does this right.<span style='mso-spacerun:yes'>  </span>Some examples:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span><span
437class=GramE>class</span> Rectangle(Blob):</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
438class=GramE>def</span> __init__(self, width, height,</pre><pre><span style='mso-spacerun:yes'>                     </span><span
439class=SpellE>color</span>='black', emphasis=None, highlight=0):</pre><pre><span style='mso-spacerun:yes'>            </span><span
440class=GramE>if</span> width == 0 and height == 0 and \</pre><pre><span style='mso-spacerun:yes'>               </span><span
441class=SpellE>color</span> == 'red' and emphasis == 'strong' or \</pre><pre><span style='mso-spacerun:yes'>               </span><span
442class=GramE>highlight</span> &gt; 100:</pre><pre><span style='mso-spacerun:yes'>                </span><span
443class=GramE>raise</span> <span class=SpellE>ValueError</span>(&quot;sorry, you lose&quot;)</pre><pre><span style='mso-spacerun:yes'>            </span><span
444class=GramE>if</span> width == 0 and height == 0 and (<span class=SpellE>color</span> == 'red' or</pre><pre><span style='mso-spacerun:yes'>                                               </span><span
445class=GramE>emphasis</span> is None):</pre><pre><span style='mso-spacerun:yes'>                </span><span
446class=GramE>raise</span> <span class=SpellE>ValueError</span>(&quot;I don't think so&quot;)</pre><pre><span style='mso-spacerun:yes'>            </span><span
447class=SpellE>Blob.__init</span>_<span class=GramE>_(</span>self, width, height,</pre><pre><span style='mso-spacerun:yes'>                          </span><span
448class=SpellE>color</span>, emphasis, highlight)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span>Blank Lines</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Separate top-level function and class definitions with two blank</pre><pre><span style='mso-spacerun:yes'>    </span><span
449class=GramE>lines</span>.<span style='mso-spacerun:yes'>  </span>Method definitions inside a class are separated by a</pre><pre><span style='mso-spacerun:yes'>    </span><span
450class=GramE>single</span> blank line.<span style='mso-spacerun:yes'>  </span>Extra blank lines may be used (<s>sparingly</s> <i
451style='mso-bidi-font-style:normal'><span style='color:blue'>liberally</span></i>) to</pre><pre><span style='mso-spacerun:yes'>    </span><span
452class=GramE>separate</span> groups of related functions.<span style='mso-spacerun:yes'>  </span>Blank lines may be omitted</pre><pre><span style='mso-spacerun:yes'>    </span><span
453class=GramE>between</span> a bunch of related one-liners (e.g. a set of dummy</pre><pre><span style='mso-spacerun:yes'>    </span><span
454class=GramE>implementations</span>).</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>When blank lines are used to separate method definitions, there is</pre><pre><span style='mso-spacerun:yes'>    </span><span
455class=GramE>also</span> a blank line between the `class' line and the first method</pre><pre><span style='mso-spacerun:yes'>    </span><span
456class=GramE>definition</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>   </span><span style='mso-spacerun:yes'> </span>Use blank lines in functions, <s>sparingly</s> <i
457style='mso-bidi-font-style:normal'><span style='color:blue'>liberally</span></i>, to indicate logical</pre><pre><span style='mso-spacerun:yes'>    </span><span
458class=GramE>sections</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Python accepts the control-L (i.e. ^L) form feed character as</pre><pre><span style='mso-spacerun:yes'>    </span><span
459class=SpellE>whitespace</span>; <span class=SpellE>Emacs</span> (and some printing tools) treat these</pre><pre><span style='mso-spacerun:yes'>    </span><span
460class=GramE>characters</span> as page separators, so you may use them to separate</pre><pre><span style='mso-spacerun:yes'>    </span><span
461class=GramE>pages</span> of related sections of your file.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span>Encodings (<a
462href="http://www.python.org/peps/pep-0263.html">PEP 263</a>)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Code in the core Python distribution should <span
463class=SpellE>aways</span> use the ASCII or</pre><pre><span style='mso-spacerun:yes'>    </span><span
464class=GramE>Latin-1 encoding (a.k.a. ISO-8859-1).</span><span style='mso-spacerun:yes'>  </span>Files using ASCII should</pre><pre><span style='mso-spacerun:yes'>    </span><span
465class=GramE>not</span> have a coding cookie.<span style='mso-spacerun:yes'>  </span>Latin-1 should only be used when a</pre><pre><span style='mso-spacerun:yes'>    </span><span
466class=GramE>comment</span> or <span class=SpellE>docstring</span> needs to mention an author name that requires</pre><pre><span style='mso-spacerun:yes'>    </span>Latin-1; otherwise, using \x escapes is the preferred way to</pre><pre><span style='mso-spacerun:yes'>    </span><span
467class=GramE>include</span> non-ASCII data in string literals.<span style='mso-spacerun:yes'>  </span>An exception is made</pre><pre><span style='mso-spacerun:yes'>    </span><span
468class=GramE>for</span> those files that are part of the test suite for the code</pre><pre><span style='mso-spacerun:yes'>    </span><span
469class=GramE>implementing</span> <a
470href="http://www.python.org/peps/pep-0263.html">PEP 263</a>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
471
472<h3>Imports</h3>
473
474<pre><span style='mso-spacerun:yes'>    </span>- Imports should usually be on separate lines, e.g.:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span>No:<span style='mso-spacerun:yes'>  </span>import sys, <span
475class=SpellE>os</span></pre><pre><span style='mso-spacerun:yes'>        </span>Yes: import sys</pre><pre><span style='mso-spacerun:yes'>             </span><span
476class=GramE>import</span> <span class=SpellE>os</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span><span
477class=GramE>it's</span> okay to say this though:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
478class=GramE>from</span> types import <span class=SpellE>StringType</span>, <span
479class=SpellE>ListType</span></pre><pre><o:p>&nbsp;</o:p></pre><pre
480style='margin-left:42.0pt;text-indent:-18.0pt;mso-list:l0 level1 lfo2'><![if !supportLists]><span
481style='mso-fareast-font-family:"Courier New"'><span style='mso-list:Ignore'>-<span
482style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp; </span></span></span><![endif]><span style='mso-spacerun:yes'> </span>Imports are always put at the top of the file (<i
483style='mso-bidi-font-style:normal'><span style='color:blue'>or top of <o:p></o:p></span></i></pre><pre
484style='margin-left:24.0pt'><i style='mso-bidi-font-style:normal'><span
485style='color:blue'><span style='mso-spacerun:yes'>  </span><span class=GramE>the</span> function/method/class in cases where the import is optional <o:p></o:p></span></i></pre><pre
486style='margin-left:24.0pt'><i style='mso-bidi-font-style:normal'><span
487style='color:blue'><span style='mso-spacerun:yes'>  </span><span class=GramE>or</span> very slow to load</span></i>), just after any module comments and <span
488class=SpellE>docstrings</span>, </pre><pre style='margin-left:24.0pt'><i
489style='mso-bidi-font-style:normal'><span style='color:blue'><span style='mso-spacerun:yes'>  </span></span></i><span
490class=GramE>and</span> before module <span class=SpellE>globals</span> and constants.<span style='mso-spacerun:yes'>  </span>Imports should be grouped, </pre><pre
491style='margin-left:24.0pt'><span style='mso-spacerun:yes'>  </span><span
492class=GramE>with</span> the order being</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>1. <span
493class=GramE>standard</span> library imports</pre><pre><span style='mso-spacerun:yes'>      </span>2. <span
494class=GramE>related</span> major package imports (i.e. all email package imports next)</pre><pre><span style='mso-spacerun:yes'>      </span>3. <span
495class=GramE>application</span> specific imports</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>You should put a blank line between each group of imports.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Relative imports for intra-package imports are highly</pre><pre><span style='mso-spacerun:yes'>      </span><span
496class=GramE>discouraged</span>.<span style='mso-spacerun:yes'>  </span>Always use the absolute package path for all</pre><pre><span style='mso-spacerun:yes'>      </span><span
497class=GramE>imports</span>. <i style='mso-bidi-font-style:normal'><span
498style='color:blue'>Package imports should be relative to a directory on the PYTHONPATH.</span></i> </pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- When importing a class from a class-containing module, it's usually</pre><pre><span style='mso-spacerun:yes'>      </span><span
499class=GramE>okay</span> to spell this</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
500class=GramE>from</span> <span class=SpellE>MyClass</span> import <span
501class=SpellE>MyClass</span></pre><pre><span style='mso-spacerun:yes'>        </span><span
502class=GramE>from</span> <span class=SpellE>foo.bar.YourClass</span> import <span
503class=SpellE>YourClass</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>If this spelling causes local name clashes, then spell them</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
504class=GramE>import</span> <span class=SpellE>MyClass</span></pre><pre><span style='mso-spacerun:yes'>        </span><span
505class=GramE>import</span> <span class=SpellE>foo.bar.YourClass</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span><span
506class=GramE>and</span> use &quot;<span class=SpellE>MyClass.MyClass</span>&quot; and &quot;<span
507class=SpellE>foo.bar.YourClass.YourClass</span>&quot;</pre><pre><span
508style='mso-tab-count:1'>      </span></pre><pre style='margin-left:24.0pt'><span
509style='mso-tab-count:1'>  </span><i style='mso-bidi-font-style:normal'><span
510style='color:blue'>Using import * is discouraged except for special cases like <o:p></o:p></span></i></pre><pre
511style='margin-left:24.0pt'><i style='mso-bidi-font-style:normal'><span
512style='color:blue'><span style='mso-spacerun:yes'>  </span><span class=GramE>unit</span> testing where only one module is imported. The reason <o:p></o:p></span></i></pre><pre
513style='margin-left:24.0pt'><i style='mso-bidi-font-style:normal'><span
514style='color:blue'><span style='mso-spacerun:yes'>  </span><span class=GramE>being</span> that multiple * imports obscures the origin of individual <o:p></o:p></span></i></pre><pre
515style='margin-left:24.0pt'><i style='mso-bidi-font-style:normal'><span
516style='color:blue'><span style='mso-spacerun:yes'>  </span><span class=GramE>objects</span> making debugging much harder.<span style='mso-spacerun:yes'>  </span><o:p></o:p></span></i></pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
517
518<h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'><span
519class=SpellE>Whitespace</span> in Expressions and Statements</h3>
520
521<pre><span style='mso-spacerun:yes'>  </span>Pet Peeves</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Guido hates <span
522class=SpellE>whitespace</span> in the following places:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Immediately inside parentheses, brackets or braces, as in:</pre><pre><span style='mso-spacerun:yes'>      </span>&quot;<span
523class=GramE>spam(</span> ham[ 1 ], { eggs: 2 } )&quot;.<span style='mso-spacerun:yes'>  </span>Always write this as</pre><pre><span style='mso-spacerun:yes'>      </span>&quot;<span
524class=GramE>spam(</span>ham[1], {eggs: 2})&quot;.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Immediately before a comma, semicolon, or colon, as in:</pre><pre><span style='mso-spacerun:yes'>      </span>&quot;<span
525class=GramE>if</span> x == 4 : print x , y ; x , y = y , x&quot;.<span style='mso-spacerun:yes'>  </span>Always write this as</pre><pre><span style='mso-spacerun:yes'>      </span>&quot;<span
526class=GramE>if</span> x == 4: print x, y; x, y = y, x&quot;.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Immediately before the open parenthesis that starts the argument</pre><pre><span style='mso-spacerun:yes'>      </span><span
527class=GramE>list</span> of a function call, as in &quot;spam (1)&quot;.<span style='mso-spacerun:yes'>  </span>Always write</pre><pre><span style='mso-spacerun:yes'>      </span><span
528class=GramE>this</span> as &quot;spam(1)&quot;.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Immediately before the open parenthesis that starts an indexing or</pre><pre><span style='mso-spacerun:yes'>      </span><span
529class=GramE>slicing</span>, as in: &quot;<span class=SpellE>dict</span> ['key'] = list [index]&quot;.<span style='mso-spacerun:yes'>  </span>Always</pre><pre><span style='mso-spacerun:yes'>      </span><span
530class=GramE>write</span> this as &quot;<span class=SpellE>dict</span>['key'] = list[index]&quot;.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- More than one space around an assignment (or other) operator to</pre><pre><span style='mso-spacerun:yes'>      </span><span
531class=GramE>align</span> it with another, as in:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>          </span>x<span style='mso-spacerun:yes'>             </span>= 1</pre><pre><span style='mso-spacerun:yes'>          </span>y<span style='mso-spacerun:yes'>             </span>= 2</pre><pre><span style='mso-spacerun:yes'>          </span><span
532class=SpellE>long_variable</span> = 3</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Always write this as</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span><span style='mso-spacerun:yes'>      </span>x = 1</pre><pre><span style='mso-spacerun:yes'>          </span>y = 2</pre><pre><span style='mso-spacerun:yes'>          </span><span
533class=SpellE>long_variable</span> = 3</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>(Don't bother to argue with him on any of the above -- Guido's</pre><pre><span style='mso-spacerun:yes'>    </span><span
534class=GramE>grown</span> accustomed to this style over 20 years.)</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span>Other Recommendations</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Always surround these binary operators with a single space on</pre><pre><span style='mso-spacerun:yes'>      </span><span
535class=GramE>either</span> side: assignment (=), comparisons (==, &lt;, &gt;, !=, &lt;&gt;, &lt;=,</pre><pre><span style='mso-spacerun:yes'>      </span>&gt;=, in, not in, is, is not), Booleans (and, or, not).</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Use your better judgment for the insertion of spaces around</pre><pre><span style='mso-spacerun:yes'>      </span><span
536class=GramE>arithmetic</span> operators.<span style='mso-spacerun:yes'>  </span>Always be consistent about <span
537class=SpellE>whitespace</span> on</pre><pre><span style='mso-spacerun:yes'>      </span><span
538class=GramE>either</span> side of a binary operator.<span style='mso-spacerun:yes'>  </span>Some examples:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>          </span><span
539class=SpellE>i</span> = i+1</pre><pre><span style='mso-spacerun:yes'>          </span><span
540class=GramE>submitted</span> = submitted + 1</pre><pre><span style='mso-spacerun:yes'>          </span>x = x*2 - 1</pre><pre><span style='mso-spacerun:yes'>          </span>hypot2 = x*x + y*y</pre><pre><span style='mso-spacerun:yes'>          </span>c = (<span
541class=SpellE>a+b</span>) * (a-b)</pre><pre><span style='mso-spacerun:yes'>          </span>c = (a + b) * (a - b)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Don't use spaces around the '=' sign when used to indicate a</pre><pre><span style='mso-spacerun:yes'>      </span><span
542class=GramE>keyword</span> argument or a default parameter value.<span style='mso-spacerun:yes'>  </span>For instance:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>          </span><span
543class=GramE>def</span> complex(real, <span class=SpellE>imag</span>=0.0):</pre><pre><span style='mso-spacerun:yes'>              </span><span
544class=GramE>return</span> magic(r=real, <span class=SpellE>i</span>=<span
545class=SpellE>imag</span>)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Compound statements (multiple statements on the same line) are</pre><pre><span style='mso-spacerun:yes'>      </span><span
546class=GramE>generally</span> discouraged.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>          </span>No:<span style='mso-spacerun:yes'>  </span>if <span
547class=SpellE>foo</span> == 'blah': <span class=SpellE>do_blah_<span
548class=GramE>thing</span></span><span class=GramE>()</span></pre><pre><span style='mso-spacerun:yes'>          </span>Yes: if <span
549class=SpellE>foo</span> == 'blah':</pre><pre><span style='mso-spacerun:yes'>                   </span><span
550class=SpellE>do_blah_<span class=GramE>thing</span></span><span class=GramE>()</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>          </span>No:<span style='mso-spacerun:yes'>  </span><span
551class=SpellE>do_<span class=GramE>one</span></span><span class=GramE>(</span>); <span
552class=SpellE>do_two</span>(); <span class=SpellE>do_three</span>()</pre><pre><span style='mso-spacerun:yes'>          </span>Yes: <span
553class=SpellE>do_<span class=GramE>one</span></span><span class=GramE>()</span></pre><pre><span style='mso-spacerun:yes'>               </span><span
554class=SpellE>do_<span class=GramE>two</span></span><span class=GramE>()</span></pre><pre><span style='mso-spacerun:yes'>               </span><span
555class=SpellE>do_<span class=GramE>three</span></span><span class=GramE>()</span></pre><pre><o:p>&nbsp;</o:p></pre>
556
557<h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'>Comments</h3>
558
559<pre><span style='mso-spacerun:yes'>    </span>Comments that contradict the code are worse than no comments.</pre><pre><span style='mso-spacerun:yes'>    </span>Always make a priority of keeping the comments up-to-date when the</pre><pre><span style='mso-spacerun:yes'>    </span><span
560class=GramE>code</span> changes!</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Comments should be complete sentences.<span style='mso-spacerun:yes'>  </span>If a comment is a phrase</pre><pre><span style='mso-spacerun:yes'>    </span><span
561class=GramE>or</span> sentence, its first word should be capitalized, unless it is an</pre><pre><span style='mso-spacerun:yes'>    </span><span
562class=GramE>identifier</span> that begins with a lower case letter (never alter the</pre><pre><span style='mso-spacerun:yes'>    </span><span
563class=GramE>case</span> of identifiers!).</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>If a comment is short, the period at the end is best omitted.</pre><pre><span style='mso-spacerun:yes'>    </span>Block comments generally consist of one or more paragraphs built</pre><pre><span style='mso-spacerun:yes'>    </span><span
564class=GramE>out</span> of complete sentences, and each sentence should end in a</pre><pre><span style='mso-spacerun:yes'>    </span><span
565class=GramE>period</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>You should use two spaces after a sentence-ending period, since it</pre><pre><span style='mso-spacerun:yes'>    </span><span
566class=GramE>makes</span> <span class=SpellE>Emacs</span> wrapping and filling work <span
567class=SpellE>consistenty</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>When writing English, <span
568class=SpellE>Strunk</span> and White apply.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Python coders from non-English speaking countries: please write</pre><pre><span style='mso-spacerun:yes'>    </span><span
569class=GramE>your</span> comments in English, unless you are 120% sure that the code</pre><pre><span style='mso-spacerun:yes'>    </span><span
570class=GramE>will</span> never be read by people who don't speak your language.</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span>Block Comments</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Block comments generally apply to some (or all) code that follows</pre><pre><span style='mso-spacerun:yes'>    </span><span
571class=GramE>them</span>, and are indented to the same level as that code.<span style='mso-spacerun:yes'>  </span>Each line</pre><pre><span style='mso-spacerun:yes'>    </span><span
572class=GramE>of</span> a block comment starts with a # and a single space (unless it</pre><pre><span style='mso-spacerun:yes'>    </span><span
573class=GramE>is</span> indented text inside the comment).<span style='mso-spacerun:yes'>  </span>Paragraphs inside a block</pre><pre><span style='mso-spacerun:yes'>    </span><span
574class=GramE>comment</span> are separated by a line containing a single #.<span style='mso-spacerun:yes'>  </span>Block</pre><pre><span style='mso-spacerun:yes'>    </span><span
575class=GramE>comments</span> are best surrounded by a blank line above and below them</pre><pre><span style='mso-spacerun:yes'>    </span>(<span
576class=GramE>or</span> two lines above and a single line below for a block comment at</pre><pre><span style='mso-spacerun:yes'>    </span><span
577class=GramE>the</span> start of a <span class=SpellE>a</span> new section of function definitions <i
578style='mso-bidi-font-style:normal'><span style='color:blue'>or to delimit <o:p></o:p></span></i></pre><pre><i
579style='mso-bidi-font-style:normal'><span style='color:blue'><span style='mso-spacerun:yes'>    </span><span
580class=GramE>logical</span> sections</span></i>).</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span>Inline Comments</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>An inline comment is a comment on the same line as a statement.</pre><pre><span style='mso-spacerun:yes'>    </span>Inline comments should be used sparingly.<span style='mso-spacerun:yes'>  </span>Inline comments should</pre><pre><span style='mso-spacerun:yes'>    </span><span
581class=GramE>be</span> separated by at least two spaces from the statement.<span style='mso-spacerun:yes'>  </span>They</pre><pre><span style='mso-spacerun:yes'>    </span><span
582class=GramE>should</span> start with a # and a single space.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Inline comments are unnecessary and in fact distracting if they state</pre><pre><span style='mso-spacerun:yes'>    </span><span
583class=GramE>the</span> obvious.<span style='mso-spacerun:yes'>  </span>Don't do this:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span>x = x+1<span style='mso-spacerun:yes'>                 </span># Increment x</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>But sometimes, this is useful:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span>x = x+1<span style='mso-spacerun:yes'>                 </span># Compensate for border</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span>Developer Comments</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>If software is being created in a multi-developer environment, it is often</pre><pre><span style='mso-spacerun:yes'>    </span><span
584class=GramE>useful</span> to comment the code to indicate those sections which require updating </pre><pre><span style='mso-spacerun:yes'>    </span><span
585class=GramE>or</span> refining. They should start with #FIXME followed by the name of the </pre><pre><span style='mso-spacerun:yes'>    </span><span
586class=GramE>developer</span> in standard brackets. The name should be consistent amongst the</pre><pre><span style='mso-spacerun:yes'>    </span><span
587class=GramE>group</span>; either full initials, first name or surname. For example, if </pre><pre><span style='mso-spacerun:yes'>    </span>Duncan S Gray found an issue, he could insert in the code:</pre><pre><o:p>&nbsp;</o:p></pre><pre
588style='margin-top:0cm;margin-right:12.0pt;margin-bottom:0cm;margin-left:12.0pt;
589margin-bottom:.0001pt'><span style='mso-spacerun:yes'>    </span>#FIXME (DSG): Should check that function returns something sensible and<o:p></o:p></pre><pre> <span style='mso-spacerun:yes'>     </span>#<span
590class=GramE>raise</span> a meaningful exception if it returns None for example</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>This allows other developers to identify areas which require attention with </pre><pre><span style='mso-spacerun:yes'>    </span><span
591class=GramE>the</span> added bonus of knowing who logged the issue.</pre><pre><o:p>&nbsp;</o:p></pre>
592
593<h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'>Documentation
594Strings</h3>
595
596<pre><span style='mso-spacerun:yes'>    </span>Conventions for writing good documentation strings</pre><pre><span style='mso-spacerun:yes'>    </span>(a.k.a. &quot;<span
597class=SpellE>docstrings</span>&quot;) are immortalized in <a
598href="http://www.python.org/peps/pep-0257.html">PEP 257</a> [3].</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Write <span
599class=SpellE>docstrings</span> for all public modules, functions, classes, and</pre><pre><span style='mso-spacerun:yes'>      </span><span
600class=GramE>methods</span>.<span style='mso-spacerun:yes'>  </span><span
601class=SpellE>Docstrings</span> are not necessary for non-public methods,</pre><pre><span style='mso-spacerun:yes'>      </span><span
602class=GramE>but</span> you should have a comment that describes what the method</pre><pre><span style='mso-spacerun:yes'>      </span><span
603class=GramE>does</span>.<span style='mso-spacerun:yes'>  </span>This comment should appear after the &quot;def&quot; line.</pre><pre><span
604style='mso-tab-count:1'>      </span><i style='mso-bidi-font-style:normal'><span
605style='color:blue'>Ideally, all modules, functions, classes, and methods should have <o:p></o:p></span></i></pre><pre><i
606style='mso-bidi-font-style:normal'><span style='color:blue'><span style='mso-spacerun:yes'>      </span><span
607class=GramE>a</span> <span class=SpellE>docstring</span>.<o:p></o:p></span></i></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <a
608href="http://www.python.org/peps/pep-0257.html">PEP 257</a> describes good <span
609class=SpellE>docstring</span> conventions.<span style='mso-spacerun:yes'>  </span>Note that most</pre><pre><span style='mso-spacerun:yes'>      </span><span
610class=GramE>importantly</span>, the &quot;&quot;&quot; that ends a <span
611class=SpellE>multiline</span> <span class=SpellE>docstring</span> should be</pre><pre><span style='mso-spacerun:yes'>      </span><span
612class=GramE>on</span> a line by itself, e.g.:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>&quot;&quot;&quot;Return a <span
613class=SpellE>foobang</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Optional <span
614class=SpellE>plotz</span> says to <span class=SpellE>frobnicate</span> the <span
615class=SpellE>bizbaz</span> first.</pre><pre><span style='mso-spacerun:yes'>   </span><span style='mso-spacerun:yes'>   </span>&quot;&quot;&quot;</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- For one liner <span
616class=SpellE>docstrings</span>, it's okay to keep the closing &quot;&quot;&quot; on</pre><pre><span style='mso-spacerun:yes'>      </span><span
617class=GramE>the</span> same line.</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
618
619<h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'>Version
620Bookkeeping</h3>
621
622<pre><span style='mso-spacerun:yes'>    </span>If you have to have RCS or CVS crud in your source file, do it as</pre><pre><span style='mso-spacerun:yes'>    </span><span
623class=GramE>follows</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span>__version__ = &quot;$Revision: 1.27 $&quot;</pre><pre><span style='mso-spacerun:yes'>        </span># $Source: /cvsroot/python/python/nondist/peps/pep-0008.txt,v $</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>These lines should be included after the module's <span
624class=SpellE>docstring</span>,</pre><pre><span style='mso-spacerun:yes'>    </span><span
625class=GramE>before</span> any other code, separated by a blank line above and</pre><pre><span style='mso-spacerun:yes'>    </span><span
626class=GramE>below</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
627
628<h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'>Naming
629Conventions</h3>
630
631<pre><span style='mso-spacerun:yes'>    </span>The naming conventions of Python's library are a bit of a mess, so we'll</pre><pre><span style='mso-spacerun:yes'>    </span><span
632class=GramE>never</span> get this completely consistent -- nevertheless, here are the</pre><pre><span style='mso-spacerun:yes'>    </span><span
633class=GramE>currently</span> recommended naming standards.<span style='mso-spacerun:yes'>  </span>New modules and packages</pre><pre><span style='mso-spacerun:yes'>    </span>(<span
634class=GramE>including</span> 3rd party frameworks) should be written to these standards, but</pre><pre><span style='mso-spacerun:yes'>    </span><span
635class=GramE>where</span> an existing library has a different style, internal consistency is</pre><pre><span style='mso-spacerun:yes'>    </span><span
636class=GramE>preferred</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span>Descriptive: Naming Styles</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>There are a lot of different naming styles.<span style='mso-spacerun:yes'>  </span>It helps to be able</pre><pre><span style='mso-spacerun:yes'>    </span><span
637class=GramE>to</span> recognize what naming style is being used, independently from</pre><pre><span style='mso-spacerun:yes'>    </span><span
638class=GramE>what</span> they are used for.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>The following naming styles are commonly distinguished:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <span
639class=GramE>b</span> (single lowercase letter)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- B (single uppercase letter)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <span
640class=GramE>lowercase</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <span
641class=SpellE>lower_case_with_underscores</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- UPPERCASE</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- UPPER_CASE_WITH_UNDERSCORES</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <span
642class=SpellE>CapitalizedWords</span> (or <span class=SpellE>CapWords</span>, or <span
643class=SpellE>CamelCase</span> -- so named because</pre><pre><span style='mso-spacerun:yes'>      </span><span
644class=GramE>of</span> the bumpy look of its letters[4]).<span style='mso-spacerun:yes'>  </span>This is also sometimes known as</pre><pre><span style='mso-spacerun:yes'>      </span><span
645class=SpellE><span class=GramE>StudlyCaps</span></span><span class=GramE>.</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <span
646class=SpellE>mixedCase</span> (differs from <span class=SpellE>CapitalizedWords</span> by initial lowercase</pre><pre><span style='mso-spacerun:yes'>      </span><span
647class=GramE>character</span>!)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <span
648class=SpellE>Capitalized_Words_With_Underscores</span> (ugly!)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>There's also the style of using a short unique prefix to group</pre><pre><span style='mso-spacerun:yes'>    </span><span
649class=GramE>related</span> names together.<span style='mso-spacerun:yes'>  </span>This is not used much in Python, but it</pre><pre><span style='mso-spacerun:yes'>   </span><span style='mso-spacerun:yes'> </span><span
650class=GramE>is</span> mentioned for completeness.<span style='mso-spacerun:yes'>  </span>For example, the <span
651class=SpellE><span class=GramE>os.stat</span></span><span class=GramE>()</span></pre><pre><span style='mso-spacerun:yes'>    </span><span
652class=GramE>function</span> returns a <span class=SpellE>tuple</span> whose items traditionally have names like</pre><pre><span style='mso-spacerun:yes'>    </span><span
653class=SpellE><span class=GramE>st_mode</span></span><span class=GramE>, <span
654class=SpellE>st_size</span>, <span class=SpellE>st_mtime</span> and so on.</span><span style='mso-spacerun:yes'>  </span>The X11 library uses a</pre><pre><span style='mso-spacerun:yes'>    </span><span
655class=GramE>leading</span> X for all its public functions.<span style='mso-spacerun:yes'>  </span>(In Python, this style is</pre><pre><span style='mso-spacerun:yes'>    </span><span
656class=GramE>generally</span> deemed unnecessary because attribute and method names</pre><pre><span style='mso-spacerun:yes'>    </span><span
657class=GramE>are</span> prefixed with an object, and function names are prefixed with</pre><pre><span style='mso-spacerun:yes'>    </span><span
658class=GramE>a</span> module name.)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>In addition, the following special forms using leading or trailing</pre><pre><span style='mso-spacerun:yes'>    </span><span
659class=GramE>underscores</span> are recognized (these can generally be combined with any</pre><pre><span style='mso-spacerun:yes'>    </span><span
660class=GramE>case</span> convention):</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- _<span
661class=SpellE>single_leading_underscore</span>: weak &quot;internal use&quot; indicator</pre><pre><span style='mso-spacerun:yes'>      </span>(e.g. &quot;from M import *&quot; does not import objects whose name</pre><pre><span style='mso-spacerun:yes'>      </span><span
662class=GramE>starts</span> with an underscore).</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <span
663class=SpellE>single_trailing_underscore</span>_: used by convention to avoid</pre><pre><span style='mso-spacerun:yes'>      </span><span
664class=GramE>conflicts</span> with Python keyword, e.g.</pre><pre><span style='mso-spacerun:yes'>      </span>&quot;<span
665class=SpellE><span class=GramE>Tkinter.Toplevel</span></span><span class=GramE>(</span>master, class_='<span
666class=SpellE>ClassName</span>')&quot;.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span><span
667class=GramE>- __<span class=SpellE>double_leading_underscore</span>: class-private names as of Python 1.4.</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- __<span
668class=SpellE>double_leading_and_trailing_underscore</span>__: &quot;magic&quot; objects or</pre><pre><span style='mso-spacerun:yes'>      </span><span
669class=GramE>attributes</span> that live in user-controlled namespaces,</pre><pre><span style='mso-spacerun:yes'>      </span><span
670class=GramE>e.g. __init__, __import__ or __file__.</span><span style='mso-spacerun:yes'>  </span>Sometimes these are</pre><pre><span style='mso-spacerun:yes'>      </span><span
671class=GramE>defined</span> by the user to trigger certain magic <span
672class=SpellE>behavior</span></pre><pre><span style='mso-spacerun:yes'>      </span>(<span
673class=GramE>e.g</span>. operator overloading); sometimes these are inserted by the</pre><pre><span style='mso-spacerun:yes'>      </span><span
674class=GramE>infrastructure</span> for its own use or for debugging purposes.<span style='mso-spacerun:yes'>  </span>Since</pre><pre><span style='mso-spacerun:yes'>      </span><span
675class=GramE>the</span> infrastructure (loosely defined as the Python interpreter</pre><pre><span style='mso-spacerun:yes'>      </span><span
676class=GramE>and</span> the standard library) may decide to grow its list of magic</pre><pre><span style='mso-spacerun:yes'>      </span><span
677class=GramE>attributes</span> in future versions, user code should generally</pre><pre><span style='mso-spacerun:yes'>      </span><span
678class=GramE>refrain</span> from using this convention for its own use.<span style='mso-spacerun:yes'>  </span>User code</pre><pre><span style='mso-spacerun:yes'>      </span><span
679class=GramE>that</span> aspires to become part of the infrastructure could combine</pre><pre><span style='mso-spacerun:yes'>      </span><span
680class=GramE>this</span> with a short prefix inside the underscores,</pre><pre><span style='mso-spacerun:yes'>      </span><span
681class=GramE>e.g. __<span class=SpellE>bobo_magic_attr</span>__.</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span>Prescriptive: Naming Conventions</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Names to Avoid</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Never use the characters `l' (lowercase letter el), `O'</pre><pre><span style='mso-spacerun:yes'>      </span>(<span
682class=GramE>uppercase</span> letter oh), or `I' (uppercase letter eye) as single</pre><pre><span style='mso-spacerun:yes'>      </span><span
683class=GramE>character</span> variable names.<span style='mso-spacerun:yes'>  </span>In some fonts, these characters are</pre><pre><span style='mso-spacerun:yes'>      </span><span
684class=SpellE>indistinguisable</span> from the numerals one and zero.<span style='mso-spacerun:yes'>  </span>When tempted</pre><pre
685style='margin-left:12.0pt'><span style='mso-spacerun:yes'>    </span><span
686class=GramE>to</span> use `l' use `L' instead, <i style='mso-bidi-font-style:
687normal'><span style='color:blue'>unless the mathematical formula <o:p></o:p></span></i></pre><pre
688style='margin-left:12.0pt'><i style='mso-bidi-font-style:normal'><span
689style='color:blue'><span style='mso-spacerun:yes'>    </span><span class=GramE>using</span> l would become harder to understand</span></i>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Module Names</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Modules should have short, lowercase names, <s>without</s> <i
690style='mso-bidi-font-style:normal'><span style='color:blue'>possibly with</span></i> </pre><pre><span style='mso-spacerun:yes'>      </span><span
691class=GramE>underscores</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Since module names are mapped to file names, and some file systems</pre><pre><span style='mso-spacerun:yes'>      </span><span
692class=GramE>are</span> case insensitive and truncate long names, it is important that</pre><pre><span style='mso-spacerun:yes'>      </span><span
693class=GramE>module</span> names be chosen to be fairly short -- this won't be a</pre><pre><span style='mso-spacerun:yes'>      </span><span
694class=GramE>problem</span> on Unix, but it may be a problem when the code is</pre><pre><span style='mso-spacerun:yes'>      </span><span
695class=GramE>transported</span> to Mac or Windows.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>When an extension module written in C or C++ has an accompanying</pre><pre><span style='mso-spacerun:yes'>      </span>Python module that provides a higher level (e.g. more object</pre><pre><span style='mso-spacerun:yes'>      </span><span
696class=GramE>oriented</span>) interface, the C/C++ module has a leading underscore</pre><pre><span style='mso-spacerun:yes'>      </span><span
697class=GramE>(e.g. _socket).</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Python packages should have short, all-lowercase names, <s>without</s> </pre><pre><span style='mso-spacerun:yes'>      </span><span
698class=GramE><i style='mso-bidi-font-style:normal'><span style='color:blue'>possibly</span></i></span><i
699style='mso-bidi-font-style:normal'><span style='color:blue'> with</span></i> underscores.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Class Names</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span><span style='mso-spacerun:yes'>  </span>Almost without exception, class names use the <span
700class=SpellE>CapWords</span> convention.</pre><pre><span style='mso-spacerun:yes'>      </span>Classes for internal use have a leading underscore in addition.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Exception Names</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>If a module defines a single exception raised for all sorts of</pre><pre><span style='mso-spacerun:yes'>      </span><span
701class=GramE>conditions</span>, it is generally called &quot;error&quot; or &quot;Error&quot;.<span style='mso-spacerun:yes'>  </span>It seems</pre><pre><span style='mso-spacerun:yes'>      </span><span
702class=GramE>that</span> built-in (extension) modules use &quot;error&quot; (e.g. <span
703class=SpellE>os.error</span>),</pre><pre><span style='mso-spacerun:yes'>      </span><span
704class=GramE>while</span> Python modules generally use &quot;Error&quot; (e.g. <span
705class=SpellE>xdrlib.Error</span>).</pre><pre><span style='mso-spacerun:yes'>      </span>The trend seems to be toward <span
706class=SpellE>CapWords</span> exception names.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Global Variable Names</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>(Let's hope that these variables are meant for use inside one</pre><pre><span style='mso-spacerun:yes'>      </span><span
707class=GramE>module</span> only.)<span style='mso-spacerun:yes'>  </span>The conventions are about the same as those for</pre><pre><span style='mso-spacerun:yes'>      </span><span
708class=GramE>functions</span>.<span style='mso-spacerun:yes'>  </span>Modules that are designed for use via &quot;from M import *&quot;</pre><pre><span style='mso-spacerun:yes'>      </span><span
709class=GramE>should</span> prefix their <span class=SpellE>globals</span> (and internal functions and classes)</pre><pre><span style='mso-spacerun:yes'>      </span><span
710class=GramE>with</span> an underscore to prevent exporting them.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Function Names</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Function names should be lowercase, possibly with words separated by</pre><pre><span style='mso-spacerun:yes'>      </span><span
711class=GramE>underscores</span> to improve readability.<span style='mso-spacerun:yes'>  </span><span
712class=SpellE>mixedCase</span> is allowed only in</pre><pre><span style='mso-spacerun:yes'>      </span><span
713class=GramE>contexts</span> where that's already the prevailing style (e.g. <span
714class=SpellE>threading.py</span>),</pre><pre><span style='mso-spacerun:yes'>      </span><span
715class=GramE>to</span> retain backwards compatibility.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Method Names and Instance Variables</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>The story is largely the same as with functions: in general, use</pre><pre><span style='mso-spacerun:yes'>      </span><span
716class=GramE>lowercase</span> with words separated by underscores as necessary to improve</pre><pre><span style='mso-spacerun:yes'>      </span><span
717class=GramE>readability</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Use one leading underscore only for internal methods and instance</pre><pre><span style='mso-spacerun:yes'>      </span><span
718class=GramE>variables</span> which are not intended to be part of the class's public</pre><pre><span style='mso-spacerun:yes'>      </span><span
719class=GramE>interface</span>.<span style='mso-spacerun:yes'>  </span>Python does not enforce this; it is up to programmers to</pre><pre><span style='mso-spacerun:yes'>      </span><span
720class=GramE>respect</span> the convention.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Use two leading underscores to denote class-private names.<span style='mso-spacerun:yes'>  </span>Python</pre><pre><span style='mso-spacerun:yes'>      </span>&quot;<span
721class=GramE>mangles</span>&quot; these names with the class name: if class <span
722class=SpellE>Foo</span> has an</pre><pre><span style='mso-spacerun:yes'>      </span><span
723class=GramE>attribute</span> named __a, it cannot be accessed by <span
724class=SpellE>Foo.__a</span>.<span style='mso-spacerun:yes'>  </span>(An insistent</pre><pre><span style='mso-spacerun:yes'>      </span><span
725class=GramE>user</span> could still gain access by calling <span class=SpellE>Foo._Foo__a</span>.)<span style='mso-spacerun:yes'>  </span>Generally,</pre><pre><span style='mso-spacerun:yes'>      </span><span
726class=GramE>double</span> leading underscores should be used only to avoid name conflicts</pre><pre><span style='mso-spacerun:yes'>      </span><span
727class=GramE>with</span> attributes in classes designed to be subclassed.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Designing for inheritance</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Always decide whether a class's methods and instance variables</pre><pre><span style='mso-spacerun:yes'>      </span><span
728class=GramE>should</span> be public or non-public.<span style='mso-spacerun:yes'>  </span>In general, never make data</pre><pre><span style='mso-spacerun:yes'>      </span><span
729class=GramE>variables</span> public unless you're implementing essentially a</pre><pre><span style='mso-spacerun:yes'>      </span><span
730class=GramE>record</span>.<span style='mso-spacerun:yes'>  </span>It's almost always <span
731class=SpellE>preferrable</span> to give a functional</pre><pre><span style='mso-spacerun:yes'>      </span><span
732class=GramE>interface</span> to your class instead (and some Python 2.2</pre><pre><span style='mso-spacerun:yes'>      </span><span
733class=GramE>developments</span> will make this much nicer). <i
734style='mso-bidi-font-style:normal'><span style='color:blue'>Consider using Python’s <o:p></o:p></span></i></pre><pre><i
735style='mso-bidi-font-style:normal'><span style='color:blue'><span style='mso-spacerun:yes'>      </span><span
736class=GramE>properties</span>.<o:p></o:p></span></i></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Also decide whether your attributes should be private or not.</pre><pre><span style='mso-spacerun:yes'>      </span>The difference between private and non-public is that the former</pre><pre><span style='mso-spacerun:yes'>      </span><span
737class=GramE>will</span> never be useful for a derived class, while the latter might</pre><pre><span style='mso-spacerun:yes'>      </span><span
738class=GramE>be</span>.<span style='mso-spacerun:yes'>  </span>Yes, you should design your classes with inheritance in</pre><pre><span style='mso-spacerun:yes'>      </span><span
739class=GramE>mind</span>!</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Private attributes should have two leading underscores, no</pre><pre><span style='mso-spacerun:yes'>      </span><span
740class=GramE>trailing</span> underscores.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Non-public attributes should have a single leading underscore,</pre><pre><span style='mso-spacerun:yes'>      </span><span
741class=GramE>no</span> trailing underscores.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Public attributes should have no leading or trailing</pre><pre><span style='mso-spacerun:yes'>      </span><span
742class=GramE>underscores</span>, unless they conflict with reserved words, in which</pre><pre><span style='mso-spacerun:yes'>      </span><span
743class=GramE>case</span>, a single trailing underscore is preferable to a leading</pre><pre><span style='mso-spacerun:yes'>      </span><span
744class=GramE>one</span>, or a corrupted spelling, e.g. class_ rather than <span
745class=SpellE>klass</span>.</pre><pre><span style='mso-spacerun:yes'>      </span>(This last point is a bit controversial; if you prefer <span
746class=SpellE>klass</span></pre><pre><span style='mso-spacerun:yes'>      </span><span
747class=GramE>over</span> class_ then just be consistent. :).</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
748
749<h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'>Programming
750Recommendations</h3>
751
752<pre><span style='mso-spacerun:yes'>    </span>- Code should be written in a way that does not disadvantage other</pre><pre><span style='mso-spacerun:yes'>      </span><span
753class=GramE>implementations</span> of Python (<span class=SpellE>PyPy</span>, <span
754class=SpellE>Jython</span>, <span class=SpellE>IronPython</span>, Pyrex, <span
755class=SpellE>Psyco</span>,</pre><pre><span style='mso-spacerun:yes'>      </span><span
756class=GramE>and</span> such).<span style='mso-spacerun:yes'>  </span>For example, do not rely on <span
757class=SpellE>CPython's</span> efficient</pre><pre><span style='mso-spacerun:yes'>      </span><span
758class=GramE>implementation</span> of in-place string concatenation for statements in</pre><pre><span style='mso-spacerun:yes'>      </span><span
759class=GramE>the</span> form a+=b or a=<span class=SpellE>a+b</span>.<span style='mso-spacerun:yes'>  </span>Those statements run more slowly in</pre><pre><span style='mso-spacerun:yes'>      </span><span
760class=SpellE><span class=GramE>Jython</span></span><span class=GramE>.</span><span style='mso-spacerun:yes'>  </span>In performance sensitive parts of the library, the</pre><pre><span style='mso-spacerun:yes'>      </span>''.<span
761class=GramE>join(</span>) form should be used instead.<span style='mso-spacerun:yes'>  </span>This will assure that</pre><pre><span style='mso-spacerun:yes'>      </span><span
762class=GramE>concatenation</span> occurs in linear time across various implementations.</pre><pre><span
763style='mso-tab-count:1'>      </span><i style='mso-bidi-font-style:normal'><span
764style='color:blue'>In performance insensitive part it is OK to use the more readable <o:p></o:p></span></i></pre><pre><i
765style='mso-bidi-font-style:normal'><span style='color:blue'><span style='mso-spacerun:yes'>      </span><span
766class=GramE>a</span>+=b and a=<span class=SpellE>a+b</span>. <o:p></o:p></span></i></pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Comparisons to singletons like <span
767class=GramE>None</span> should always be done with</pre><pre><span style='mso-spacerun:yes'>      </span>'<span
768class=GramE>is</span>' or 'is not'.<span style='mso-spacerun:yes'>  </span>Also, beware of writing &quot;if x&quot; when you</pre><pre><span style='mso-spacerun:yes'>      </span><span
769class=GramE>really</span> mean &quot;if x is not None&quot; -- e.g. when testing whether a</pre><pre><span style='mso-spacerun:yes'>      </span><span
770class=GramE>variable</span> or argument that defaults to None was set to some other</pre><pre><span style='mso-spacerun:yes'>      </span><span
771class=GramE>value</span>.<span style='mso-spacerun:yes'>  </span>The other value might be a value that's false in a</pre><pre><span style='mso-spacerun:yes'>      </span>Boolean context!</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Class-based exceptions are always preferred over string-based</pre><pre><span style='mso-spacerun:yes'>      </span><span
772class=GramE>exceptions</span>.<span style='mso-spacerun:yes'>  </span>Modules or packages should define their own</pre><pre><span style='mso-spacerun:yes'>      </span><span
773class=GramE>domain-specific</span> base exception class, which should be subclassed</pre><pre><span style='mso-spacerun:yes'>      </span><span
774class=GramE>from</span> the built-in Exception class.<span style='mso-spacerun:yes'>  </span>Always include a class</pre><pre><span style='mso-spacerun:yes'>      </span><span
775class=SpellE>docstring</span>.<span style='mso-spacerun:yes'>  </span>E.g.:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
776class=GramE>class</span> <span class=SpellE>MessageError</span>(Exception):</pre><pre><span style='mso-spacerun:yes'>            </span><span
777class=GramE>&quot;&quot;&quot;Base class for errors in the email package.&quot;&quot;&quot;</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>When raising an exception, use &quot;raise <span
778class=SpellE><span class=GramE>ValueError</span></span><span class=GramE>(</span>'message')&quot;</pre><pre><span style='mso-spacerun:yes'>      </span><span
779class=GramE>instead</span> of the older form &quot;raise <span class=SpellE>ValueError</span>, 'message'&quot;.<span style='mso-spacerun:yes'>  </span>The</pre><pre><span style='mso-spacerun:yes'>      </span><span
780class=SpellE><span class=GramE>paren</span></span><span class=GramE>-using</span> form is preferred because when the exception</pre><pre><span style='mso-spacerun:yes'>      </span><span
781class=GramE>arguments</span> are long or include string formatting, you don't need</pre><pre><span style='mso-spacerun:yes'>      </span><span
782class=GramE>to</span> use line continuation characters thanks to the containing</pre><pre><span style='mso-spacerun:yes'>      </span><span
783class=GramE>parentheses</span>.<span style='mso-spacerun:yes'>  </span>The older form will be removed in Python 3000.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Use string methods instead of the string module unless</pre><pre><span style='mso-spacerun:yes'>      </span><span
784class=GramE>backward-compatibility</span> with versions earlier than Python 2.0 is</pre><pre><span style='mso-spacerun:yes'>      </span><span
785class=GramE>important</span>.<span style='mso-spacerun:yes'>  </span>String methods are always much faster and share the</pre><pre><span style='mso-spacerun:yes'>      </span><span
786class=GramE>same</span> API with <span class=SpellE>unicode</span> strings.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Avoid slicing strings when checking for prefixes or suffixes.</pre><pre><span style='mso-spacerun:yes'>      </span>Use <span
787class=SpellE><span class=GramE>startswith</span></span><span class=GramE>(</span>) and <span
788class=SpellE>endswith</span>() instead, since they are</pre><pre><span style='mso-spacerun:yes'>      </span><span
789class=GramE>cleaner</span> and less error prone.<span style='mso-spacerun:yes'>  </span>For example:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span>No:<span style='mso-spacerun:yes'>  </span>if <span
790class=SpellE><span class=GramE>foo</span></span><span class=GramE>[</span>:3] == 'bar':</pre><pre><span style='mso-spacerun:yes'>        </span>Yes: if <span
791class=SpellE><span class=GramE>foo.startswith</span></span><span class=GramE>(</span>'bar'):</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>The exception is if your code must work with Python 1.5.2 (but</pre><pre><span style='mso-spacerun:yes'>      </span><span
792class=GramE>let's</span> hope not!).</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Object type comparisons should always use <span
793class=SpellE><span class=GramE>isinstance</span></span><span class=GramE>(</span>) instead</pre><pre><span style='mso-spacerun:yes'>      </span><span
794class=GramE>of</span> comparing types directly.<span style='mso-spacerun:yes'>  </span><span
795class=GramE>E.g.</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span>No:<span style='mso-spacerun:yes'>  </span>if <span
796class=GramE>type(</span>obj) is type(1):</pre><pre><span style='mso-spacerun:yes'>        </span>Yes: if <span
797class=SpellE><span class=GramE>isinstance</span></span><span class=GramE>(</span>obj, <span
798class=SpellE>int</span>):</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>When checking if an object is a string, keep in mind that it</pre><pre><span style='mso-spacerun:yes'>      </span><span
799class=GramE>might</span> be a <span class=SpellE>unicode</span> string too!<span style='mso-spacerun:yes'>  </span>In Python 2.3, <span
800class=SpellE>str</span> and <span class=SpellE>unicode</span></pre><pre><span style='mso-spacerun:yes'>      </span><span
801class=GramE>have</span> a common base class, <span class=SpellE>basestring</span>, so you can do:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
802class=GramE>if</span> <span class=SpellE>isinstance</span>(obj, <span
803class=SpellE>basestring</span>):</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>In Python 2.2, the <span
804class=GramE>types</span> module has the <span class=SpellE>StringTypes</span> type defined</pre><pre><span style='mso-spacerun:yes'>      </span><span
805class=GramE>for</span> that purpose, e.g.:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
806class=GramE>from</span> types import <span class=SpellE>StringTypes</span></pre><pre><span style='mso-spacerun:yes'>        </span><span
807class=GramE>if</span> <span class=SpellE>isinstance</span>(obj, <span
808class=SpellE>StringTypes</span>):</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>     </span><span style='mso-spacerun:yes'> </span>In Python 2.0 and 2.1, you should do:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
809class=GramE>from</span> types import <span class=SpellE>StringType</span>, <span
810class=SpellE>UnicodeType</span></pre><pre><span style='mso-spacerun:yes'>        </span><span
811class=GramE>if</span> <span class=SpellE>isinstance</span>(obj, <span
812class=SpellE>StringType</span>) or \</pre><pre><span style='mso-spacerun:yes'>           </span><span
813class=SpellE><span class=GramE>isinstance</span></span><span class=GramE>(</span>obj, <span
814class=SpellE>UnicodeType</span>) :</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- For sequences, (strings, lists, <span
815class=SpellE>tuples</span>), use the fact that empty</pre><pre><span style='mso-spacerun:yes'>      </span><span
816class=GramE>sequences</span> are false, so &quot;if not <span class=SpellE>seq</span>&quot; or &quot;if <span
817class=SpellE>seq</span>&quot; is preferable</pre><pre><span style='mso-spacerun:yes'>      </span><span
818class=GramE>to</span> &quot;if <span class=SpellE>len</span>(<span
819class=SpellE>seq</span>)&quot; or &quot;if not <span class=SpellE>len</span>(<span
820class=SpellE>seq</span>)&quot;.</pre><pre><span style='mso-spacerun:yes'>      </span><i
821style='mso-bidi-font-style:normal'><span style='color:blue'>We prefer using “if <span
822class=SpellE><span class=GramE>len</span></span><span class=GramE>(</span><span
823class=SpellE>seq</span>) == 0” to check for emptiness.<o:p></o:p></span></i></pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Don't write string literals that rely on significant trailing</pre><pre><span style='mso-spacerun:yes'>      </span><span
824class=SpellE>whitespace</span>.<span style='mso-spacerun:yes'>  </span>Such trailing <span
825class=SpellE>whitespace</span> is visually</pre><pre><span style='mso-spacerun:yes'>      </span><span
826class=GramE>indistinguishable</span> and some editors (or more recently,</pre><pre><span style='mso-spacerun:yes'>      </span><span
827class=SpellE>reindent.py</span>) will trim them.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Don't compare <span
828class=SpellE>boolean</span> values to True or False using == (<span
829class=SpellE>bool</span></pre><pre><span style='mso-spacerun:yes'>      </span><span
830class=GramE>types</span> are new in Python 2.3):</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span>No:<span style='mso-spacerun:yes'>  </span>if greeting == True:</pre><pre><span style='mso-spacerun:yes'>        </span>Yes: if greeting:</pre><pre><span
831style='mso-tab-count:1'>      </span><span style='mso-spacerun:yes'>  </span><i
832style='mso-bidi-font-style:normal'><span style='color:blue'>Yes:<span
833style='mso-tab-count:1'>  </span>if greeting is True:<o:p></o:p></span></i></pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
834
835<h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'>References</h3>
836
837<pre><span style='mso-spacerun:yes'>    </span>[1] <a
838href="http://www.python.org/peps/pep-0007.html">PEP 7</a>, Style Guide for C Code, van <span
839class=SpellE>Rossum</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>[2] <a
840href="http://www.python.org/doc/essays/styleguide.html">http://www.python.org/doc/essays/styleguide.html</a></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>[3] <a
841href="http://www.python.org/peps/pep-0257.html">PEP 257</a>, <span
842class=SpellE>Docstring</span> Conventions, <span class=SpellE>Goodger</span>, <span
843class=GramE>van</span> <span class=SpellE>Rossum</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>[4] <a
844href="http://www.wikipedia.com/wiki/CamelCase">http://www.wikipedia.com/wiki/CamelCase</a></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>[5] Barry's GNU Mailman style guide</pre><pre><span style='mso-spacerun:yes'>        </span><a
845href="http://barry.warsaw.us/software/STYLEGUIDE.txt">http://barry.warsaw.us/software/STYLEGUIDE.txt</a></pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
846
847<h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'>Copyright</h3>
848
849<pre><span style='mso-spacerun:yes'>    </span>This document has been placed in the public domain.</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre></div>
850
851</div>
852
853</body>
854
855</html>
Note: See TracBrowser for help on using the repository browser.