async – Asynchronous Job Handling Module

Components for asynchronous job (task) handling, mainly based on zc.async.

class waeup.kofa.async.JobContainer

Bases: grokcore.content.components.Container

A container for IKofa jobs.

__doc__ = 'A container for :class:`IKofa` jobs.\n '

__implemented__ = <implementedBy waeup.kofa.async.JobContainer>

__module__ = 'waeup.kofa.async'

__provides__

Special descriptor for class __provides__

The descriptor caches the implementedBy info, so that we can get declarations for objects without instance-specific interfaces a bit quicker.

For example:

>>> from zope.interface import Interface
>>> class IFooFactory(Interface):
...     pass
>>> class IFoo(Interface):
...     pass
>>> class C(object):
...     implements(IFoo)
...     classProvides(IFooFactory)
>>> [i.getName() for i in C.__provides__]
['IFooFactory']

>>> [i.getName() for i in C().__provides__]
['IFoo']

class waeup.kofa.async.JobContainerInstaller(db_name=None)

Bases: object

Install a JobContainer in root of given DB.

Instances of this installer can be called when a Zope instance comes up (i.e. when an IDatabaseOpenedEvent was triggered).

It looks for some database named as in db_name and installs a job container in the root of this database (None by default) if it does not exist already.

__call__(ev)

__dict__ = dict_proxy({'__module__': 'waeup.kofa.async', '__dict__': <attribute '__dict__' of 'JobContainerInstaller' objects>, '__call__': <function __call__ at 0x7f4027d1da28>, '__weakref__': <attribute '__weakref__' of 'JobContainerInstaller' objects>, '__doc__': 'Install a JobContainer in root of given DB.\n\n Instances of this installer can be called when a Zope instance\n comes up (i.e. when an IDatabaseOpenedEvent was triggered).\n\n It looks for some database named as in `db_name` and installs a\n job container in the root of this database (``None`` by default)\n if it does not exist already.\n ', '__init__': <function __init__ at 0x7f4027d1d9b0>})

__doc__ = 'Install a JobContainer in root of given DB.\n\n Instances of this installer can be called when a Zope instance\n comes up (i.e. when an IDatabaseOpenedEvent was triggered).\n\n It looks for some database named as in `db_name` and installs a\n job container in the root of this database (``None`` by default)\n if it does not exist already.\n '

__init__(db_name=None)

__module__ = 'waeup.kofa.async'

__weakref__

list of weak references to the object (if defined)

class waeup.kofa.async.JobManager

Bases: grokcore.component.components.GlobalUtility

A manager for asynchronous running jobs (tasks).

Registered as a global utility for the waeup.kofa.interfaces.IJobManager interface.

This is the central location for managing asynchronous running jobs/tasks.

It works roughly like this: for usual tasks it looks up some JobContainer installed in a ZODB database root (the installation can happen during startup; see the respective installer classes and functions in this module) and then interacts with this JobContainer.

The optional site parameter for most methods in here serves for finding the databases’ roots. It is sufficient to pass any persisted object (or more precisely: some object with a valid _p_jar__ attribte). As long as some site was already set (for instance during regular requests), the site is looked up automatically and you don’t have to pass the site parameter then. So, in most cases you won’t have to give a site parameter.

__doc__ = "A manager for asynchronous running jobs (tasks).\n\n Registered as a global utility for the\n `waeup.kofa.interfaces.IJobManager` interface.\n\n This is the central location for managing asynchronous running\n jobs/tasks.\n\n It works roughly like this: for usual tasks it looks up some\n JobContainer installed in a ZODB database root (the installation\n can happen during startup; see the respective installer classes\n and functions in this module) and then interacts with this\n JobContainer.\n\n The optional `site` parameter for most methods in here serves for\n finding the databases' roots. It is sufficient to pass any\n persisted object (or more precisely: some object with a valid\n ``_p_jar__`` attribte). As long as some site was already set (for\n instance during regular requests), the site is looked up\n automatically and you don't have to pass the `site` parameter\n then. So, in most cases you won't have to give a `site` parameter.\n "

__implemented__ = <implementedBy waeup.kofa.async.JobManager>

__module__ = 'waeup.kofa.async'

__provides__

Special descriptor for class __provides__

The descriptor caches the implementedBy info, so that we can get declarations for objects without instance-specific interfaces a bit quicker.

For example:

>>> from zope.interface import Interface
>>> class IFooFactory(Interface):
...     pass
>>> class IFoo(Interface):
...     pass
>>> class C(object):
...     implements(IFoo)
...     classProvides(IFooFactory)
>>> [i.getName() for i in C.__provides__]
['IFooFactory']

>>> [i.getName() for i in C().__provides__]
['IFoo']

_get_jobs_container(site)

_get_site(site)

get(job_id, site=None)

Get the job with job_id from local site.

If job_id cannot be found, None is returned. This suitable e.g. when used with a traverser.

jobs(site=None)

Get all stored jobs as an iterable.

Result provides tuples (JOB_ID, JOB_OBJECT).

put(job, site=None)

Start the job and store it in local site.

The job must be an IJob instance.

It will be put into the default queue and then stored in local site. The status of the job can be seen immediately in job.status.

Please specify special treatments like begin_after or begin_by by setting the respectives attributes of the job itself.

remove(job_id, site=None)

Remove job with job_id from local job container.

If no such job can be found this is silently ignored.

Please note: removing a job from the job container does not mean to stop its execution (if it wasn’t started yet or is currently running).

start_test_job(duration=60, site=None)

Start a test job.

A method for testing the general asynchronous functionality of waeup.kofa. The test job started here executes the local compute() function with 23 as argument.

class waeup.kofa.async.JobManagerTraverser(context, request)

Bases: grok.components.Traverser

A traverser for the global IJobManager.

Looks up jobs by job_id and returns the respective job if it can be found.

__doc__ = 'A traverser for the global ``IJobManager``.\n\n Looks up jobs by job_id and returns the respective job if it\n can be found.\n '

__module__ = 'waeup.kofa.async'

traverse(name)

class waeup.kofa.async.ManageJobs(id, title='', description='')

Bases: grokcore.security.components.Permission

__doc__ = None

__module__ = 'waeup.kofa.async'

class waeup.kofa.async.ProgressableJob(*args, **kwargs)

Bases: zc.async.job.Job

A job that can indicate its progress via a percent attribute.

__doc__ = 'A job that can indicate its progress via a `percent` attribute.\n '

__implemented__ = <implementedBy waeup.kofa.async.ProgressableJob>

__module__ = 'waeup.kofa.async'

__provides__

Special descriptor for class __provides__

The descriptor caches the implementedBy info, so that we can get declarations for objects without instance-specific interfaces a bit quicker.

For example:

>>> from zope.interface import Interface
>>> class IFooFactory(Interface):
...     pass
>>> class IFoo(Interface):
...     pass
>>> class C(object):
...     implements(IFoo)
...     classProvides(IFooFactory)
>>> [i.getName() for i in C.__provides__]
['IFooFactory']

>>> [i.getName() for i in C().__provides__]
['IFoo']

percent = None

class waeup.kofa.async.ViewJobs(id, title='', description='')

Bases: grokcore.security.components.Permission

__doc__ = None

__module__ = 'waeup.kofa.async'

waeup.kofa.async.compute(num, duration=60)

A convenience function to test asynchronous jobs.

duration gives the seconds, this job should (artificially) need for completing.

waeup.kofa.async.get_job_id(persisted_job)

Get the object id of an already persisted job.

The persisted_job must provide a _p_oid attribute.

waeup.kofa.async.job_container_installer = <waeup.kofa.async.JobContainerInstaller object>

Can be used as event subscriber from ZCML; installs a job container in default database (named '') root.

waeup.kofa.async.multidb_job_container_installer = <waeup.kofa.async.JobContainerInstaller object>

An installer instance that installs a job container in a ZODB called async - this name is used in several components of the zc.async package we don’t want to reimplement here.

To use this installer as an event subscriber by ZCML, make sure the instance provides also a ZODB called async.