paulb@68 | 1 | Introduction
|
paulb@68 | 2 | ------------
|
paulb@68 | 3 |
|
paulb@301 | 4 | WebStack is a package which provides a common API for Python Web
|
paulb@301 | 5 | applications, regardless of the underlying server or framework environment.
|
paulb@301 | 6 | It should be possible with WebStack to design and implement an application,
|
paulb@301 | 7 | to choose a deployment environment, and then to be able to deploy the
|
paulb@301 | 8 | application in a different environment later on without having to go back
|
paulb@301 | 9 | and rewrite substantial parts of the application.
|
paulb@60 | 10 |
|
paulb@362 | 11 | Quick Start
|
paulb@362 | 12 | -----------
|
paulb@362 | 13 |
|
paulb@362 | 14 | Try running the demo:
|
paulb@362 | 15 |
|
paulb@362 | 16 | python tools/demo.py
|
paulb@362 | 17 |
|
paulb@363 | 18 | An introductory guide to creating applications can be found in the docs
|
paulb@363 | 19 | directory - see docs/index.html for the start page.
|
paulb@363 | 20 |
|
paulb@363 | 21 | Contact, Copyright and Licence Information
|
paulb@363 | 22 | ------------------------------------------
|
paulb@363 | 23 |
|
paulb@363 | 24 | The current Web page for WebStack at the time of release is:
|
paulb@363 | 25 |
|
paulb@363 | 26 | http://www.boddie.org.uk/python/WebStack.html
|
paulb@363 | 27 |
|
paulb@363 | 28 | Copyright and licence information can be found in the docs directory - see
|
paulb@413 | 29 | docs/COPYING.txt, docs/LICENCE.txt and docs/LICENCE-PyServlet.txt for more
|
paulb@413 | 30 | information.
|
paulb@363 | 31 |
|
paulb@68 | 32 | Framework Support
|
paulb@68 | 33 | -----------------
|
paulb@68 | 34 |
|
paulb@218 | 35 | Currently, BaseHTTPRequestHandler (via BaseHTTPServer in the standard
|
paulb@301 | 36 | library), CGI, Jython/Java Servlet API, mod_python, Twisted, Webware, WSGI
|
paulb@301 | 37 | and Zope 2 are supported. Each framework has its own set of strengths and
|
paulb@301 | 38 | weaknesses, but the idea is that deployment concerns can be considered
|
paulb@301 | 39 | separately from the implementation of application functionality. Consult the
|
paulb@301 | 40 | NOTES.txt files in each framework's subdirectory of the docs directory for
|
paulb@301 | 41 | some notes on how applications may be run in each environment.
|
paulb@60 | 42 |
|
paulb@244 | 43 | Tested Frameworks Release Information
|
paulb@244 | 44 | ----------------- -------------------
|
paulb@68 | 45 |
|
paulb@362 | 46 | BaseHTTPRequestHandler Python 2.2.2, Python 2.3.3, Python 2.4.1
|
paulb@405 | 47 | CGI Apache 2.0.44, Apache 2.0.53, AOLserver 4.0.10, lighttpd 1.3.15
|
paulb@438 | 48 | Jython/Java Servlet API Jython 2.1, Java JDK 1.3.1_02, Tomcat 4.1.31 (Servlet 2.3)
|
paulb@244 | 49 | mod_python 3.0.3 (3.1.3 for framework cookie and session support)
|
paulb@308 | 50 | Twisted 1.0.5, 1.3.0
|
paulb@438 | 51 | Webware 0.8.1, CVS (2004-02-06), 0.9b2
|
paulb@304 | 52 | WSGI run_with_cgi (PEP 333)
|
paulb@388 | 53 | Zope 2.7.2-0, 2.8.0-final
|
paulb@388 | 54 |
|
paulb@409 | 55 | New in WebStack 1.0 (Changes since WebStack 0.10)
|
paulb@409 | 56 | -------------------------------------------------
|
paulb@409 | 57 |
|
paulb@447 | 58 | Changed the behaviour of get_path, get_path_without_query, get_path_info,
|
paulb@447 | 59 | get_virtual_path_info, get_processed_virtual_path_info and
|
paulb@434 | 60 | get_fields_from_path to return Unicode data decoded using the optional
|
paulb@434 | 61 | encoding parameter or a common default encoding.
|
paulb@451 | 62 | Updated/fixed LoginResource and LoginRedirectResource to use the updated path
|
paulb@451 | 63 | API and to handle special characters properly.
|
paulb@434 | 64 | Added convenience methods to Transaction for the decoding and encoding of path
|
paulb@434 | 65 | values (to and from Unicode objects) - see the decode_path and encode_path
|
paulb@434 | 66 | methods.
|
paulb@447 | 67 | Added the notion of processed virtual path info - the part of the original
|
paulb@447 | 68 | path info not represented in the current virtual path info.
|
paulb@447 | 69 | Added "pass through" behaviour to ResourceMap.MapResource (prompted by a patch
|
paulb@447 | 70 | from Scott Robinson).
|
paulb@447 | 71 | Fixed ResourceMap.MapResource to handle non-existent resources properly (where
|
paulb@447 | 72 | the virtual path info is only one component in length).
|
paulb@409 | 73 | Added Debian package support.
|
paulb@414 | 74 | Added automatic session directory creation for the WebStack sessions
|
paulb@414 | 75 | implementation.
|
paulb@418 | 76 | Added support for the repeated retrieval of sessions from the same WebStack
|
paulb@418 | 77 | session store, avoiding deadlocks.
|
paulb@415 | 78 | Fixed the calendar example, making it perform a proper function.
|
paulb@409 | 79 |
|
paulb@388 | 80 | New in WebStack 0.10 (Changes since WebStack 0.9)
|
paulb@388 | 81 | -------------------------------------------------
|
paulb@388 | 82 |
|
paulb@388 | 83 | Changes to make the tools/demo.py script work on Windows (and other) platforms
|
paulb@388 | 84 | (suggested by Jim Madsen).
|
paulb@394 | 85 | Fixed end of header newlines for CGI (suggested by Matt Harrison).
|
paulb@388 | 86 | Minor documentation fixes and improvements, adding information on AOLserver in
|
paulb@388 | 87 | the CGI and Webware notes.
|
paulb@395 | 88 | Changed the mod_python server name method to use the server object rather than
|
paulb@395 | 89 | the connection object.
|
paulb@396 | 90 | Added a parameter to the ResourceMap.MapResource class to permit automatic
|
paulb@398 | 91 | redirects into resource hierarchies when no trailing "/" was given in the URL;
|
paulb@398 | 92 | changed the updated virtual path info so that empty values may be set (the
|
paulb@398 | 93 | guarantee that "/" will always appear no longer applies).
|
paulb@398 | 94 | Fixed virtual path info retrieval when the value is an empty string.
|
paulb@192 | 95 |
|
paulb@314 | 96 | New in WebStack 0.9 (Changes since WebStack 0.8)
|
paulb@314 | 97 | ------------------------------------------------
|
paulb@314 | 98 |
|
paulb@314 | 99 | Standardised error handling in the adapters so that tracebacks can be
|
paulb@314 | 100 | suppressed and an internal server error condition raised.
|
paulb@314 | 101 | Added overriding of path info in transactions.
|
paulb@314 | 102 | Added a ResourceMap resource for dispatching to different resources
|
paulb@314 | 103 | according to path components.
|
paulb@329 | 104 | Standardised deployment for some frameworks (see docs/deploying.html).
|
paulb@329 | 105 | Introductory documentation in XHTML format.
|
paulb@343 | 106 | Added server name and port methods to the transaction.
|
paulb@363 | 107 | Added a simple demonstration application, incorporating many of the examples
|
paulb@363 | 108 | and launched under a single script.
|
paulb@373 | 109 | Fixed mod_python native sessions.
|
paulb@382 | 110 | Fixed Zope request stream access.
|
paulb@370 | 111 | WebStack is now licensed under the LGPL - see docs/COPYING.txt for details.
|
paulb@314 | 112 |
|
paulb@300 | 113 | New in WebStack 0.8 (Changes since WebStack 0.7)
|
paulb@295 | 114 | ------------------------------------------------
|
paulb@295 | 115 |
|
paulb@295 | 116 | Added a standard exception, EndOfResponse, which can be used to immediately
|
paulb@295 | 117 | stop the processing/production of a response; this is useful when resources
|
paulb@295 | 118 | need to issue a redirect without unnecessary content being generated, for
|
paulb@295 | 119 | example.
|
paulb@299 | 120 | Fixed path information for Zope.
|
paulb@301 | 121 | Added WSGI support.
|
paulb@308 | 122 | Verified Twisted 1.3.0 support with Python 2.3.3.
|
paulb@295 | 123 |
|
paulb@300 | 124 | New in WebStack 0.7 (Changes since WebStack 0.6)
|
paulb@192 | 125 | ------------------------------------------------
|
paulb@192 | 126 |
|
paulb@218 | 127 | Fixed path information semantics.
|
paulb@192 | 128 | Fixed file upload semantics.
|
paulb@227 | 129 | Fixed content type handling for Unicode output and for interpreting request
|
paulb@227 | 130 | body fields/parameters (although some improvement remains).
|
paulb@253 | 131 | Added a method to discover the chosen response stream encoding.
|
paulb@227 | 132 | Fixed field/parameter retrieval so that path and body fields are distinct,
|
paulb@227 | 133 | regardless of the framework employed.
|
paulb@363 | 134 | Added a method to get a combination of path and body fields (suggested by
|
paulb@363 | 135 | Jacob Smullyan).
|
paulb@192 | 136 | Introduced Zope 2 support.
|
paulb@247 | 137 | Improved Jython/Java Servlet API support (although a special PyServlet class
|
paulb@247 | 138 | must now be used, and certain libraries must be deployed with applications).
|
paulb@293 | 139 | Introduced authentication/authorisation support for Jython/Java Servlet API.
|
paulb@293 | 140 | Session support has been added (except for Webware 0.8.1).
|
paulb@247 | 141 | Alternative cookie support for mod_python has been added.
|
paulb@293 | 142 | Cookie support now supports encoded Unicode sequences for names and values.
|
paulb@68 | 143 |
|
paulb@300 | 144 | New in WebStack 0.6 (Changes since WebStack 0.5)
|
paulb@178 | 145 | ------------------------------------------------
|
paulb@178 | 146 |
|
paulb@178 | 147 | Introduced Jython/Java Servlet API support.
|
paulb@178 | 148 | Minor fixes to example applications and to BaseHTTPRequestHandler.
|
paulb@178 | 149 |
|
paulb@300 | 150 | New in WebStack 0.5 (Changes since WebStack 0.4)
|
paulb@171 | 151 | ------------------------------------------------
|
paulb@171 | 152 |
|
paulb@363 | 153 | Changed request body fields/parameters so that they are now represented
|
paulb@363 | 154 | using Unicode objects rather than plain strings.
|
paulb@171 | 155 | Introduced better support for Unicode in response streams.
|
paulb@171 | 156 |
|
paulb@300 | 157 | New in WebStack 0.4 (Changes since WebStack 0.3)
|
paulb@160 | 158 | ------------------------------------------------
|
paulb@140 | 159 |
|
paulb@140 | 160 | Added application definition of user identity, permitting alternative
|
paulb@140 | 161 | authentication mechanisms.
|
paulb@363 | 162 | Improved BaseHTTPRequestHandler and mod_python reliability around fields
|
paulb@363 | 163 | from request bodies.
|
paulb@142 | 164 | Provided stream and environment parameterisation in the CGI adapter.
|
paulb@140 | 165 | Added LoginRedirect and Login examples.
|
paulb@164 | 166 | Added get_path_without_query and fixed get_path behaviour.
|
paulb@140 | 167 |
|
paulb@300 | 168 | New in WebStack 0.3 (Changes since WebStack 0.2)
|
paulb@160 | 169 | ------------------------------------------------
|
paulb@120 | 170 |
|
paulb@120 | 171 | Added better header support for Webware (suggested by Ian Bicking).
|
paulb@120 | 172 | Introduced CGI and Java Servlet support (the latter is currently
|
paulb@120 | 173 | broken/unfinished).
|
paulb@120 | 174 | Introduced support for cookies.
|
paulb@120 | 175 |
|
paulb@68 | 176 | Future Work
|
paulb@68 | 177 | -----------
|
paulb@68 | 178 |
|
paulb@308 | 179 | (Essential)
|
paulb@308 | 180 |
|
paulb@308 | 181 | JythonServlet libraries need to be configured using sys.add_package when
|
paulb@308 | 182 | these do not feature in the compiled-in list. Adding such configuration to
|
paulb@308 | 183 | the handler may be most appropriate (since the web.xml file can be too
|
paulb@308 | 184 | arcane), but this needs testing.
|
paulb@308 | 185 |
|
paulb@308 | 186 | (Important)
|
paulb@308 | 187 |
|
paulb@165 | 188 | Things to consider for future releases: improved cookie support, redirects,
|
paulb@218 | 189 | access to shared resources and much better documentation.
|
paulb@68 | 190 |
|
paulb@363 | 191 | Field access needs testing, especially for anything using the
|
paulb@363 | 192 | cgi.FieldStorage class, and the way file uploads are exposed should be
|
paulb@363 | 193 | reviewed (currently the meta-data is not exposed). The acquisition of fields
|
paulb@363 | 194 | from specific sources should be tested with different request methods - some
|
paulb@363 | 195 | frameworks provide path fields in the body fields dictionary, others (eg.
|
paulb@363 | 196 | Zope) change the fields exposed depending on request method.
|
paulb@248 | 197 |
|
paulb@363 | 198 | Interpretation of path field encodings needs to be verified. Currently,
|
paulb@363 | 199 | stray path fields are handled (eg. in WebStack.Helpers.Request) as being
|
paulb@363 | 200 | ISO-8859-1, but it might be the case that some such fields might be
|
paulb@438 | 201 | submitted as UTF-8. The decode_path method on Transaction does do much of the
|
paulb@438 | 202 | work that is likely to be required, however.
|
paulb@438 | 203 |
|
paulb@438 | 204 | An interesting test of encodings is to introduce things like the following to
|
paulb@438 | 205 | the path info and query string sections of the URL: %25F0?%E6=%F8&%25F0=%F8
|
paulb@438 | 206 | This should produce the following decoded result: %F0?æ=ø&%F0=ø
|
paulb@438 | 207 | (The above needs to be read in ISO-8859-1 or ISO-8859-15.)
|
paulb@102 | 208 |
|
paulb@102 | 209 | Cookie objects need defining strictly, especially since the standard library
|
paulb@363 | 210 | Cookie object behaves differently to mod_python (and possibly Webware)
|
paulb@363 | 211 | Cookie objects. Moreover, the set_cookie_value method needs to provide
|
paulb@363 | 212 | access to the usual cookie parameters as supported by the frameworks. The
|
paulb@363 | 213 | standard library Cookie module has issues with Unicode cookie names (and
|
paulb@363 | 214 | possibly values) - this is worked around, but it would be best to resolve
|
paulb@363 | 215 | this comprehensively.
|
paulb@90 | 216 |
|
paulb@363 | 217 | UTF-16 (and possibly other encodings) causes problems with HTML form data
|
paulb@363 | 218 | sent in POST requests using the application/x-www-form-urlencoded content
|
paulb@363 | 219 | type. This should be reviewed at a later date when proper standardisation
|
paulb@363 | 220 | has taken place.
|
paulb@218 | 221 |
|
paulb@239 | 222 | Session support, especially through WebStack.Helpers.Session, should be
|
paulb@248 | 223 | reviewed and be made compatible with non-cookie mechanisms.
|
paulb@248 | 224 |
|
paulb@248 | 225 | HeaderValue objects should be employed more extensively. Thus, the header
|
paulb@248 | 226 | access methods may need to change their behaviour slightly.
|
paulb@248 | 227 |
|
paulb@248 | 228 | Investigate the nicer functions in the cgi module, discarding the "magic"
|
paulb@248 | 229 | stuff like FieldStorage.
|
paulb@239 | 230 |
|
paulb@304 | 231 | WSGI support could demand that a special "end of headers" method be
|
paulb@304 | 232 | introduced into WebStack, thus making response output more efficient (and
|
paulb@304 | 233 | probably also for other frameworks, too).
|
paulb@304 | 234 |
|
paulb@363 | 235 | The algorithm employed in the WebStack.Helpers.Auth.get_token function
|
paulb@363 | 236 | should be reviewed and improved for better security.
|
paulb@332 | 237 |
|
paulb@336 | 238 | Investigate proper support for HEAD, OPTIONS and other request methods.
|
paulb@336 | 239 |
|
paulb@438 | 240 | Consider packages for different operating systems (other than Debian).
|
paulb@365 | 241 |
|
paulb@355 | 242 | (Completed/rejected)
|
paulb@355 | 243 |
|
paulb@355 | 244 | The location of deployed applications in the filesystem should be exposed to
|
paulb@355 | 245 | those applications. (This is actually available in the __file__ module
|
paulb@355 | 246 | variable.)
|
paulb@355 | 247 |
|
paulb@355 | 248 | Path information should be consistent across all frameworks, and the "path
|
paulb@355 | 249 | info" value should be meaningful. (This should now be correct.)
|
paulb@355 | 250 |
|
paulb@159 | 251 | Release Procedures
|
paulb@159 | 252 | ------------------
|
paulb@159 | 253 |
|
paulb@159 | 254 | Update the WebStack/__init__.py __version__ attribute.
|
paulb@329 | 255 | Change the version number and package filename/directory in the documentation.
|
paulb@332 | 256 | Change code examples in the documentation if appropriate.
|
paulb@159 | 257 | Update the release notes (see above).
|
paulb@159 | 258 | Check the setup.py file and ensure that all package directories are mentioned.
|
paulb@417 | 259 | Check the release information in the PKG-INFO file and in the package
|
paulb@417 | 260 | changelog (and other files).
|
paulb@253 | 261 | Tag, export.
|
paulb@247 | 262 | Generate the PyServlet classes.
|
paulb@355 | 263 | Generate the API documentation.
|
paulb@384 | 264 | Remove generated .pyc files: rm `find . -name "*.pyc"`
|
paulb@253 | 265 | Archive, upload.
|
paulb@367 | 266 | Upload the introductory documentation.
|
paulb@365 | 267 | Update PyPI, PythonInfo Wiki, Vaults of Parnassus entries.
|
paulb@355 | 268 |
|
paulb@355 | 269 | Generating the API Documentation
|
paulb@355 | 270 | --------------------------------
|
paulb@355 | 271 |
|
paulb@363 | 272 | In order to prepare the API documentation, it is necessary to generate some
|
paulb@363 | 273 | Web pages from the Python source code. For this, the epydoc application must
|
paulb@363 | 274 | be available on your system. Then, inside the WebStack directory, run the
|
paulb@355 | 275 | apidocs.sh tool script as follows:
|
paulb@355 | 276 |
|
paulb@355 | 277 | ./tools/apidocs.sh
|
paulb@355 | 278 |
|
paulb@355 | 279 | Some warnings may be generated by the script, but the result should be a new
|
paulb@355 | 280 | apidocs directory within the WebStack directory.
|