machinerry

CherryPy-based framework for running tasks repeatedly.

Docs Release Version Python Version License Build Status Coverage Code Climate

Project Home

You can browse the source code and file issues at the project repository.

API

class Machine(name)[source]

A CherryPy-integrated task which runs continuously in its own thread.

Generally, you will want to subclass this and override the ‘execute’ method to perform the same work on a recurring basis:

>>> class MyMachine(Machine):
...    def execute(self):
...        foo()
>>> m = MyMachine('test')
>>> m.subscribe()

There are a lot of exposed variables and hooks available to customise some behaviour.

pause_until

Override pause_until - it should base itself on the next time we are due to generate an alert.

pause_alert_next

The next time a pause alert is due to be generated - this is calculated automatically based on the time of the previous alert (if any).

start()[source]

Start processing in a new Thread.

on_machine_fail(exception)[source]

Hook provided to allow subclasses to react when a fatal error has caused the machine service to halt.

Default implementation will call on_error.

on_machine_pause_due_to_error(error)[source]

Hook to allow subclasses to react on the event that the machine is going to move into a paused state due to an error occurring.

Subclasses can override this method, but must call the subclass definition of it. Prior to the call, the machine will still be in a running state - after it, the machine will be internally set to paused.

on_machine_pause_elapsed()[source]

Subclasses should override on_machine_pause_until_elapsed rather than this method.

on_machine_pause()[source]

Hook provided to allow subclasses to react when the machine puts itself into a paused state; if an external caller requests the machine to pause, this hook is invoked when the machine itself actually enters into the paused state, and not at the point that a pause “request” is made (there may be a delay between the two events).

Default implementation will log a message about going into a paused state via cherrypy.log.

on_machine_resume()[source]

Hook provided to allow subclasses to react when the machine resumes itself from a paused state; if an external caller requests the machine to resume, this hook is invoked when the machine itself actually has resumed running, and not at the point that a resume “request” is made (there may be a delay between the two events).

Default implementation will log a message about resuming execution via cherrypy.log.

on_machine_run_complete()[source]

Hook provided to allow subclasses to perform a particular act when an execution run has finished.

The main use cases for overriding this will be:

  1. When you want to perform an action after the run has completed, but you need to know when the next run time is scheduled for (if you don’t, you can just do what you need at the end of “execute”).
  2. When you want to add additional information to a run object - although you can do this during the execute loop by accessing the machine_run attribute.

The machine_run attribute will still link to the run object to allow it to be queried and modified.

pause_for_reason(actor, reason)[source]

Tells the machine to pause, but indicates who is requesting it and why.

actor should be a dictionary of the form:
{‘buserid’: buserid_int, ‘username’: username_str}
This is usually available in a CherryPy request as:
cherrypy.request.buser[‘username’]

If actor is None, this indicates the machine itself is doing this.

reason should be a string.

resume_by(actor)[source]

Tells the machine to resume, and indicates who is requesting it.

actor should be a dictionary of the form:
{‘buserid’: buserid_int, ‘username’: username_str}
This is usually available in a CherryPy request as:
cherrypy.request.buser[‘username’]

If actor is None, this indicates the machine itself is doing this.

override_signal_handler()[source]

Integrates with CherryPy’s signal handling mechanism so that it will only shut down the web service once the main thread itself has terminated.

Returns true if it was modified successfully.

execute()

Main block of code to execute in a run. Subclasses must define this.

interrupt()

Tell the execution thread to wake up.

on_machine_error(exception)

Hook provided to allow subclasses to react when an error occurs outside of the execute block.

Default implementation will log via cherrypy.log.

on_machine_stopping()

Hook provided to allow subclasses to react when the machine is being terminated - this is primarily to allow winding down of open resources.

paused

A flag to indicate if the machine should be paused or should be running. Setting it will not normally result in an immediate pause or resumption of execution, but it will take place as soon as is convenient.

run()

Continuously run self.execute(). Errors are trapped and logged.

run_now()

Tell the execution thread to perform an execution now.

run_once()

Run self.execute() once. Errors are trapped.

This is the equivalent of performing a single run immediately in the context of the machine (with regard to all the prep work which takes place around it). You should not execute this in a thread separate to the machine thread (unless that thread has ceased execution).

status()[source]

Returns a dictionary describing the current state of the machine. Intended to be called from any thread. Subclasses are encouraged to override the definition to include additional data.

stop()

Stop processing.

Indices and tables