[1981] | 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" |
---|
| 4 | xmlns:o="urn:schemas-microsoft-com:office:office" |
---|
| 5 | xmlns:w="urn:schemas-microsoft-com:office:word" |
---|
| 6 | xmlns:st1="urn:schemas-microsoft-com:office:smarttags" |
---|
| 7 | xmlns="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 |
---|
| 15 | href="Style%20Guide%20for%20Python%20Code,%20GA%20version_files/filelist.xml"> |
---|
| 16 | <link rel=Edit-Time-Data |
---|
| 17 | href="Style%20Guide%20for%20Python%20Code,%20GA%20version_files/editdata.mso"> |
---|
| 18 | <!--[if !mso]> |
---|
| 19 | <style> |
---|
| 20 | v\:* {behavior:url(#default#VML);} |
---|
| 21 | o\:* {behavior:url(#default#VML);} |
---|
| 22 | w\:* {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" |
---|
[2419] | 28 | name="date"/> |
---|
| 29 | <o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags" |
---|
[1981] | 30 | name="country-region"/> |
---|
| 31 | <o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags" |
---|
| 32 | name="place"/> |
---|
| 33 | <!--[if gte mso 9]><xml> |
---|
| 34 | <o:DocumentProperties> |
---|
| 35 | <o:Author>nielsen ole</o:Author> |
---|
[2419] | 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> |
---|
[1981] | 41 | <o:Pages>1</o:Pages> |
---|
[2419] | 42 | <o:Words>4006</o:Words> |
---|
| 43 | <o:Characters>22839</o:Characters> |
---|
[1981] | 44 | <o:Company>Geoscience Australia</o:Company> |
---|
[2419] | 45 | <o:Lines>190</o:Lines> |
---|
| 46 | <o:Paragraphs>53</o:Paragraphs> |
---|
| 47 | <o:CharactersWithSpaces>26792</o:CharactersWithSpaces> |
---|
[1981] | 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> |
---|
| 59 | st1\:*{behavior:url(#ieooui) } |
---|
| 60 | </style> |
---|
| 61 | <![endif]--> |
---|
| 62 | <link rel=Stylesheet type="text/css" media=all |
---|
| 63 | href="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";} |
---|
| 75 | h3 |
---|
| 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;} |
---|
| 83 | a:link, span.MsoHyperlink |
---|
| 84 | {color:blue; |
---|
| 85 | text-decoration:underline; |
---|
| 86 | text-underline:single;} |
---|
| 87 | a:visited, span.MsoHyperlinkFollowed |
---|
| 88 | {color:blue; |
---|
| 89 | text-decoration:underline; |
---|
| 90 | text-underline:single;} |
---|
| 91 | pre |
---|
| 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";} |
---|
| 98 | p.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";} |
---|
| 108 | p.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";} |
---|
| 115 | p.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";} |
---|
| 123 | p.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";} |
---|
| 134 | p.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";} |
---|
| 145 | p.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";} |
---|
| 156 | p.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";} |
---|
| 167 | span.SpellE |
---|
| 168 | {mso-style-name:""; |
---|
| 169 | mso-spl-e:yes;} |
---|
| 170 | span.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;} |
---|
| 179 | div.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;} |
---|
| 230 | ol |
---|
| 231 | {margin-bottom:0cm;} |
---|
| 232 | ul |
---|
| 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]--><!-- |
---|
| 253 | This HTML is auto-generated. DO NOT EDIT THIS FILE! If you are writing a new |
---|
| 254 | PEP, see http://www.python.org/peps/pep-0001.html for instructions and links |
---|
| 255 | to templates. DO NOT USE THIS HTML FILE AS YOUR TEMPLATE! |
---|
| 256 | --><!--[if gte mso 9]><xml> |
---|
[2419] | 257 | <o:shapedefaults v:ext="edit" spidmax="8194"/> |
---|
[1981] | 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> </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: <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: <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: <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: <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> <<span |
---|
| 327 | class=SpellE>guido</span> at python.org>, Barry Warsaw <<span |
---|
| 328 | class=SpellE>barry</span> at python.org></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: <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: <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: <o:p></o:p></span></b></p> |
---|
| 353 | </td> |
---|
| 354 | <td style='padding:.75pt .75pt .75pt .75pt'> |
---|
[2419] | 355 | <p class=MsoNormal><st1:date Year="2001" Day="5" Month="7">05-Jul-2001</st1:date></p> |
---|
[1981] | 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: <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 <<span class=SpellE>Ole.Nielsen</span> |
---|
| 365 | at <span class=SpellE>ga.gov.au</span>> and Duncan Gray <<span |
---|
| 366 | class=SpellE>Duncan.gray</span> at <span class=SpellE>ga.gov.au</span>></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 |
---|
| 387 | class=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 |
---|
[2419] | 388 | class=GramE>guidelines</span> for the C code in the C implementation of Python[1].</pre><pre><o:p> </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 |
---|
[1981] | 389 | class=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 |
---|
| 390 | class=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 |
---|
| 391 | class=GramE>be</span> finished <wink>).</pre><pre><o:p> </o:p></pre><pre><o:p> </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 |
---|
| 396 | class=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 |
---|
| 397 | class=GramE>important</span>. Consistency within one module or function is most</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 398 | class=GramE>important</span>.</pre><pre><o:p> </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 |
---|
| 399 | class=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 |
---|
| 400 | class=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> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Two good reasons to break a particular rule:</pre><pre><o:p> </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 |
---|
[2419] | 401 | class=GramE>for</span> someone who is used to reading code that follows the rules.</pre><pre><o:p> </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 |
---|
[1981] | 402 | class=GramE>maybe</span> for historic reasons) -- <span class=GramE>although</span> this is also an</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 403 | class=GramE>opportunity</span> to clean up someone else's mess (in true XP style).</pre><pre><o:p> </o:p></pre><pre><o:p> </o:p></pre> |
---|
| 404 | |
---|
| 405 | <h3>Code lay-out</h3> |
---|
| 406 | |
---|
| 407 | <pre><span style='mso-spacerun:yes'> </span>Indentation</pre><pre><o:p> </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 |
---|
| 409 | class=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 |
---|
| 412 | class=GramE>auto-</span>detects the prevailing indentation level used in a file and</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 413 | class=GramE>sets</span> its indentation parameters accordingly.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 414 | class=GramE>Tabs or Spaces?</span></pre><pre><o:p> </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 |
---|
| 415 | class=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 |
---|
| 418 | class=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 |
---|
| 419 | class=GramE>command</span> line interpreter with the -t option, it issues warnings</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 420 | class=GramE>about</span> code that illegally mixes tabs and spaces.<span style='mso-spacerun:yes'> </span>When using -<span |
---|
| 421 | class=SpellE>tt</span></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 422 | class=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> </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 |
---|
| 425 | class=GramE>make</span> sure indent-tabs-mode is nil).</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Maximum Line Length</pre><pre><o:p> </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 |
---|
| 426 | class=GramE>character</span> lines; plus, limiting windows to 80 characters makes it</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 427 | class=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 |
---|
| 428 | class=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 |
---|
| 430 | class=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 |
---|
[2419] | 431 | class=SpellE>docstrings</span> or comments), limiting the length to 72 characters is</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
[1981] | 432 | class=GramE>recommended</span>.</pre><pre><o:p> </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 |
---|
| 433 | class=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 |
---|
| 434 | class=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> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 437 | class=GramE>class</span> Rectangle(Blob):</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 438 | class=GramE>def</span> __init__(self, width, height,</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
[2419] | 439 | class=SpellE>color</span>='black', emphasis=None, highlight=0):</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
[1981] | 440 | class=GramE>if</span> width == 0 and height == 0 and \</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
[2419] | 441 | class=SpellE>color</span> == 'red' and emphasis == 'strong' or \</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
[1981] | 442 | class=GramE>highlight</span> > 100:</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 443 | class=GramE>raise</span> <span class=SpellE>ValueError</span>("sorry, you lose")</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 |
---|
| 445 | class=GramE>emphasis</span> is None):</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 446 | class=GramE>raise</span> <span class=SpellE>ValueError</span>("I don't think so")</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 447 | class=SpellE>Blob.__init</span>_<span class=GramE>_(</span>self, width, height,</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
[2419] | 448 | class=SpellE>color</span>, emphasis, highlight)</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Blank Lines</pre><pre><o:p> </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 |
---|
[1981] | 449 | class=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 |
---|
| 450 | class=GramE>single</span> blank line.<span style='mso-spacerun:yes'> </span>Extra blank lines may be used (<s>sparingly</s> <i |
---|
| 451 | style='mso-bidi-font-style:normal'><span style='color:blue'>liberally</span></i>) to</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 452 | class=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 |
---|
| 453 | class=GramE>between</span> a bunch of related one-liners (e.g. a set of dummy</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 454 | class=GramE>implementations</span>).</pre><pre><o:p> </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 |
---|
| 455 | class=GramE>also</span> a blank line between the `class' line and the first method</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
[2419] | 456 | class=GramE>definition</span>.</pre><pre><o:p> </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 |
---|
[1981] | 457 | style='mso-bidi-font-style:normal'><span style='color:blue'>liberally</span></i>, to indicate logical</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 458 | class=GramE>sections</span>.</pre><pre><o:p> </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 |
---|
[2419] | 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 |
---|
[1981] | 460 | class=GramE>characters</span> as page separators, so you may use them to separate</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 461 | class=GramE>pages</span> of related sections of your file.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Encodings (<a |
---|
| 462 | href="http://www.python.org/peps/pep-0263.html">PEP 263</a>)</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Code in the core Python distribution should <span |
---|
| 463 | class=SpellE>aways</span> use the ASCII or</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 464 | class=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 |
---|
| 465 | class=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 |
---|
| 466 | class=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 |
---|
| 467 | class=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 |
---|
| 468 | class=GramE>for</span> those files that are part of the test suite for the code</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 469 | class=GramE>implementing</span> <a |
---|
| 470 | href="http://www.python.org/peps/pep-0263.html">PEP 263</a>.</pre><pre><o:p> </o:p></pre><pre><o:p> </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> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>No:<span style='mso-spacerun:yes'> </span>import sys, <span |
---|
| 475 | class=SpellE>os</span></pre><pre><span style='mso-spacerun:yes'> </span>Yes: import sys</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 476 | class=GramE>import</span> <span class=SpellE>os</span></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 477 | class=GramE>it's</span> okay to say this though:</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 478 | class=GramE>from</span> types import <span class=SpellE>StringType</span>, <span |
---|
| 479 | class=SpellE>ListType</span></pre><pre><o:p> </o:p></pre><pre |
---|
| 480 | style='margin-left:42.0pt;text-indent:-18.0pt;mso-list:l0 level1 lfo2'><![if !supportLists]><span |
---|
| 481 | style='mso-fareast-font-family:"Courier New"'><span style='mso-list:Ignore'>-<span |
---|
| 482 | style='font:7.0pt "Times New Roman"'> </span></span></span><![endif]><span style='mso-spacerun:yes'> </span>Imports are always put at the top of the file (<i |
---|
| 483 | style='mso-bidi-font-style:normal'><span style='color:blue'>or top of <o:p></o:p></span></i></pre><pre |
---|
| 484 | style='margin-left:24.0pt'><i style='mso-bidi-font-style:normal'><span |
---|
| 485 | style='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 |
---|
| 486 | style='margin-left:24.0pt'><i style='mso-bidi-font-style:normal'><span |
---|
| 487 | style='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 |
---|
| 488 | class=SpellE>docstrings</span>, </pre><pre style='margin-left:24.0pt'><i |
---|
| 489 | style='mso-bidi-font-style:normal'><span style='color:blue'><span style='mso-spacerun:yes'> </span></span></i><span |
---|
| 490 | class=GramE>and</span> before module <span class=SpellE>globals</span> and constants.<span style='mso-spacerun:yes'> </span>Imports should be grouped, </pre><pre |
---|
| 491 | style='margin-left:24.0pt'><span style='mso-spacerun:yes'> </span><span |
---|
| 492 | class=GramE>with</span> the order being</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>1. <span |
---|
| 493 | class=GramE>standard</span> library imports</pre><pre><span style='mso-spacerun:yes'> </span>2. <span |
---|
| 494 | class=GramE>related</span> major package imports (i.e. all email package imports next)</pre><pre><span style='mso-spacerun:yes'> </span>3. <span |
---|
[2419] | 495 | class=GramE>application</span> specific imports</pre><pre><o:p> </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> </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 |
---|
[1981] | 496 | class=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 |
---|
| 497 | class=GramE>imports</span>. <i style='mso-bidi-font-style:normal'><span |
---|
| 498 | style='color:blue'>Package imports should be relative to a directory on the PYTHONPATH.</span></i> </pre><pre><o:p> </o:p></pre><pre><o:p> </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 |
---|
| 499 | class=GramE>okay</span> to spell this</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 500 | class=GramE>from</span> <span class=SpellE>MyClass</span> import <span |
---|
| 501 | class=SpellE>MyClass</span></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 502 | class=GramE>from</span> <span class=SpellE>foo.bar.YourClass</span> import <span |
---|
| 503 | class=SpellE>YourClass</span></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>If this spelling causes local name clashes, then spell them</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 504 | class=GramE>import</span> <span class=SpellE>MyClass</span></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 505 | class=GramE>import</span> <span class=SpellE>foo.bar.YourClass</span></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 506 | class=GramE>and</span> use "<span class=SpellE>MyClass.MyClass</span>" and "<span |
---|
| 507 | class=SpellE>foo.bar.YourClass.YourClass</span>"</pre><pre><span |
---|
| 508 | style='mso-tab-count:1'> </span></pre><pre style='margin-left:24.0pt'><span |
---|
| 509 | style='mso-tab-count:1'> </span><i style='mso-bidi-font-style:normal'><span |
---|
| 510 | style='color:blue'>Using import * is discouraged except for special cases like <o:p></o:p></span></i></pre><pre |
---|
| 511 | style='margin-left:24.0pt'><i style='mso-bidi-font-style:normal'><span |
---|
| 512 | style='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 |
---|
| 513 | style='margin-left:24.0pt'><i style='mso-bidi-font-style:normal'><span |
---|
| 514 | style='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 |
---|
| 515 | style='margin-left:24.0pt'><i style='mso-bidi-font-style:normal'><span |
---|
| 516 | style='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> </o:p></pre><pre><o:p> </o:p></pre><pre><o:p> </o:p></pre><pre><o:p> </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 |
---|
| 519 | class=SpellE>Whitespace</span> in Expressions and Statements</h3> |
---|
| 520 | |
---|
| 521 | <pre><span style='mso-spacerun:yes'> </span>Pet Peeves</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Guido hates <span |
---|
| 522 | class=SpellE>whitespace</span> in the following places:</pre><pre><o:p> </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>"<span |
---|
| 523 | class=GramE>spam(</span> ham[ 1 ], { eggs: 2 } )".<span style='mso-spacerun:yes'> </span>Always write this as</pre><pre><span style='mso-spacerun:yes'> </span>"<span |
---|
| 524 | class=GramE>spam(</span>ham[1], {eggs: 2})".</pre><pre><o:p> </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 |
---|
| 525 | class=GramE>if</span> x == 4 : print x , y ; x , y = y , x".<span style='mso-spacerun:yes'> </span>Always write this as</pre><pre><span style='mso-spacerun:yes'> </span>"<span |
---|
| 526 | class=GramE>if</span> x == 4: print x, y; x, y = y, x".</pre><pre><o:p> </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 |
---|
| 527 | class=GramE>list</span> of a function call, as in "spam (1)".<span style='mso-spacerun:yes'> </span>Always write</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 528 | class=GramE>this</span> as "spam(1)".</pre><pre><o:p> </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 |
---|
| 529 | class=GramE>slicing</span>, as in: "<span class=SpellE>dict</span> ['key'] = list [index]".<span style='mso-spacerun:yes'> </span>Always</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 530 | class=GramE>write</span> this as "<span class=SpellE>dict</span>['key'] = list[index]".</pre><pre><o:p> </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 |
---|
[2419] | 531 | class=GramE>align</span> it with another, as in:</pre><pre><o:p> </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> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Always write this as</pre><pre><o:p> </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 |
---|
[1981] | 533 | class=SpellE>long_variable</span> = 3</pre><pre><o:p> </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 |
---|
| 534 | class=GramE>grown</span> accustomed to this style over 20 years.)</pre><pre><o:p> </o:p></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Other Recommendations</pre><pre><o:p> </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 |
---|
| 535 | class=GramE>either</span> side: assignment (=), comparisons (==, <, >, !=, <>, <=,</pre><pre><span style='mso-spacerun:yes'> </span>>=, in, not in, is, is not), Booleans (and, or, not).</pre><pre><o:p> </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 |
---|
| 536 | class=GramE>arithmetic</span> operators.<span style='mso-spacerun:yes'> </span>Always be consistent about <span |
---|
| 537 | class=SpellE>whitespace</span> on</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 538 | class=GramE>either</span> side of a binary operator.<span style='mso-spacerun:yes'> </span>Some examples:</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 539 | class=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> </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 |
---|
| 542 | class=GramE>keyword</span> argument or a default parameter value.<span style='mso-spacerun:yes'> </span>For instance:</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
[2419] | 543 | class=GramE>def</span> complex(real, <span class=SpellE>imag</span>=0.0):</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
[1981] | 544 | class=GramE>return</span> magic(r=real, <span class=SpellE>i</span>=<span |
---|
| 545 | class=SpellE>imag</span>)</pre><pre><o:p> </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 |
---|
| 546 | class=GramE>generally</span> discouraged.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>No:<span style='mso-spacerun:yes'> </span>if <span |
---|
| 547 | class=SpellE>foo</span> == 'blah': <span class=SpellE>do_blah_<span |
---|
| 548 | class=GramE>thing</span></span><span class=GramE>()</span></pre><pre><span style='mso-spacerun:yes'> </span>Yes: if <span |
---|
| 549 | class=SpellE>foo</span> == 'blah':</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
[2419] | 550 | class=SpellE>do_blah_<span class=GramE>thing</span></span><span class=GramE>()</span></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>No:<span style='mso-spacerun:yes'> </span><span |
---|
[1981] | 551 | class=SpellE>do_<span class=GramE>one</span></span><span class=GramE>(</span>); <span |
---|
| 552 | class=SpellE>do_two</span>(); <span class=SpellE>do_three</span>()</pre><pre><span style='mso-spacerun:yes'> </span>Yes: <span |
---|
| 553 | class=SpellE>do_<span class=GramE>one</span></span><span class=GramE>()</span></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 554 | class=SpellE>do_<span class=GramE>two</span></span><span class=GramE>()</span></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 555 | class=SpellE>do_<span class=GramE>three</span></span><span class=GramE>()</span></pre><pre><o:p> </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 |
---|
| 560 | class=GramE>code</span> changes!</pre><pre><o:p> </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 |
---|
| 561 | class=GramE>or</span> sentence, its first word should be capitalized, unless it is an</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 562 | class=GramE>identifier</span> that begins with a lower case letter (never alter the</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 563 | class=GramE>case</span> of identifiers!).</pre><pre><o:p> </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 |
---|
| 564 | class=GramE>out</span> of complete sentences, and each sentence should end in a</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 565 | class=GramE>period</span>.</pre><pre><o:p> </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> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>When writing English, <span |
---|
| 568 | class=SpellE>Strunk</span> and White apply.</pre><pre><o:p> </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 |
---|
| 569 | class=GramE>your</span> comments in English, unless you are 120% sure that the code</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 570 | class=GramE>will</span> never be read by people who don't speak your language.</pre><pre><o:p> </o:p></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Block Comments</pre><pre><o:p> </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 |
---|
| 571 | class=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 |
---|
| 572 | class=GramE>of</span> a block comment starts with a # and a single space (unless it</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 573 | class=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 |
---|
| 574 | class=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 |
---|
| 575 | class=GramE>comments</span> are best surrounded by a blank line above and below them</pre><pre><span style='mso-spacerun:yes'> </span>(<span |
---|
| 576 | class=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 |
---|
| 577 | class=GramE>the</span> start of a <span class=SpellE>a</span> new section of function definitions <i |
---|
| 578 | style='mso-bidi-font-style:normal'><span style='color:blue'>or to delimit <o:p></o:p></span></i></pre><pre><i |
---|
| 579 | style='mso-bidi-font-style:normal'><span style='color:blue'><span style='mso-spacerun:yes'> </span><span |
---|
| 580 | class=GramE>logical</span> sections</span></i>).</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Inline Comments</pre><pre><o:p> </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 |
---|
| 581 | class=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 |
---|
| 582 | class=GramE>should</span> start with a # and a single space.</pre><pre><o:p> </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 |
---|
[2419] | 583 | class=GramE>the</span> obvious.<span style='mso-spacerun:yes'> </span>Don't do this:</pre><pre><o:p> </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> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>But sometimes, this is useful:</pre><pre><o:p> </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> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Developer Comments</pre><pre><o:p> </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 |
---|
| 584 | class=GramE>useful</span> to comment the code to indicate those sections which require updating </pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 585 | class=GramE>or</span> refining. They should start with #FIXME followed by the name of the </pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 586 | class=GramE>developer</span> in standard brackets. The name should be consistent amongst the</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 587 | class=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> </o:p></pre><pre |
---|
| 588 | style='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 |
---|
| 590 | class=GramE>raise</span> a meaningful exception if it returns None for example</pre><pre><o:p> </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 |
---|
| 591 | class=GramE>the</span> added bonus of knowing who logged the issue.</pre><pre><o:p> </o:p></pre> |
---|
[1981] | 592 | |
---|
| 593 | <h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'>Documentation |
---|
| 594 | Strings</h3> |
---|
| 595 | |
---|
| 596 | <pre><span style='mso-spacerun:yes'> </span>Conventions for writing good documentation strings</pre><pre><span style='mso-spacerun:yes'> </span>(a.k.a. "<span |
---|
| 597 | class=SpellE>docstrings</span>") are immortalized in <a |
---|
| 598 | href="http://www.python.org/peps/pep-0257.html">PEP 257</a> [3].</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- Write <span |
---|
| 599 | class=SpellE>docstrings</span> for all public modules, functions, classes, and</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 600 | class=GramE>methods</span>.<span style='mso-spacerun:yes'> </span><span |
---|
| 601 | class=SpellE>Docstrings</span> are not necessary for non-public methods,</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 602 | class=GramE>but</span> you should have a comment that describes what the method</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 603 | class=GramE>does</span>.<span style='mso-spacerun:yes'> </span>This comment should appear after the "def" line.</pre><pre><span |
---|
| 604 | style='mso-tab-count:1'> </span><i style='mso-bidi-font-style:normal'><span |
---|
| 605 | style='color:blue'>Ideally, all modules, functions, classes, and methods should have <o:p></o:p></span></i></pre><pre><i |
---|
| 606 | style='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> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- <a |
---|
| 608 | href="http://www.python.org/peps/pep-0257.html">PEP 257</a> describes good <span |
---|
| 609 | class=SpellE>docstring</span> conventions.<span style='mso-spacerun:yes'> </span>Note that most</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 610 | class=GramE>importantly</span>, the """ that ends a <span |
---|
| 611 | class=SpellE>multiline</span> <span class=SpellE>docstring</span> should be</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 612 | class=GramE>on</span> a line by itself, e.g.:</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>"""Return a <span |
---|
| 613 | class=SpellE>foobang</span></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Optional <span |
---|
| 614 | class=SpellE>plotz</span> says to <span class=SpellE>frobnicate</span> the <span |
---|
[2419] | 615 | class=SpellE>bizbaz</span> first.</pre><pre><span style='mso-spacerun:yes'> </span><span style='mso-spacerun:yes'> </span>"""</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- For one liner <span |
---|
[1981] | 616 | class=SpellE>docstrings</span>, it's okay to keep the closing """ on</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 617 | class=GramE>the</span> same line.</pre><pre><o:p> </o:p></pre><pre><o:p> </o:p></pre> |
---|
| 618 | |
---|
| 619 | <h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'>Version |
---|
| 620 | Bookkeeping</h3> |
---|
| 621 | |
---|
| 622 | <pre><span style='mso-spacerun:yes'> </span>If you have to have RCS or CVS crud in your source file, do it as</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 623 | class=GramE>follows</span>.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>__version__ = "$Revision: 1.27 $"</pre><pre><span style='mso-spacerun:yes'> </span># $Source: /cvsroot/python/python/nondist/peps/pep-0008.txt,v $</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>These lines should be included after the module's <span |
---|
| 624 | class=SpellE>docstring</span>,</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 625 | class=GramE>before</span> any other code, separated by a blank line above and</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 626 | class=GramE>below</span>.</pre><pre><o:p> </o:p></pre><pre><o:p> </o:p></pre> |
---|
| 627 | |
---|
| 628 | <h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'>Naming |
---|
| 629 | Conventions</h3> |
---|
| 630 | |
---|
| 631 | <pre><span style='mso-spacerun:yes'> </span>The naming conventions of Python's library are a bit of a mess, so we'll</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 632 | class=GramE>never</span> get this completely consistent -- nevertheless, here are the</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 633 | class=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 |
---|
| 634 | class=GramE>including</span> 3rd party frameworks) should be written to these standards, but</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 635 | class=GramE>where</span> an existing library has a different style, internal consistency is</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 636 | class=GramE>preferred</span>.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Descriptive: Naming Styles</pre><pre><o:p> </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 |
---|
| 637 | class=GramE>to</span> recognize what naming style is being used, independently from</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 638 | class=GramE>what</span> they are used for.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>The following naming styles are commonly distinguished:</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- <span |
---|
| 639 | class=GramE>b</span> (single lowercase letter)</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- B (single uppercase letter)</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- <span |
---|
| 640 | class=GramE>lowercase</span></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- <span |
---|
| 641 | class=SpellE>lower_case_with_underscores</span></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- UPPERCASE</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- UPPER_CASE_WITH_UNDERSCORES</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- <span |
---|
| 642 | class=SpellE>CapitalizedWords</span> (or <span class=SpellE>CapWords</span>, or <span |
---|
| 643 | class=SpellE>CamelCase</span> -- so named because</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 644 | class=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 |
---|
| 645 | class=SpellE><span class=GramE>StudlyCaps</span></span><span class=GramE>.</span></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- <span |
---|
[2419] | 646 | class=SpellE>mixedCase</span> (differs from <span class=SpellE>CapitalizedWords</span> by initial lowercase</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
[1981] | 647 | class=GramE>character</span>!)</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- <span |
---|
| 648 | class=SpellE>Capitalized_Words_With_Underscores</span> (ugly!)</pre><pre><o:p> </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 |
---|
[2419] | 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 |
---|
[1981] | 650 | class=GramE>is</span> mentioned for completeness.<span style='mso-spacerun:yes'> </span>For example, the <span |
---|
| 651 | class=SpellE><span class=GramE>os.stat</span></span><span class=GramE>()</span></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 652 | class=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 |
---|
| 653 | class=SpellE><span class=GramE>st_mode</span></span><span class=GramE>, <span |
---|
| 654 | class=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 |
---|
| 655 | class=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 |
---|
| 656 | class=GramE>generally</span> deemed unnecessary because attribute and method names</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 657 | class=GramE>are</span> prefixed with an object, and function names are prefixed with</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 658 | class=GramE>a</span> module name.)</pre><pre><o:p> </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 |
---|
| 659 | class=GramE>underscores</span> are recognized (these can generally be combined with any</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 660 | class=GramE>case</span> convention):</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- _<span |
---|
| 661 | class=SpellE>single_leading_underscore</span>: weak "internal use" indicator</pre><pre><span style='mso-spacerun:yes'> </span>(e.g. "from M import *" does not import objects whose name</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 662 | class=GramE>starts</span> with an underscore).</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- <span |
---|
| 663 | class=SpellE>single_trailing_underscore</span>_: used by convention to avoid</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 664 | class=GramE>conflicts</span> with Python keyword, e.g.</pre><pre><span style='mso-spacerun:yes'> </span>"<span |
---|
| 665 | class=SpellE><span class=GramE>Tkinter.Toplevel</span></span><span class=GramE>(</span>master, class_='<span |
---|
| 666 | class=SpellE>ClassName</span>')".</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 667 | class=GramE>- __<span class=SpellE>double_leading_underscore</span>: class-private names as of Python 1.4.</span></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- __<span |
---|
| 668 | class=SpellE>double_leading_and_trailing_underscore</span>__: "magic" objects or</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 669 | class=GramE>attributes</span> that live in user-controlled namespaces,</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 670 | class=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 |
---|
| 671 | class=GramE>defined</span> by the user to trigger certain magic <span |
---|
| 672 | class=SpellE>behavior</span></pre><pre><span style='mso-spacerun:yes'> </span>(<span |
---|
| 673 | class=GramE>e.g</span>. operator overloading); sometimes these are inserted by the</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 674 | class=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 |
---|
| 675 | class=GramE>the</span> infrastructure (loosely defined as the Python interpreter</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 676 | class=GramE>and</span> the standard library) may decide to grow its list of magic</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 677 | class=GramE>attributes</span> in future versions, user code should generally</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 678 | class=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 |
---|
| 679 | class=GramE>that</span> aspires to become part of the infrastructure could combine</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 680 | class=GramE>this</span> with a short prefix inside the underscores,</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 681 | class=GramE>e.g. __<span class=SpellE>bobo_magic_attr</span>__.</span></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Prescriptive: Naming Conventions</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Names to Avoid</pre><pre><o:p> </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 |
---|
| 682 | class=GramE>uppercase</span> letter oh), or `I' (uppercase letter eye) as single</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 683 | class=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 |
---|
[2419] | 684 | class=SpellE>indistinguisable</span> from the numerals one and zero.<span style='mso-spacerun:yes'> </span>When tempted</pre><pre |
---|
[1981] | 685 | style='margin-left:12.0pt'><span style='mso-spacerun:yes'> </span><span |
---|
| 686 | class=GramE>to</span> use `l' use `L' instead, <i style='mso-bidi-font-style: |
---|
| 687 | normal'><span style='color:blue'>unless the mathematical formula <o:p></o:p></span></i></pre><pre |
---|
| 688 | style='margin-left:12.0pt'><i style='mso-bidi-font-style:normal'><span |
---|
| 689 | style='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> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Module Names</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Modules should have short, lowercase names, <s>without</s> <i |
---|
| 690 | style='mso-bidi-font-style:normal'><span style='color:blue'>possibly with</span></i> </pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 691 | class=GramE>underscores</span>.</pre><pre><o:p> </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 |
---|
| 692 | class=GramE>are</span> case insensitive and truncate long names, it is important that</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 693 | class=GramE>module</span> names be chosen to be fairly short -- this won't be a</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 694 | class=GramE>problem</span> on Unix, but it may be a problem when the code is</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 695 | class=GramE>transported</span> to Mac or Windows.</pre><pre><o:p> </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 |
---|
| 696 | class=GramE>oriented</span>) interface, the C/C++ module has a leading underscore</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 697 | class=GramE>(e.g. _socket).</span></pre><pre><o:p> </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 |
---|
| 698 | class=GramE><i style='mso-bidi-font-style:normal'><span style='color:blue'>possibly</span></i></span><i |
---|
[2419] | 699 | style='mso-bidi-font-style:normal'><span style='color:blue'> with</span></i> underscores.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Class Names</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span style='mso-spacerun:yes'> </span>Almost without exception, class names use the <span |
---|
[1981] | 700 | class=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> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Exception Names</pre><pre><o:p> </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 |
---|
| 701 | class=GramE>conditions</span>, it is generally called "error" or "Error".<span style='mso-spacerun:yes'> </span>It seems</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 702 | class=GramE>that</span> built-in (extension) modules use "error" (e.g. <span |
---|
| 703 | class=SpellE>os.error</span>),</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 704 | class=GramE>while</span> Python modules generally use "Error" (e.g. <span |
---|
| 705 | class=SpellE>xdrlib.Error</span>).</pre><pre><span style='mso-spacerun:yes'> </span>The trend seems to be toward <span |
---|
| 706 | class=SpellE>CapWords</span> exception names.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Global Variable Names</pre><pre><o:p> </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 |
---|
| 707 | class=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 |
---|
| 708 | class=GramE>functions</span>.<span style='mso-spacerun:yes'> </span>Modules that are designed for use via "from M import *"</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 709 | class=GramE>should</span> prefix their <span class=SpellE>globals</span> (and internal functions and classes)</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 710 | class=GramE>with</span> an underscore to prevent exporting them.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Function Names</pre><pre><o:p> </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 |
---|
| 711 | class=GramE>underscores</span> to improve readability.<span style='mso-spacerun:yes'> </span><span |
---|
[2419] | 712 | class=SpellE>mixedCase</span> is allowed only in</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
[1981] | 713 | class=GramE>contexts</span> where that's already the prevailing style (e.g. <span |
---|
| 714 | class=SpellE>threading.py</span>),</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 715 | class=GramE>to</span> retain backwards compatibility.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Method Names and Instance Variables</pre><pre><o:p> </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 |
---|
| 716 | class=GramE>lowercase</span> with words separated by underscores as necessary to improve</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
[2419] | 717 | class=GramE>readability</span>.</pre><pre><o:p> </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 |
---|
[1981] | 718 | class=GramE>variables</span> which are not intended to be part of the class's public</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 719 | class=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 |
---|
| 720 | class=GramE>respect</span> the convention.</pre><pre><o:p> </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>"<span |
---|
| 721 | class=GramE>mangles</span>" these names with the class name: if class <span |
---|
| 722 | class=SpellE>Foo</span> has an</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 723 | class=GramE>attribute</span> named __a, it cannot be accessed by <span |
---|
| 724 | class=SpellE>Foo.__a</span>.<span style='mso-spacerun:yes'> </span>(An insistent</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 725 | class=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 |
---|
| 726 | class=GramE>double</span> leading underscores should be used only to avoid name conflicts</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 727 | class=GramE>with</span> attributes in classes designed to be subclassed.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>Designing for inheritance</pre><pre><o:p> </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 |
---|
| 728 | class=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 |
---|
| 729 | class=GramE>variables</span> public unless you're implementing essentially a</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 730 | class=GramE>record</span>.<span style='mso-spacerun:yes'> </span>It's almost always <span |
---|
| 731 | class=SpellE>preferrable</span> to give a functional</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 732 | class=GramE>interface</span> to your class instead (and some Python 2.2</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 733 | class=GramE>developments</span> will make this much nicer). <i |
---|
| 734 | style='mso-bidi-font-style:normal'><span style='color:blue'>Consider using Pythons <o:p></o:p></span></i></pre><pre><i |
---|
| 735 | style='mso-bidi-font-style:normal'><span style='color:blue'><span style='mso-spacerun:yes'> </span><span |
---|
| 736 | class=GramE>properties</span>.<o:p></o:p></span></i></pre><pre><o:p> </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 |
---|
| 737 | class=GramE>will</span> never be useful for a derived class, while the latter might</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 738 | class=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 |
---|
| 739 | class=GramE>mind</span>!</pre><pre><o:p> </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 |
---|
| 740 | class=GramE>trailing</span> underscores.</pre><pre><o:p> </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 |
---|
| 741 | class=GramE>no</span> trailing underscores.</pre><pre><o:p> </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 |
---|
| 742 | class=GramE>underscores</span>, unless they conflict with reserved words, in which</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 743 | class=GramE>case</span>, a single trailing underscore is preferable to a leading</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 744 | class=GramE>one</span>, or a corrupted spelling, e.g. class_ rather than <span |
---|
| 745 | class=SpellE>klass</span>.</pre><pre><span style='mso-spacerun:yes'> </span>(This last point is a bit controversial; if you prefer <span |
---|
| 746 | class=SpellE>klass</span></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 747 | class=GramE>over</span> class_ then just be consistent. :).</pre><pre><o:p> </o:p></pre><pre><o:p> </o:p></pre> |
---|
| 748 | |
---|
| 749 | <h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'>Programming |
---|
| 750 | Recommendations</h3> |
---|
| 751 | |
---|
| 752 | <pre><span style='mso-spacerun:yes'> </span>- Code should be written in a way that does not disadvantage other</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 753 | class=GramE>implementations</span> of Python (<span class=SpellE>PyPy</span>, <span |
---|
| 754 | class=SpellE>Jython</span>, <span class=SpellE>IronPython</span>, Pyrex, <span |
---|
| 755 | class=SpellE>Psyco</span>,</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 756 | class=GramE>and</span> such).<span style='mso-spacerun:yes'> </span>For example, do not rely on <span |
---|
| 757 | class=SpellE>CPython's</span> efficient</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 758 | class=GramE>implementation</span> of in-place string concatenation for statements in</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 759 | class=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 |
---|
| 760 | class=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 |
---|
| 761 | class=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 |
---|
| 762 | class=GramE>concatenation</span> occurs in linear time across various implementations.</pre><pre><span |
---|
| 763 | style='mso-tab-count:1'> </span><i style='mso-bidi-font-style:normal'><span |
---|
| 764 | style='color:blue'>In performance insensitive part it is OK to use the more readable <o:p></o:p></span></i></pre><pre><i |
---|
| 765 | style='mso-bidi-font-style:normal'><span style='color:blue'><span style='mso-spacerun:yes'> </span><span |
---|
| 766 | class=GramE>a</span>+=b and a=<span class=SpellE>a+b</span>. <o:p></o:p></span></i></pre><pre><o:p> </o:p></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- Comparisons to singletons like <span |
---|
| 767 | class=GramE>None</span> should always be done with</pre><pre><span style='mso-spacerun:yes'> </span>'<span |
---|
| 768 | class=GramE>is</span>' or 'is not'.<span style='mso-spacerun:yes'> </span>Also, beware of writing "if x" when you</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 769 | class=GramE>really</span> mean "if x is not None" -- e.g. when testing whether a</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 770 | class=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> </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 |
---|
| 772 | class=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 |
---|
| 773 | class=GramE>domain-specific</span> base exception class, which should be subclassed</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 774 | class=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 |
---|
[2419] | 775 | class=SpellE>docstring</span>.<span style='mso-spacerun:yes'> </span>E.g.:</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
[1981] | 776 | class=GramE>class</span> <span class=SpellE>MessageError</span>(Exception):</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 777 | class=GramE>"""Base class for errors in the email package."""</span></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>When raising an exception, use "raise <span |
---|
| 778 | class=SpellE><span class=GramE>ValueError</span></span><span class=GramE>(</span>'message')"</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 779 | class=GramE>instead</span> of the older form "raise <span class=SpellE>ValueError</span>, 'message'".<span style='mso-spacerun:yes'> </span>The</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 780 | class=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 |
---|
| 781 | class=GramE>arguments</span> are long or include string formatting, you don't need</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 782 | class=GramE>to</span> use line continuation characters thanks to the containing</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 783 | class=GramE>parentheses</span>.<span style='mso-spacerun:yes'> </span>The older form will be removed in Python 3000.</pre><pre><o:p> </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 |
---|
| 784 | class=GramE>backward-compatibility</span> with versions earlier than Python 2.0 is</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 785 | class=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 |
---|
| 786 | class=GramE>same</span> API with <span class=SpellE>unicode</span> strings.</pre><pre><o:p> </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 |
---|
| 787 | class=SpellE><span class=GramE>startswith</span></span><span class=GramE>(</span>) and <span |
---|
| 788 | class=SpellE>endswith</span>() instead, since they are</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 789 | class=GramE>cleaner</span> and less error prone.<span style='mso-spacerun:yes'> </span>For example:</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>No:<span style='mso-spacerun:yes'> </span>if <span |
---|
| 790 | class=SpellE><span class=GramE>foo</span></span><span class=GramE>[</span>:3] == 'bar':</pre><pre><span style='mso-spacerun:yes'> </span>Yes: if <span |
---|
| 791 | class=SpellE><span class=GramE>foo.startswith</span></span><span class=GramE>(</span>'bar'):</pre><pre><o:p> </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 |
---|
| 792 | class=GramE>let's</span> hope not!).</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- Object type comparisons should always use <span |
---|
| 793 | class=SpellE><span class=GramE>isinstance</span></span><span class=GramE>(</span>) instead</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 794 | class=GramE>of</span> comparing types directly.<span style='mso-spacerun:yes'> </span><span |
---|
| 795 | class=GramE>E.g.</span></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>No:<span style='mso-spacerun:yes'> </span>if <span |
---|
| 796 | class=GramE>type(</span>obj) is type(1):</pre><pre><span style='mso-spacerun:yes'> </span>Yes: if <span |
---|
| 797 | class=SpellE><span class=GramE>isinstance</span></span><span class=GramE>(</span>obj, <span |
---|
| 798 | class=SpellE>int</span>):</pre><pre><o:p> </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 |
---|
| 799 | class=GramE>might</span> be a <span class=SpellE>unicode</span> string too!<span style='mso-spacerun:yes'> </span>In Python 2.3, <span |
---|
[2419] | 800 | class=SpellE>str</span> and <span class=SpellE>unicode</span></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
[1981] | 801 | class=GramE>have</span> a common base class, <span class=SpellE>basestring</span>, so you can do:</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 802 | class=GramE>if</span> <span class=SpellE>isinstance</span>(obj, <span |
---|
| 803 | class=SpellE>basestring</span>):</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>In Python 2.2, the <span |
---|
| 804 | class=GramE>types</span> module has the <span class=SpellE>StringTypes</span> type defined</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 805 | class=GramE>for</span> that purpose, e.g.:</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 806 | class=GramE>from</span> types import <span class=SpellE>StringTypes</span></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 807 | class=GramE>if</span> <span class=SpellE>isinstance</span>(obj, <span |
---|
[2419] | 808 | class=SpellE>StringTypes</span>):</pre><pre><o:p> </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> </o:p></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
[1981] | 809 | class=GramE>from</span> types import <span class=SpellE>StringType</span>, <span |
---|
[2419] | 810 | class=SpellE>UnicodeType</span></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
[1981] | 811 | class=GramE>if</span> <span class=SpellE>isinstance</span>(obj, <span |
---|
| 812 | class=SpellE>StringType</span>) or \</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 813 | class=SpellE><span class=GramE>isinstance</span></span><span class=GramE>(</span>obj, <span |
---|
| 814 | class=SpellE>UnicodeType</span>) :</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- For sequences, (strings, lists, <span |
---|
| 815 | class=SpellE>tuples</span>), use the fact that empty</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 816 | class=GramE>sequences</span> are false, so "if not <span class=SpellE>seq</span>" or "if <span |
---|
| 817 | class=SpellE>seq</span>" is preferable</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 818 | class=GramE>to</span> "if <span class=SpellE>len</span>(<span |
---|
| 819 | class=SpellE>seq</span>)" or "if not <span class=SpellE>len</span>(<span |
---|
| 820 | class=SpellE>seq</span>)".</pre><pre><span style='mso-spacerun:yes'> </span><i |
---|
| 821 | style='mso-bidi-font-style:normal'><span style='color:blue'>We prefer using if <span |
---|
| 822 | class=SpellE><span class=GramE>len</span></span><span class=GramE>(</span><span |
---|
| 823 | class=SpellE>seq</span>) == 0 to check for emptiness.<o:p></o:p></span></i></pre><pre><o:p> </o:p></pre><pre><o:p> </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 |
---|
[2419] | 824 | class=SpellE>whitespace</span>.<span style='mso-spacerun:yes'> </span>Such trailing <span |
---|
[1981] | 825 | class=SpellE>whitespace</span> is visually</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 826 | class=GramE>indistinguishable</span> and some editors (or more recently,</pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 827 | class=SpellE>reindent.py</span>) will trim them.</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>- Don't compare <span |
---|
[2419] | 828 | class=SpellE>boolean</span> values to True or False using == (<span |
---|
[1981] | 829 | class=SpellE>bool</span></pre><pre><span style='mso-spacerun:yes'> </span><span |
---|
| 830 | class=GramE>types</span> are new in Python 2.3):</pre><pre><o:p> </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 |
---|
| 831 | style='mso-tab-count:1'> </span><span style='mso-spacerun:yes'> </span><i |
---|
| 832 | style='mso-bidi-font-style:normal'><span style='color:blue'>Yes:<span |
---|
| 833 | style='mso-tab-count:1'> </span>if greeting is True:<o:p></o:p></span></i></pre><pre><o:p> </o:p></pre><pre><o:p> </o:p></pre> |
---|
| 834 | |
---|
| 835 | <h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'>References</h3> |
---|
| 836 | |
---|
| 837 | <pre><span style='mso-spacerun:yes'> </span>[1] <a |
---|
| 838 | href="http://www.python.org/peps/pep-0007.html">PEP 7</a>, Style Guide for C Code, van <span |
---|
| 839 | class=SpellE>Rossum</span></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>[2] <a |
---|
[2419] | 840 | href="http://www.python.org/doc/essays/styleguide.html">http://www.python.org/doc/essays/styleguide.html</a></pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>[3] <a |
---|
[1981] | 841 | href="http://www.python.org/peps/pep-0257.html">PEP 257</a>, <span |
---|
| 842 | class=SpellE>Docstring</span> Conventions, <span class=SpellE>Goodger</span>, <span |
---|
| 843 | class=GramE>van</span> <span class=SpellE>Rossum</span></pre><pre><o:p> </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> </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 |
---|
| 845 | href="http://barry.warsaw.us/software/STYLEGUIDE.txt">http://barry.warsaw.us/software/STYLEGUIDE.txt</a></pre><pre><o:p> </o:p></pre><pre><o:p> </o:p></pre> |
---|
| 846 | |
---|
| 847 | <h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'>Copyright</h3> |
---|
| 848 | |
---|
| 849 | <pre><span style='mso-spacerun:yes'> </span>This document has been placed in the public domain.</pre><pre><o:p> </o:p></pre><pre><o:p> </o:p></pre></div> |
---|
| 850 | |
---|
| 851 | </div> |
---|
| 852 | |
---|
| 853 | </body> |
---|
| 854 | |
---|
| 855 | </html> |
---|