diff options
Diffstat (limited to 'app/static/doc/flask-docs/styleguide.html')
| -rw-r--r-- | app/static/doc/flask-docs/styleguide.html | 321 |
1 files changed, 321 insertions, 0 deletions
diff --git a/app/static/doc/flask-docs/styleguide.html b/app/static/doc/flask-docs/styleguide.html new file mode 100644 index 0000000..f45955d --- /dev/null +++ b/app/static/doc/flask-docs/styleguide.html @@ -0,0 +1,321 @@ + +<!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 |