Hosted by:

Embedding PTK Engines

You can control your own program using the PTK interface by embedding an engine in your python application. This allows you access to all of the interactive facilities found in PTK, such as the Namespace browser and debugger, whilst having the freedom and flexibility of a standalone application.

Why embed a PTK engine?

Possible reasons to embed an engine your applications:

Debug your application

Embedding an engine will allow you to use the PTK debugger to assist in developing your program, or simply allow you to try things out interactively.

Add command console functionality to your program

By embedding an engine in your program you can give your users access to a fully featured interactive environment via the PTK application. For instance specialist scientifc software can offer a conventional interface and a 'console' mode via PTK for users to manipulate their data.

How to embed a PTK engine

Embedding is simple:

1) Import the engine package

Import an engine module from the ptk_lib.engine package. The engine package you should use will depend upon the GUI toolkit that you are using for your application. E.g. for a wxpython application:

from ptk_lib.engine import wx_engine

2) Setup the user namespace/dictionary

Setup the namespace exposed to the engine (this is the objects that will be accessable from the console without imports). This is simply a python dictionary containg objects that you want the user to see in the main namespace, e.g.:

usr_dict = {}
usr_dict['pi']=3.14159265

Alternatively you can expose the top level namespace of your program using:

import __main__
usr_dict = __main__.__dict__

3) Create the engine object

Create an instance of the engine object.

#create the engine object
# parent        - The parent wxpython object used for events
# engine label  - The label display to the user on the console tab in PTK
# userdict  - The local dictionary for the top level namespace
self.eng = wx_engine.wxEngine( self, 
                                'wxTestApp',
                                userdict=usr_dict)

4) Bind/Listen for events/signals

The engine object will use the event/signal system for whatever gui toolkit it supports to communicate when PTK disconnects from the engine (for example if the user closes the console or types exit()). You can then exit the program or reset a menu/button to allow a new connection to be made. e.g. for wxpython use the wx_engine.EVT_ENGINE_DISCONNECT event. See the examples below for other toolkits events/signals

It is also a good idea to bind to any events/signals indicating when your program is exiting and disconnect the engine from the PTK application. The engine.disconnect() method should be called to disconnect from the PTK interface and exit your application gracefully. e.g.)

#wxpython frame close handler
def OnClose(self,event):
    self.eng.disconnect()
    event.Skip()

5) Connect to a running PTK instance

Call engine.connect( hostname, port) to connect to a running PTK instance. This will connect to the PTK and a console will be created in the PTK console window that will allow you to interact with your program. The default hostname and port are 'localhost' and 6666 however this can be changed in the PTK applications settings. (Message port). Use eng_misc.get_message_port() to find the current PTK message port.

Subclassing

Alternatively the engine class can be subclassed - this allows you integrate engines in your own mainloops as well as being able to define a welcome message and other behaviour (see the source code for details).

Examples

The following links contain simple examples of embedding engines using different gui toolkits available for python.

Too embed a PTK engine in your own mainloop you can use a subclass of the base PTK engine class (ptk_lib.engine.engine.Engine):

Custom mainloop

Important notes!

PTK must be running to connect!: When an engine is embedded in your app it will create a console in the PTK app so remember to start this first!.

Long running user commands: If a user executes a long running command in the console - your application will become unresponsive until the command completes. This is because the engine will execute commands in a GUI event handler.

Contents: