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 GXException(message)[source]

Bases: geosoft.GXRuntimeError

Exceptions from geosoft.gxpy.gx.

New in version 9.1.

GXpy(name='geosoft.gxpy.gx', version='2021.2.0', parent_window=0, log=None, max_res_heap=10000000, res_stack=6, max_warnings=10, suppress_progress=False, key='Core', per_user_key=False, redist_override=False, redist_dir=None, user_dir=None, temp_dir=None)[source]

Instantiate a Geosoft GX context. There should be only one instance of this created per thread. To simplify usage, use this method to instantiaate the context and the gxpy.gx.gx() methods instead to obtain the current thread instance.

It is a good idea to use the with statement pattern to ensure timely cleanup of unmanaged resources.

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)

key

Default Geosoft registry key to use (in absence of geosoft.key file) to discover GX developer common redistributables or Desktop Applications software (default ‘Core’)

per_user_key

Use per-user registry instead of local machine (default False)

redist_override

Override registry mechanism to discover redistributables with redist_dir, user_dir and temp_dir parameters. (default False)

redist_dir

Path containing the redistributable files, i.e. containing bin, csv and other folders. Only used if redist_override is True (default None)

user_dir

Writable path to directory containing the user redistributable files. Only used if redist_override is True (default None). If redist_override is True and user_dir is None a unique folder in system temp will be used for this purpose.

temp_dir

Path to use for temporary files. Only used if redist_override is True (default None) If redist_override is True and temp_dir is None a unique folder in system temp will be used for this purpose.

See also

Class gxpy.gx.GXpyContext

class GXpyContext(name='geosoft.gxpy.gx', version='2021.2.0', parent_window=0, log=None, max_res_heap=10000000, res_stack=6, max_warnings=10, suppress_progress=False, key='Core', per_user_key=False, redist_override=False, redist_dir=None, user_dir=None, temp_dir=None)[source]

Bases: object

Geosoft GX context. There should be only one instance of this created per thread. To simplify usage, use the gxpy.gx.GXpy() and gxpy.gx.gx() methods instead of instantiating this class directly.

This class does not need to be instantiated by the main thread in Oasis montaj desktop extension scripts, since the context is instantiated prior to entering the rungx method. If called, the desktop context is returned.

It is a good idea to use the with statement pattern to ensure timely cleanup of unmanaged resources.

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)

key

Default Geosoft registry key to use (in absence of geosoft.key file) to discover GX developer common redistributables or Desktop Applications software (default ‘Core’)

per_user_key

Use per-user registry instead of local machine (default False)

redist_override

Override registry mechanism to discover redistributables with redist_dir, user_dir and temp_dir parameters. (default False)

redist_dir

Path containing the redistributable files, i.e. containing bin, csv and other folders. Only used if redist_override is True (default None)

user_dir

Writable path to directory containing the user redistributable files. Only used if redist_override is True (default None). If redist_override is True and user_dir is None a unique folder in system temp will be used for this purpose.

temp_dir

Path to use for temporary files. Only used if redist_override is True (default None) If redist_override is True and temp_dir is None a unique folder in system temp will be used for this purpose.

Properties
gxapi

GX context to be used to call geosoft.gxapi methods

tkframe

tkframe for UI applications. Will be None if a the context was created from a window application.

gid

User’s Geosoft ID

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

New in version 9.1.

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.
__init__(name='geosoft.gxpy.gx', version='2021.2.0', parent_window=0, log=None, max_res_heap=10000000, res_stack=6, max_warnings=10, suppress_progress=False, key='Core', per_user_key=False, redist_override=False, redist_dir=None, user_dir=None, temp_dir=None)[source]

Initialize self. See help(type(self)) for accurate signature.

property active_wind_id

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

New in version 9.1.

close_log()[source]

close logging

disable_app()[source]

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)[source]

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()[source]

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

New in version 9.1.

property entitled

True if this user has a minimal Geosoft desktop licence/entitlement

New in version 9.3.

entitlements()[source]
Returns

The current user entitlements as a dictionary.

New in version 9.1.

environment(formated_indent=- 1)[source]

Deprecated since version 9.2: replaced by properties.

folder_temp()[source]

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

folder_user()[source]

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

folder_workspace()[source]

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

property geosoft_build_label

Geosoft build label.

New in version 9.3.2.

property geosoft_build_number

Geosoft build numberl.

New in version 9.3.2.

property geosoft_name

Geosoft installed product name

New in version 9.3.2.

property geosoft_version_label

Geosoft version label.

New in version 9.3.2.

property geosoft_version_major

Geosoft major version number.

New in version 9.3.2.

property geosoft_version_micro

Geosoft micro version number.

New in version 9.3.2.

property geosoft_version_minor

Geosoft minor version number.

New in version 9.3.2.

property gxapi

gxapi context for calls to geosoft.gxapi

has_entitlement(ent)[source]

Returns True if the user has this entitlement.

Parameters

ent – Entitlement number or descriptive name (case sensitive)

Partial list of entitlements as of 9.3 platform (subject to change):
1000: “Oasis montaj™ Base”
10000: “Oasis montaj™ Mapping and Processing System”
100010: “Geosoft - Virtual Computer License”
10100: “Geophysics”
10101: “Geochemistry”
10102: “Drillhole Plotting”
10103: “Induced Polarization”
10104: “Geophysics Levelling”
10105: “MAGMAP Filtering”
10106: “Grav/Mag Interpretation”
10107: “Airborne Quality Control”
10108: “256-Channel Radiometric Processing”
10109: “Gravity and Terrain Correction”
10110: “GridKnit”
10111: “UXO Land”
10114: “UXO Marine”
10500: “montaj plus™ Modeling Lite (PotentQ)”
10520: “GM-SYS Basic Profile Modeling”
10521: “GM-SYS Intermediate Profile Modeling”
10522: “GM-SYS Advanced Profile Modeling”
10523: “GM-SYS 3D Modeling”
10524: “Depth to Basement”
10525: “Isostatic Residual”
10540: “montaj plus™ Grav/Mag Filtering”
10541: “montaj plus™ Compudrape”
10550: “montaj plus™ Praga Radiometric Processing System”
10560: “montaj plus™ CET Grid Analysis”
10561: “montaj plus™ CET Porphyry Analysis”
2000: “ArcGIS”
3000: “MapInfo”
30000: “Target™ Surface and Drillhole Mapping”
30101: “Target™ Geochemistry”
40000: “Target™ for ArcGIS Surface and Drillhole Mapping”
41000: “Geochemistry for ArcGIS”
5104: “montaj™ Geophysics Leveling - Basic”
5106: “montaj™ Grav/Mag Interpretation - Basic”

New in version 9.3.

keep_temp_folder(keep=True)[source]

Keep temporary file folder setting.

Parameters

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

New in version 9.2.

property license_class

The user’s license class.

New in version 9.1.

log(*args)[source]

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.

property main_wind_id

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

New in version 9.1.

property parent_window

parent window for this context

property profile_name

Geosoft ID profile use name.

New in version 9.4.

property profile_url

Geosoft ID profile url in My Geosoft portal.

New in version 9.4.

remove_stale_temporary_files(age=86400)[source]

Removes stale temporary files from the current instance temporary file folder.

Parameters

age – files older than this age is seconds are removed. The default is 24 * 60 * 60.

Many classes that depend on a persistent file will support the creation of a class instance without providing a specific file name, in which case a temporary file is created in the temporary folder for this running GX instance. Upon loss of GX context all temporary files will be removed, but for a long-running process, such as a GX instnce that supports a web application, it can be useful to use this function to remove stale files and free valuable disk space.

Folders, if any, are not removed, but stale-dated files within folders will be removed.

New in version 9.3.2.

run_gx(gx)[source]

Runs a GX.

Parameters

gx – GX name to run

Returns

success, cancelled, exit_val, error_list, warning_list

New in version 9.6.

temp_file(ext='')[source]

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

Returns

uuid-based file name in the instance temporary folder.

New in version 9.2.

temp_folder()[source]

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.

property tkframe

tkframe if created fro this context, None if not created

property version

API version description

New in version 9.3.

class TLSGlobals[source]

Bases: object

gx()[source]

Returns the current thread GXpy instance.

pop_resource(res_id)[source]

Pop a tracked resource off the resource stack.

Parameters

res_id – the resource id returned by track_resource()

New in version 9.2.

Changed in version 9.3.1: changed id to res_id to avoid built-in shadow

track_resource(resource_class, info)[source]

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.