netsight.async 1.1.1

Basic

First, subclass the BaseAsyncView class. Where you might ordinarily write code in the __call__ method of a view class, to perform some process, instead, place it in the __run__ method.

>>> import time
>>> from netsight.async.browser.BaseAsyncView import BaseAsyncView
>>> class MyView(BaseAsyncView):
...
...    def __run__(self, *args, **kwargs):
...         time.sleep(30)
...         return "Hello world!"
...
>>>

When you call this view from the browser, it will display whatever output is configured as normal. When you perform a POST request to the view, however, the __run__ method will be called in the background as if it were the __call__ method of the view class. Meanwhile, a page displaying a spinner will be returned to the browser and will poll at 5 second intervals until the process defined in __run__ completes.

Once the __run__ method has completed, the browser will redirect to the result.

Using with page templates

If you have configured a browser view for your view class with a page template file specified in ZCML, this will be shown by default when the view is first called. If the view is POSTed to, then the process will be kick-started. You can change the initial template and the conditions under which the process is started by overriding the initial_page and the run_process methods of the view.

>>> from Products.Five.browser.pagetemplatefile import \
...      ViewPageTemplateFile
>>>
>>> class MyView(BaseAsyncView):
...
...     def run_process(self):
...         return 'run' in self.request.form
...
...     initial_page = \
...         ViewPageTemplateFile('templates/my_template.pt')
...
>>>

Or you could use a method:

>>> class MyView(BaseAsyncView):
...
...     def initial_page(self, *args, **kwargs):
...         return 'Hello world!'
...
>>>

You can also override the page returned to the browser once the process has been started by overriding the processing_page method.

If you want to call a template defined in ZCML from your __run__ method, you may pass a True value named no_process` to the call method if your ``run_process method would ordinarily start the process again.

>>> class MyView(BaseAsyncView):
...
...     def __run__(self, *args, **kwargs):
...         return self.__call__(message="Hello world",
...                              no_process=True)
...
>>>

Checking the status & retrieving the result

Once you have kicked off your __run__ method, the resulting response will redirect to the processing view, with a unique ID for the newly started process given as a GET variable, process_id.

This process ID can be used to retrieve information on the status of the process and its result.

Calling the completed method of the view with the process ID will return either a True or False completion state, or a number representing a percentage completion out of 100 (more on recording progress later). If the optional argument, output_json is set to some value which evaluates to True, the method returns a JSON object with the single key, completed containing the same True, False or numeric value.

If your process died before it completed, it will raise an error, or if JSON output is chosen, it will return a completed value of the string, ‘ERROR’.

To retrieve the result of the __run__ method once it has completed, call the result method of the view with the process ID.

If your process died before it completed, this too will raise an error, or if JSON output is chosen, it will return a completed value of the string, ‘ERROR’.

If the process has not yet completed when result is called, None will be returned.

Setting process progress from your task

If you want your task to return some measure of completion you can call the set_progress method with the process ID and some numeric value.

>>> class MyView(BaseAsyncView):
...
...    def __run__(self, process_id=None, *args, **kwargs):
...         time.sleep(15)
...         self.set_progress(process_id, 50)
...         time.sleep(15)
...         return "Hello world!"
...
>>>

When your task completes without raising an exception, the progress is automatically set to 100 so there is no need to set this before the method returns.

1.1.1 - (2011-10-27)

• Fix process completion detection when progress is set to 100.

1.1.0 - (2011-10-27)

• Made Python 2.4 compatible.

• Process progress/result storage is now held in the ZODB, rather than in a Python instance’s memory.

1.0.1 - (2011-10-19)

• Fixed package manifest.

• Fixed markup on processing page.

1.0.0 - (2011-10-19)

Initial release.