1 ++++++++++++++++++++++++++++ 2 Python Paste Developer Guide 3 ++++++++++++++++++++++++++++ 4 5 Hi. Welcome to Paste. I hope you enjoy your stay here. 6 7 I hope to bring together multiple efforts here, for Paste to support 8 multiple frameworks and directions, while presenting a fairly 9 integrated frontend to users. How to do that? That's an open 10 question, and this code is in some ways an exploration. 11 12 There'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 40 Developer Info 41 ============== 42 43 Mostly, if there's a problem we can discuss it and work it out, no one 44 is 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
