1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
|
<!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>Python Paste Developer Guide — Paste v1.7.5 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">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '1.7.5',
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="Paste v1.7.5 documentation" href="index.html" />
<link rel="next" title="Paste Style Guide" href="StyleGuide.html" />
<link rel="prev" title="Features" href="developer-features.html" />
<link rel="stylesheet" type="text/css"
href="_static/paste.css.html">
</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="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="StyleGuide.html" title="Paste Style Guide"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="developer-features.html" title="Features"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Paste v1.7.5 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<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="http://codespeak.net/py/current/doc/test.html">py.test</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. <tt class="docutils literal"><span class="pre">unittest</span></tt> is kind of
annoying, and py.test is both more powerful and easier to write for.
Tests should go in the <tt class="docutils literal"><span class="pre">tests/</span></tt> directory. <tt class="docutils literal"><span class="pre">paste.fixture</span></tt>
contains some convenience functions for testing WSGI applications
and middleware. Pay particular attention to <tt class="docutils literal"><span class="pre">TestApp</span></tt>.</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-python"><div class="highlight"><pre><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="c"># 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="s">'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 <tt class="docutils literal"><span class="pre">http://svn.w4py.org/home/username</span></tt>.</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-python"><pre>$ easy_install svn://lesscode.org/buildutils/trunk \
svn://lesscode.org/pudge/trunk
$ cd Paste
$ python setup.py pudge</pre>
</div>
<p>This will install Pudge and <a class="reference external" href="http://buildutils.lesscode.org/">buildutils</a>, and then generate the
documentation into <tt class="docutils literal"><span class="pre">Paste/docs/html/</span></tt>.</p>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="http://pythonpaste.org/" class="invisible-link">Python Paste</a></h3>
<ul>
<li><a href="http://trac.pythonpaste.org">Issue tracker</a></li>
<li><a href="http://pythonpaste.org/">Paste core</a></li>
<li><a href="http://pythonpaste.org/webob/">WebOb</a></li>
<li><a href="http://pythonpaste.org/deploy/">Paste Deploy</a></li>
<li><a href="http://pythonpaste.org/script/">Paste Script</a></li>
<li><a href="http://pythonpaste.org/webtest/">WebTest</a></li>
<li><a href="http://pythonpaste.org/scripttest/">ScriptType</a></li>
<li><a href="http://pythonpaste.org/initools/">INITools</a></li>
<li><a href="http://pythonpaste.org/tempita/">Tempita</a></li>
<li><a href="http://pythonpaste.org/waitforit/">WaitForIt</a></li>
<li><a href="http://pythonpaste.org/wphp/">WPHP</a></li>
<li><a href="http://pythonpaste.org/wsgifilter/">WSGIFilter</a></li>
<li><a href="http://pythonpaste.org/wsgiproxy/">WSGIProxy</a></li>
</ul>
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Python Paste Developer Guide</a><ul>
<li><a class="reference internal" href="#developer-info">Developer Info</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="developer-features.html"
title="previous chapter">Features</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="StyleGuide.html"
title="next chapter">Paste Style Guide</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/DeveloperGuidelines.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" size="18" />
<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="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="StyleGuide.html" title="Paste Style Guide"
>next</a> |</li>
<li class="right" >
<a href="developer-features.html" title="Features"
>previous</a> |</li>
<li><a href="index.html">Paste v1.7.5 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2008, Ian Bicking.
Last updated on Sep 14, 2010.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.1.
</div>
</body>
</html>
|
