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

Last change on this file since 2182 was 1981, checked in by ole, 19 years ago

Added documentation directory and updated style guide (based on PEP 8)
File size: 83.1 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="country-region"/>
29<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
30 name="place"/>
31<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
32 name="date"/>
33<!--[if gte mso 9]><xml>
34 <o:DocumentProperties>
35  <o:Author>nielsen ole</o:Author>
36  <o:LastAuthor>nielsen ole</o:LastAuthor>
37  <o:Revision>8</o:Revision>
38  <o:TotalTime>26</o:TotalTime>
39  <o:Created>2005-10-26T07:20:00Z</o:Created>
40  <o:LastSaved>2005-10-26T07:49:00Z</o:LastSaved>
41  <o:Pages>1</o:Pages>
42  <o:Words>3898</o:Words>
43  <o:Characters>22219</o:Characters>
44  <o:Company>Geoscience Australia</o:Company>
45  <o:Lines>185</o:Lines>
46  <o:Paragraphs>52</o:Paragraphs>
47  <o:CharactersWithSpaces>26065</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="7170"/>
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 Month="7" Day="5" Year="2001">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>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
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><span class=GramE>docstrings</span></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><span class=GramE>color</span></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><span class=GramE>color</span></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><span class=GramE>color</span></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>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><span class=GramE>whitespace</span></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><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>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 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><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><o:p>&nbsp;</o:p></pre>
584
585<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
586Strings</h3>
587
588<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
589class=SpellE>docstrings</span>&quot;) are immortalized in <a
590href="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
591class=SpellE>docstrings</span> for all public modules, functions, classes, and</pre><pre><span style='mso-spacerun:yes'>      </span><span
592class=GramE>methods</span>.<span style='mso-spacerun:yes'>  </span><span
593class=SpellE>Docstrings</span> are not necessary for non-public methods,</pre><pre><span style='mso-spacerun:yes'>      </span><span
594class=GramE>but</span> you should have a comment that describes what the method</pre><pre><span style='mso-spacerun:yes'>      </span><span
595class=GramE>does</span>.<span style='mso-spacerun:yes'>  </span>This comment should appear after the &quot;def&quot; line.</pre><pre><span
596style='mso-tab-count:1'>      </span><i style='mso-bidi-font-style:normal'><span
597style='color:blue'>Ideally, all modules, functions, classes, and methods should have <o:p></o:p></span></i></pre><pre><i
598style='mso-bidi-font-style:normal'><span style='color:blue'><span style='mso-spacerun:yes'>      </span><span
599class=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
600href="http://www.python.org/peps/pep-0257.html">PEP 257</a> describes good <span
601class=SpellE>docstring</span> conventions.<span style='mso-spacerun:yes'>  </span>Note that most</pre><pre><span style='mso-spacerun:yes'>      </span><span
602class=GramE>importantly</span>, the &quot;&quot;&quot; that ends a <span
603class=SpellE>multiline</span> <span class=SpellE>docstring</span> should be</pre><pre><span style='mso-spacerun:yes'>      </span><span
604class=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
605class=SpellE>foobang</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Optional <span
606class=SpellE>plotz</span> says to <span class=SpellE>frobnicate</span> the <span
607class=SpellE>bizbaz</span> first.</pre><pre><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
608class=SpellE>docstrings</span>, it's okay to keep the closing &quot;&quot;&quot; on</pre><pre><span style='mso-spacerun:yes'>      </span><span
609class=GramE>the</span> same line.</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
610
611<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
612Bookkeeping</h3>
613
614<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
615class=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
616class=SpellE>docstring</span>,</pre><pre><span style='mso-spacerun:yes'>    </span><span
617class=GramE>before</span> any other code, separated by a blank line above and</pre><pre><span style='mso-spacerun:yes'>    </span><span
618class=GramE>below</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
619
620<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
621Conventions</h3>
622
623<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
624class=GramE>never</span> get this completely consistent -- nevertheless, here are the</pre><pre><span style='mso-spacerun:yes'>    </span><span
625class=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
626class=GramE>including</span> 3rd party frameworks) should be written to these standards, but</pre><pre><span style='mso-spacerun:yes'>    </span><span
627class=GramE>where</span> an existing library has a different style, internal consistency is</pre><pre><span style='mso-spacerun:yes'>    </span><span
628class=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
629class=GramE>to</span> recognize what naming style is being used, independently from</pre><pre><span style='mso-spacerun:yes'>    </span><span
630class=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
631class=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
632class=GramE>lowercase</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <span
633class=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
634class=SpellE>CapitalizedWords</span> (or <span class=SpellE>CapWords</span>, or <span
635class=SpellE>CamelCase</span> -- so named because</pre><pre><span style='mso-spacerun:yes'>      </span><span
636class=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
637class=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
638class=SpellE><span class=GramE>mixedCase</span></span> (differs from <span
639class=SpellE>CapitalizedWords</span> by initial lowercase</pre><pre><span style='mso-spacerun:yes'>      </span><span
640class=GramE>character</span>!)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <span
641class=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
642class=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
643class=GramE>is</span> mentioned for completeness.<span style='mso-spacerun:yes'>  </span>For example, the <span
644class=SpellE><span class=GramE>os.stat</span></span><span class=GramE>()</span></pre><pre><span style='mso-spacerun:yes'>    </span><span
645class=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
646class=SpellE><span class=GramE>st_mode</span></span><span class=GramE>, <span
647class=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
648class=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
649class=GramE>generally</span> deemed unnecessary because attribute and method names</pre><pre><span style='mso-spacerun:yes'>    </span><span
650class=GramE>are</span> prefixed with an object, and function names are prefixed with</pre><pre><span style='mso-spacerun:yes'>    </span><span
651class=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
652class=GramE>underscores</span> are recognized (these can generally be combined with any</pre><pre><span style='mso-spacerun:yes'>    </span><span
653class=GramE>case</span> convention):</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- _<span
654class=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
655class=GramE>starts</span> with an underscore).</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <span
656class=SpellE>single_trailing_underscore</span>_: used by convention to avoid</pre><pre><span style='mso-spacerun:yes'>      </span><span
657class=GramE>conflicts</span> with Python keyword, e.g.</pre><pre><span style='mso-spacerun:yes'>      </span>&quot;<span
658class=SpellE><span class=GramE>Tkinter.Toplevel</span></span><span class=GramE>(</span>master, class_='<span
659class=SpellE>ClassName</span>')&quot;.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span><span
660class=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
661class=SpellE>double_leading_and_trailing_underscore</span>__: &quot;magic&quot; objects or</pre><pre><span style='mso-spacerun:yes'>      </span><span
662class=GramE>attributes</span> that live in user-controlled namespaces,</pre><pre><span style='mso-spacerun:yes'>      </span><span
663class=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
664class=GramE>defined</span> by the user to trigger certain magic <span
665class=SpellE>behavior</span></pre><pre><span style='mso-spacerun:yes'>      </span>(<span
666class=GramE>e.g</span>. operator overloading); sometimes these are inserted by the</pre><pre><span style='mso-spacerun:yes'>      </span><span
667class=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
668class=GramE>the</span> infrastructure (loosely defined as the Python interpreter</pre><pre><span style='mso-spacerun:yes'>      </span><span
669class=GramE>and</span> the standard library) may decide to grow its list of magic</pre><pre><span style='mso-spacerun:yes'>      </span><span
670class=GramE>attributes</span> in future versions, user code should generally</pre><pre><span style='mso-spacerun:yes'>      </span><span
671class=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
672class=GramE>that</span> aspires to become part of the infrastructure could combine</pre><pre><span style='mso-spacerun:yes'>      </span><span
673class=GramE>this</span> with a short prefix inside the underscores,</pre><pre><span style='mso-spacerun:yes'>      </span><span
674class=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
675class=GramE>uppercase</span> letter oh), or `I' (uppercase letter eye) as single</pre><pre><span style='mso-spacerun:yes'>      </span><span
676class=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
677class=SpellE><span class=GramE>indistinguisable</span></span> from the numerals one and zero.<span style='mso-spacerun:yes'>  </span>When tempted</pre><pre
678style='margin-left:12.0pt'><span style='mso-spacerun:yes'>    </span><span
679class=GramE>to</span> use `l' use `L' instead, <i style='mso-bidi-font-style:
680normal'><span style='color:blue'>unless the mathematical formula <o:p></o:p></span></i></pre><pre
681style='margin-left:12.0pt'><i style='mso-bidi-font-style:normal'><span
682style='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
683style='mso-bidi-font-style:normal'><span style='color:blue'>possibly with</span></i> </pre><pre><span style='mso-spacerun:yes'>      </span><span
684class=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
685class=GramE>are</span> case insensitive and truncate long names, it is important that</pre><pre><span style='mso-spacerun:yes'>      </span><span
686class=GramE>module</span> names be chosen to be fairly short -- this won't be a</pre><pre><span style='mso-spacerun:yes'>      </span><span
687class=GramE>problem</span> on Unix, but it may be a problem when the code is</pre><pre><span style='mso-spacerun:yes'>      </span><span
688class=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
689class=GramE>oriented</span>) interface, the C/C++ module has a leading underscore</pre><pre><span style='mso-spacerun:yes'>      </span><span
690class=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
691class=GramE><i style='mso-bidi-font-style:normal'><span style='color:blue'>possibly</span></i></span><i
692style='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>Almost without exception, class names use the <span
693class=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
694class=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
695class=GramE>that</span> built-in (extension) modules use &quot;error&quot; (e.g. <span
696class=SpellE>os.error</span>),</pre><pre><span style='mso-spacerun:yes'>      </span><span
697class=GramE>while</span> Python modules generally use &quot;Error&quot; (e.g. <span
698class=SpellE>xdrlib.Error</span>).</pre><pre><span style='mso-spacerun:yes'>      </span>The trend seems to be toward <span
699class=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
700class=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
701class=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
702class=GramE>should</span> prefix their <span class=SpellE>globals</span> (and internal functions and classes)</pre><pre><span style='mso-spacerun:yes'>      </span><span
703class=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
704class=GramE>underscores</span> to improve readability.<span style='mso-spacerun:yes'>  </span><span
705class=SpellE><span class=GramE>mixedCase</span></span> is allowed only in</pre><pre><span style='mso-spacerun:yes'>      </span><span
706class=GramE>contexts</span> where that's already the prevailing style (e.g. <span
707class=SpellE>threading.py</span>),</pre><pre><span style='mso-spacerun:yes'>      </span><span
708class=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
709class=GramE>lowercase</span> with words separated by underscores as necessary to improve</pre><pre><span style='mso-spacerun:yes'>      </span><span
710class=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 style='mso-spacerun:yes'>   </span><span
711class=GramE>variables</span> which are not intended to be part of the class's public</pre><pre><span style='mso-spacerun:yes'>      </span><span
712class=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
713class=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
714class=GramE>mangles</span>&quot; these names with the class name: if class <span
715class=SpellE>Foo</span> has an</pre><pre><span style='mso-spacerun:yes'>      </span><span
716class=GramE>attribute</span> named __a, it cannot be accessed by <span
717class=SpellE>Foo.__a</span>.<span style='mso-spacerun:yes'>  </span>(An insistent</pre><pre><span style='mso-spacerun:yes'>      </span><span
718class=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
719class=GramE>double</span> leading underscores should be used only to avoid name conflicts</pre><pre><span style='mso-spacerun:yes'>      </span><span
720class=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
721class=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
722class=GramE>variables</span> public unless you're implementing essentially a</pre><pre><span style='mso-spacerun:yes'>      </span><span
723class=GramE>record</span>.<span style='mso-spacerun:yes'>  </span>It's almost always <span
724class=SpellE>preferrable</span> to give a functional</pre><pre><span style='mso-spacerun:yes'>      </span><span
725class=GramE>interface</span> to your class instead (and some Python 2.2</pre><pre><span style='mso-spacerun:yes'>      </span><span
726class=GramE>developments</span> will make this much nicer). <i
727style='mso-bidi-font-style:normal'><span style='color:blue'>Consider using Python’s <o:p></o:p></span></i></pre><pre><i
728style='mso-bidi-font-style:normal'><span style='color:blue'><span style='mso-spacerun:yes'>      </span><span
729class=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
730class=GramE>will</span> never be useful for a derived class, while the latter might</pre><pre><span style='mso-spacerun:yes'>      </span><span
731class=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
732class=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
733class=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
734class=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
735class=GramE>underscores</span>, unless they conflict with reserved words, in which</pre><pre><span style='mso-spacerun:yes'>      </span><span
736class=GramE>case</span>, a single trailing underscore is preferable to a leading</pre><pre><span style='mso-spacerun:yes'>      </span><span
737class=GramE>one</span>, or a corrupted spelling, e.g. class_ rather than <span
738class=SpellE>klass</span>.</pre><pre><span style='mso-spacerun:yes'>      </span>(This last point is a bit controversial; if you prefer <span
739class=SpellE>klass</span></pre><pre><span style='mso-spacerun:yes'>      </span><span
740class=GramE>over</span> class_ then just be consistent. :).</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
741
742<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
743Recommendations</h3>
744
745<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
746class=GramE>implementations</span> of Python (<span class=SpellE>PyPy</span>, <span
747class=SpellE>Jython</span>, <span class=SpellE>IronPython</span>, Pyrex, <span
748class=SpellE>Psyco</span>,</pre><pre><span style='mso-spacerun:yes'>      </span><span
749class=GramE>and</span> such).<span style='mso-spacerun:yes'>  </span>For example, do not rely on <span
750class=SpellE>CPython's</span> efficient</pre><pre><span style='mso-spacerun:yes'>      </span><span
751class=GramE>implementation</span> of in-place string concatenation for statements in</pre><pre><span style='mso-spacerun:yes'>      </span><span
752class=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
753class=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
754class=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
755class=GramE>concatenation</span> occurs in linear time across various implementations.</pre><pre><span
756style='mso-tab-count:1'>      </span><i style='mso-bidi-font-style:normal'><span
757style='color:blue'>In performance insensitive part it is OK to use the more readable <o:p></o:p></span></i></pre><pre><i
758style='mso-bidi-font-style:normal'><span style='color:blue'><span style='mso-spacerun:yes'>      </span><span
759class=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
760class=GramE>None</span> should always be done with</pre><pre><span style='mso-spacerun:yes'>      </span>'<span
761class=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
762class=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
763class=GramE>variable</span> or argument that defaults to None was set to some other</pre><pre><span style='mso-spacerun:yes'>      </span><span
764class=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
765class=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
766class=GramE>domain-specific</span> base exception class, which should be subclassed</pre><pre><span style='mso-spacerun:yes'>      </span><span
767class=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
768class=SpellE><span class=GramE>docstring</span></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
769class=GramE>class</span> <span class=SpellE>MessageError</span>(Exception):</pre><pre><span style='mso-spacerun:yes'>            </span><span
770class=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
771class=SpellE><span class=GramE>ValueError</span></span><span class=GramE>(</span>'message')&quot;</pre><pre><span style='mso-spacerun:yes'>      </span><span
772class=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
773class=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
774class=GramE>arguments</span> are long or include string formatting, you don't need</pre><pre><span style='mso-spacerun:yes'>      </span><span
775class=GramE>to</span> use line continuation characters thanks to the containing</pre><pre><span style='mso-spacerun:yes'>      </span><span
776class=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
777class=GramE>backward-compatibility</span> with versions earlier than Python 2.0 is</pre><pre><span style='mso-spacerun:yes'>      </span><span
778class=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
779class=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
780class=SpellE><span class=GramE>startswith</span></span><span class=GramE>(</span>) and <span
781class=SpellE>endswith</span>() instead, since they are</pre><pre><span style='mso-spacerun:yes'>      </span><span
782class=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
783class=SpellE><span class=GramE>foo</span></span><span class=GramE>[</span>:3] == 'bar':</pre><pre><span style='mso-spacerun:yes'>        </span>Yes: if <span
784class=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
785class=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
786class=SpellE><span class=GramE>isinstance</span></span><span class=GramE>(</span>) instead</pre><pre><span style='mso-spacerun:yes'>      </span><span
787class=GramE>of</span> comparing types directly.<span style='mso-spacerun:yes'>  </span><span
788class=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
789class=GramE>type(</span>obj) is type(1):</pre><pre><span style='mso-spacerun:yes'>        </span>Yes: if <span
790class=SpellE><span class=GramE>isinstance</span></span><span class=GramE>(</span>obj, <span
791class=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
792class=GramE>might</span> be a <span class=SpellE>unicode</span> string too!<span style='mso-spacerun:yes'>  </span>In Python 2.3, <span
793class=SpellE><span class=GramE>str</span></span> and <span class=SpellE>unicode</span></pre><pre><span style='mso-spacerun:yes'>      </span><span
794class=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
795class=GramE>if</span> <span class=SpellE>isinstance</span>(obj, <span
796class=SpellE>basestring</span>):</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>In Python 2.2, the <span
797class=GramE>types</span> module has the <span class=SpellE>StringTypes</span> type defined</pre><pre><span style='mso-spacerun:yes'>      </span><span
798class=GramE>for</span> that purpose, e.g.:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
799class=GramE>from</span> types import <span class=SpellE>StringTypes</span></pre><pre><span style='mso-spacerun:yes'>        </span><span
800class=GramE>if</span> <span class=SpellE>isinstance</span>(obj, <span
801class=SpellE>StringTypes</span>):</pre><pre><o:p>&nbsp;</o:p></pre><pre><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
802class=GramE>from</span> types import <span class=SpellE>StringType</span>, <span
803class=SpellE>UnicodeType</span></pre><pre><span style='mso-spacerun:yes'>    </span><span style='mso-spacerun:yes'>    </span><span
804class=GramE>if</span> <span class=SpellE>isinstance</span>(obj, <span
805class=SpellE>StringType</span>) or \</pre><pre><span style='mso-spacerun:yes'>           </span><span
806class=SpellE><span class=GramE>isinstance</span></span><span class=GramE>(</span>obj, <span
807class=SpellE>UnicodeType</span>) :</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- For sequences, (strings, lists, <span
808class=SpellE>tuples</span>), use the fact that empty</pre><pre><span style='mso-spacerun:yes'>      </span><span
809class=GramE>sequences</span> are false, so &quot;if not <span class=SpellE>seq</span>&quot; or &quot;if <span
810class=SpellE>seq</span>&quot; is preferable</pre><pre><span style='mso-spacerun:yes'>      </span><span
811class=GramE>to</span> &quot;if <span class=SpellE>len</span>(<span
812class=SpellE>seq</span>)&quot; or &quot;if not <span class=SpellE>len</span>(<span
813class=SpellE>seq</span>)&quot;.</pre><pre><span style='mso-spacerun:yes'>      </span><i
814style='mso-bidi-font-style:normal'><span style='color:blue'>We prefer using “if <span
815class=SpellE><span class=GramE>len</span></span><span class=GramE>(</span><span
816class=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
817class=SpellE><span class=GramE>whitespace</span></span>.<span style='mso-spacerun:yes'>  </span>Such trailing <span
818class=SpellE>whitespace</span> is visually</pre><pre><span style='mso-spacerun:yes'>      </span><span
819class=GramE>indistinguishable</span> and some editors (or more recently,</pre><pre><span style='mso-spacerun:yes'>      </span><span
820class=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
821class=SpellE><span class=GramE>boolean</span></span> values to True or False using == (<span
822class=SpellE>bool</span></pre><pre><span style='mso-spacerun:yes'>      </span><span
823class=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
824style='mso-tab-count:1'>      </span><span style='mso-spacerun:yes'>  </span><i
825style='mso-bidi-font-style:normal'><span style='color:blue'>Yes:<span
826style='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>
827
828<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>
829
830<pre><span style='mso-spacerun:yes'>    </span>[1] <a
831href="http://www.python.org/peps/pep-0007.html">PEP 7</a>, Style Guide for C Code, van <span
832class=SpellE>Rossum</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>[2] <a
833href="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><span style='mso-spacerun:yes'> </span>[3] <a
834href="http://www.python.org/peps/pep-0257.html">PEP 257</a>, <span
835class=SpellE>Docstring</span> Conventions, <span class=SpellE>Goodger</span>, <span
836class=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
837href="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
838href="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>
839
840<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>
841
842<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>
843
844</div>
845
846</body>
847
848</html>
Note: See TracBrowser for help on using the repository browser.