Email Archive: webware-checkins (read-only)
|
[Webware-checkins] r2368 - Paste/trunk/docs
From: <ianb@co...> - 2005-04-22 03:21
|
Author: ianb Date: 2005-04-21 21:21:08 -0600 (Thu, 21 Apr 2005) New Revision: 2368 Added: Paste/trunk/docs/Paste.txt Removed: Paste/trunk/docs/WSGIKit.txt Log: Renamed doc Copied: Paste/trunk/docs/Paste.txt (from rev 2366, Paste/trunk/docs/WSGIKit.txt) Deleted: Paste/trunk/docs/WSGIKit.txt =================================================================== --- Paste/trunk/docs/WSGIKit.txt 2005-04-22 03:18:20 UTC (rev 2367) +++ Paste/trunk/docs/WSGIKit.txt 2005-04-22 03:21:08 UTC (rev 2368) @@ -1,232 +0,0 @@ -Python Paste -============ - -This is a WSGI_ version of WebKit. In addition to supporting WSGI, it -also is a simplification and refactoring of Webware. - -.. _WSGI: http://www.python.org/peps/pep-0333.html - -License -------- - -Paste is distributed under the `Python Software Foundation`__ -license. This is a BSD/MIT-style license. - -.. __: http://www.python.org/psf/license.html - -Quick Start ------------ - -First, grab WSGIUtils, at http://www.owlfish.com/software/wsgiutils/, -or download it directly from -http://www.owlfish.com/software/wsgiutils/downloads/WSGI%20Utils-0.5.tar.gz - -You can use other servers with Paste, but WSGIUtils is pretty easy -and built on SimpleHTTPServer. Run ``python setup.py install`` to -install it. - -Right now it's best NOT to install Paste with ``setup.py``, but just -to run it out of the checkout. An easy way to do that:: - - ./scripts/app-setup create webkit_zpt /path/to/put/files - cd /path/to/put/files - /path/to/paste/scripts/server -v - -And it will be running a server on http://localhost:8080/ - -Compatibility -------------- - -This system is intended to be largely compatible with current Webware -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: - -* Configuration. Right now configuration is a little inconsistent. - -* Contexts. These were half-formed in Webware, and didn't really - provide much benefit. There are much more general and useful ways - to deal with URLs. - -* 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. It's - certainly possible -- and hopefully clearer -- to do introspection - in Paste, but it might not be backward compatible (but still file - bugs if you find problems). - -Discussion ----------- - -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 -``paste/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 -``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 -~~~ - -The ``cgiserver`` script is included. It's not particularly good, -but it's there for you. To use it, you'll set up your own CGI script, -like:: - - #!/usr/bin/env python - # maybe import sys and modify sys.path - from paste import cgiserver - from paste.webkit import wsgiwebkit - app = wsgiwebkit.webkit('/path/to/app') - cgiserver.run_with_cgi(app) - -Twisted -~~~~~~~ - -This package includes ``twisted_wsgi``, which is a WSGI adapter -written by Peter Hunt. The canonical location for this file is: -http://st0rm.hopto.org:8080/wsgi/ (note -- Twisted 2.0 will include -native WSGI support; there's been reports of bugs in the version we -are currently shipping). - -This is closer to the normal Webware environment than CGI. To set up -this server use:: - - #!/usr/bin/env python - # maybe import sys and modify sys.path - from paste import twisted_wsgi - from paste.webkit import wsgiwebkit - app = wsgiwebkit.webkit('/path/to/app') - twisted_wsgi.serve_application(app, 8080) - -Note, the twisted server is dependent on wsgiref which can be found at -http://cvs.eby-sarna.com/wsgiref - - -Multi-threaded -~~~~~~~~~~~~~~ - -WSGIUtils_ includes a SimpleHTTPServer_-based multi-threaded server. -This is an architecture very similar to Webware's AppServer. Twisted -may be the better approach, but who knows? - -.. _WSGIUtils: http://www.owlfish.com/software/wsgiutils/ -.. _SimpleHTTPServer: http://python.org/doc/current/lib/module-SimpleHTTPServer.html - -To set up this server use:: - - #!/usr/bin/env python - from wsgiutils import wsgiServer - from paste.webkit import wsgiwebkit - app_root='/path/to/app' - app = wsgiwebkit.webkit(app_root) - server = wsgiServer.WSGIServer(('127.0.0.1', 8080), {'/': app}) - server.serve_forever() - -Interactive -~~~~~~~~~~~ - -This allows you to test an application without running any web server. -While you can use this several ways (e.g., for acceptance tests), this -is a simple way:: - - #!/usr/bin/env python - # maybe import sys and modify sys.path - from paste import wsgilib - from paste.webkit import wsgiwebkit - app = wsgiwebkit.webkit('/path/to/app') - def run(url): - print wsgilib.interactive(application, url) - if __name__ == '__main__': - import sys - url = sys.argv[1] - run(url) - -Then you run this script with the URL you want to access; the headers -and page will be printed out. This can also be used at the -interactive prompt, e.g., ``python -i interactiveapp.py``, and you can -use pdb_ or other debugging tools with this. - -.. _pdb: http://python.org/doc/current/lib/module-pdb.html - -Comparison of architectures ---------------------------- - -WSGI WebKit's implementation of ``Page`` (and ``HTTPServlet``) -implements a ``__call__`` method, which is all that is required to -make a servlet into a WSGI application. The __call__ method creates -the transaction (``wktransaction.Transaction``), which in turn creates -the request (``wkrequest.HTTPRequest``) and response -(``wkresponse.HTTPResponse``). Then there's a bit of back-and-forth - -There are also session and application objects, which are largely -dummy objects that provide some of the interface that was previously -implemented by those objects. In WSGI WebKit these features -(forwarding and sessions) are implemented in middleware. - -This is in contrast to normal Webware, where the ``AppServer`` starts -the connection, hands it off to ``Application``, which creates -``Transaction``, ``HTTPRequest``, and ``HTTPResponse``, then finds the -servlet and runs it with those objects. |
Thread View
| Thread | Author | Date |
|---|---|---|
| [Webware-checkins] r2368 - Paste/trunk/docs | <ianb@co...> |