<!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="X-UA-Compatible" content="IE=Edge" /> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>Python Paste Developer Guide — Paste 3.0.0 documentation</title> <link rel="stylesheet" href="_static/default.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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> <script type="text/javascript" src="_static/language_data.js"></script> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="next" title="Paste Style Guide" href="StyleGuide.html" /> <link rel="prev" title="Features" href="developer-features.html" /> <link rel="stylesheet" href="_static/custom.css" type="text/css" /> <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> </head><body> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body" role="main"> <div class="section" id="python-paste-developer-guide"> <h1>Python Paste Developer Guide<a class="headerlink" href="#python-paste-developer-guide" title="Permalink to this headline">¶</a></h1> <p>Hi. Welcome to Paste. I hope you enjoy your stay here.</p> <p>I hope to bring together multiple efforts here, for Paste to support multiple frameworks and directions, while presenting a fairly integrated frontend to users. How to do that? That’s an open question, and this code is in some ways an exploration.</p> <p>There’s some basic principles:</p> <ul class="simple"> <li>Keep stuff decoupled.</li> <li>Must be testable. Of course tested is even better than testable.</li> <li>Use WSGI standards for communication between decoupled libraries.</li> <li>When possible, use HTTP semantics for communicating between libraries (e.g., indicate cachability using the appropriate HTTP headers).</li> <li>When possible, use WSGI as a wrapper around web-neutral libraries. For instance, the configuration is a simple library, but the WSGI middleware that puts the configuration in place is really really simple. If it could be used outside of a web context, then having both a library and middleware form is good.</li> <li>Entry into frameworks should be easy, but exit should also be easy. Heterogeneous frameworks and applications are the ambition. But we have to get some messiness into Paste before we can try to resolve that messiness.</li> <li>When all is said and done, users should be able to ignore much of what we’ve done and focus on writing their applications, and Stuff Just Works. Documentation is good; stuff that works without user intervention is better.</li> </ul> <div class="section" id="developer-info"> <h2>Developer Info<a class="headerlink" href="#developer-info" title="Permalink to this headline">¶</a></h2> <p>Mostly, if there’s a problem we can discuss it and work it out, no one is going to bite your head off for committing something.</p> <ul class="simple"> <li>Framework-like things should go in subpackages, or perhaps in separate distributions entirely (Paste WebKit and Wareweb were extracted for this reason).</li> <li>Integrating external servers and frameworks is also interesting, but it’s best to introduce that as a requirement instead of including the work here. Paste Script contains several wrappers for external projects (servers in particular).</li> <li>Tests are good. We use <a class="reference external" href="https://docs.pytest.org/en/latest/">pytest</a>, because it is simple. I want to use doctests too, but the infrastructure isn’t really there now – but please feel free to use those too. <code class="docutils literal notranslate"><span class="pre">unittest</span></code> is kind of annoying, and pytest is both more powerful and easier to write for. Tests should go in the <code class="docutils literal notranslate"><span class="pre">tests/</span></code> directory. <code class="docutils literal notranslate"><span class="pre">paste.fixture</span></code> contains some convenience functions for testing WSGI applications and middleware. Pay particular attention to <code class="docutils literal notranslate"><span class="pre">TestApp</span></code>.</li> </ul> <ul> <li><p class="first">If you move something around that someone may be using, keep their imports working and introduce a warning, like:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">backward_compat_function</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span> <span class="kn">import</span> <span class="nn">warnings</span> <span class="c1"># Deprecated on 2005 Mar 5</span> <span class="n">warnings</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span><span class="s1">'Moved to foo.function'</span><span class="p">,</span> <span class="ne">DeprecationWarning</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span> <span class="k">return</span> <span class="n">foo</span><span class="o">.</span><span class="n">function</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">)</span> </pre></div> </div> </li> <li><p class="first">If something is really experimental, put it in your home directory, or make a branch in your home directory. You can make a home directory for yourself, in <code class="docutils literal notranslate"><span class="pre">http://svn.w4py.org/home/username</span></code>.</p> </li> <li><p class="first">Not everything in the repository or even in the trunk will necessarily go into the release. The release should contain stuff that is tested, documented, and useful. Each module or feature also needs a champion – someone who will stand by the code, answer questions, etc. It doesn’t have to be the original developer, but there has to be <em>someone</em>. So when a release is cut, if some modules don’t fulfill that they may be left out.</p> </li> <li><p class="first">Try to keep to the <a class="reference external" href="StyleGuide.html">Style Guidelines</a>. But if you are bringing in outside work, don’t stress out too much about it. Still, if you have a choice, follow that. Those guidelines are meant to represent conventional Python style guides, there’s nothing out of the normal there.</p> </li> </ul> <ul> <li><p class="first">Write your docstrings in <a class="reference external" href="http://docutils.sourceforge.net/rst.html">restructured text</a>. As time goes on, I want to rely on docstrings more for documentation, with shorter narrative documentation pointing into the documentation generated from docstrings.</p> <p>The generation is done with <a class="reference external" href="http://pudge.lesscode.org/">Pudge</a>. To try generating the documentation, this should work:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ easy_install svn://lesscode.org/buildutils/trunk \ svn://lesscode.org/pudge/trunk $ cd Paste $ python setup.py pudge </pre></div> </div> <p>This will install Pudge and <a class="reference external" href="http://buildutils.lesscode.org/">buildutils</a>, and then generate the documentation into <code class="docutils literal notranslate"><span class="pre">Paste/docs/html/</span></code>.</p> </li> </ul> </div> </div> </div> </div> </div> <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebarwrapper"> <h1 class="logo"><a href="index.html">Paste</a></h1> <h3>Navigation</h3> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="news.html">News</a></li> <li class="toctree-l1"><a class="reference internal" href="future.html">The Future Of Paste</a></li> <li class="toctree-l1"><a class="reference internal" href="testing-applications.html">Testing Applications with Paste</a></li> <li class="toctree-l1"><a class="reference internal" href="url-parsing-with-wsgi.html">URL Parsing With WSGI And Paste</a></li> <li class="toctree-l1"><a class="reference internal" href="do-it-yourself-framework.html">A Do-It-Yourself Framework</a></li> <li class="toctree-l1"><a class="reference internal" href="paste-httpserver-threadpool.html">The Paste HTTP Server Thread Pool</a></li> <li class="toctree-l1"><a class="reference internal" href="developer-features.html">Features</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="#">Python Paste Developer Guide</a></li> <li class="toctree-l1"><a class="reference internal" href="StyleGuide.html">Paste Style Guide</a></li> <li class="toctree-l1"><a class="reference internal" href="paste-httpserver-threadpool.html">The Paste HTTP Server Thread Pool</a></li> <li class="toctree-l1"><a class="reference internal" href="testing-applications.html">Testing Applications with Paste</a></li> <li class="toctree-l1"><a class="reference internal" href="url-parsing-with-wsgi.html">URL Parsing With WSGI And Paste</a></li> <li class="toctree-l1"><a class="reference internal" href="community/index.html">Community</a></li> <li class="toctree-l1"><a class="reference internal" href="community/mailing-list.html">Mailing Lists</a></li> <li class="toctree-l1"><a class="reference internal" href="community/repository.html">Repository</a></li> <li class="toctree-l1"><a class="reference internal" href="download/index.html">Downloads</a></li> </ul> <div class="relations"> <h3>Related Topics</h3> <ul> <li><a href="index.html">Documentation overview</a><ul> <li>Previous: <a href="developer-features.html" title="previous chapter">Features</a></li> <li>Next: <a href="StyleGuide.html" title="next chapter">Paste Style Guide</a></li> </ul></li> </ul> </div> <div id="searchbox" style="display: none" role="search"> <h3>Quick search</h3> <div class="searchformwrapper"> <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> </div> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <div class="clearer"></div> </div> <div class="footer"> ©2008, Ian Bicking. | Powered by <a href="http://sphinx-doc.org/">Sphinx 1.8.4</a> & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a> | <a href="_sources/DeveloperGuidelines.txt" rel="nofollow">Page source</a> </div> </body> </html>