diff options
| author | Sebastian Silva <sebastian@sugarlabs.org> | 2011-11-16 07:56:19 (GMT) |
|---|---|---|
| committer | Sebastian Silva <sebastian@sugarlabs.org> | 2011-11-16 07:56:19 (GMT) |
| commit | 82511a6fe2d29d50c1cdca4b2abb23ff681a1943 (patch) | |
| tree | ff6359d68287417abfaaf49e492e2630239e60c9 /studio/static/doc/flask-docs/styleguide.html | |
| parent | 61517139f02df2ce417f465dfabdbf5dbe8f4063 (diff) | |
Major improvements in IDE usability.
Diffstat (limited to 'studio/static/doc/flask-docs/styleguide.html')
| -rw-r--r-- | studio/static/doc/flask-docs/styleguide.html | 321 |
1 files changed, 0 insertions, 321 deletions
diff --git a/studio/static/doc/flask-docs/styleguide.html b/studio/static/doc/flask-docs/styleguide.html deleted file mode 100644 index f45955d..0000000 --- a/studio/static/doc/flask-docs/styleguide.html +++ /dev/null @@ -1,321 +0,0 @@ - -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> - - -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> - - <title>Pocoo Styleguide — Flask 0.8 documentation</title> - - <link rel="stylesheet" href="_static/flasky.css" type="text/css" /> - <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> - - <script type="text/javascript"> - var DOCUMENTATION_OPTIONS = { - URL_ROOT: '', - VERSION: '0.8', - COLLAPSE_INDEX: false, - FILE_SUFFIX: '.html', - HAS_SOURCE: true - }; - </script> - <script type="text/javascript" src="_static/jquery.js"></script> - <script type="text/javascript" src="_static/underscore.js"></script> - <script type="text/javascript" src="_static/doctools.js"></script> - <link rel="top" title="Flask 0.8 documentation" href="index.html" /> - <link rel="next" title="Upgrading to Newer Releases" href="upgrading.html" /> - <link rel="prev" title="Flask Extension Development" href="extensiondev.html" /> - - - <link rel="apple-touch-icon" href="_static/touch-icon.png" /> - - <link media="only screen and (max-device-width: 480px)" href="_static/small_flask.css" type= "text/css" rel="stylesheet" /> - - </head> - <body> - <div class="related"> - <h3>Navigation</h3> - <ul> - <li class="right" style="margin-right: 10px"> - <a href="genindex.html" title="General Index" - accesskey="I">index</a></li> - <li class="right" > - <a href="upgrading.html" title="Upgrading to Newer Releases" - accesskey="N">next</a> |</li> - <li class="right" > - <a href="extensiondev.html" title="Flask Extension Development" - accesskey="P">previous</a> |</li> - <li><a href="index.html">Flask 0.8 documentation</a> »</li> - </ul> - </div> - - <div class="document"> - <div class="documentwrapper"> - <div class="bodywrapper"> - <div class="body"> - - <div class="section" id="pocoo-styleguide"> -<h1>Pocoo Styleguide<a class="headerlink" href="#pocoo-styleguide" title="Permalink to this headline">¶</a></h1> -<p>The Pocoo styleguide is the styleguide for all Pocoo Projects, including -Flask. This styleguide is a requirement for Patches to Flask and a -recommendation for Flask extensions.</p> -<p>In general the Pocoo Styleguide closely follows <span class="target" id="index-0"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-0008"><strong>PEP 8</strong></a> with some small -differences and extensions.</p> -<div class="section" id="general-layout"> -<h2>General Layout<a class="headerlink" href="#general-layout" title="Permalink to this headline">¶</a></h2> -<dl class="docutils"> -<dt>Indentation:</dt> -<dd>4 real spaces. No tabs, no exceptions.</dd> -<dt>Maximum line length:</dt> -<dd>79 characters with a soft limit for 84 if absolutely necessary. Try -to avoid too nested code by cleverly placing <cite>break</cite>, <cite>continue</cite> and -<cite>return</cite> statements.</dd> -<dt>Continuing long statements:</dt> -<dd><p class="first">To continue a statement you can use backslashes in which case you should -align the next line with the last dot or equal sign, or indent four -spaces:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="n">this_is_a_very_long</span><span class="p">(</span><span class="n">function_call</span><span class="p">,</span> <span class="s">'with many parameters'</span><span class="p">)</span> \ - <span class="o">.</span><span class="n">that_returns_an_object_with_an_attribute</span> - -<span class="n">MyModel</span><span class="o">.</span><span class="n">query</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">MyModel</span><span class="o">.</span><span class="n">scalar</span> <span class="o">></span> <span class="mi">120</span><span class="p">)</span> \ - <span class="o">.</span><span class="n">order_by</span><span class="p">(</span><span class="n">MyModel</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">desc</span><span class="p">())</span> \ - <span class="o">.</span><span class="n">limit</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span> -</pre></div> -</div> -<p>If you break in a statement with parentheses or braces, align to the -braces:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="n">this_is_a_very_long</span><span class="p">(</span><span class="n">function_call</span><span class="p">,</span> <span class="s">'with many parameters'</span><span class="p">,</span> - <span class="mi">23</span><span class="p">,</span> <span class="mi">42</span><span class="p">,</span> <span class="s">'and even more'</span><span class="p">)</span> -</pre></div> -</div> -<p>For lists or tuples with many items, break immediately after the -opening brace:</p> -<div class="last highlight-python"><div class="highlight"><pre><span class="n">items</span> <span class="o">=</span> <span class="p">[</span> - <span class="s">'this is the first'</span><span class="p">,</span> <span class="s">'set of items'</span><span class="p">,</span> <span class="s">'with more items'</span><span class="p">,</span> - <span class="s">'to come in this line'</span><span class="p">,</span> <span class="s">'like this'</span> -<span class="p">]</span> -</pre></div> -</div> -</dd> -<dt>Blank lines:</dt> -<dd><p class="first">Top level functions and classes are separated by two lines, everything -else by one. Do not use too many blank lines to separate logical -segments in code. Example:</p> -<div class="last highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">hello</span><span class="p">(</span><span class="n">name</span><span class="p">):</span> - <span class="k">print</span> <span class="s">'Hello </span><span class="si">%s</span><span class="s">!'</span> <span class="o">%</span> <span class="n">name</span> - - -<span class="k">def</span> <span class="nf">goodbye</span><span class="p">(</span><span class="n">name</span><span class="p">):</span> - <span class="k">print</span> <span class="s">'See you </span><span class="si">%s</span><span class="s">.'</span> <span class="o">%</span> <span class="n">name</span> - - -<span class="k">class</span> <span class="nc">MyClass</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span> - <span class="sd">"""This is a simple docstring"""</span> - - <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span> - <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span> - - <span class="k">def</span> <span class="nf">get_annoying_name</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> - <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">upper</span><span class="p">()</span> <span class="o">+</span> <span class="s">'!!!!111'</span> -</pre></div> -</div> -</dd> -</dl> -</div> -<div class="section" id="expressions-and-statements"> -<h2>Expressions and Statements<a class="headerlink" href="#expressions-and-statements" title="Permalink to this headline">¶</a></h2> -<dl class="docutils"> -<dt>General whitespace rules:</dt> -<dd><ul class="first simple"> -<li>No whitespace for unary operators that are not words -(e.g.: <tt class="docutils literal"><span class="pre">-</span></tt>, <tt class="docutils literal"><span class="pre">~</span></tt> etc.) as well on the inner side of parentheses.</li> -<li>Whitespace is placed between binary operators.</li> -</ul> -<p>Good:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="n">exp</span> <span class="o">=</span> <span class="o">-</span><span class="mf">1.05</span> -<span class="n">value</span> <span class="o">=</span> <span class="p">(</span><span class="n">item_value</span> <span class="o">/</span> <span class="n">item_count</span><span class="p">)</span> <span class="o">*</span> <span class="n">offset</span> <span class="o">/</span> <span class="n">exp</span> -<span class="n">value</span> <span class="o">=</span> <span class="n">my_list</span><span class="p">[</span><span class="n">index</span><span class="p">]</span> -<span class="n">value</span> <span class="o">=</span> <span class="n">my_dict</span><span class="p">[</span><span class="s">'key'</span><span class="p">]</span> -</pre></div> -</div> -<p>Bad:</p> -<div class="last highlight-python"><div class="highlight"><pre><span class="n">exp</span> <span class="o">=</span> <span class="o">-</span> <span class="mf">1.05</span> -<span class="n">value</span> <span class="o">=</span> <span class="p">(</span> <span class="n">item_value</span> <span class="o">/</span> <span class="n">item_count</span> <span class="p">)</span> <span class="o">*</span> <span class="n">offset</span> <span class="o">/</span> <span class="n">exp</span> -<span class="n">value</span> <span class="o">=</span> <span class="p">(</span><span class="n">item_value</span><span class="o">/</span><span class="n">item_count</span><span class="p">)</span><span class="o">*</span><span class="n">offset</span><span class="o">/</span><span class="n">exp</span> -<span class="n">value</span><span class="o">=</span><span class="p">(</span> <span class="n">item_value</span><span class="o">/</span><span class="n">item_count</span> <span class="p">)</span> <span class="o">*</span> <span class="n">offset</span><span class="o">/</span><span class="n">exp</span> -<span class="n">value</span> <span class="o">=</span> <span class="n">my_list</span><span class="p">[</span> <span class="n">index</span> <span class="p">]</span> -<span class="n">value</span> <span class="o">=</span> <span class="n">my_dict</span> <span class="p">[</span><span class="s">'key'</span><span class="p">]</span> -</pre></div> -</div> -</dd> -<dt>Yoda statements are a no-go:</dt> -<dd><p class="first">Never compare constant with variable, always variable with constant:</p> -<p>Good:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="k">if</span> <span class="n">method</span> <span class="o">==</span> <span class="s">'md5'</span><span class="p">:</span> - <span class="k">pass</span> -</pre></div> -</div> -<p>Bad:</p> -<div class="last highlight-python"><div class="highlight"><pre><span class="k">if</span> <span class="s">'md5'</span> <span class="o">==</span> <span class="n">method</span><span class="p">:</span> - <span class="k">pass</span> -</pre></div> -</div> -</dd> -<dt>Comparisons:</dt> -<dd><ul class="first last simple"> -<li>against arbitrary types: <tt class="docutils literal"><span class="pre">==</span></tt> and <tt class="docutils literal"><span class="pre">!=</span></tt></li> -<li>against singletons with <tt class="docutils literal"><span class="pre">is</span></tt> and <tt class="docutils literal"><span class="pre">is</span> <span class="pre">not</span></tt> (eg: <tt class="docutils literal"><span class="pre">foo</span> <span class="pre">is</span> <span class="pre">not</span> -<span class="pre">None</span></tt>)</li> -<li>never compare something with <cite>True</cite> or <cite>False</cite> (for example never -do <tt class="docutils literal"><span class="pre">foo</span> <span class="pre">==</span> <span class="pre">False</span></tt>, do <tt class="docutils literal"><span class="pre">not</span> <span class="pre">foo</span></tt> instead)</li> -</ul> -</dd> -<dt>Negated containment checks:</dt> -<dd>use <tt class="docutils literal"><span class="pre">foo</span> <span class="pre">not</span> <span class="pre">in</span> <span class="pre">bar</span></tt> instead of <tt class="docutils literal"><span class="pre">not</span> <span class="pre">foo</span> <span class="pre">in</span> <span class="pre">bar</span></tt></dd> -<dt>Instance checks:</dt> -<dd><tt class="docutils literal"><span class="pre">isinstance(a,</span> <span class="pre">C)</span></tt> instead of <tt class="docutils literal"><span class="pre">type(A)</span> <span class="pre">is</span> <span class="pre">C</span></tt>, but try to avoid -instance checks in general. Check for features.</dd> -</dl> -</div> -<div class="section" id="naming-conventions"> -<h2>Naming Conventions<a class="headerlink" href="#naming-conventions" title="Permalink to this headline">¶</a></h2> -<ul class="simple"> -<li>Class names: <tt class="docutils literal"><span class="pre">CamelCase</span></tt>, with acronyms kept uppercase (<tt class="docutils literal"><span class="pre">HTTPWriter</span></tt> -and not <tt class="docutils literal"><span class="pre">HttpWriter</span></tt>)</li> -<li>Variable names: <tt class="docutils literal"><span class="pre">lowercase_with_underscores</span></tt></li> -<li>Method and function names: <tt class="docutils literal"><span class="pre">lowercase_with_underscores</span></tt></li> -<li>Constants: <tt class="docutils literal"><span class="pre">UPPERCASE_WITH_UNDERSCORES</span></tt></li> -<li>precompiled regular expressions: <tt class="docutils literal"><span class="pre">name_re</span></tt></li> -</ul> -<p>Protected members are prefixed with a single underscore. Double -underscores are reserved for mixin classes.</p> -<p>On classes with keywords, trailing underscores are appended. Clashes with -builtins are allowed and <strong>must not</strong> be resolved by appending an -underline to the variable name. If the function needs to access a -shadowed builtin, rebind the builtin to a different name instead.</p> -<dl class="docutils"> -<dt>Function and method arguments:</dt> -<dd><ul class="first last simple"> -<li>class methods: <tt class="docutils literal"><span class="pre">cls</span></tt> as first parameter</li> -<li>instance methods: <tt class="docutils literal"><span class="pre">self</span></tt> as first parameter</li> -<li>lambdas for properties might have the first parameter replaced -with <tt class="docutils literal"><span class="pre">x</span></tt> like in <tt class="docutils literal"><span class="pre">display_name</span> <span class="pre">=</span> <span class="pre">property(lambda</span> <span class="pre">x:</span> <span class="pre">x.real_name</span> -<span class="pre">or</span> <span class="pre">x.username)</span></tt></li> -</ul> -</dd> -</dl> -</div> -<div class="section" id="docstrings"> -<h2>Docstrings<a class="headerlink" href="#docstrings" title="Permalink to this headline">¶</a></h2> -<dl class="docutils"> -<dt>Docstring conventions:</dt> -<dd><p class="first">All docstrings are formatted with reStructuredText as understood by -Sphinx. Depending on the number of lines in the docstring, they are -laid out differently. If it’s just one line, the closing triple -quote is on the same line as the opening, otherwise the text is on -the same line as the opening quote and the triple quote that closes -the string on its own line:</p> -<div class="last highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">foo</span><span class="p">():</span> - <span class="sd">"""This is a simple docstring"""</span> - - -<span class="k">def</span> <span class="nf">bar</span><span class="p">():</span> - <span class="sd">"""This is a longer docstring with so much information in there</span> -<span class="sd"> that it spans three lines. In this case the closing triple quote</span> -<span class="sd"> is on its own line.</span> -<span class="sd"> """</span> -</pre></div> -</div> -</dd> -<dt>Module header:</dt> -<dd><p class="first">The module header consists of an utf-8 encoding declaration (if non -ASCII letters are used, but it is recommended all the time) and a -standard docstring:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="c"># -*- coding: utf-8 -*-</span> -<span class="sd">"""</span> -<span class="sd"> package.module</span> -<span class="sd"> ~~~~~~~~~~~~~~</span> - -<span class="sd"> A brief description goes here.</span> - -<span class="sd"> :copyright: (c) YEAR by AUTHOR.</span> -<span class="sd"> :license: LICENSE_NAME, see LICENSE_FILE for more details.</span> -<span class="sd">"""</span> -</pre></div> -</div> -<p class="last">Please keep in mind that proper copyrights and license files are a -requirement for approved Flask extensions.</p> -</dd> -</dl> -</div> -<div class="section" id="comments"> -<h2>Comments<a class="headerlink" href="#comments" title="Permalink to this headline">¶</a></h2> -<p>Rules for comments are similar to docstrings. Both are formatted with -reStructuredText. If a comment is used to document an attribute, put a -colon after the opening pound sign (<tt class="docutils literal"><span class="pre">#</span></tt>):</p> -<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">User</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span> - <span class="c">#: the name of the user as unicode string</span> - <span class="n">name</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">String</span><span class="p">)</span> - <span class="c">#: the sha1 hash of the password + inline salt</span> - <span class="n">pw_hash</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">String</span><span class="p">)</span> -</pre></div> -</div> -</div> -</div> - - - </div> - </div> - </div> - <div class="sphinxsidebar"> - <div class="sphinxsidebarwrapper"><p class="logo"><a href="index.html"> - <img class="logo" src="_static/flask.png" alt="Logo"/> -</a></p> - <h3><a href="index.html">Table Of Contents</a></h3> - <ul> -<li><a class="reference internal" href="#">Pocoo Styleguide</a><ul> -<li><a class="reference internal" href="#general-layout">General Layout</a></li> -<li><a class="reference internal" href="#expressions-and-statements">Expressions and Statements</a></li> -<li><a class="reference internal" href="#naming-conventions">Naming Conventions</a></li> -<li><a class="reference internal" href="#docstrings">Docstrings</a></li> -<li><a class="reference internal" href="#comments">Comments</a></li> -</ul> -</li> -</ul> -<h3>Related Topics</h3> -<ul> - <li><a href="index.html">Documentation overview</a><ul> - <li>Previous: <a href="extensiondev.html" title="previous chapter">Flask Extension Development</a></li> - <li>Next: <a href="upgrading.html" title="next chapter">Upgrading to Newer Releases</a></li> - </ul></li> -</ul> - <h3>This Page</h3> - <ul class="this-page-menu"> - <li><a href="_sources/styleguide.txt" - rel="nofollow">Show Source</a></li> - </ul> -<div id="searchbox" style="display: none"> - <h3>Quick search</h3> - <form class="search" action="search.html" method="get"> - <input type="text" name="q" /> - <input type="submit" value="Go" /> - <input type="hidden" name="check_keywords" value="yes" /> - <input type="hidden" name="area" value="default" /> - </form> - <p class="searchtip" style="font-size: 90%"> - Enter search terms or a module, class or function name. - </p> -</div> -<script type="text/javascript">$('#searchbox').show(0);</script> - </div> - </div> - <div class="clearer"></div> - </div> - <div class="footer"> - © Copyright 2010, Armin Ronacher. - Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>. - </div> - </body> -</html>
\ No newline at end of file |