Webware for Python

Update of /cvsroot/webware/Webware/WebKit
In directory sc8-pr-cvs1:/tmp/cvs-serv26542

Modified Files:
	URLParser.py 
Log Message:
Filenames starting with a . (i.e., hidden) were being considered
files with empty names, and the . started the extension.  Now they
are ignored.


Index: URLParser.py
===================================================================
RCS file: /cvsroot/webware/Webware/WebKit/URLParser.py,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** URLParser.py	26 Mar 2003 01:55:22 -0000	1.3
--- URLParser.py	26 Mar 2003 03:17:32 -0000	1.4
***************
*** 333,337 ****
  		filenames = []
  		for filename in os.listdir(dir):
! 			if filename == fileStart:
  				filenames.append(os.path.join(dir, filename))
  			elif filename.startswith(fileStart) \
--- 333,339 ----
  		filenames = []
  		for filename in os.listdir(dir):
! 			if filename.startswith('.'):
! 				continue
! 			elif filename == fileStart:
  				filenames.append(os.path.join(dir, filename))
  			elif filename.startswith(fileStart) \

Update of /cvsroot/webware/Webware/WebKit
In directory sc8-pr-cvs1:/tmp/cvs-serv21641

Modified Files:
	ThreadedAppServerService.py 
Log Message:
Fixed reST/extractor wonkiness


Index: ThreadedAppServerService.py
===================================================================
RCS file: /cvsroot/webware/Webware/WebKit/ThreadedAppServerService.py,v
retrieving revision 1.10
retrieving revision 1.11
diff -C2 -d -r1.10 -r1.11
*** ThreadedAppServerService.py	26 Mar 2003 00:49:32 -0000	1.10
--- ThreadedAppServerService.py	26 Mar 2003 03:03:48 -0000	1.11
***************
*** 36,39 ****
--- 36,41 ----
  
      python ThreadedAppServerService.py remove
+ 
+ Currently only one AppServer per system can be set up this way.
  """

Update of /cvsroot/webware/Webware/WebKit
In directory sc8-pr-cvs1:/tmp/cvs-serv20733

Modified Files:
	ExceptionHandler.py 
Log Message:
Fixed funny reST behavior


Index: ExceptionHandler.py
===================================================================
RCS file: /cvsroot/webware/Webware/WebKit/ExceptionHandler.py,v
retrieving revision 1.29
retrieving revision 1.30
diff -C2 -d -r1.29 -r1.30
*** ExceptionHandler.py	26 Mar 2003 00:49:32 -0000	1.29
--- ExceptionHandler.py	26 Mar 2003 03:01:42 -0000	1.30
***************
*** 59,62 ****
--- 59,65 ----
  		def contextInitialize(app, ctxPath):
  			app._exceptionHandlerClass = ExceptionHandler
+ 
+ 	You can also control the errors with settings in
+ 	``Application.config``	
  	"""

Update of /cvsroot/webware/Webware/WebKit
In directory sc8-pr-cvs1:/tmp/cvs-serv17770

Modified Files:
	HTTPExceptions.py 
Log Message:
docstring work


Index: HTTPExceptions.py
===================================================================
RCS file: /cvsroot/webware/Webware/WebKit/HTTPExceptions.py,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** HTTPExceptions.py	19 Mar 2003 11:48:55 -0000	1.1
--- HTTPExceptions.py	26 Mar 2003 02:55:21 -0000	1.2
***************
*** 1,2 ****
--- 1,15 ----
+ """
+ HTTPExceptions are for situations that are predicted by the
+ HTTP spec.  Where the ``200 OK`` response is typical, a
+ ``404 Not Found`` or ``301 Moved Temporarily`` response is not
+ entirely unexpected.
+ 
+ `Application` catches all `HTTPException` exceptions (and subclasses
+ of HTTPException), and instead of being errors these are translated
+ into responses.  In various places these can also be caught and
+ changed, for instance an `HTTPAuthenticationRequired` could be
+ turned into a normal login page.
+ """
+ 
  from types import *
  from WebUtils.Funcs import htmlEncode
***************
*** 9,16 ****
  	Subclasses must define these variables (usually as class
  	variables):
! 	_code: a tuple of the integer error code, and the short
! 	    description that goes with it (like (200, "OK"))
! 	_description: the long-winded description, to be presented
! 	    in the response page.  Or you can override description().
  	"""
  
--- 22,33 ----
  	Subclasses must define these variables (usually as class
  	variables):
! 
! 	`_code`:
! 	    a tuple of the integer error code, and the short
! 	    description that goes with it (like ``(200, "OK")``)
! 	`_description`:
! 	    the long-winded description, to be presented
! 	    in the response page.  Or you can override description()
! 	    if you want something more context-sensitive.
  	"""
  
***************
*** 18,34 ****
  
  	def code(self):
  		return self._code[0]
  
  	def codeMessage(self):
  		return self._code[1]
  
  	def html(self):
  		return '''
  <html><head><title>%(code)s %(title)s</title></head>
  <body>
! <h1>%(title)s</h1>
  %(body)s
  </body></html>''' % {
! 			"title": self.htTitle(),
  			"body": self.htBody(),
  			"code": self.code()
--- 35,66 ----
  
  	def code(self):
+ 		"""
+ 		The integer code
+ 		"""
  		return self._code[0]
  
  	def codeMessage(self):
+ 		"""
+ 		The message (like ``Not Found``) that goes with the code
+ 		"""
  		return self._code[1]
  
+ 	"""
+ 	**HTML Description**
+ 	"""
+ 
  	def html(self):
+ 		"""
+ 		The HTML page that should be sent with the error,
+ 		usually a description of the problem.
+ 		"""
  		return '''
  <html><head><title>%(code)s %(title)s</title></head>
  <body>
! <h1>%(htTitle)s</h1>
  %(body)s
  </body></html>''' % {
! 			"htTitle": self.htTitle(),
! 			"title": self.title(),
  			"body": self.htBody(),
  			"code": self.code()
***************
*** 36,45 ****
--- 68,87 ----
  
  	def title(self):
+ 		"""
+ 		The title used in the HTML page
+ 		"""
  		return self.codeMessage()
  
  	def htTitle(self):
+ 		"""
+ 		The title, but it may include HTML markup (like
+ 		italics)
+ 		"""
  		return self.title()
  
  	def htBody(self):
+ 		"""
+ 		The HTML body of the page.
+ 		"""
  		body = self.htDescription()
  		if self.args:
***************
*** 47,75 ****
  		return body
  
- 	def headers(self):
- 		return {}
- 
- 	def title(self):
- 		return self.codeMessage()
- 
  	def description(self):
  		return self._description
  
  	def htDescription(self):
  		return self.description()
  
  	def setTransaction(self, trans):
  		self._transaction = trans
  
  
  class HTTPNotImplemented(HTTPException):
  	_code = 501, "Not Implemented"
  	_description = "The method given is not yet implemented by this application"
  
  class HTTPForbidden(HTTPException):
  	_code = 403, 'Forbidden'
  	_description = "You are not authorized to access this resource"
  
  class HTTPAuthenticationRequired(HTTPException):
  	_code = 401, 'Authentication Required'
  	_description = "You must log in to access this resource"
--- 89,169 ----
  		return body
  
  	def description(self):
+ 		"""
+ 		Possibly a plain text version of the error description,
+ 		though usually just identical to `htDescription`.
+ 		"""
  		return self._description
  
  	def htDescription(self):
+ 		"""
+ 		The HTML description of the error, for presentation
+ 		to the browser user.
+ 		"""
  		return self.description()
  
+ 	"""
+ 	**Misc**
+ 	"""
+ 
+ 	def headers(self):
+ 		"""
+ 		Additional headers that should be sent with the
+ 		response, not including the Status header.  For instance,
+ 		the redirect exception adds a Location header
+ 		"""
+ 		return {}
+ 
  	def setTransaction(self, trans):
+ 		"""
+ 		When the exception is caught by `Application`, it tells
+ 		the exception what the transaction is.  This way you
+ 		can resolve relative paths, or otherwise act in a manner
+ 		sensitive of the context of the error.
+ 		"""
  		self._transaction = trans
  
  
  class HTTPNotImplemented(HTTPException):
+ 
+ 	"""
+ 	When methods (like GET, POST, PUT, PROPFIND, etc) are not
+ 	implemented for this resource.
+ 	"""
+ 	
  	_code = 501, "Not Implemented"
  	_description = "The method given is not yet implemented by this application"
  
  class HTTPForbidden(HTTPException):
+ 
+ 	"""
+ 	When access is not allowed to this resource.  If the user is
+ 	anonymous, and must be authenticated, then
+ 	HTTPAuthenticationRequired is a preferable exception.  If the
+ 	user should not be able to get to this resource (at least through
+ 	the path they did), or is authenticated and still doesn't have
+ 	access, or no one is allowed to view this, then HTTPForbidden would
+ 	be the proper response.
+ 	"""
+ 	
  	_code = 403, 'Forbidden'
  	_description = "You are not authorized to access this resource"
  
  class HTTPAuthenticationRequired(HTTPException):
+ 
+ 	"""
+ 	HTTPAuthenticationRequired will usually cause the browser
+ 	to open up an HTTP login box, and after getting login information
+ 	from the user, the browser will resubmit the request.  However,
+ 	this should also trigger login pages in properly set up
+ 	environments (though much code will not work this way).
+ 
+ 	Browsers will usually not send authentication information unless
+ 	they receive this response, even when other pages on the site
+ 	have given 401 responses before.  So when using this
+ 	authentication every request will usually be doubled, once
+ 	without authentication, once with.
+ 	"""
+ 	
  	_code = 401, 'Authentication Required'
  	_description = "You must log in to access this resource"
***************
*** 84,111 ****
--- 178,251 ----
  		return {'WWW-Authenticate': 'Basic realm="%s"' % self._realm}
  
+ """
+ There is also an alias `HTTPAuthorizationRequired`, as it is hard
+ to distinguish between these two names.
+ """
+ 
  ## This is for wording mistakes.  I'm unsure about their benefit.
  HTTPAuthorizationRequired = HTTPAuthenticationRequired
  
  class HTTPMethodNotAllowed(HTTPException):
+ 	"""
+ 	When a method (like GET, PROPFIND, POST, etc) is not allowed
+ 	on this resource (usually because it does not make sense, not
+ 	because it is not permitted).  Mostly for WebDAV.
+ 	"""
+ 	
  	_code = 405, 'Method Not Allowed'
  	_description = 'The method is not supported on this resource'
  
  class HTTPConflict(HTTPException):
+ 	"""
+ 	When there's a locking conflict on this resource (in response
+ 	to something like a PUT, not for most other conflicts).
+ 	Mostly for WebDAV.
+ 	"""
+ 	
  	_code = 409, 'Conflict'
  
  class HTTPUnsupportedMediaType(HTTPException):
+ 	"""
+ 	Uhh....
+ 	"""
+ 	
  	_code = 415, 'Unsupported Media Type'
  
  class HTTPInsufficientStorage(HTTPException):
+ 	"""
+ 	When there is not sufficient storage, usually in response
+ 	to a PUT when there isn't enough disk space.  Mostly for WebDAV.
+ 	"""
+ 	
  	_code = 507, 'Insufficient Storage'
  	_description = 'There was not enough storage space on the server to complete your request'
  
  class HTTPPreconditionFailed(HTTPException):
+ 	"""
+ 	During compound, atomic operations, when a precondition for
+ 	an early operation fail, then later operations in will fail
+ 	with this code.  Mostly for WebDAV.
+ 	"""
+ 	
  	_code = 412, 'Precondition Failed'
  
  class HTTPMovedPermanently(HTTPException):
+ 	"""
+ 	When a resource is permanently moved.  The browser may remember
+ 	this relocation, and later requests may skip requesting the
+ 	original resource altogether.
+ 	"""
+ 	
  	_code = 301, 'Moved Permanently'
  	
  	def __init__(self, location=None, webkitLocation=None, *args):
+ 		"""
+ 		HTTPMovedPermanently needs a destination that you
+ 		it should be directed to -- you can pass `location`
+ 		*or* `webkitLocation` -- if you pass `webkitLocation`
+ 		it will be relative to the WebKit base (the portion
+ 		through the adapter).
+ 		"""
+ 		
  		self._location = location
  		self._webkitLocation = webkitLocation
***************
*** 113,116 ****
--- 253,259 ----
  
  	def location(self):
+ 		"""
+ 		The location that we will be redirecting to
+ 		"""
  		if self._webkitLocation:
  			environ = self._transaction.request().environ()
***************
*** 126,129 ****
--- 269,275 ----
  
  	def headers(self):
+ 		"""
+ 		We include a Location header
+ 		"""
  		return {'Location': self.location()}
  
***************
*** 133,136 ****
--- 279,289 ----
  class HTTPTemporaryRedirect(HTTPMovedPermanently):
  
+ 	"""
+ 	Like HTTPMovedPermanently, except the redirect is only valid for
+ 	this request.  Internally identical to HTTPMovedPermanently,
+ 	except with a different response code.  Browsers will check the
+ 	server for each request to see where it's redirected to.
+ 	"""
+ 
  	_code = 307, 'Temporary Redirect'
  
***************
*** 139,145 ****
--- 292,309 ----
  
  class HTTPBadRequest(HTTPException):
+ 	"""
+ 	When the browser sends an invalid request.
+ 	"""
+ 	
  	_code = 400, 'Bad Request'
  
  class HTTPNotFound(HTTPException):
+ 	"""
+ 	When the requested resource does not exist.  To be more secretive,
+ 	it is okay to return a 404 if access to the resource is not
+ 	permitted (you are not required to use HTTPForbidden, though it
+ 	makes it more clear why access was disallowed).
+ 	"""
+ 	
  	_code = 404, 'Not Found'
  	_description = 'The resource you were trying to access was not found'

Update of /cvsroot/webware/Webware/WebKit
In directory sc8-pr-cvs1:/tmp/cvs-serv17313

Modified Files:
	Application.py 
Log Message:
Fixed indent



Index: Application.py
===================================================================
RCS file: /cvsroot/webware/Webware/WebKit/Application.py,v
retrieving revision 1.166
retrieving revision 1.167
diff -C2 -d -r1.166 -r1.167
*** Application.py	25 Mar 2003 23:15:33 -0000	1.166
--- Application.py	26 Mar 2003 02:54:16 -0000	1.167
***************
*** 91,99 ****
  
  		URLParser.initApp(self)
!                 self._rootURLParser = URLParser.ContextParser(self)
  
  		self.running = 1
  
!                 self.startSessionSweeper()
  
  		self._exceptionHandlerClass = ExceptionHandler
--- 91,99 ----
  
  		URLParser.initApp(self)
! 		self._rootURLParser = URLParser.ContextParser(self)
  
  		self.running = 1
  
! 		self.startSessionSweeper()
  
  		self._exceptionHandlerClass = ExceptionHandler
***************
*** 326,330 ****
  	def serverSidePath(self, path=None):
  		"""
!                 Returns the absolute server-side path of the WebKit
  		application. If the optional path is passed in, then
  		it is joined with the server side directory to form a
--- 326,330 ----
  	def serverSidePath(self, path=None):
  		"""
! 		Returns the absolute server-side path of the WebKit
  		application. If the optional path is passed in, then
  		it is joined with the server side directory to form a

Update of /cvsroot/webware/Webware/WebKit
In directory sc8-pr-cvs1:/tmp/cvs-serv31733

Modified Files:
	URLParser.py 
Log Message:
docstring work


Index: URLParser.py
===================================================================
RCS file: /cvsroot/webware/Webware/WebKit/URLParser.py,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** URLParser.py	25 Mar 2003 22:58:05 -0000	1.2
--- URLParser.py	26 Mar 2003 01:55:22 -0000	1.3
***************
*** 1,2 ****
--- 1,17 ----
+ """
+ URL parsing is done through objects which are subclasses of the
+ `URLParser` class.  `Application` delegates most of the URL parsing
+ to these objects.
+ 
+ Application has a single "root" URL parser, which is used to parse
+ all URLs.  This parser then can pass the request on to other parsers,
+ usually taking off parts of the URL with each step.
+ 
+ This root parser is generally `ContextParser`, which is instantiated
+ and set up by `Application` (accessible through
+ `Application.rootURLParser`).
+ """
+ 
+ 
  import WebKit.ImportSpy as imp
  import re, os, sys
***************
*** 11,14 ****
--- 26,33 ----
  
  def application():
+ 	"""
+ 	Returns the global Application.
+ 	:ignore:
+ 	"""
  	return AppServer.globalAppServer.application()
  
***************
*** 22,25 ****
--- 41,56 ----
  	control how the parser works (for instance, passing a starting
  	path for the parser)
+ 
+ 	The `parse` method is where most of the work is done.  It takes
+ 	two arguments -- the transaction and the portion of the URL
+ 	that is still to be parsed.  The transaction may (and usually
+ 	is) modified along the way.  The URL is passed through so that
+ 	you can take pieces off the front, and then pass the reduced
+ 	URL to another parser.  The method should return a servlet
+ 	(never None).
+ 
+ 	If you cannot find a servlet, or some other (somewhat)
+ 	expected error occurs, you should raise an exception.
+ 	HTTPNotFound probably being the most interesting.
  	"""
  
***************
*** 28,31 ****
--- 59,66 ----
  
  	def findServletForTransaction(self, trans):
+ 		"""
+ 		Returns a servlet for the transaction.  This is the
+ 		top-level entry point, below it `parse` is used.
+ 		"""
  		return self.parse(trans, trans.request().urlPath())
  
***************
*** 33,37 ****
  
  	"""
! 	ContextParser uses the Application.config context settings
  	to find the context of the request.  It then passes the
  	request to a FileParser rooted in the context path.
--- 68,72 ----
  
  	"""
! 	ContextParser uses the ``Application.config`` context settings
  	to find the context of the request.  It then passes the
  	request to a FileParser rooted in the context path.
***************
*** 40,43 ****
--- 75,81 ----
  	matches that then it is the ``default`` context (and the
  	entire URL is passed to the default context's FileParser).
+ 
+ 	There is generally only one ContextParser, which can be
+ 	found as ``application.rootURLParser()``.  
  	"""
  
***************
*** 127,130 ****
--- 165,173 ----
  
  	def absContextPath(self, path):
+ 		"""
+ 		Resolves relative paths, which are assumed to be
+ 		relative to the Application's serverSidePath (the
+ 		working directory).
+ 		"""
  		if os.path.isabs(path):
  			return path
***************
*** 136,139 ****
--- 179,186 ----
  		Get the context name, and dispatch to a FileParser
  		rooted in the context's path.
+ 
+ 		The context name and file path are stored in the
+ 		request (accessible through `Request.serverSidePath`
+ 		and `Request.contextName`).
  		"""
  		# This is a hack... this should probably go in the
***************
*** 164,171 ****
  	FileParser objects are threadsafe.  A factory function is
  	used to cache FileParser instances, so for any one path only
! 	a single FileParser instance will exist.
  	"""
  
  	def __init__(self, path):
  		URLParser.__init__(self)
  		self._path = path
--- 211,232 ----
  	FileParser objects are threadsafe.  A factory function is
  	used to cache FileParser instances, so for any one path only
! 	a single FileParser instance will exist.  The `_FileParser`
! 	class is the real class, and `FileParser` is a factory that
! 	either returns an existant _FileParser object, or creates a
! 	new one if none exists.
! 
! 	FileParser uses several settings from ``Application.config``,
! 	which are persistant over the life of the application.  These
! 	are set up in the function `initApp`, as class variables.
! 	They cannot be set when the module is loaded, because the
! 	Application is not yet set up, so `initApp` is called in
! 	`Application.__init__`.
  	"""
  
  	def __init__(self, path):
+ 		"""
+ 		Each parsed directory has a FileParser instance associated
+ 		with it (``self._path``).
+ 		"""
  		URLParser.__init__(self)
  		self._path = path
***************
*** 175,179 ****
  		"""
  		Return the servlet.  __init__ files will be used for various
! 		hooks (see parseInit for more)
  		"""
  
--- 236,251 ----
  		"""
  		Return the servlet.  __init__ files will be used for various
! 		hooks (see `parseInit` for more)
! 
! 		If the next part of the URL is a directory, it calls
! 		``FileParser(dirPath).parse(trans, restOfPath)`` where
! 		``restOfPath`` is `requestPath` with the first section
! 		of the path removed (the part of the path that this
! 		FileParser just handled).
! 
! 		This uses `fileNamesForBaseName` to find files in its
! 		directory.  That function has several functions to define
! 		what files are ignored, hidden, etc.  See its documentation
! 		for more information.
  		"""
  
***************
*** 218,223 ****
  
  
- 	_filesSetup = 0
- 				
  	def filenamesForBaseName(self, baseName):
  		"""
--- 290,293 ----
***************
*** 310,314 ****
  		"""
  		Return the servlet for a directory index (i.e., ``Main`` or
! 		``index``).
  		"""
  
--- 380,404 ----
  		"""
  		Return the servlet for a directory index (i.e., ``Main`` or
! 		``index``).  When `parse` encounters a directory and there's
! 		nothing left in the URL, or when there is something left
! 		and no file matches it, then it will try `parseIndex` to
! 		see if there's an index file.
! 
! 		That means that if ``/a/b/c`` is requested, and in ``/a``
! 		there's no file or directory matching ``b``, then it'll
! 		look for an index file (like ``Main.py``), and that
! 		servlet will be returned.  In fact, if no ``a`` was found,
! 		and the default context had an index (like ``index.html``)
! 		then that would be called with ``/a/b/c`` as
! 		`HTTPRequest.extraURLPath`.  If you don't want that
! 		to occur, you should raise an HTTPNotFound in your
! 		no-extra-url-path-taking servlets.
! 
! 		The directory names are based off the ``Application.config``
! 		setting ``DirectoryFile``, which is a list of base names,
! 		by default ``["Main", "index", "main", "Index"]``, which
! 		are searched in order.  A file with any extension is
! 		allowed, so the index can be an HTML file, a PSP file,
! 		a Python servlet, etc.
  		"""
  
***************
*** 509,513 ****
  	will be set in the request (so long as no field by that name
  	already exists -- if a field does exist the variable is thrown
! 	away).
  
  	It should be put in an __init__, like::
--- 599,603 ----
  	will be set in the request (so long as no field by that name
  	already exists -- if a field does exist the variable is thrown
! 	away).  These are put in the place of GET or POST variables.
  
  	It should be put in an __init__, like::
***************
*** 525,531 ****
--- 615,632 ----
  
  	def parse(self, trans, requestPath):
+ 		"""
+ 		Delegates to `parseHook`.
+ 		"""
  		return self.parseHook(trans, requestPath, self.fileParser)
  
  	def parseHook(self, trans, requestPath, hook):
+ 		"""
+ 		Munges the path.  The `hook` is the FileParser object
+ 		that originally called this -- we just want to strip
+ 		stuff out of the URL and then give it back to the
+ 		FileParser instance, which can actually find the
+ 		servlet.
+ 		"""
+ 		
  		parts = requestPath.split('/')
  		result = []
***************
*** 543,559 ****
  
  	"""
! 	This singleton class manages all the servlet factories
! 	that are installed.  The primary instance is called
! 	ServletFactoryManager.
! 
! 	Servlets can add themselves with the `addServletFactory(factory)`
! 	method; the factory must have an `extensions` method, which
! 	should return a list of extensions that the factory handles
! 	(like ``['.ht']``).  The special extension ``.*`` will match
! 	any file if no other factory is found.
  
! 	The method `servetForFile(trans, path)` will create a servlet
! 	based on the path, raising HTTPNotFound if no appropriate
! 	factory can be found.
  	"""
  
--- 644,652 ----
  
  	"""
! 	This singleton (called `ServletFactoryManager`) collects
! 	and manages all the servlet factories that are installed.
  
! 	See `addServletFactory` for adding new factories, and
! 	`servletForFile` for getting the factories back.
  	"""
  
***************
*** 563,566 ****
--- 656,671 ----
  
  	def addServletFactory(self, factory):
+ 		"""
+ 		Servlet factories can add themselves with::
+ 		
+ 		    ServletFactoryManager.addServletFactory(factory)
+ 	    
+ 		The factory must have an `extensions` method, which should
+ 		return a list of extensions that the factory handles (like
+ 		``['.ht']``).  The special extension ``.*`` will match any
+ 		file if no other factory is found.  See `ServletFactory`
+ 		for more information.
+ 		"""
+ 
  		self._factories.append(factory)
  		for ext in factory.extensions():
***************
*** 572,575 ****
--- 677,684 ----
  
  	def factoryForFile(self, path):
+ 		"""
+ 		Gets a factory for a filename.
+ 		"""
+ 		
  		name, ext = os.path.splitext(path)
  		if self._factoryExtensions.has_key(ext):
***************
*** 580,583 ****
--- 689,698 ----
  
  	def servletForFile(self, trans, path):
+ 		"""
+ 		Gets a servlet for a filename and transaction.
+ 		Uses `factoryForFile` to find the factory, which
+ 		creates the servlet.
+ 		"""
+ 		
  		factory = self.factoryForFile(path)
  		return factory.servletForTransaction(trans)
***************
*** 615,619 ****
  	cls._useCascading = app.setting('UseCascadingExtensions')
  	cls._cascadeOrder = app.setting('ExtensionCascadeOrder')
- 	cls._filesSetup = 1
  	cls._directoryFile = app.setting('DirectoryFile')
  
--- 730,733 ----

Update of /cvsroot/webware/Webware/WebKit
In directory sc8-pr-cvs1:/tmp/cvs-serv10158

Modified Files:
	ASStreamOut.py Cookie.py ExceptionHandler.py 
	ThreadedAppServerService.py 
Log Message:
docstring work


Index: ASStreamOut.py
===================================================================
RCS file: /cvsroot/webware/Webware/WebKit/ASStreamOut.py,v
retrieving revision 1.6
retrieving revision 1.7
diff -C2 -d -r1.6 -r1.7
*** ASStreamOut.py	27 Jan 2003 16:06:08 -0000	1.6
--- ASStreamOut.py	26 Mar 2003 00:49:32 -0000	1.7
***************
*** 15,30 ****
  	"""
  	This is a response stream to the client.
  	The key attributes of this class are:
  	
! 	autoCommit: if True (1), the stream will automatically start sending data once
! 	it has accumulated bufferSize data.  This means that it will ask the response
! 	to commit itself, without developer interaction.
! 
! 	bufferSize: The size of the data buffer.  This is only used when autocommit is true (1).
! 	If not using autocommit, the whole response is buffered and sent in one shot when the
! 	servlet is done..
! 
! 	flush(): Send the accumulated response data now. Will ask the Response to commit if
! 	it hasn't already done so.
  	"""
  
--- 15,33 ----
  	"""
  	This is a response stream to the client.
+ 	
  	The key attributes of this class are:
  	
! 	`_autoCommit`:
! 	    if True (1), the stream will automatically start sending data
! 	    once it has accumulated `_bufferSize` data.  This means that
! 	    it will ask the response to commit itself, without developer
! 	    interaction.
! 	`_bufferSize`:
! 	    The size of the data buffer.  This is only used when autocommit
! 	    is true (1).  If not using autocommit, the whole response is
! 	    buffered and sent in one shot when the servlet is done.
! 	`flush()`:
! 	    Send the accumulated response data now. Will ask the `Response`
! 	    to commit if it hasn't already done so.
  	"""
  
***************
*** 39,45 ****
  		self._closed = 0
  
- 
  	def autoCommit(self, val=0):
! 		"""Get/Set the value of autoCommit."""
  		assert type(val) is types.IntType, "autoCommit must be an integer"
  		self._autoCommit = val
--- 42,52 ----
  		self._closed = 0
  
  	def autoCommit(self, val=0):
! 		# @@ 2003-03 ib: doing both get and set in the same
! 		# function is not good.
! 		"""
! 		Get/Set the value of _autoCommit.
! 		"""
! 		
  		assert type(val) is types.IntType, "autoCommit must be an integer"
  		self._autoCommit = val
***************
*** 47,50 ****
--- 54,58 ----
  
  	def bufferSize(self, size=8192):
+ 		# @@ 2003-03 ib: again, get/set not good
  		"""
  		Returns the size of the buffer, and sets a new size if one is
***************
*** 58,62 ****
  		"""
  		Send available data as soon as possible, ie Now
! 		Returns 1 if we are ready to send, otherwise 0
  		"""
  		assert not self._closed, "Trying to flush when already closed"
--- 66,71 ----
  		"""
  		Send available data as soon as possible, ie Now
! 		Returns 1 if we are ready to send, otherwise 0 (i.e.,
! 		if the buffer is full enough).
  		"""
  		assert not self._closed, "Trying to flush when already closed"
***************
*** 90,94 ****
  	def clear(self):
  		"""
! 		Try to clear any accumulated response data.  Will fail if the response is already sommitted.
  		"""
  		if debug: print ">>> strmOut clear called"
--- 99,104 ----
  	def clear(self):
  		"""
! 		Try to clear any accumulated response data.  Will fail
! 		if the response is already sommitted.
  		"""
  		if debug: print ">>> strmOut clear called"
***************
*** 151,155 ****
  	def needCommit(self):
  		"""
! 		Called by the HTTPResponse instance that is using this instance
  		to ask if the response needs to be prepared to be delivered.
  		The response should then commit it's headers, etc.
--- 161,165 ----
  	def needCommit(self):
  		"""
! 		Called by the `HTTPResponse` instance that is using this instance
  		to ask if the response needs to be prepared to be delivered.
  		The response should then commit it's headers, etc.
***************
*** 159,165 ****
  	def commit(self, autoCommit=1):
  		"""
! 		Called by the Response to tell us to go.
! 		If autoCommit is 1, then we will be placed into autoCommit mode.
  		"""
  		if debug: print ">>> ASStreamOut Committing"
  		self._committed = 1
--- 169,176 ----
  	def commit(self, autoCommit=1):
  		"""
! 		Called by the Response to tell us to go.  If `_autoCommit`
! 		is 1, then we will be placed into autoCommit mode.
  		"""
+ 		
  		if debug: print ">>> ASStreamOut Committing"
  		self._committed = 1
***************
*** 171,174 ****
--- 182,186 ----
  		Write a string to the buffer.
  		"""
+ 		
  		if debug: print ">>> ASStreamOut writing %s characters" % len(charstr)
  		assert not self._closed, "Stream Already Closed"

Index: Cookie.py
===================================================================
RCS file: /cvsroot/webware/Webware/WebKit/Cookie.py,v
retrieving revision 1.8
retrieving revision 1.9
diff -C2 -d -r1.8 -r1.9
*** Cookie.py	8 Jan 2003 05:47:42 -0000	1.8
--- Cookie.py	26 Mar 2003 00:49:32 -0000	1.9
***************
*** 1,16 ****
  from Common import *
  
! # If this is Python 2.2 or greater, import the standard Cookie module as CookieEngine.
! # Otherwise, import WebUtils.Cookie as CookieEngine.  This is because there is a nasty
! # bug in the Cookie.py module included in Python 2.1 and earlier, and Python 1.5.2
! # doesn't even include Cookie.py at all.
  
  pyVer = getattr(sys, 'version_info', None)
  if pyVer and pyVer[:2] >= (2, 2):
! 	# Get Python's Cookie module.
! 	# We have to do some work since it has the same name as we do.  So we'll strip out
! 	# anything from the path that might cause us to import from the WebKit directory, then
! 	# import Cookie using that restricted path -- that ought to ensure that we're using Python's
! 	# module.
  	import imp, string, sys
  	def ok(directory):
--- 1,17 ----
  from Common import *
  
! # If this is Python 2.2 or greater, import the standard Cookie module
! # as CookieEngine.  Otherwise, import WebUtils.Cookie as CookieEngine.
! # This is because there is a nasty bug in the Cookie.py module
! # included in Python 2.1 and earlier, and Python 1.5.2 doesn't even
! # include Cookie.py at all.
  
  pyVer = getattr(sys, 'version_info', None)
  if pyVer and pyVer[:2] >= (2, 2):
! 	# Get Python's Cookie module.  We have to do some work since
! 	# it has the same name as we do.  So we'll strip out anything
! 	# from the path that might cause us to import from the WebKit
! 	# directory, then import Cookie using that restricted path --
! 	# that ought to ensure that we're using Python's module.
  	import imp, string, sys
  	def ok(directory):
***************
*** 24,29 ****
  			file.close()
  else:
! 	# For Python versions < 2.2, we are including a copy of the standard Cookie.py module from
! 	# Python 2.2, but modified to work with Python 1.5.2 and up.
  	from WebUtils import Cookie
  	CookieEngine = Cookie
--- 25,31 ----
  			file.close()
  else:
! 	# For Python versions < 2.2, we are including a copy of the
! 	# standard Cookie.py module from Python 2.2, but modified to
! 	# work with Python 1.5.2 and up.
  	from WebUtils import Cookie
  	CookieEngine = Cookie
***************
*** 33,57 ****
  class Cookie(Object):
  	"""
! 	Cookie is used to create cookies that have additional attributes beyond their value.
! 
! 	Note that web browsers don't typically send any information with the cookie other than it's value. Therefore, in HTTPRequest, cookie() simply returns a value such as an integer or a string.
! 
! 	When the server sends cookies back to the browser, it can send a cookie that simply has a value, or the cookie can be accompanied by various attributes (domain, path, max-age, ...) as described in RFC 2109. Therefore, in HTTPResponse, setCookie() can take either an instance of the Cookie class, as defined in this module, or a value.
! 
! 	Note that Cookies values get pickled (see the pickle module), so you can set and get cookies that are integers, lists, dictionaries, etc.
  
! 	HTTP Cookies are officially described in RFC 2109:
  
! 		ftp://ftp.isi.edu/in-notes/rfc2109.txt
  
! 	FUTURE
  
! 		* This class should provide error checking in the setFoo() methods. Or maybe our internal Cookie implementation already does that?
! 		* This implementation is probably not as efficient as it should be, [a] it works and [b] the interface is stable. We can optimize later.
  	"""
  
! 	## Init ##
  
  	def __init__(self, name, value):
  		self._cookies = CookieEngine.SmartCookie()
  		self._name = name
--- 35,75 ----
  class Cookie(Object):
  	"""
! 	Cookie is used to create cookies that have additional
! 	attributes beyond their value.
  
! 	Note that web browsers don't typically send any information
! 	with the cookie other than it's value. Therefore
! 	`HTTPRequest.cookie` simply returns a value such as an
! 	integer or a string.
  
! 	When the server sends cookies back to the browser, it can send
! 	a cookie that simply has a value, or the cookie can be
! 	accompanied by various attributes (domain, path, max-age, ...)
! 	as described in `RFC 2109`_. Therefore, in HTTPResponse,
! 	`setCookie` can take either an instance of the Cookie class,
! 	as defined in this module, or a value.
  
! 	Note that Cookies values get pickled (see the `pickle` module),
! 	so you can set and get cookies that are integers, lists,
! 	dictionaries, etc.
  
! 	.. _`RFC 2109`: ftp://ftp.isi.edu/in-notes/rfc2109.txt
  	"""
  
! 	## Future
! 	##
! 	##	* This class should provide error checking in the setFoo()
! 	##	  methods. Or maybe our internal Cookie implementation
! 	##	  already does that?
! 	##	* This implementation is probably not as efficient as it
! 	##	  should be, [a] it works and [b] the interface is stable.
! 	##	  We can optimize later.
  
  	def __init__(self, name, value):
+ 		"""
+ 		Create a cookie -- properties other than `name` and
+ 		`value` are set with methods.
+ 		"""
+ 		
  		self._cookies = CookieEngine.SmartCookie()
  		self._name = name
***************
*** 60,65 ****
  		self._cookie = self._cookies[name]
  
! 
! 	## Access attributes ##
  
  	def comment(self):
--- 78,84 ----
  		self._cookie = self._cookies[name]
  
! 	"""
! 	**Accessors**
! 	"""
  
  	def comment(self):
***************
*** 91,95 ****
  
  
! 	## Setting attributes ##
  
  	def setComment(self, comment):
--- 110,116 ----
  
  
! 	"""
! 	**Setters**
! 	"""
  
  	def setComment(self, comment):
***************
*** 118,123 ****
  		self._cookie['version'] = version
  
! 	## Convenience ##
  	def delete(self):
  		self._value = ''
  		self._cookie['expires'] = "Mon, 01-Jan-1900 00:00:00 GMT"
--- 139,156 ----
  		self._cookie['version'] = version
  
! 
! 	"""
! 	**Misc**
! 	"""
! 
  	def delete(self):
+ 		"""
+ 		When sent, this should delete the cookie from the user's
+ 		browser, by making it empty, expiring it in the past,
+ 		and setting its max-age to 0.  One of these will delete
+ 		the cookie for any browser (which one actually works
+ 		depends on the browser).
+ 		"""
+ 		
  		self._value = ''
  		self._cookie['expires'] = "Mon, 01-Jan-1900 00:00:00 GMT"
***************
*** 126,133 ****
  
  
- 	## HTTP Headers ##
- 
  	def headerValue(self):
! 		""" Returns a string with the value that should be used in the HTTP headers. """
  		items = self._cookies.items()
  		assert(len(items)==1)
--- 159,167 ----
  
  
  	def headerValue(self):
! 		"""
! 		Returns a string with the value that should be
! 		used in the HTTP headers. """
! 		
  		items = self._cookies.items()
  		assert(len(items)==1)
***************
*** 135,138 ****
  
  	def headerString(self):
! 		""" @@ 2000-06-09 ce: Not typically needed now that raw responses are structured dictionaries instead of opaque strigns. headerValue() is used instead. """
  		return str(self._cookies)
--- 169,178 ----
  
  	def headerString(self):
! 		""" @@ 2000-06-09 ce: Not typically needed now that
! 		raw responses are structured dictionaries instead of
! 		opaque strigns. headerValue() is used instead.
! 
! 		:ignore:
! 		"""
! 
  		return str(self._cookies)

Index: ExceptionHandler.py
===================================================================
RCS file: /cvsroot/webware/Webware/WebKit/ExceptionHandler.py,v
retrieving revision 1.28
retrieving revision 1.29
diff -C2 -d -r1.28 -r1.29
*** ExceptionHandler.py	4 Mar 2003 02:11:05 -0000	1.28
--- ExceptionHandler.py	26 Mar 2003 00:49:32 -0000	1.29
***************
*** 17,39 ****
  	After handling an exception, it should be removed.
  
! 	At some point, the exception handler sends "writeExceptionReport"
! 	to the transaction (if present), which in turn sends it to the other
! 	transactional objects (application, request, response, etc.)
! 	The handler is the single argument for this message.
  
! 	Classes may find it useful to do things like this:
  
! 	exceptionReportAttrs = 'foo bar baz'.split()
! 	def writeExceptionReport(self, handler):
! 		handler.writeTitle(self.__class__.__name__)
! 		handler.writeAttrs(self, self.exceptionReportAttrs)
  
  	The handler write methods that may be useful are:
! 		def write(self, s):
! 		def writeln(self, s):
! 		def writeTitle(self, s):
! 		def writeDict(self, d):
! 		def writeTable(self, listOfDicts, keys=None):
! 		def writeAttrs(self, obj, attrNames):
  
  	Derived classes must not assume that the error occured in a
--- 17,40 ----
  	After handling an exception, it should be removed.
  
! 	At some point, the exception handler sends
! 	`writeExceptionReport` to the transaction (if present), which
! 	in turn sends it to the other transactional objects
! 	(application, request, response, etc.)  The handler is the
! 	single argument for this message.
  
! 	Classes may find it useful to do things like this::
  
! 		exceptionReportAttrs = 'foo bar baz'.split()
! 		def writeExceptionReport(self, handler):
! 			handler.writeTitle(self.__class__.__name__)
! 			handler.writeAttrs(self, self.exceptionReportAttrs)
  
  	The handler write methods that may be useful are:
! 
! 	.. inline:: write
! 	.. inline:: writeTitle
! 	.. inline:: writeDict
! 	.. inline:: writeTable
! 	.. inline: writeAttrs
  
  	Derived classes must not assume that the error occured in a
***************
*** 41,50 ****
  	of transactions.
  
! 	See the WebKit.html documentation for other information.
! 
! 
! 	HOW TO CREATE A CUSTOM EXCEPTION HANDLER
  
! 	In the __init__.py of your context:
  
  		from WebKit.ExceptionHandler import ExceptionHandler as _ExceptionHandler
--- 42,48 ----
  	of transactions.
  
! 	**HOW TO CREATE A CUSTOM EXCEPTION HANDLER**
  
! 	In the ``__init__.py`` of your context::
  
  		from WebKit.ExceptionHandler import ExceptionHandler as _ExceptionHandler
***************
*** 75,78 ****
--- 73,83 ----
  	def __init__(self, application, transaction, excInfo,
  				 formatOptions=None):
+ 		"""
+ 		ExceptionHandler instances are created anew for
+ 		each exception.  Instantiating ExceptionHandler
+ 		completes the process -- the caller need not
+ 		do anything else.
+ 		"""
+ 		
  		Object.__init__(self)
  
***************
*** 89,95 ****
  		self._formatOptions = formatOptions
  
! 		# Make some repairs, if needed. We use the transaction & response to get the error page back out
! 		# @@ 2000-05-09 ce: Maybe a fresh transaction and response should always be made for that purpose
! 		## @@ 2003-01-10 sd: This requires a transaction which we do not have.
  		## Making remaining code safe for no transaction.
  		##
--- 94,106 ----
  		self._formatOptions = formatOptions
  
! 		# Make some repairs, if needed. We use the transaction
! 		# & response to get the error page back out
! 
! 		# @@ 2000-05-09 ce: Maybe a fresh transaction and
! 		# response should always be made for that purpose
! 
! 		## @@ 2003-01-10 sd: This requires a transaction which
! 		## we do not have.
! 
  		## Making remaining code safe for no transaction.
  		##
***************
*** 107,117 ****
  		self.work()
  
! 
! 	## Utilities ##
  
  	def setting(self, name):
  		return self._app.setting(name)
  
  	def servletPathname(self):
  		try:
  			return self._tra.request().serverSidePath()
--- 118,136 ----
  		self.work()
  
! 	"""
! 	**Accessors**
! 	"""
  
  	def setting(self, name):
+ 		"""
+ 		Settings are inherited from Application.
+ 		"""
  		return self._app.setting(name)
  
  	def servletPathname(self):
+ 		"""
+ 		The full filesystem path for the servlet.
+ 		"""
+ 		
  		try:
  			return self._tra.request().serverSidePath()
***************
*** 121,124 ****
--- 140,146 ----
  
  	def basicServletName(self):
+ 		"""
+ 		The base name for the servlet (sans directory).
+ 		"""
  		name = self.servletPathname()
  		if name is None:
***************
*** 127,135 ****
  			return os.path.basename(name)
  
! 
! 	## Exception handling ##
  
  	def work(self):
! 		''' Invoked by __init__ to do the main work. '''
  
  		if self._res:
--- 149,167 ----
  			return os.path.basename(name)
  
! 	"""
! 	**Exception Handling**
! 	"""
  
  	def work(self):
! 		"""
! 		Invoked by `__init__` to do the main work.
! 		This calls `logExceptionToConsole`, then checks
! 		settings to see if it should call `saveErrorPage`
! 		(to save the error to disk) and `emailException`.
! 
! 		It also sends gives a page from `privateErrorPage`
! 		or `publicErrorPage` (which one based on
! 		``ShowDebugInfoOnErrors``).
! 		"""
  
  		if self._res:
***************
*** 164,168 ****
  
  	def logExceptionToConsole(self, stderr=None):
! 		''' Logs the time, servlet name and traceback to the console (typically stderr). This usually results in the information appearing in console/terminal from which AppServer was launched. '''
  		if stderr is None:
  			stderr = sys.stderr
--- 196,206 ----
  
  	def logExceptionToConsole(self, stderr=None):
! 		"""
! 		Logs the time, servlet name and traceback to the
! 		console (typically stderr). This usually results in
! 		the information appearing in console/terminal from
! 		which AppServer was launched.
! 		"""
! 
  		if stderr is None:
  			stderr = sys.stderr
***************
*** 172,175 ****
--- 210,219 ----
  
  	def publicErrorPage(self):
+ 		"""
+ 		Returns a brief error pae telling the user that an
+ 		error has occurred.  Body of the message comes from
+ 		``UserErrorMessage`` setting.
+ 		"""
+ 		
  		return '''<html>
  	<head>
***************
*** 184,188 ****
  
  	def privateErrorPage(self):
! 		''' Returns an HTML page intended for the developer with useful information such as the traceback. '''
  		html = ['''
  <html>
--- 228,238 ----
  
  	def privateErrorPage(self):
! 		"""
! 		Returns an HTML page intended for the developer with
! 		useful information such as the traceback. '''
! 
! 		Most of the contents are generated in `htmlDebugInfo`.
! 		"""
! 		
  		html = ['''
  <html>
***************
*** 200,204 ****
  
  	def htmlDebugInfo(self):
! 		''' Return HTML-formatted debugging information about the current exception. '''
  		self.html = []
  		self.writeHTML()
--- 250,259 ----
  
  	def htmlDebugInfo(self):
! 		"""
! 		Return HTML-formatted debugging information about the
! 		current exception.  Calls `writeHTML`, which uses
! 		``self.write(...)`` to add content.
! 		"""
! 		
  		self.html = []
  		self.writeHTML()
***************
*** 208,211 ****
--- 263,275 ----
  
  	def writeHTML(self):
+ 		"""
+ 		Writes all the parts of the traceback, invoking:
+ 		* `writeTraceback`
+ 		* `writeMiscInfo`
+ 		* `writeTransaction`
+ 		* `writeEnvironment`
+ 		* `writeIds`
+ 		* `writeFancyTraceback`
+ 		"""
  		self.writeTraceback()
  		self.writeMiscInfo()
***************
*** 215,248 ****
  		self.writeFancyTraceback()
  
! 
! 	## Write utility methods ##
  
  	def write(self, s):
  		self.html.append(str(s))
  
  	def writeln(self, s):
  		self.html.append(str(s))
  		self.html.append('\n')
  
  	def writeTitle(self, s):
  		self.writeln(htTitle(s))
  
  	def writeDict(self, d):
  		self.writeln(htmlForDict(d, filterValueCallBack=self.filterDictValue, maxValueLength=self._maxValueLength))
  
  	def writeTable(self, listOfDicts, keys=None):
  		"""
! 		Writes a table whose contents are given by listOfDicts. The
! 		keys of each dictionary are expected to be the same. If the
! 		keys arg is None, the headings are taken in alphabetical order
! 		from the first dictionary. If listOfDicts is "false", nothing
  		happens.
  
! 		The keys and values are already considered to be HTML.
  
  		Caveat: There's no way to influence the formatting or to use
  		column titles that are different than the keys.
  
! 		Note: Used by writeAttrs().
  		"""
  		if not listOfDicts:
--- 279,328 ----
  		self.writeFancyTraceback()
  
! 	"""
! 	**Write Methods**
! 	"""
  
  	def write(self, s):
+ 		"""
+ 		Write `s` to the body
+ 		"""
  		self.html.append(str(s))
  
  	def writeln(self, s):
+ 		"""
+ 		Write `s` plus a newline
+ 		"""
  		self.html.append(str(s))
  		self.html.append('\n')
  
  	def writeTitle(self, s):
+ 		"""
+ 		Write a title line (a sub-heading, really, to define
+ 		a section)
+ 		"""
  		self.writeln(htTitle(s))
  
  	def writeDict(self, d):
+ 		"""
+ 		Write a table-formated dictionary
+ 		"""
  		self.writeln(htmlForDict(d, filterValueCallBack=self.filterDictValue, maxValueLength=self._maxValueLength))
  
  	def writeTable(self, listOfDicts, keys=None):
  		"""
! 		Writes a table whose contents are given by
! 		`listOfDicts`. The keys of each dictionary are
! 		expected to be the same. If the `keys` arg is None,
! 		the headings are taken in alphabetical order from the
! 		first dictionary. If listOfDicts is false, nothing
  		happens.
  
! 		The keys and values are already considered to be HTML,
! 		and no quoting is applied.
  
  		Caveat: There's no way to influence the formatting or to use
  		column titles that are different than the keys.
  
! 		Used by `writeAttrs`
  		"""
  		if not listOfDicts:
***************
*** 270,275 ****
  		"""
  		Writes the attributes of the object as given by attrNames.
! 		Tries obj._name first, followed by obj.name(). Is resilient
! 		regarding exceptions so as not to spoil the exception report.
  		"""
  		rows = []
--- 350,356 ----
  		"""
  		Writes the attributes of the object as given by attrNames.
! 		Tries ``obj._name` first, followed by ``obj.name()``.
! 		Is resilient regarding exceptions so as not to spoil the
! 		exception report.
  		"""
  		rows = []
***************
*** 295,302 ****
  		self.writeTable(rows, ('attr', 'value'))
  
! 
! 	## Write specific parts ##
  
  	def writeTraceback(self):
  		self.writeTitle('Traceback')
  		self.write('<p> <i>%s</i>' % self.servletPathname())
--- 376,389 ----
  		self.writeTable(rows, ('attr', 'value'))
  
! 	"""
! 	**Traceback sections**
! 	"""
  
  	def writeTraceback(self):
+ 		"""
+ 		Writes the traceback, with most of the work done
+ 		by `WebUtils.HTMLForException.HTMLForException`
+ 		"""
+ 		
  		self.writeTitle('Traceback')
  		self.write('<p> <i>%s</i>' % self.servletPathname())
***************
*** 304,307 ****
--- 391,399 ----
  
  	def writeMiscInfo(self):
+ 		"""
+ 		Write a couple little pieces of information about
+ 		the environment.
+ 		"""
+ 		
  		self.writeTitle('MiscInfo')
  		info = {
***************
*** 314,317 ****
--- 406,413 ----
  
  	def writeTransaction(self):
+ 		"""
+ 		Lets the transaction talk about itself, using
+ 		`Transaction.writeExceptionReport`
+ 		"""
  		if self._tra:
  			self._tra.writeExceptionReport(self)
***************
*** 321,332 ****
--- 417,442 ----
  
  	def writeEnvironment(self):
+ 		"""
+ 		Writes the environment this is being run in.  This
+ 		is *not* the environment that was passed in with
+ 		the request (holding the CGI information) -- it's
+ 		just the information from the environment that the
+ 		AppServer is being executed in.
+ 		"""
  		self.writeTitle('Environment')
  		self.writeDict(os.environ)
  
  	def writeIds(self):
+ 		"""
+ 		Prints some values from the OS (like processor ID)
+ 		"""
  		self.writeTitle('Ids')
  		self.writeTable(osIdTable(), ['name', 'value'])
  
  	def writeFancyTraceback(self):
+ 		"""
+ 		Writes a fancy traceback, using cgitb
+ 		"""
+ 		
  		if self.setting('IncludeFancyTraceback'):
  			self.writeTitle('Fancy Traceback')
***************
*** 342,346 ****
  
  	def saveErrorPage(self, html):
! 		''' Saves the given HTML error page for later viewing by the developer, and returns the filename used. '''
  		filename = self._app.serverSidePath(os.path.join(self.setting('ErrorMessagesDir'), self.errorPageFilename()))
  		f = open(filename, 'w')
--- 452,459 ----
  
  	def saveErrorPage(self, html):
! 		"""
! 		Saves the given HTML error page for later viewing by
! 		the developer, and returns the filename used.  """
! 		
  		filename = self._app.serverSidePath(os.path.join(self.setting('ErrorMessagesDir'), self.errorPageFilename()))
  		f = open(filename, 'w')
***************
*** 350,362 ****
  
  	def errorPageFilename(self):
! 		''' Construct a filename for an HTML error page, not including the 'ErrorMessagesDir' setting. '''
  		return 'Error-%s-%s-%d.html' % (
  			self.basicServletName(),
  			string.join(map(lambda x: '%02d' % x, localtime(self._time)[:6]), '-'),
  			whrandom.whrandom().randint(10000, 99999))
! 			# @@ 2000-04-21 ce: Using the timestamp & a random number is a poor technique for filename uniqueness, but this works for now
  
  	def logExceptionToDisk(self, errorMsgFilename=''):
! 		''' Writes a tuple containing (date-time, filename, pathname, exception-name, exception-data,error report filename) to the errors file (typically 'Errors.csv') in CSV format. Invoked by handleException(). '''
  		logline = (
  			asctime(localtime(self._time)),
--- 463,486 ----
  
  	def errorPageFilename(self):
! 		"""
! 		Construct a filename for an HTML error page, not
! 		including the ``ErrorMessagesDir`` setting
! 		(which `saveError` adds on)"""
! 
  		return 'Error-%s-%s-%d.html' % (
  			self.basicServletName(),
  			string.join(map(lambda x: '%02d' % x, localtime(self._time)[:6]), '-'),
  			whrandom.whrandom().randint(10000, 99999))
! 			# @@ 2000-04-21 ce: Using the timestamp & a
! 			# random number is a poor technique for
! 			# filename uniqueness, but this works for now
  
  	def logExceptionToDisk(self, errorMsgFilename=''):
! 		"""
! 		Writes a tuple containing (date-time, filename,
! 		pathname, exception-name, exception-data,error report
! 		filename) to the errors file (typically 'Errors.csv')
! 		in CSV format. Invoked by `handleException`. """
! 		
  		logline = (
  			asctime(localtime(self._time)),
***************
*** 386,389 ****
--- 510,518 ----
  
  	def emailException(self, htmlErrMsg):
+ 		"""
+ 		Emails the exception, either as an attachment, or in the
+ 		body of the mail.
+ 		"""
+ 		
  		message = StringIO.StringIO()
  		writer = MimeWriter.MimeWriter(message)
***************
*** 437,443 ****
  
  
! 	## Filtering Values ##
  
  	def filterDictValue(self, value, key, dict):
  		return self.filterValue(value, key)
  
--- 566,579 ----
  
  
! 	"""
! 	**Filtering**
! 	"""
  
  	def filterDictValue(self, value, key, dict):
+ 		"""
+ 		Filters keys from a dict.  Currently ignores the
+ 		dictionary, and just filters based on the key.
+ 		"""
+ 		
  		return self.filterValue(value, key)
  
***************
*** 467,477 ****
  
  
! 	## Self utility ##
  
  	def repr(self, x):
  		"""
! 		Returns the repr() of x already html encoded. As a special case, dictionaries are nicely formatted in table.
  
! 		This is a utility method for writeAttrs.
  		"""
  		if type(x) is DictType:
--- 603,617 ----
  
  
! 	"""
! 	**Utility**
! 	"""
  
  	def repr(self, x):
  		"""
! 		Returns the repr() of x already html encoded. As a
! 		special case, dictionaries are nicely formatted in
! 		table.
  
! 		This is a utility method for `writeAttrs`.
  		"""
  		if type(x) is DictType:
***************
*** 486,489 ****
--- 626,633 ----
  # Some misc functions
  def htTitle(name):
+ 	"""
+ 	Formats a `name` as a section title
+ 	"""
+ 	
  	return '''
  <p> <br> <table border=0 cellpadding=4 cellspacing=0 bgcolor=#A00000 width=100%%> <tr> <td align=center>
***************
*** 493,499 ****
  
  def osIdTable():
! 	''' Returns a list of dictionaries contained id information such as uid, gid, etc.,
! 		all obtained from the os module. Dictionary keys are 'name' and 'value'. '''
! 	funcs = ['getegid', 'geteuid', 'getgid', 'getpgrp', 'getpid', 'getppid', 'getuid']
  	table = []
  	for funcName in funcs:
--- 637,647 ----
  
  def osIdTable():
! 	"""
! 	Returns a list of dictionaries contained id information such
! 	as uid, gid, etc., all obtained from the os module. Dictionary
! 	keys are ``"name"`` and ``"value"``. """
! 		
! 	funcs = ['getegid', 'geteuid', 'getgid', 'getpgrp', 'getpid',
! 		 'getppid', 'getuid']
  	table = []
  	for funcName in funcs:

Index: ThreadedAppServerService.py
===================================================================
RCS file: /cvsroot/webware/Webware/WebKit/ThreadedAppServerService.py,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -d -r1.9 -r1.10
*** ThreadedAppServerService.py	6 Dec 2002 20:09:26 -0000	1.9
--- ThreadedAppServerService.py	26 Mar 2003 00:49:32 -0000	1.10
***************
*** 3,12 ****
  ThreadedAppServerService
  
! For general notes, see ThreadedAppServer.py.
  
  This version of the app server is a threaded app server that runs as
  a Windows NT Service.  This means it can be started and stopped from
! the Control Panel or from the command line using "net start" and
! "net stop", and it can be configured in the Control Panel to
  auto-start when the machine boots.
  
--- 3,12 ----
  ThreadedAppServerService
  
! For general notes, see `ThreadedAppServer`.
  
  This version of the app server is a threaded app server that runs as
  a Windows NT Service.  This means it can be started and stopped from
! the Control Panel or from the command line using ``net start`` and
! ``net stop``, and it can be configured in the Control Panel to
  auto-start when the machine boots.
  
***************
*** 16,53 ****
  the service, just run this program with no arguments.  Typical usage is
  to install the service to run under a particular user account and startup
! automatically on reboot with
  
! python ThreadedAppServerService.py --username mydomain\myusername --password mypassword --startup auto install
  
  Then, you can start the service from the Services applet in the Control Panel,
  where it will be listed as "WebKit Threaded Application Server".  Or, from
! the command line, it can be started with either of the following commands:
! 
! net start WebKit
! python ThreadedAppServerService.py start
  
! The service can be stopped from the Control Panel or with:
  
! net stop WebKit
! python ThreadedAppServerService.py stop
  
! And finally, to uninstall the service, stop it and then run:
  
! python ThreadedAppServerService.py remove
  
! FUTURE
! 	* This shares a lot of code with ThreadedAppServer.py --
! 	  instead it should inherit from ThreadedAppServer and have
! 	  very little code of its own.
! 	* Have an option for sys.stdout and sys.stderr to go to a logfile instead
! 	  of going nowhere.
! 	* Optional NT event log messages on start, stop, and errors.
! 	* Allow the option of installing multiple copies of WebKit with
! 	  different configurations and different service names.
! 	* Figure out why I need the Python service hacks marked with ### below.
! 	* Allow it to work with wkMonitor, or some other fault tolerance
! 	  mechanism.
  """
  
  import time
  startTime = time.time()
--- 16,55 ----
  the service, just run this program with no arguments.  Typical usage is
  to install the service to run under a particular user account and startup
! automatically on reboot with::
  
!     python ThreadedAppServerService.py --username mydomain\myusername \
!            --password mypassword --startup auto install
  
  Then, you can start the service from the Services applet in the Control Panel,
  where it will be listed as "WebKit Threaded Application Server".  Or, from
! the command line, it can be started with either of the following commands::
  
!     net start WebKit
!     python ThreadedAppServerService.py start
  
! The service can be stopped from the Control Panel or with::
  
!     net stop WebKit
!     python ThreadedAppServerService.py stop
  
! And finally, to uninstall the service, stop it and then run::
  
!     python ThreadedAppServerService.py remove
  """
  
+ ## FUTURE
+ ## 	* This shares a lot of code with ThreadedAppServer.py --
+ ## 	  instead it should inherit from ThreadedAppServer and have
+ ## 	  very little code of its own.
+ ## 	* Have an option for sys.stdout and sys.stderr to go to a logfile
+ ##	  instead of going nowhere.
+ ## 	* Optional NT event log messages on start, stop, and errors.
+ ## 	* Allow the option of installing multiple copies of WebKit with
+ ## 	  different configurations and different service names.
+ ## 	* Figure out why I need the Python service hacks marked with ### below.
+ ## 	* Allow it to work with wkMonitor, or some other fault tolerance
+ ## 	  mechanism.
+ 
+ 
  import time
  startTime = time.time()
***************
*** 57,60 ****
--- 59,63 ----
  
  class ThreadedAppServerService(win32serviceutil.ServiceFramework):
+ 
  	_svc_name_ = 'WebKit'
  	_svc_display_name_ = 'WebKit Threaded Application Server'