DeveloperGuidelines.txt 4.5 KB

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