Subsections

8. Internal API

This section describe the public methods/attributes/classes of PyWork. Is intended to people interested in extending its functionality and/or join the project. But if you a web developer you may also be interested in PyWork internals. This chapter is organized with one secetion per "PyWork" module.

8.1 `pywork` -- The PyWork ModPython Handler

This modules is the binding point of mod_python and PyWork. ModPython loads this module and calls it directly to process its requests

8.1.1 Module Contents

The module defines the following function

handler( req): Process an apache request. This function is called by mod_python/apache when a request enters its Request Handling phase.

8.2 `action` -- The PyWork Action Module

This module defines the Action class, and a class to load actions from an XML.

8.2.1 Module Contents

The module defines the following exceptions and classes.

exception ActionConfigurationError: This exception is raised when a configuration error is found when loading the XML pywork-map.xml file.

exception ActionInstanceError: This exception is raised when an exception is raised creating an instance of an Action

Action instances support the following methods and attributes. Action is PyWork's framework main class.

auth( ): This is the authentication Action method. It is called on the authentication phase. By default returns True

preExecute( ): This is the pre execution method called before execute.

execute( ): This is the main Action method, it should alway be overwritten. It's called by PyWork on the client class after all parameters are set. It should return a string identifying the view to be displayd or None , and set the "_redirectUri" attribute.

postExecute( ): This is the post execution method called after execute.

bind( name, method): Binds a parameter to a method. It receives the parameter name (a string) and the method object as second argument.

unbind( name): Unbinds a previously binded parameter to a method.

setVariableFormProperties( value): If set to True tells the action object to accept any parameter and store it in "_form" if no property is found. USE WITH CARE!

_descriptor: The value of _descriptor is set upon action instantiation with the data retrieved from the configuration file. See ActionDescriptor.

_redirectUri: PyWork examines this value after calling the execute method and if its not None redirects the response to the specified URL.

_session: This is the session object , normally it's a dictionary. It is set before calling the execute method.

_name: This is the full virtual URI of the request executing It is set before calling the execute method.

_form: This is a dictionary containing all parameters that were not found as properties, if variableFormProperties is set to True.

_locale: If the client sends an "Accept-Language" header, PyWork will try to parse the clients locale and set it here.

_context: A reference to the main PyWork controller. It will serve you for accessing configuration directives and more.

ActionMap instances support the following methods and attributes. This class is the structure that uses PyWork to resolve the URI's into actions.

loadFromFile( file, configuration, availableViews): This method is called by PyWork to load all the information from a pywork-map.xml file. It also receives a reference to the global configuration and availableViews, to resolve and validate the XML data.

getActionDescriptor( actionId): Given an actionId (the virtual URI) returns the corresponding descriptor (see ActionDescriptor), or None if not found.

8.3 `descriptor` -- The PyWork Descriptor Module

This module defines the descriptor for actions, views, and view handlers.

8.3.1 Module Contents

The module defines the following classes.

ActionDescriptor instances support the following methods and attributes. ActionDescriptors are created when action elements are read from the configuration file.

instance( ): This method returns an instance of the Action described by this object. If the creation is successfull it sets the "_descriptor" attribute with self.

name: The name of the action.

moduleName: The module where the action class resides.

className: The class implementing Action

classObject: The class object. It serves to create instances at runtime

context: The context in which the action is being executed. It's set at runtime by PyWork, and has a reference to the controller , see Controller.

views: A dictionary containing all the available views for this action. Each key is the view name, and the elements are references to view descriptors, see ViewDescriptor

ViewDescriptor instances support the following methods and attributes. ViewDescriptors are created when view elements are read from the configuration file.

name: The name of the view. This name identifies the view.

viewHandlerName: The identifier of the view handler that will be used to process this view.

viewFile: The view file to be processed.

viewContentType: The content type to be used when writing the view output to the response.

ViewHandlerDescriptor instances support the following methods and attributes. ViewHandlersDescriptors are created when view-handler elements are read from the configuration file.

instance( ): This method returns an instance subclass of ViewHandler . If the creation is successfull it sets the "_descriptor"attribute with self.

name: The name of the view handler.

moduleName: The module where the view handler class resides.

className: The class implementing ViewHandler

classObject: The class object. It serves to create instances at configuration time

8.4 `controller` -- The PyWork Main Controller

This module defines the Controller class. Instances of this class are in charge of resceiving the requests, calling action methods and calling the views. Normally there would be one instance per interpreter.

8.4.1 Module Contents

The module defines the following class.

Controller instances support the following methods and attributes. An instance of Controller is created by pywork, and its reused between requests.

processRequest( req): This method is in charge of processing all the request. It receives the apache request and calls the proper action and view.

getconf( property): This method gets the value of a global configuration directive of PyWork (see pywork.xml).

gconf: A reference the global configuration see Configuration.

gaction: A reference the action configuration see ActionMap.

gview: A reference the view handlers configuration see ViewHandlerMap.

8.5 `conf` -- The PyWork Configuration Module

This module defines the Configuration class.

8.5.1 Module Contents

The module defines the following exceptions and classes.

exception ConfigurationError: This exception is raised when a configuration error is found when loading the XML pywork.xml file.

Configuration instances support the following methods and attributes.

loadFromFile( file): This method is called by PyWork to load all the information from a pywork.xml file.

getconf( property): Returns the value of property as loaded from the configuration file.

getconfint( property): Returns the value of property converted to an int.

replaceconf( str)

Searches str for strings of the form:

	${property}

And returns a string with all values resolved by calling getconf.

8.6 `view` -- The PyWork View Module

This module defines the View Handler class and the 3 view thecnologies, namely: PYTHON, ZPT and XSLT.

8.6.1 Module Contents

The module defines the following exceptions, classes and functions.

exception ViewHandlerConfigurationError: This exception is raised when a configuration error is found when loading the XML pywork-views.xml file.

register_extension( extension, name): extension may be a sequence or a simple value. This function is called by PyWork to register certain extension with the view specified by name.

resolve_viewfile( file): It examins file to see it it ends with some of the registered extensions, if matches returns the correspongin view name, otherwise None is returned.

ViewHandler instances support the following methods and attributes. ViewHandler is the base class for view processing classes.

display( request): This method should always be overwritten is called by the controller when the view is to be displayed.

descriptor: The value of descriptor is set before calling the object's display method. With the corresponding view descriptor, see ViewDescriptor.

action: The value of action is set before calling the object's display method. With the action executed, , see Action.

context: The context in which the action is being executed. It's set at runtime by PyWork, and has a reference to the controller , see Controller.

viewFile: The view file to be processed.

PythonViewHandler support the PYTHON view techonology. It does not define anything more than ViewHandler.

ZPTViewHandler support the ZPT view techonology. It does not define anything more than ViewHandler. This class is available if you have installed the ZPT package.

XSLTViewHandler support the XSLT view techonology. It does not define anything more than ViewHandler. This class is available if you have installed the libxml2, libxslt python bindings. See the chapter Installation.

8.7 `util` -- The PyWork Utility Module

This module defines the utility functions, to load modules and objects. And generate XML.

8.7.1 Module Contents

The module defines the following exceptions and functions.

exception ClassResolveError: This exception is raised when PyWork tries to create an instance of user class and fails.

searchpath( filename): This functions return the full path of the file, searching in PyWork's path. See Installation.

getlastmodified( filename): Returns filename MTIME. Its used for the configuration utilities.

resolveobject( module,object): Loads module and returns a reference to object. If running inside mod_python , apache.import_module its used otherwise, standard python imports are used. Module maybe module.submodule.submodule... etc.

action2xml( action): Transform the action into an XML. See XSLT view for more information. This function is implemented in C if module compilation was successful, otherwise is implemented in Python.

See About this document... for information on suggesting changes.