1++++++++++++++++++++++++++++
2Python Paste Developer Guide
3++++++++++++++++++++++++++++
4
5Hi.  Welcome to Paste.  I hope you enjoy your stay here.
6
7I hope to bring together multiple efforts here, for Paste to support
8multiple frameworks and directions, while presenting a fairly
9integrated frontend to users.  How to do that?  That's an open
10question, and this code is in some ways an exploration.
11
12There's some basic principles:
13
14* Keep stuff decoupled.
15
16* Must be testable.  Of course tested is even better than testable.
17
18* Use WSGI standards for communication between decoupled libraries.
19
20* When possible, use HTTP semantics for communicating between
21  libraries (e.g., indicate cachability using the appropriate HTTP
22  headers).
23
24* When possible, use WSGI as a wrapper around web-neutral libraries.
25  For instance, the configuration is a simple library, but the WSGI
26  middleware that puts the configuration in place is really really
27  simple.  If it could be used outside of a web context, then having
28  both a library and middleware form is good.
29
30* Entry into frameworks should be easy, but exit should also be easy.
31  Heterogeneous frameworks and applications are the ambition.  But we
32  have to get some messiness into Paste before we can try to resolve
33  that messiness.
34
35* When all is said and done, users should be able to ignore much of
36  what we've done and focus on writing their applications, and Stuff
37  Just Works.  Documentation is good; stuff that works without user
38  intervention is better.
39
40Developer Info
41==============
42
43Mostly, if there's a problem we can discuss it and work it out, no one
44is going to bite your head off for committing something.
45
46* Framework-like things should go in subpackages, or perhaps in
47  separate distributions entirely (Paste WebKit and Wareweb were
48  extracted for this reason).
49
50* Integrating external servers and frameworks is also interesting, but
51  it's best to introduce that as a requirement instead of including
52  the work here.  Paste Script contains several wrappers for external
53  projects (servers in particular).
54
55* Tests are good.  We use py.test_, because it is simple.  I want to
56  use doctests too, but the infrastructure isn't really there now --
57  but please feel free to use those too.  ``unittest`` is kind of
58  annoying, and py.test is both more powerful and easier to write for.
59  Tests should go in the ``tests/`` directory.  ``paste.fixture``
60  contains some convenience functions for testing WSGI applications
61  and middleware.  Pay particular attention to ``TestApp``.
62
63.. _py.test: http://codespeak.net/py/current/doc/test.html
64
65* If you move something around that someone may be using, keep their
66  imports working and introduce a warning, like::
67
68    def backward_compat_function(*args, **kw):
69        import warnings
70        # Deprecated on 2005 Mar 5
71        warnings.warn('Moved to foo.function', DeprecationWarning, 2)
72        return foo.function(*args, **kw)
73
74* If something is really experimental, put it in your home directory,
75  or make a branch in your home directory.  You can make a home
76  directory for yourself, in ``http://svn.w4py.org/home/username``.
77
78* Not everything in the repository or even in the trunk will
79  necessarily go into the release.  The release should contain stuff
80  that is tested, documented, and useful.  Each module or feature also
81  needs a champion -- someone who will stand by the code, answer
82  questions, etc.  It doesn't have to be the original developer, but
83  there has to be *someone*.  So when a release is cut, if some
84  modules don't fulfill that they may be left out.
85
86* Try to keep to the `Style Guidelines`_.  But if you are bringing in
87  outside work, don't stress out too much about it.  Still, if you
88  have a choice, follow that.  Those guidelines are meant to represent
89  conventional Python style guides, there's nothing out of the normal
90  there.
91
92.. _Style Guidelines: StyleGuide.html
93
94* Write your docstrings in `restructured text
95  <http://docutils.sourceforge.net/rst.html>`_.  As time goes on, I
96  want to rely on docstrings more for documentation, with shorter
97  narrative documentation pointing into the documentation generated
98  from docstrings.
99
100  The generation is done with `Pudge <http://pudge.lesscode.org/>`_.
101  To try generating the documentation, this should work::
102
103    $ easy_install svn://lesscode.org/buildutils/trunk \
104                   svn://lesscode.org/pudge/trunk
105    $ cd Paste
106    $ python setup.py pudge
107
108  This will install Pudge and `buildutils
109  <http://buildutils.lesscode.org/>`_, and then generate the
110  documentation into ``Paste/docs/html/``.
111