| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110 |
- ++++++++++++++++++++++++++++
- Python Paste Developer Guide
- ++++++++++++++++++++++++++++
- Hi. Welcome to Paste. I hope you enjoy your stay here.
- 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.
- There's some basic principles:
- * Keep stuff decoupled.
- * Must be testable. Of course tested is even better than testable.
- * Use WSGI standards for communication between decoupled libraries.
- * When possible, use HTTP semantics for communicating between
- libraries (e.g., indicate cachability using the appropriate HTTP
- headers).
- * 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.
- * 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.
- * 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.
- Developer Info
- ==============
- 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.
- * Framework-like things should go in subpackages, or perhaps in
- separate distributions entirely (Paste WebKit and Wareweb were
- extracted for this reason).
- * 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).
- * Tests are good. We use py.test_, 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. ``unittest`` is kind of
- annoying, and py.test is both more powerful and easier to write for.
- Tests should go in the ``tests/`` directory. ``paste.fixture``
- contains some convenience functions for testing WSGI applications
- and middleware. Pay particular attention to ``TestApp``.
-
- .. _py.test: http://codespeak.net/py/current/doc/test.html
- * If you move something around that someone may be using, keep their
- imports working and introduce a warning, like::
- def backward_compat_function(*args, **kw):
- import warnings
- # Deprecated on 2005 Mar 5
- warnings.warn('Moved to foo.function', DeprecationWarning, 2)
- return foo.function(*args, **kw)
- * 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 ``http://svn.w4py.org/home/username``.
- * 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 *someone*. So when a release is cut, if some
- modules don't fulfill that they may be left out.
- * Try to keep to the `Style Guidelines`_. 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.
- .. _Style Guidelines: StyleGuide.html
- * Write your docstrings in `restructured text
- <http://docutils.sourceforge.net/rst.html>`_. As time goes on, I
- want to rely on docstrings more for documentation, with shorter
- narrative documentation pointing into the documentation generated
- from docstrings.
- The generation is done with `Pudge <http://pudge.lesscode.org/>`_.
- To try generating the documentation, this should work::
- $ easy_install svn://lesscode.org/buildutils/trunk \
- svn://lesscode.org/pudge/trunk
- $ cd Paste
- $ python setup.py pudge
- This will install Pudge and `buildutils
- <http://buildutils.lesscode.org/>`_, and then generate the
- documentation into ``Paste/docs/html/``.
|