Author: ianb
Date: 2005-03-30 17:40:58 -0700 (Wed, 30 Mar 2005)
New Revision: 2266
Added:
WSGIKit/trunk/docs/DeveloperGuidelines.txt
WSGIKit/trunk/docs/StyleGuide.txt
Modified:
WSGIKit/trunk/docs/WSGIWebKit.txt
Log:
Updated main doc a little, added developer docs
Added: WSGIKit/trunk/docs/DeveloperGuidelines.txt
===================================================================
--- WSGIKit/trunk/docs/DeveloperGuidelines.txt 2005-03-31 00:40:41 UTC (rev 2265)
+++ WSGIKit/trunk/docs/DeveloperGuidelines.txt 2005-03-31 00:40:58 UTC (rev 2266)
@@ -0,0 +1,80 @@
++++++++++++++++++++++++
+WSGIKit Developer Guide
++++++++++++++++++++++++
+
+Hi. Welcome to WSGIKit. I hope you enjoy your stay here.
+
+I hope to bring together multiple efforts here, for WSGIKit 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 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 WSGIKit 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. The top level is
+ only for things that are lower-level than a framework.
+
+* Integrating external servers and frameworks is also interesting, but
+ if someone else is maintaining the code elsewhere you shouldn't
+ import their work into the repository -- it'll just cause
+ confusion. Create a script to pull in their work or something, and
+ check that in.
+
+* 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 a ``tests/`` subdirectory.
+ ``wsgikit.tests.fixture`` contains some convenience functions for
+ testing WSGI applications and middleware.
+
+.. _py.test: http://codespeak.net/py/current/doc/test.html
+
+* 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
+
Added: WSGIKit/trunk/docs/StyleGuide.txt
===================================================================
--- WSGIKit/trunk/docs/StyleGuide.txt 2005-03-31 00:40:41 UTC (rev 2265)
+++ WSGIKit/trunk/docs/StyleGuide.txt 2005-03-31 00:40:58 UTC (rev 2266)
@@ -0,0 +1,102 @@
++++++++++++++++++++
+WSGIKit Style Guide
++++++++++++++++++++
+
+Generally you should follow the recommendations in `PEP 8`_, the
+Python Style Guide. Some things to take particular note of:
+
+.. _PEP 8: http://www.python.org/peps/pep-0008.html
+
+* **No tabs**. Not anywhere. Always indent with 4 spaces.
+
+* I don't stress too much on line length. But try to break lines up
+ by grouping with parenthesis instead of with backslashes (if you
+ can). Do asserts like::
+
+ assert some_condition(a, b), (
+ "Some condition failed, %r isn't right!" % a)
+
+* But if you are having problems with line length, maybe you should
+ just break the expression up into multiple statements.
+
+* Blank lines between methods, unless they are very small and closely
+ bound to each other.
+
+* Don't use the form ``condition and trueValue or falseValue``. Break
+ it out and use a variable.
+
+* I (Ian Bicking) am very picky about whitespace. There's one and
+ only one right way to do it. Good examples::
+
+ short = 3
+ longerVar = 4
+
+ if x == 4:
+ do stuff
+
+ func(arg1='a', arg2='b')
+ func((a + b)*10)
+
+ **Bad** examples::
+
+ short =3
+ longerVar=4
+
+ if x==4: do stuff
+
+ func(arg1 = 'a', arg2 = 'b')
+ func(a,b)
+ func( a, b )
+ [ 1, 2, 3 ]
+
+ If the whitespace isn't right, it'll annoy me and I'll feel a need
+ to fix it. Really, this whitespace stuff shouldn't be that
+ controversial should it? Some particular points that I feel
+ strongly about:
+
+ * No space after a function name (bad: ``func (arg)``).
+ * No space after or before a parenthesis (bad: ``func( arg )``).
+ * Always one space after a comma (bad: ``func(a,b)``).
+
+* Use ``@@`` to mark something that is suboptimal, or where you have a
+ concern that it's not right. Try to also date it and put your
+ username there.
+
+* Docstrings are good. They should look like::
+
+ class AClass(object):
+ """
+ doc string...
+ """
+
+ Don't use single quotes (''') -- they tend to cause problems in
+ Emacs. Don't bother trying make the string less vertically compact.
+
+* Comments go right before the thing they are commenting on.
+
+* Methods never, ever, ever start with capital letters. Generally
+ only classes are capitalized. But definitely never methods.
+
+* Use ``cls`` to refer to a class. Use ``meta`` to refer to a
+ metaclass (which also happens to be a class, but calling a metaclass
+ ``cls`` will be confusing).
+
+* Use ``isinstance`` instead of comparing types. E.g.::
+
+ if isinstance(var, str): ...
+ # Bad:
+ if type(var) is StringType: ...
+
+* Never, ever use two leading underscores. This is annoyingly
+ private. If name clashes are a concern, use name mangling instead
+ (e.g., ``_MyThing_blahblah``). This is essentially the same thing
+ as double-underscore, only it's transparent where double underscore
+ obscures.
+
+* Module names should be unique in the package. Subpackages shouldn't
+ share module names with sibling or parent packages. Sadly this
+ isn't possible for ``__init__``, but it's otherwise easy enough.
+
+* Module names should be all lower case, and probably have no
+ underscores (smushedwords).
+
Modified: WSGIKit/trunk/docs/WSGIWebKit.txt
===================================================================
--- WSGIKit/trunk/docs/WSGIWebKit.txt 2005-03-31 00:40:41 UTC (rev 2265)
+++ WSGIKit/trunk/docs/WSGIWebKit.txt 2005-03-31 00:40:58 UTC (rev 2266)
@@ -38,7 +38,7 @@
-------------
This system is intended to be largely compatible with current Webware
-applications. This is only an intension; use with real-world
+applications. This is only an intention; use with real-world
applications will help us refine this compatibility.
Some parts that aren't being brought over:
@@ -52,7 +52,10 @@
* URL introspection. I tried to get some of it, but there's way too
many ways of refactoring the URL in Webware, and I didn't deal with
all of them. The environment (``request.environ()``) may look
- different than in Webware -- it matches the WSGI expectations.
+ different than in Webware -- it matches the WSGI expectations. It's
+ certainly possible -- and hopefully clearer -- to do introspection
+ in WSGIKit, but it might not be backward compatible (but still file
+ bugs if you find problems).
Discussion
----------
@@ -60,13 +63,71 @@
Discussion should take place on the Webware mailing list,
webware-discuss@... and webware-devel@...
+Configuration
+-------------
+
+Configuration is done with normal Python files. Global variables
+become configuration values. So a configuration file might look
+like::
+
+ host = 'localhost'
+ port = 8080
+ webkit_dir = '/path/to/dir'
+ database_name = 'app_data'
+
+And so on. There's a default configuration file in
+``wsgikit/default_config.conf`` which will also serve as
+documentation. Your configuration overrides those values. The
+extension is arbitrary at this point.
+
+Some important configuration values:
+
+``config_file``:
+ Load the given configuration file.
+
+``server``:
+ The (string) name of the server you want to use. Right now there
+ is ``"wsgiutils"`` and ``"twisted"``.
+
+``webkit_dir``:
+ The base directory to find Webware servlets. (In the future other
+ frameworks will also be supported.)
+
+``debug``:
+ If true, then errors will be displayed in the browser.
+
+``reload``:
+ If true, then we'll monitor for any changed modules and restart
+ the server if those are found.
+
+``verbose``:
+ If true, talk a lot.
+
Use
---
-These are some manual ways to set up a WSGI server, but ``server.py``
-is the easiest. Right now integration is kind of an unsolved problem,
-but manual application setup would be the way to go about it...
+These are some manual ways to set up a WSGI server, but
+``scripts/server`` is the easiest.
+This script takes takes options that turn into configuration
+parameters. If there's a ``port`` configuration value you can also
+use the ``--port=X`` command-line option. ``-`` is also replaced with
+``_``.
+
+Another option is ``-f config_file.conf`` which loads the given
+configuration file. This might be the only option you need, if you
+put all the other settings in the configuration file.
+
+Note that ``--verbose``, ``--reload`` and ``--debug`` do not require
+an argument.
+
+Multiple Applications / Manual Setup
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Right now integration of multiple applications into a single server is
+kind of an unsolved problem, but manual application setup would be the
+way to go about it...
+
CGI
~~~
|