geosoft.gxpy.gx submodule

GX Context and related methods required for Geosoft Python.

Classes:
GXpy the Geosoft GX context

The GX context is a singleton, which is either created for stand-alone Python scripts, or is provided to the script for extensions to Geosoft Desktop applications.

Note

Regression tests provide usage examples: gx tests

exception geosoft.gxpy.gx.GXException

Bases: Exception

Exceptions from geosoft.gxpy.gx.

New in version 9.1.

class geosoft.gxpy.gx.GXpy(name='geosoft.gxpy.gx', version='9.2.1', parent_window=0, log=None, max_res_heap=10000000, res_stack=6, max_warnings=10, suppress_progress=False)

Bases: geosoft.gxpy.gx._Singleton

Geosoft GX context. This is a singleton class, so subsequent creation returns an instance identical to the initial creation. This also means that initialization arguments are ignored on a subsequent instantiation.

This class does not need to be instantiated by desktop extensions as the context is provided by the Geosoft desktop application. If called, the desktop context is returned.

Parameters:
name:application name, default is the script name
version:application version number, default Geosoft version
parent_window:ID of the parent window. A parent window is required for GUI-dependent functions to work. Set parent_window=-1 to create a Tkinter frame that provides a default parent window handle for GUI/Viewer functions.
log:name of a file to record logging information, or a call-back function that accepts a string. Specifying log=’‘ will log to a default file named using the current date and time. If not provided calls to log() are ignored.
max_res_heap:If logging is on, open gxpy resources (like grids, or databases) are tracked. This is the maximum size of resource heap for tracking open resources. Set to 0 to not track resources. On exit, if any resources remain open a warning is logged together with a list of the open resources, each with a call stack to help find the function that created the resources.
res_stack:Depth of the call-stack to report for open-resource warning.
max_warnings:Maximum number of resource warnings to report.
suppress_progress:
 True to suppress progress reporting (default False)
Properties:
gxapi:GX context to be used to call geosoft.gxapi methods
gid:User’s Geosoft ID
global gx:Global reference to this singleton class instance, None if invalid. The construct geosoft.gxpy.gx.gx can be accessed anywhere.
current_date:date at start-up
current_utc_date:
 UTC date at start-up
current_time:time at start-up
current_utc_time:
 UTC time at start-up
folder_workspace:
 Geosoft workspace folder
folder_temp:Geosoft temporary folder
folder_user:Geosoft Desktop installation ‘user’ folder
Raises:
GXException():if unable to create context

Changed in version 9.2: parent_window=-1 creates a Tkinter frame as a parent for scripts that call UI functions.

Added log argument to support log().

Made environment dictionary properties, deprecated environment.

New in version 9.1.

active_wind_id

The active window ID (HWND cast to unsigned for Windows).

New in version 9.1.

disable_app()

Disables application windows to allow modal Python UI. Call before opening your own UI window.

New in version 9.1.

elapsed_seconds(tag='', log=False)

Return the elapsed seconds since this GX instance started. The elapsed time is logged if logging is on.

Parameters:
  • log – True to log, which also requires logging to be on
  • tag – optional string to add to the log
Returns:

elapsed time in seconds

New in version 9.2.

enable_app()

Enables application windows to allow modal Python UI. Call before returning control to OM.

New in version 9.1.

entitlements()
Returns:The current user entitlements as a dictionary.

New in version 9.1.

environment(formated_indent=-1)

Deprecated since version 9.2: replaced by properties.

folder_temp()

Deprecated since version 9.2: use geosoft.gxpy.utility.folder_temp()

folder_user()

Deprecated since version 9.2: use geosoft.gxpy.utility.folder_user()

folder_workspace()

Deprecated since version 9.2: use geosoft.gxpy.utility.folder_workspace()

keep_temp_folder(keep=True)

Keep temporary file folder setting.

Parameters:keep – True to keep the temporary file folder, False to remove

New in version 9.2.

license_class

The user’s license class.

New in version 9.1.

log(*args)

Log a string to the log file or log call-back as defined when creating GXpy instance.

Parameters:args – arguments to log, each will be converted to a str()

If logging to a file each line is preceded by the date and time:

2016-12-25 12:34:16.175 log_str_line_1
2016-12-25 12:34:16.175 log_str_line_2

New in version 9.2.

main_wind_id

The main window ID (HWND cast to unsigned for Windows).

New in version 9.1.

temp_file(ext='')

Return a unique temporary file name as a full path. The temporary file is created in the instance temporary folder and will be deleted when this GXpy instance is deleted.

Parameters:ext – optional extension, including ”.” separator
Returns:uuid-based file name in the instance temporary folder.

New in version 9.2.

temp_folder()

Return the GX temporary folder path.

Each GX instance will create an instance-specific temporary folder as a child in the Geosoft temporary folder. Placing temporary files in the GX-specific temporary folder will ensure temporary file names will not collide with other running GX-based programs, and that all temporarty files are removed on termination of this GX.

Call keep_temp_folder to prevent deletion of the temporary files, which can be useful when debugging.

New in version 9.2.

geosoft.gxpy.gx.pop_resource(id)

Pop a tracked resource off the resource stack.

Parameters:id – the resource id returned by track_resource()

New in version 9.2.

geosoft.gxpy.gx.track_resource(resource_class, info)

Track a resource. Resource tracking is useful for debugging resource leaks. If you create a class or resource that you expect to be removed before your script ends you can track it with this call. When you dispose of your resource call pop_resource() to remove it from the tracking heap. On exit, any resource left on the tracked resource heap will be reported together with the call stack for each resource and the information you provided.

Parameters:
  • resource_class – the resource class name
  • info – some information about the resource
Returns:

resource_id, can be used with pop_resource()

New in version 9.2.