Python Extensions

A Python extension is a Python script that contains a rungx() function, and you can run a Python extension script just as you would a GX file.  This includes adding a Python extension script file name to a menu or running a Python extension script from the "Settings / Run GX...".

If you are running Python extension scripts from a custom menu

• You should place custom menu files in: ...\user\omn

• You should place Python script referenced from your menus in: ...\user\python

• See Oasis montaj Menus for more information.

Geosoft Python API

Within the Geosoft package there are two modules for Python development.  The gxapi module contains the complete GX API, and the gxpy module provides a simpler pythonic interface that is only available to Python. Select the module name in the following table to see the detailed API documentation.

Python Examples

A number of example python extensions are provided in the gxpy-examples repository (https://github.com/GeosoftInc/gxpy/tree/master/examples).

To run the examples, open an Oasis montaj project and run the python script by clicking on the GX button (or choose "Settings / Run a GX..."), then browse to the script (for example "hello_world.py"):

Your script must contain a "rungx()" function, which will be run.

hello_world

This is a classically basic script that illustrates the of the API to do something very simple, which is say hello to the user.

import geosoft.gxapi as gxapi	# gxapi methods
import geosoft.gxpy as gxpy		# gxpy methods

def rungx():																# a python script must have a rungx(), which is executed by OM when the script is run
    gxp = gxpy.gx.GXpy()													# get the current gx context
    gxapi.GXSYS.display_message("GX Python", "Hello {}".format(gxp.gid))	# say hello to the user identified by gxp.gid.

When you run this script from Oasis montaj you will see the following:

Debugging Python Extensions

Because Python extensions are run from Oasis montaj, interactive debugging of a Python script requires use of a remote debugging hook from an IDE that supports remote debugging using the pydevd package. For example, PyCharm is an excellent (and highly recommended) IDE that supports remote debugging using the pydevd package.  

"pydevd" is not part of standard Anaconda Python and needs to be installed: 

pip install pydevd

To create a debugging session from PyCharm, add a "Remote debugging" configuration to your project:
                 

At the top of your extension script add the lines indicated in steps 2. and 3. in the Remote debugging configuration.  For example, to setup the "hello_world.py" for remote debugging add lines 5 and 6 (these should be commented out or removed when not debugging):

# Oasis montaj Python extension to say Hello.import geosoft.gxapi as gxapi # gxapi methods
# To run this extension, select "Settings / Run GX or Python...", then browse to this script file.

# import pydevd
import pydevd
# when the following line is executed the IDE will break at the next executable line.  The settrace() call  must
# be reemoved for normal use.
pydevd.settrace('localhost', port=34765, stdoutToServer=True, stderrToServer=True)
# You should set the next breakpoint somewhere after rungx(), and run to that point.  Note that you cannot step
# through the def rungx() line because that line is not visible to the remote debugger.

import geosoft.gxapi as gxapi
import geosoft.gxpy as gxpy

# a python script must have a rungx(), which is executed by OM when the script is run
def rungx():


    # get the current gx context
    gxp = gxpy.gx.GXpy()
    
    # say hello to the user identified by gxp.gid.
    gxapi.GXSYS.display_message("GX Python", "Hello {}".format(gxp.gid))

With the "Remote debugging" configuration, run the debugger from the IDE and a remote server will start-up and wait for the "pydevd.settrace(...)" call:

 Run the extension from Oasis montaj using "Run a GX":

The debugger will give you control at the first executable line  following the setrace(...) call.  Debug as you normally would, though note that you cannot step through the def rungx() line because the remote debugger cannot see that line.  We suggest you set a breakpoint somewhere after that line and run to the breakpoint.

Note that to maintain the integrity of the client-server interaction between Oasis montaj and your debugger server you should complete your script and exit normally, with or without raising errors, such that Oasis montaj returns to a normal state.  Closing Oasis montaj or your debugger during a debugging station may require you to restart Oasis montaj.  Any change of configuration in the underlying Python installation, such as the addition or removal of a package, will also require that Oasis montaj be stopped and restarted.