Changeset 2419


Ignore:
Timestamp:
Feb 16, 2006, 5:05:12 PM (19 years ago)
Author:
sexton
Message:

Doing action item from Wed 15 Feb meeting (adding FIXME to style guide)

File:
1 edited

Legend:

Unmodified
Added
Removed

  • documentation/coding_standards/Style Guide for Python Code, GA version.htm

    r2372 r2419  
    2626<title>PEP 8 -- Style Guide for Python Code</title>
    2727<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
     28 name="date"/>
     29<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
    2830 name="country-region"/>
    2931<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
    3032 name="place"/>
    31 <o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
    32  name="date"/>
    3333<!--[if gte mso 9]><xml>
    3434 <o:DocumentProperties>
    3535  <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>
     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>
    4141  <o:Pages>1</o:Pages>
    42   <o:Words>3898</o:Words>
    43   <o:Characters>22219</o:Characters>
     42  <o:Words>4006</o:Words>
     43  <o:Characters>22839</o:Characters>
    4444  <o:Company>Geoscience Australia</o:Company>
    45   <o:Lines>185</o:Lines>
    46   <o:Paragraphs>52</o:Paragraphs>
    47   <o:CharactersWithSpaces>26065</o:CharactersWithSpaces>
     45  <o:Lines>190</o:Lines>
     46  <o:Paragraphs>53</o:Paragraphs>
     47  <o:CharactersWithSpaces>26792</o:CharactersWithSpaces>
    4848  <o:Version>10.6626</o:Version>
    4949 </o:DocumentProperties>
    … …  
    255255to templates.  DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
    256256--><!--[if gte mso 9]><xml>
    257  <o:shapedefaults v:ext="edit" spidmax="7170"/>
     257 <o:shapedefaults v:ext="edit" spidmax="8194"/>
    258258</xml><![endif]--><!--[if gte mso 9]><xml>
    259259 <o:shapelayout v:ext="edit">
    … …  
    353353  </td>
    354354  <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>
     355  <p class=MsoNormal><st1:date Year="2001" Day="5" Month="7">05-Jul-2001</st1:date></p>
    356356  </td>
    357357 </tr>
    … …  
    386386<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
    387387class=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
    388 class=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
     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
    389389class=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
    390390class=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
    … …  
    399399class=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
    400400class=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
    401 class=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
     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
    402402class=GramE>maybe</span> for historic reasons) -- <span class=GramE>although</span> this is also an</pre><pre><span style='mso-spacerun:yes'>        </span><span
    403403class=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>
    … …  
    429429class=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
    430430class=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
    431 class=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
     431class=SpellE>docstrings</span> or comments), limiting the length to 72 characters is</pre><pre><span style='mso-spacerun:yes'>    </span><span
    432432class=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
    433433class=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
    … …  
    437437class=GramE>class</span> Rectangle(Blob):</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
    438438class=GramE>def</span> __init__(self, width, height,</pre><pre><span style='mso-spacerun:yes'>                     </span><span
    439 class=SpellE><span class=GramE>color</span></span>='black', emphasis=None, highlight=0):</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
    440440class=GramE>if</span> width == 0 and height == 0 and \</pre><pre><span style='mso-spacerun:yes'>               </span><span
    441 class=SpellE><span class=GramE>color</span></span> == 'red' and emphasis == 'strong' or \</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
    442442class=GramE>highlight</span> &gt; 100:</pre><pre><span style='mso-spacerun:yes'>                </span><span
    443443class=GramE>raise</span> <span class=SpellE>ValueError</span>(&quot;sorry, you lose&quot;)</pre><pre><span style='mso-spacerun:yes'>            </span><span
    … …  
    446446class=GramE>raise</span> <span class=SpellE>ValueError</span>(&quot;I don't think so&quot;)</pre><pre><span style='mso-spacerun:yes'>            </span><span
    447447class=SpellE>Blob.__init</span>_<span class=GramE>_(</span>self, width, height,</pre><pre><span style='mso-spacerun:yes'>                          </span><span
    448 class=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
     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
    449449class=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
    450450class=GramE>single</span> blank line.<span style='mso-spacerun:yes'>  </span>Extra blank lines may be used (<s>sparingly</s> <i
    … …  
    454454class=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
    455455class=GramE>also</span> a blank line between the `class' line and the first method</pre><pre><span style='mso-spacerun:yes'>    </span><span
    456 class=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
     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
    457457style='mso-bidi-font-style:normal'><span style='color:blue'>liberally</span></i>, to indicate logical</pre><pre><span style='mso-spacerun:yes'>    </span><span
    458458class=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
    459 class=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
     459class=SpellE>whitespace</span>; <span class=SpellE>Emacs</span> (and some printing tools) treat these</pre><pre><span style='mso-spacerun:yes'>    </span><span
    460460class=GramE>characters</span> as page separators, so you may use them to separate</pre><pre><span style='mso-spacerun:yes'>    </span><span
    461461class=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
    … …  
    493493class=GramE>standard</span> library imports</pre><pre><span style='mso-spacerun:yes'>      </span>2. <span
    494494class=GramE>related</span> major package imports (i.e. all email package imports next)</pre><pre><span style='mso-spacerun:yes'>      </span>3. <span
    495 class=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
     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
    496496class=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
    497497class=GramE>imports</span>. <i style='mso-bidi-font-style:normal'><span
    … …  
    529529class=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
    530530class=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
    531 class=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
    532 class=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
     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
    533533class=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
    534534class=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
    … …  
    541541class=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
    542542class=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
    543 class=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
     543class=GramE>def</span> complex(real, <span class=SpellE>imag</span>=0.0):</pre><pre><span style='mso-spacerun:yes'>              </span><span
    544544class=GramE>return</span> magic(r=real, <span class=SpellE>i</span>=<span
    545545class=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
    … …  
    548548class=GramE>thing</span></span><span class=GramE>()</span></pre><pre><span style='mso-spacerun:yes'>          </span>Yes: if <span
    549549class=SpellE>foo</span> == 'blah':</pre><pre><span style='mso-spacerun:yes'>                   </span><span
    550 class=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
     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
    551551class=SpellE>do_<span class=GramE>one</span></span><span class=GramE>(</span>); <span
    552552class=SpellE>do_two</span>(); <span class=SpellE>do_three</span>()</pre><pre><span style='mso-spacerun:yes'>          </span>Yes: <span
    … …  
    581581class=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
    582582class=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
    583 class=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>
     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>
    584592
    585593<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
    … …  
    605613class=SpellE>foobang</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Optional <span
    606614class=SpellE>plotz</span> says to <span class=SpellE>frobnicate</span> the <span
    607 class=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
     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
    608616class=SpellE>docstrings</span>, it's okay to keep the closing &quot;&quot;&quot; on</pre><pre><span style='mso-spacerun:yes'>      </span><span
    609617class=GramE>the</span> same line.</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
    … …  
    636644class=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
    637645class=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
    638 class=SpellE><span class=GramE>mixedCase</span></span> (differs from <span
    639 class=SpellE>CapitalizedWords</span> by initial lowercase</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
    640647class=GramE>character</span>!)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <span
    641648class=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
    642 class=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
     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
    643650class=GramE>is</span> mentioned for completeness.<span style='mso-spacerun:yes'>  </span>For example, the <span
    644651class=SpellE><span class=GramE>os.stat</span></span><span class=GramE>()</span></pre><pre><span style='mso-spacerun:yes'>    </span><span
    … …  
    675682class=GramE>uppercase</span> letter oh), or `I' (uppercase letter eye) as single</pre><pre><span style='mso-spacerun:yes'>      </span><span
    676683class=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
    677 class=SpellE><span class=GramE>indistinguisable</span></span> from the numerals one and zero.<span style='mso-spacerun:yes'>  </span>When tempted</pre><pre
     684class=SpellE>indistinguisable</span> from the numerals one and zero.<span style='mso-spacerun:yes'>  </span>When tempted</pre><pre
    678685style='margin-left:12.0pt'><span style='mso-spacerun:yes'>    </span><span
    679686class=GramE>to</span> use `l' use `L' instead, <i style='mso-bidi-font-style:
    … …  
    690697class=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
    691698class=GramE><i style='mso-bidi-font-style:normal'><span style='color:blue'>possibly</span></i></span><i
    692 style='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
     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
    693700class=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
    694701class=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
    … …  
    703710class=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
    704711class=GramE>underscores</span> to improve readability.<span style='mso-spacerun:yes'>  </span><span
    705 class=SpellE><span class=GramE>mixedCase</span></span> is allowed only in</pre><pre><span style='mso-spacerun:yes'>      </span><span
     712class=SpellE>mixedCase</span> is allowed only in</pre><pre><span style='mso-spacerun:yes'>      </span><span
    706713class=GramE>contexts</span> where that's already the prevailing style (e.g. <span
    707714class=SpellE>threading.py</span>),</pre><pre><span style='mso-spacerun:yes'>      </span><span
    708715class=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
    709716class=GramE>lowercase</span> with words separated by underscores as necessary to improve</pre><pre><span style='mso-spacerun:yes'>      </span><span
    710 class=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
     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
    711718class=GramE>variables</span> which are not intended to be part of the class's public</pre><pre><span style='mso-spacerun:yes'>      </span><span
    712719class=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
    … …  
    766773class=GramE>domain-specific</span> base exception class, which should be subclassed</pre><pre><span style='mso-spacerun:yes'>      </span><span
    767774class=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
    768 class=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
     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
    769776class=GramE>class</span> <span class=SpellE>MessageError</span>(Exception):</pre><pre><span style='mso-spacerun:yes'>            </span><span
    770777class=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
    … …  
    791798class=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
    792799class=GramE>might</span> be a <span class=SpellE>unicode</span> string too!<span style='mso-spacerun:yes'>  </span>In Python 2.3, <span
    793 class=SpellE><span class=GramE>str</span></span> and <span class=SpellE>unicode</span></pre><pre><span style='mso-spacerun:yes'>      </span><span
     800class=SpellE>str</span> and <span class=SpellE>unicode</span></pre><pre><span style='mso-spacerun:yes'>      </span><span
    794801class=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
    795802class=GramE>if</span> <span class=SpellE>isinstance</span>(obj, <span
    … …  
    799806class=GramE>from</span> types import <span class=SpellE>StringTypes</span></pre><pre><span style='mso-spacerun:yes'>        </span><span
    800807class=GramE>if</span> <span class=SpellE>isinstance</span>(obj, <span
    801 class=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
     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
    802809class=GramE>from</span> types import <span class=SpellE>StringType</span>, <span
    803 class=SpellE>UnicodeType</span></pre><pre><span style='mso-spacerun:yes'>    </span><span style='mso-spacerun:yes'>    </span><span
     810class=SpellE>UnicodeType</span></pre><pre><span style='mso-spacerun:yes'>        </span><span
    804811class=GramE>if</span> <span class=SpellE>isinstance</span>(obj, <span
    805812class=SpellE>StringType</span>) or \</pre><pre><span style='mso-spacerun:yes'>           </span><span
    … …  
    815822class=SpellE><span class=GramE>len</span></span><span class=GramE>(</span><span
    816823class=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
    817 class=SpellE><span class=GramE>whitespace</span></span>.<span style='mso-spacerun:yes'>  </span>Such trailing <span
     824class=SpellE>whitespace</span>.<span style='mso-spacerun:yes'>  </span>Such trailing <span
    818825class=SpellE>whitespace</span> is visually</pre><pre><span style='mso-spacerun:yes'>      </span><span
    819826class=GramE>indistinguishable</span> and some editors (or more recently,</pre><pre><span style='mso-spacerun:yes'>      </span><span
    820827class=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
    821 class=SpellE><span class=GramE>boolean</span></span> values to True or False using == (<span
     828class=SpellE>boolean</span> values to True or False using == (<span
    822829class=SpellE>bool</span></pre><pre><span style='mso-spacerun:yes'>      </span><span
    823830class=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
    … …  
    831838href="http://www.python.org/peps/pep-0007.html">PEP 7</a>, Style Guide for C Code, van <span
    832839class=SpellE>Rossum</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>[2] <a
    833 href="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
     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
    834841href="http://www.python.org/peps/pep-0257.html">PEP 257</a>, <span
    835842class=SpellE>Docstring</span> Conventions, <span class=SpellE>Goodger</span>, <span
Note: See TracChangeset for help on using the changeset viewer.