Pants applications are powered by a singleton object called the engine.
The Engine can be accessed in one of two ways, by importing it directly from the pants package:
from pants import engine
Or by using the instance() classmethod:
from pants.engine import Engine
engine = Engine.instance()
These two methods are equivalent.
The engine is started with a call to Engine.start():
engine.start()
This method will enter a loop which will continuously call Engine.poll() until the engine is stopped with a call to Engine.stop():
engine.stop()
After the engine is started, it blocks the process until it is stopped. This means that you must completely initialise your application before starting the engine in order for it to work as expected.
It is possible to integrate Pants into an existing main loop, such as a GUI framework’s event loop.
If you need to integrate with an existing loop, you should not use the Engine.start() and Engine.stop() methods, but instead call Engine.poll() on each iteration of your loop. Ideally, poll() should be called many times each second to ensure that Pants is as fast as it can be.