Application Interface

For the application API autocron provides the decorators cron and delay and the functions start(), stop() and get_results(). After importing autocron the decorators and function are accessible like i.e. autocron.start().

Functions decorated with delay will get executes later in a separate process. Functions decorated with cron will get executed periodically.

To start the autocron background workers, the function start() must get called somewere in the code. The function stop() will stop the workers. It is not necessary to call stop() because autocron stops the workers on shutdown of the main application.

cron

A function decorated with cron should get never called from the application. Instead it will get called from autocron periodically. Because of this a cron-decorated function should not get arguments. To import the decorator autocron provides a shortcut:

from autocron import cron

To register a cron-function (that means autocron is aware of the decorated function) the module where the function is defined must get imported from the application.

Implementatiom of the decorators cron and delay for running recurring task and to delegate long running tasks to a background process.

autocron.decorators.cron(crontab=None, minutes=None, hours=None, dow=None, months=None, dom=None)

Decorator for a cronjob. Functions running cronjobs should not get called from the main program and therefore don’t get arguments. Example usage for a cronjob to run every hour, at the beginning of the hour:

>>> @cron("0 * * * *")
>>> def some_callable():
>>>    # do periodic stuff here ...

The decorator can take a couple of arguments but if just the first argument crontab is given then all other arguments are ignored. To use the other arguments instead, provide them all as keyword-arguments. If no arguments are given the default-crontab (* * * * *) is used to execute a task every minute.

Crontab:

a string representing a valid crontab. See: https://en.wikipedia.org/wiki/Cron#CRON_expression with the restriction that only integers and the special signs (* , -) are allowed. Some examples

The order of arguments is:
'minutes hours dow months dom'

'* * * * *':       runs every minute
                   (same as @periodic_task(seconds=60))
'15,30 7 * * *':   runs every day at 7:15 and 7:30
'* 9 0 4,7 10-15': runs at 9:00 every monday and
                   from the 10th to the 15th of a month
                   but only in April and July.

Minutes:

list of minutes during an hour when the task should run. Valid entries are integers in the range 0-59. Defaults to None which is the same as * in a crontab, meaning that the task gets executed every minute.

Hours:

list of hours during a day when the task should run. Valid entries are integers in the range 0-23. Defaults to None which is the same as * in a crontab, meaning that the task gets executed every hour.

Dow:

days of week. A list of integers from 0 to 6 with Monday as 0. The task runs only on the given weekdays. Defaults to None which is the same as * in a crontab, meaning that the task gets executed every day of the week.

Months:

list of month during a year when the task should run. Valid entries are integers in the range 1-12. Defaults to None which is the same as * in a crontab, meaning that the task gets executed every month.

Dom:

list of days in an month the task should run. Valid entries are integers in the range 1-31. Defaults to None which is the same as * in a crontab, meaning that the task gets executed every day.

If neither dom nor dow are given, then the task will run every day of a month. If one of both is set, then the given restrictions apply. If both are set, then the allowed days complement each other.

Example

Let’s consider a newsletter should get send on Monday and Wednesday at 9:30 am. This could be configured by means of a cron-string:

@cron("30 9 0,2 * *")
def send_newsletter():
    ...

This could also be configured by keyword-arguments:

@cron(minutes=[30], hours=[9], dow=[0, 2])
def send_newsletter():
    ...

delay

To use the delay decorator autocron provides a shortcut for import:

from autocron import delay

Functions decorated with delay will return TaskResult instances (see below), wrapping the result. In case that the result can be ignored (may be the function returns no result) it is safe to ignore the return value. autocron will clean up the database from time to time to delete outdated results.

Implementatiom of the decorators cron and delay for running recurring task and to delegate long running tasks to a background process.

autocron.decorators.delay(func)

Decorator for a delayed task. Apply this as:

>>> @delay
>>> def sendmail(recipient, message):
>>>     # conde goes here ...

The decorator does not take any arguments. Calling sendmail() will return from the call immediately and this callable will get executed later in another process.

TaskResult

A delay-decorated function returns a TaskResult instance. This is a wrapper around the delayed result. The instance provide attributes like is_ready to indicate whether a result is available:

@delay
def do_this_later():
    # code here ...

task_result = do_this_later()
...
if task_result.is_ready:
    result = task_result.result
else:
    # try to get the result later

If autocron is inactive the decorated function will not return a TaskResult instance but the original return value of the function.

class autocron.sql_interface.TaskResult(data=None)

Helper class to make task-results more handy.

property has_error

indicates error_message is set.

property is_ready

indicates task has been processed.

property is_waiting

indicates task still waiting to get processed.

property result

Shortcut to access the result. If the result is not available because the task still waits to get executed an AttributeError with the message “result not available” is raised.

start and stop

To start the autocron background workers, call autocron.start(<filename>) with a database-filename as argument. Calling stop() is not necessary. If the application terminates, autocron stops the workers. The number of workers can get set by the admin-interface.

class autocron.engine.Engine(interface=None)

The Engine is the entry-point for autocron. In the __init__.py module an instance of Engine gets created for calling the start() method to start the monitor thread. The monitor-thread will start the workers.

start(database_file)

Starts the monitor in case no other monitor is already running and the configuration indicates that autocron is active. To start the engine, a project-name is required. The project-name represents the name of the directory in ‘~/.autocron’ where project-specific data are stored (like the database). Returns a boolean: True if a monitor-thread has been started and False otherwise. Returning False does not mean that no monitor is running. There could be a monitor-thread in another process that has started earlier.

stop()

Shut down the monitor thread which in turn will stop all running workers. Also release the monitor_lock flag.

accessing results

Calling a delay-decorated function will return a TaskResult instance. This instance allows to access the delayed result of the function call. A call to autocron.get_results() returns a list of all available TaskResult instances.

class autocron.sql_interface.SQLiteInterface

SQLite interface for application specific operations. This class is a Singleton.

get_results()

Generic method to return all results

Results are deleted from the database after a timespan given by result_ttl. This value defaults to 1800 seconds (30 minutes) and can get set by the admin-interface. Do not missuse the autocron database as a long-term storage for results. Instead use another dedicated database.