Changeset 3449


Ignore:
Timestamp:
Aug 4, 2006, 11:49:36 AM (19 years ago)
Author:
duncan
Message:

adding documentation

Location:
documentation
Files:
2 edited

Legend:

Unmodified
Added
Removed

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

    r2419 r3449  
    3434 <o:DocumentProperties>
    3535  <o:Author>nielsen ole</o:Author>
    36   <o:LastAuthor>sexton jane</o:LastAuthor>
    37   <o:Revision>3</o:Revision>
    38   <o:TotalTime>45</o:TotalTime>
     36  <o:LastAuthor>gray duncan</o:LastAuthor>
     37  <o:Revision>6</o:Revision>
     38  <o:TotalTime>51</o:TotalTime>
    3939  <o:Created>2006-02-16T06:00:00Z</o:Created>
    40   <o:LastSaved>2006-02-16T06:02:00Z</o:LastSaved>
    41   <o:Pages>1</o:Pages>
    42   <o:Words>4006</o:Words>
    43   <o:Characters>22839</o:Characters>
     40  <o:LastSaved>2006-08-04T01:38:00Z</o:LastSaved>
     41  <o:Pages>2</o:Pages>
     42  <o:Words>4017</o:Words>
     43  <o:Characters>22898</o:Characters>
    4444  <o:Company>Geoscience Australia</o:Company>
    4545  <o:Lines>190</o:Lines>
    4646  <o:Paragraphs>53</o:Paragraphs>
    47   <o:CharactersWithSpaces>26792</o:CharactersWithSpaces>
     47  <o:CharactersWithSpaces>26862</o:CharactersWithSpaces>
    4848  <o:Version>10.6626</o:Version>
    4949 </o:DocumentProperties>
    … …  
    5252  <w:SpellingState>Clean</w:SpellingState>
    5353  <w:GrammarState>Clean</w:GrammarState>
     54  <w:Compatibility>
     55   <w:UseFELayout/>
     56  </w:Compatibility>
    5457  <w:BrowserLevel>MicrosoftInternetExplorer4</w:BrowserLevel>
    5558 </w:WordDocument>
    … …  
    6467<style>
    6568<!--
     69 /* Font Definitions */
     70 @font-face
     71        {font-family:"MS Mincho";
     72        panose-1:2 2 6 9 4 2 5 8 3 4;
     73        mso-font-alt:"\FF2D\FF33 \660E\671D";
     74        mso-font-charset:128;
     75        mso-generic-font-family:modern;
     76        mso-font-pitch:fixed;
     77        mso-font-signature:-1610612033 1757936891 16 0 131231 0;}
     78@font-face
     79        {font-family:"\@MS Mincho";
     80        panose-1:2 2 6 9 4 2 5 8 3 4;
     81        mso-font-charset:128;
     82        mso-generic-font-family:modern;
     83        mso-font-pitch:fixed;
     84        mso-font-signature:-1610612033 1757936891 16 0 131231 0;}
    6685 /* Style Definitions */
    6786 p.MsoNormal, li.MsoNormal, div.MsoNormal
    … …  
    7291        font-size:12.0pt;
    7392        font-family:"Times New Roman";
    74         mso-fareast-font-family:"Times New Roman";}
     93        mso-fareast-font-family:"Times New Roman";
     94        mso-bidi-font-family:"Times New Roman";}
    7595h3
    7696        {mso-margin-top-alt:auto;
    … …  
    95115        font-size:10.0pt;
    96116        font-family:"Courier New";
    97         mso-fareast-font-family:"Times New Roman";}
     117        mso-fareast-font-family:"Times New Roman";
     118        mso-bidi-font-family:"Courier New";}
    98119p.navigation, li.navigation, div.navigation
    99120        {mso-style-name:navigation;
    … …  
    105126        font-size:12.0pt;
    106127        font-family:"Times New Roman";
    107         mso-fareast-font-family:"Times New Roman";}
     128        mso-fareast-font-family:"Times New Roman";
     129        mso-bidi-font-family:"Times New Roman";}
    108130p.header, li.header, div.header
    109131        {mso-style-name:header;
    … …  
    112134        font-size:12.0pt;
    113135        font-family:"Times New Roman";
    114         mso-fareast-font-family:"Times New Roman";}
     136        mso-fareast-font-family:"Times New Roman";
     137        mso-bidi-font-family:"Times New Roman";}
    115138p.content, li.content, div.content
    116139        {mso-style-name:content;
    … …  
    120143        font-size:12.0pt;
    121144        font-family:"Times New Roman";
    122         mso-fareast-font-family:"Times New Roman";}
     145        mso-fareast-font-family:"Times New Roman";
     146        mso-bidi-font-family:"Times New Roman";}
    123147p.navicon, li.navicon, div.navicon
    124148        {mso-style-name:navicon;
    … …  
    131155        font-size:12.0pt;
    132156        font-family:"Times New Roman";
    133         mso-fareast-font-family:"Times New Roman";}
     157        mso-fareast-font-family:"Times New Roman";
     158        mso-bidi-font-family:"Times New Roman";}
    134159p.textlinks, li.textlinks, div.textlinks
    135160        {mso-style-name:textlinks;
    … …  
    142167        font-size:12.0pt;
    143168        font-family:"Times New Roman";
    144         mso-fareast-font-family:"Times New Roman";}
     169        mso-fareast-font-family:"Times New Roman";
     170        mso-bidi-font-family:"Times New Roman";}
    145171p.navicon1, li.navicon1, div.navicon1
    146172        {mso-style-name:navicon1;
    … …  
    153179        font-size:12.0pt;
    154180        font-family:"Times New Roman";
    155         mso-fareast-font-family:"Times New Roman";}
     181        mso-fareast-font-family:"Times New Roman";
     182        mso-bidi-font-family:"Times New Roman";}
    156183p.textlinks1, li.textlinks1, div.textlinks1
    157184        {mso-style-name:textlinks1;
    … …  
    164191        font-size:12.0pt;
    165192        font-family:"Times New Roman";
    166         mso-fareast-font-family:"Times New Roman";}
     193        mso-fareast-font-family:"Times New Roman";
     194        mso-bidi-font-family:"Times New Roman";}
    167195span.SpellE
    168196        {mso-style-name:"";
    … …  
    255283to templates.  DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
    256284--><!--[if gte mso 9]><xml>
    257  <o:shapedefaults v:ext="edit" spidmax="8194"/>
     285 <o:shapedefaults v:ext="edit" spidmax="9218"/>
    258286</xml><![endif]--><!--[if gte mso 9]><xml>
    259287 <o:shapelayout v:ext="edit">
    … …  
    353381  </td>
    354382  <td style='padding:.75pt .75pt .75pt .75pt'>
    355   <p class=MsoNormal><st1:date Year="2001" Day="5" Month="7">05-Jul-2001</st1:date></p>
     383  <p class=MsoNormal><st1:date Month="7" Day="5" Year="2001">05-Jul-2001</st1:date></p>
    356384  </td>
    357385 </tr>
    … …  
    363391  <td style='padding:.75pt .75pt .75pt .75pt'>
    364392  <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>
     393  at ga.gov.au&gt; and Duncan Gray &lt;<span class=SpellE>Duncan.gray</span> at
     394  ga.gov.au&gt;</p>
    367395  <p class=MsoNormal>Geoscience Australia 2005. </p>
    368396  <p class=MsoNormal>The GA modifications are clearly flagged using blue
    … …  
    386414<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
    387415class=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><span style='mso-spacerun:yes'> </span>Guide <span
     416class=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
    389417class=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
    390418class=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
    … …  
    399427class=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
    400428class=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 style='mso-spacerun:yes'>     </span>(<span
     429class=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
    402430class=GramE>maybe</span> for historic reasons) -- <span class=GramE>although</span> this is also an</pre><pre><span style='mso-spacerun:yes'>        </span><span
    403431class=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>
    … …  
    405433<h3>Code lay-out</h3>
    406434
    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
    408 class=SpellE>Emacs</span>' Python-mode: 4 spaces for one</pre><pre><span style='mso-spacerun:yes'>    </span><span
     435<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 Emacs' Python-mode: 4 spaces for one</pre><pre><span style='mso-spacerun:yes'>    </span><span
    409436class=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
    410 class=GramE>mess</span> up, you can continue to use 8-space tabs.<span style='mso-spacerun:yes'>  </span><span
    411 class=SpellE>Emacs</span> Python-mode</pre><pre><span style='mso-spacerun:yes'>    </span><span
     437class=GramE>mess</span> up, you can continue to use 8-space tabs.<span style='mso-spacerun:yes'>  </span>Emacs Python-mode</pre><pre><span style='mso-spacerun:yes'>    </span><span
    412438class=GramE>auto-</span>detects the prevailing indentation level used in a file and</pre><pre><span style='mso-spacerun:yes'>    </span><span
    413439class=GramE>sets</span> its indentation parameters accordingly.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span><span
    414440class=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
    415441class=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
    416 class=GramE>be</span> converted to using spaces exclusively.<span style='mso-spacerun:yes'>  </span>(In <span
    417 class=SpellE>Emacs</span>, select the</pre><pre><span style='mso-spacerun:yes'>    </span><span
     442class=GramE>be</span> converted to using spaces exclusively.<span style='mso-spacerun:yes'>  </span>(In Emacs, select the</pre><pre><span style='mso-spacerun:yes'>    </span><span
    418443class=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
    419444class=GramE>command</span> line interpreter with the -t option, it issues warnings</pre><pre><span style='mso-spacerun:yes'>    </span><span
    … …  
    421446class=SpellE>tt</span></pre><pre><span style='mso-spacerun:yes'>    </span><span
    422447class=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
    423 class=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
    424 class=SpellE>Emacs</span>,</pre><pre><span style='mso-spacerun:yes'>    </span><span
     448class=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 Emacs,</pre><pre><span style='mso-spacerun:yes'>    </span><span
    425449class=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
    426450class=GramE>character</span> lines; plus, limiting windows to 80 characters makes it</pre><pre><span style='mso-spacerun:yes'>    </span><span
    427451class=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
    428452class=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
    429 class=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
     453class=GramE>lines</span> to a maximum of 79 characters (Emacs wraps lines that are</pre><pre><span style='mso-spacerun:yes'>    </span><span
    430454class=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
    431455class=SpellE>docstrings</span> or comments), limiting the length to 72 characters is</pre><pre><span style='mso-spacerun:yes'>    </span><span
    … …  
    433457class=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
    434458class=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
    435 class=GramE>sure</span> to indent the continued line appropriately.<span style='mso-spacerun:yes'>  </span><span
    436 class=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
     459class=GramE>sure</span> to indent the continued line appropriately.<span style='mso-spacerun:yes'>  </span>Emacs</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
    437460class=GramE>class</span> Rectangle(Blob):</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
    438461class=GramE>def</span> __init__(self, width, height,</pre><pre><span style='mso-spacerun:yes'>                     </span><span
    … …  
    442465class=GramE>highlight</span> &gt; 100:</pre><pre><span style='mso-spacerun:yes'>                </span><span
    443466class=GramE>raise</span> <span class=SpellE>ValueError</span>(&quot;sorry, you lose&quot;)</pre><pre><span style='mso-spacerun:yes'>            </span><span
    444 class=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
     467class=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 style='mso-spacerun:yes'>                     </span><span
    445468class=GramE>emphasis</span> is None):</pre><pre><span style='mso-spacerun:yes'>                </span><span
    446469class=GramE>raise</span> <span class=SpellE>ValueError</span>(&quot;I don't think so&quot;)</pre><pre><span style='mso-spacerun:yes'>            </span><span
    … …  
    454477class=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
    455478class=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><span style='mso-spacerun:yes'> </span>Use blank lines in functions, <s>sparingly</s> <i
     479class=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
    457480style='mso-bidi-font-style:normal'><span style='color:blue'>liberally</span></i>, to indicate logical</pre><pre><span style='mso-spacerun:yes'>    </span><span
    458481class=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>whitespace</span>; <span class=SpellE>Emacs</span> (and some printing tools) treat these</pre><pre><span style='mso-spacerun:yes'>    </span><span
     482class=SpellE>whitespace</span>; Emacs (and some printing tools) treat these</pre><pre><span style='mso-spacerun:yes'>    </span><span
    460483class=GramE>characters</span> as page separators, so you may use them to separate</pre><pre><span style='mso-spacerun:yes'>    </span><span
    461484class=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
    … …  
    490513class=GramE>and</span> before module <span class=SpellE>globals</span> and constants.<span style='mso-spacerun:yes'>  </span>Imports should be grouped, </pre><pre
    491514style='margin-left:24.0pt'><span style='mso-spacerun:yes'>  </span><span
    492 class=GramE>with</span> the order being</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>1. <span
     515class=GramE>with</span> the order being</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span><span style='mso-spacerun:yes'>    </span>1. <span
    493516class=GramE>standard</span> library imports</pre><pre><span style='mso-spacerun:yes'>      </span>2. <span
    494517class=GramE>related</span> major package imports (i.e. all email package imports next)</pre><pre><span style='mso-spacerun:yes'>      </span>3. <span
    … …  
    522545class=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
    523546class=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
    524 class=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
    525 class=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
    526 class=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
     547class=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><span
     548lang=ES style='mso-ansi-language:ES'>&quot;<span class=SpellE>if</span> x == <span
     549class=GramE>4 :</span> <span class=SpellE>print</span> x , y ; x , y = y , x&quot;.<span style='mso-spacerun:yes'>  </span></span>Always write this as</pre><pre><span style='mso-spacerun:yes'>      </span><span
     550lang=ES style='mso-ansi-language:ES'>&quot;<span class=SpellE>if</span> x == 4: <span
     551class=SpellE>print</span> x, y; x, y = y, x&quot;.<o:p></o:p></span></pre><pre><span
     552lang=ES style='mso-ansi-language:ES'><o:p>&nbsp;</o:p></span></pre><pre><span
     553lang=ES style='mso-ansi-language:ES'><span style='mso-spacerun:yes'>    </span></span>- Immediately before the open parenthesis that starts the argument</pre><pre><span style='mso-spacerun:yes'>      </span><span
    527554class=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
    528555class=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
    529556class=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
    530557class=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><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
     558class=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
     559class=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
    533560class=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
    534561class=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
    … …  
    538565class=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
    539566class=SpellE>i</span> = i+1</pre><pre><span style='mso-spacerun:yes'>          </span><span
    540 class=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
    541 class=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
     567class=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><span
     568lang=ES style='mso-ansi-language:ES'>hypot2 = <span class=SpellE>x*x</span> + <span
     569class=SpellE>y*y</span><o:p></o:p></span></pre><pre><span lang=ES
     570style='mso-ansi-language:ES'><span style='mso-spacerun:yes'>          </span>c = (<span
     571class=SpellE>a+b</span>) * (a-b)<o:p></o:p></span></pre><pre><span lang=ES
     572style='mso-ansi-language:ES'><span style='mso-spacerun:yes'>          </span></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
    542573class=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
     574class=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
    544575class=GramE>return</span> magic(r=real, <span class=SpellE>i</span>=<span
    545576class=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
    … …  
    548579class=GramE>thing</span></span><span class=GramE>()</span></pre><pre><span style='mso-spacerun:yes'>          </span>Yes: if <span
    549580class=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>No:<span style='mso-spacerun:yes'>  </span><span
     581class=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
    551582class=SpellE>do_<span class=GramE>one</span></span><span class=GramE>(</span>); <span
    552583class=SpellE>do_two</span>(); <span class=SpellE>do_three</span>()</pre><pre><span style='mso-spacerun:yes'>          </span>Yes: <span
    … …  
    564595class=GramE>out</span> of complete sentences, and each sentence should end in a</pre><pre><span style='mso-spacerun:yes'>    </span><span
    565596class=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
    566 class=GramE>makes</span> <span class=SpellE>Emacs</span> wrapping and filling work <span
    567 class=SpellE>consistenty</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>When writing English, <span
     597class=GramE>makes</span> Emacs wrapping and filling work <span class=SpellE>consistenty</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>When writing English, <span
    568598class=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
    569599class=GramE>your</span> comments in English, unless you are 120% sure that the code</pre><pre><span style='mso-spacerun:yes'>    </span><span
    … …  
    587617class=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
    588618style='margin-top:0cm;margin-right:12.0pt;margin-bottom:0cm;margin-left:12.0pt;
    589 margin-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
     619margin-bottom:.0001pt'><span style='mso-spacerun:yes'>    </span>#FIXME (DSG): Should check that function returns something sensible and</pre><pre><span style='mso-spacerun:yes'>      </span>#<span
    590620class=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
    591621class=GramE>the</span> added bonus of knowing who logged the issue.</pre><pre><o:p>&nbsp;</o:p></pre>
    … …  
    605635style='color:blue'>Ideally, all modules, functions, classes, and methods should have <o:p></o:p></span></i></pre><pre><i
    606636style='mso-bidi-font-style:normal'><span style='color:blue'><span style='mso-spacerun:yes'>      </span><span
    607 class=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
     637class=GramE>a</span> <span class=SpellE>docstring</span>.<o:p></o:p></span></i></pre><pre><i
     638style='mso-bidi-font-style:normal'><span style='color:blue'> <span style='mso-spacerun:yes'>   </span>- For test methods #’s are preferred, over <span
     639class=SpellE>docstrings</span>.<span style='mso-spacerun:yes'>  </span><span
     640class=SpellE>Docstrings</span> don’t <o:p></o:p></span></i></pre><pre><i
     641style='mso-bidi-font-style:normal'><span style='color:blue'><span
     642style='mso-tab-count:1'>      </span>work well with verbose=2. <o:p></o:p></span></i></pre><pre><i
     643style='mso-bidi-font-style:normal'><span style='color:blue'><o:p>&nbsp;</o:p></span></i></pre><pre><i
     644style='mso-bidi-font-style:normal'><span style='color:blue'><o:p>&nbsp;</o:p></span></i></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <a
    608645href="http://www.python.org/peps/pep-0257.html">PEP 257</a> describes good <span
    609646class=SpellE>docstring</span> conventions.<span style='mso-spacerun:yes'>  </span>Note that most</pre><pre><span style='mso-spacerun:yes'>      </span><span
    … …  
    613650class=SpellE>foobang</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Optional <span
    614651class=SpellE>plotz</span> says to <span class=SpellE>frobnicate</span> the <span
    615 class=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
     652class=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
    616653class=SpellE>docstrings</span>, it's okay to keep the closing &quot;&quot;&quot; on</pre><pre><span style='mso-spacerun:yes'>      </span><span
    617654class=GramE>the</span> same line.</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
    … …  
    647684class=GramE>character</span>!)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <span
    648685class=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
    649 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 style='mso-spacerun:yes'> </span><span
     686class=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
    650687class=GramE>is</span> mentioned for completeness.<span style='mso-spacerun:yes'>  </span>For example, the <span
    651688class=SpellE><span class=GramE>os.stat</span></span><span class=GramE>()</span></pre><pre><span style='mso-spacerun:yes'>    </span><span
    … …  
    697734class=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
    698735class=GramE><i style='mso-bidi-font-style:normal'><span style='color:blue'>possibly</span></i></span><i
    699 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><span style='mso-spacerun:yes'>  </span>Almost without exception, class names use the <span
     736style='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
    700737class=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
    701738class=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
    … …  
    769806class=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
    770807class=GramE>variable</span> or argument that defaults to None was set to some other</pre><pre><span style='mso-spacerun:yes'>      </span><span
    771 class=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
     808class=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
    772809class=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
    773810class=GramE>domain-specific</span> base exception class, which should be subclassed</pre><pre><span style='mso-spacerun:yes'>      </span><span
    … …  
    806843class=GramE>from</span> types import <span class=SpellE>StringTypes</span></pre><pre><span style='mso-spacerun:yes'>        </span><span
    807844class=GramE>if</span> <span class=SpellE>isinstance</span>(obj, <span
    808 class=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
     845class=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
    809846class=GramE>from</span> types import <span class=SpellE>StringType</span>, <span
    810847class=SpellE>UnicodeType</span></pre><pre><span style='mso-spacerun:yes'>        </span><span
    … …  
    842879class=SpellE>Docstring</span> Conventions, <span class=SpellE>Goodger</span>, <span
    843880class=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
    844 href="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
     881href="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><span style='mso-spacerun:yes'>  </span><a
    845882href="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>
    846883

  • documentation/user_manual/anuga_user_manual.tex

    r3441 r3449  
    1313%Figures \label{fig: }
    1414
     15% Is latex failing with;
     16% `modanuga_user_manual.ind' not found?
     17% try this command-line
     18%   makeindex modanuga_user_manual.idx
     19% To produce the modanuga_user_manual.ind file.
    1520
    1621
    … …  
    14631468\begin{itemize}
    14641469\item \code{indices} which is a list of ids of triangles to which set\_quantity should apply its assignment of values.
    1465 \item \code{location} determines which part of the triangles to assign to. Options are 'vertices' (default), 'edges', and 'centroids'.
     1470\item \code{location} determines which part of the triangles to assign
     1471  to. Options are 'vertices' (default), 'edges', 'unique vertices', and 'centroids'.
    14661472\end{itemize}
    1467 
    1468 
    1469 \end{methoddesc}
    1470 
    1471 
    1472 
    1473 
    1474 
    1475 
    14761473
    14771474%%%
    14781475\anuga provides a number of predefined initial conditions to be used
    14791476with \code{set\_quantity}.
     1477
     1478\end{methoddesc}
     1479
     1480
     1481
     1482
     1483\begin{funcdesc}{set_region}{tag, quantity, X, location='vertices'}
     1484  Module: \module{pyvolution.domain}
     1485  (see also \module{pyvolution.region.Set\_region})
     1486  (see also \module{pyvolution.quantity.set\_values})
     1487 
     1488This function is used to assign values to individual quantities given
     1489a regional tag.   It is similar to set\_quantity.
     1490For example, if in pmesh a regional tag of 'ditch' was
     1491used, set\_region can be used to set elevation of this region to
     1492-10m. X is the constant or function to be applied to the quantity,
     1493over the tagged region.  Location describes how the values will be
     1494applied.  Options are 'vertices' (default), 'edges', 'unique
     1495vertices', and 'centroids'.
     1496
     1497This method can also be called with a list of region objects.  This is
     1498useful for adding quantities in regions, and having one quantity
     1499value based on another quantity. See  \module{pyvolution.region} for
     1500more details.
     1501\end{funcdesc}
     1502
     1503
     1504
    14801505
    14811506\begin{funcdesc}{slump_tsunami}{length, depth, slope, width=None, thickness=None,
Note: See TracChangeset for help on using the changeset viewer.