geosoft.gxpy.utility submodule¶

Utility functions to support Geosoft Python scripts and modules.

Note

Regression tests provide usage examples: Tests

exception UtilityException(message)[source]¶

Bases: geosoft.GXRuntimeError

Exceptions from geosoft.gxpy.utility.

New in version 9.1.

check_version(v, raise_on_fail=True)[source]¶

Check the minimum API version.

Parameters

v – minimum version string required (ie “9.1” or “9.2.4”)
raise_on_fail – if True, raises an error if the version check fails, returns False otherwise

Returns

True if version is OK, False otherwise(unless raise_on_fail is False)

Note

A valid version consists of two or three dot-separated numeric components, with an optional development version tag on the end. The development version tag consists of the letter ‘b’ (for beta) followed by a number. If the numeric components of two version numbers are equal, then a development version will always be deemed earlier (lesser) than one without.

The following are valid version numbers (shown in order of used for meeting minimum requirements):

9.1 or 9.1.0 (they are equivalent)

9.1.1b0 (development version)

9.1.1

9.2

The following are examples of invalid version numbers:

1

2.7.2.2

1.3.a4

1.3pl1

1.3c4

The rationale for this version numbering system is explained in the distutils documentation.

New in version 9.1.

crc32(byte_buffer, crc=0)[source]¶

Return 32-bit CRC of a byte buffer.

Parameters

byte_buffer – byte buffer (fulfills the Buffer Protocol)
crc – seed crc, can be passed along to accumulate the crc

New in version 9.2.

crc32_file(filename, crc=0)[source]¶

Return 32-bit CRC of a file.

Parameters

filename – file name
crc – seed crc, default 0

New in version 9.2.

crc32_str(s, crc=0)[source]¶

Return 32-bit CRC of a string.

Parameters

s – string
crc – seed crc, default 0

New in version 9.2.

datetime_from_year(year)[source]¶

Return the Python datetime from a decimal Gregorian year.

Parameters: year – decimal year on the Gregorian calendar.
Returns: datetime (resolved to 1 millisecond)

New in version 9.2.

decode(s, f)[source]¶

Decode a string (s) to a numpy format defined by string (f).

Parameters

s – string to decode

f –

format string:

b	Boolean
i	(signed) integer
u	unsigned integer
f	floating-point
S	string, interpreted as ‘U’ unicode
a	string, interpreted as ‘U’ unicode
U	unicode, requires length suffix, ie ‘U1’, ‘U14’

Times

Times in the form hh:mm:ss.sss return a decimal hour.

Dates

Dates in form yyyy-mm-dd, yyyy-m-d, yy/mm/dd or yyyy/m/d will be decoded naturally and return a decimal Gregorian year. Other date formats will raise a ValueErr.

Errors

TypeError	if unable to recognize type
ValueError	if there is a problem with the string.

New in version 9.1.

delete_file(file_name)[source]¶

Delete a file, does nothing if file does not exist.

Parameters: file_name – file to delete

New in version 9.3.1.

delete_files_by_root(file_root)[source]¶

Delete all files that have the same file_root (without extension). This can be safely applied to remove temporary files that use named using geosoft.gxpy.gx.temp_file.

Parameters: file_root – file root name

New in version 9.4.

delete_folder(folder_name, age=None, raise_on_error=False)[source]¶

Delete a folder if all files and sub-folders are accessible and deletable.

Parameters

folder_name – name of the folder
age – age in seconds relative to the current date/time
raise_on_error – True to raise an error if unsuccessful, otherwise just returns False

Returns

True if successful

New in version 9.3.1.

dict_from_http_response_text(text, prune_xml_root=True, object_hook=None, object_pairs_hook=None, **kw)[source]¶

Decode http response text to a dictionary. Response may be json or xml.

Parameters

text – http response.text from requests module response objects
prune_xml_root – True to remove the xml root, False to keep it
object_hook – json.loads decoder hook for objects
object_pairs_hook – json.loads decoder for object pairs (see json.loads documentation).
kw – arguments passed to json.loads()

Returns

dictionary of content

If the content is xml, the root node is removed and a dictionary is constructed from the content above the root node. If one of the hook functions is present, the dictionary is converted to json and a dictionary is reconstructed using the hooks.

New in version 9.4.

dict_from_lst(lst, ordered=False)[source]¶

Return a dictionary from a Geosoft geosoft.gxapi.GXLST instance.

Parameters

lst – geosoft.gxapi.GXLST instance
ordered – True to return an OrderedDict

Returns

python dictionary from a Geosoft GXLST

New in version 9.1.

dict_from_reg(reg, ordered=False)[source]¶

dictionary from a geosoft.gxapi.GXREG instance

Parameters

reg – geosoft.gxapi.GXREG instance
ordered – True to return and OrderedDict

Returns

python dictionary from a Geosoft GXREG

New in version 9.1.

dict_from_xml(xml)[source]¶

Return a dictionary of an xml string.

Parameters: xml – xml string
Returns: dictionary of the XML content.

If the XML root is ‘__gx_xml__’, the root is stripped.

Based on: https://github.com/martinblech/xmltodict

Tag attributes will become keys with ‘@’ as the first character, and the key value will be the attribute setting.

For example, XML string:

<?xml version="1.0" encoding="UTF-8"?>
<gmd:MD_Metadata xsi:schemaLocation="http://www.isotc211.org/2005/gmd ../schemas/iso19139fra/gmd/gmd.xsd">
    <geosoft xmlns="http://www.geosoft.com/schema/geo">
        <dataset version="1" beta="abc">
            <title>test_grid_1</title>
            <file_format>Geosoft Grid</file_format>
        </dataset>
    </geosoft>
</gmd:MD_Metadata>

returns dictionary:

{'gmd:MD_Metadata': {
    '@xsi:schemaLocation': "http://www.isotc211.org/2005/gmd ../schemas/iso19139fra/gmd/gmd.xsd",
    'geosoft': {
        '@xmlns': "http://www.geosoft.com/schema/geo",
        'dataset': {
            '@beta': "abc",
            '@version': "1",
            'title': "test_grid_1",
            'file_format': "Geosoft Grid"
            }
        }
    }
}

See also

xml_from_dict()

New in version 9.2.

display_message(title, message)[source]¶

Display a message to the user.

Parameters

title – message title
message – message

New in version 9.1.

dtype_gx(gtype)[source]¶

Returns: numpy dtype from a GX type

New in version 9.1.

dtype_gx_dimension(gtype)[source]¶

Returns: numpy dtype and dimension of the type, 1, 2 or 3. The dimension indicates 1D, 2D or 3D data.

New in version 9.3.1.

dummyMask(npd)[source]¶: Deprecated since version 9.2: use dummy_mask()

dummy_mask(npd)[source]¶

Return a 1-D dummy mask that is True for all rows in a 2D numpy array that have a Geosoft dummy value.

Parameters: npd – numpy data array
Returns: numpy 1D array, True for any row that had a dummy in any data field

New in version 9.2.

dummy_none(v)[source]¶: Returns None if dummy, otherwise the value.

New in version 9.2.

dummy_to_nan(data)[source]¶

Replaces dummies in float data to numpy.nan. All other data types are returned unchanged.

If passed data is a numpy array, dummies are changed in-place. The numpy array is returned.

Parameters: data – float value or a numpy array
Returns: data with dummies replaced by numpy.nan

New in version 9.2.

file_age(file_name)[source]¶

Returns the age of a file in seconds from now. -1 if the file does not exist.

Parameters: file_name – file name

New in version 9.3.1.

folder_temp(use_override=True)[source]¶

Return the Geosoft temporary folder name.

Parameters: use_override – True to use the _temp_folder_overide if it is defined (used by tests)

Note

If creating temporary files, better to use gx method temp_file(), which will create the temporary file in the GX-specific folder temp_folder.

New in version 9.1.

folder_user()[source]¶: Return the Geosoft user configurations folder name.

New in version 9.1.

folder_workspace()[source]¶: Return the Geosoft project folder name.

New in version 9.1.

geosoft_metadata(geosoft_file_name)[source]¶

Get the metadata dictionary for a geosoft data file.

Parameters: geosoft_file_name – geosoft supported file name
Returns: dictionary of the metadata

If the metadata for the file does not exist {‘metadata’: {}} is returned.

New in version 9.2.

geosoft_xml_from_dict(d, pretty=True)[source]¶

Return a unicode XML string of a dictionary with geosoft namespace defined.

Parameters

d – dictionary
pretty – True to indent with line-feeds for pretty-printing

The tag xmlns=”http://www.geosoft.com/schema/geo” is added to the root element.

New in version 9.4.

get_parameters(group='_', parms=None, default=None)[source]¶

Get parameters from the Project Parameter Block.

Parameters

group – name in the parameter block group name
parms – if specified only these keys are searched and the value is replaced by the found parameter. Parameter keys are not case sensitive, though if parms is not provided all returned keys will be upper-case.
default – default value for parameters not found, ignored if parms is provided as a dict, in which case the current key:value settings will be unchanged.

Returns

dictionary containing group parameters

Changed in version 9.2.1: Now retains case on keys passed in to parms, which allows callers to maintain case. Note that if not specifying parms, the returned keys will always be upper-case. Fixed bug handling file name construction on Windows.

New in version 9.1.

get_shared_dict()[source]¶: Get a dictionary shared by an external application. The shared dictionary is cleared (popped) so a subsequent call will return an empty dictionary.

New in version 9.1.

gxDummy(dtype)[source]¶: Deprecated since version 9.2: use gx_dummy()

gx_dtype(dtype)[source]¶

Returns: GX type for a numpy dtype

New in version 9.1.

gx_dtype_dimension(dtype, dimension=1)[source]¶

Returns: GX type for a numpy dtype, with dimensions 2 and 3

New in version 9.3.1.

gx_dummy(dtype)[source]¶

Return the dummy for this value, or this type.

Returns: GX dummy for this data
Raises: KeyError if the dtype is not supported

New in version 9.2.

is_file_locked(file_name, age=None)[source]¶

Returns True if the file exists and is currently locked by another process or is younger than age.

Parameters

file_name – file to test
age – minimum age in seconds, default ignores age

New in version 9.3.1.

is_float(gxtype)[source]¶: Return True of gxtype can be stored in a 64-bit float

is_int(gxtype)[source]¶: Return True of gxtype can be stored in a 64-bit integer

is_path_locked(path, age=None)[source]¶

Returns True if any files in this folder or sub-folders are locked or younger than age.

Parameters

path – name of the folder
age – age in seconds from now

New in version 9.3.1.

is_string(gxtype)[source]¶: Return length of a gxtype string, 0 (False) if not a string. Note that this is the number of available bytes in UTF-8 encoding and not equivalent to number of Unicode characters

jupyter_markdown_toc(j_file, numbered=True, start_level=1, max_depth=1, prefix=' ')[source]¶

Create a markdoown table-of-content string from a jupyter notebook based on markdown “#”.

Parameters

j_file – jupyter notebook name. Default file extension is ‘.ipynb’
numbered – True (default) to number the main headings, False for all bulletys
start_level – toc base level, default is 1, which starts TOC at “##”
max_depth – maximum levels relative to the start level, default is first level only.
prefix – previx for each TOC line, default is ‘ ‘ so TOC will appear indented.

Returns

toc string.

Include this in a jupyter notebook to create a TOC that can then be cut/pasted into the introductory markdown:

import geosoft.gxpy.utility as gxu
print (gxu.jupyter_markdown_toc('my_notebook_name'))

New in version 9.3.1.

merge_dict(d, d2)[source]¶

Update a dictionary by adding key-values from second dictionary. Unlike Python’s update(), this adds new keys to nested dictionaries rather than replace everything in a nested dictionary.

Parameters

d – dictionary to update
d2 – new items to add or replace

Returns

merged dictionary

New in version 9.2.

normalize_file_name(fn)[source]¶

Normalize a file name string by replacing ‘’ with ‘/’. This is useful for writing file names to control files.

Parameters: fn – file name
Returns: normalized file name

New in version 9.2.

rdecode(s)[source]¶

Geosoft string (number, date, time, geographic) conversion to a number, always works.

Parameters: s – string to decode
Returns: decoded number, gxapi.rDUMMY if unable to decode the string

See rdecode_err(string) for more details.

New in version 9.1.

rdecode_err(s)[source]¶

Geosoft string conversion to a number, raising ValueError on failure

Parameters: s – string to be decoded
Returns: float of decoded string

If unable to decode string:: rdecode_err() raises ValueError

rdecode() returns gxapi.rDUMMY

Any string that begins with “*” character is interpreted as a dummy.

If unable to directly convert simple string, decoder will clean-up the string by removing leading/trailing white space and converting ‘o’ or ‘O’ to numeral ‘0’.

If decoder still fails, it will attempt to decode time and geographic formatted strings to return decimal hours or decimal degrees respectively:

Date: yyyy-mm-dd

yyyy/mm/dd

date will be fractional Gregorian year
Time: hh:mm:ss.ssAM/am

hh:mm:ss.ssPM/pm

PM/pm adds 12 hours (for example 2:30pm returns 14.5)
Geographic: [+/-]deg mm ss.ss[N/S/E/W/n/s/e/w]

[+/-]deg.mm.ss.ss[N/S/E/W/n/s/e/w]

S/s and W/w return negative of decoded value

Example:

“-90 15 18.0” = “90 15 18.0W” = “90.15.18w”, returns -90.255

“14” = “14N” = “14.00.00” = “14 00 00”, returns 14.0

Note that mm and ss.ss can go over 60.0 and will be decoded as minutes or seconds as presented. For example, “20 90 0.00” will return 21.5.

New in version 9.1.

reg_from_dict(rd, max_size=4096, json_encode=True)[source]¶

geosoft.gxapi.GXREG instance from a dictionary

Parameters

rd – dictionary
max_size – maximum “key=value” string size
json_encode – if True, non-string values in the dictionary are converted to JSON strings and stored as “_JSON:json-string”. False will encode non-string values as str(value)

Returns

geosoft.gxapi.GXREG instance

New in version 9.1.

run_external_python(script, script_args='', python_args='', shared_dict=None, console=True, catcherr=True)[source]¶

Run a python script as an external program, returning results as a dictionary. External program calls gxpy.utility.get_shared_dict() to get the caller’s dictionary, and gxpy.utility.set_shared_dict(return_dictionary) to return a dictionary back to caller.

Parameters

script – full path of the python script
shared_dict – dictionary passed to the external script (get_shared_dict() to retrieve)
script_args – command line arguments as a string
python_args – command line arguments as a string
console – True (default) will create a separate console for the process.
catcherr – True (default) Catch and re-raise errors from the sub-process.

Returns

dictionary passed back from caller via set_shared_dict(dict)

New in version 9.1.

save_parameters(group='_', parms=None)[source]¶

Save parameters to the Project Parameter Block. Parameter group names and member names are converted to uppercase.

Parameters

group – parameter block group name, default is ‘_’
parms – dict containing named parameter settings, must be specified

New in version 9.1.

set_shared_dict(shared_dict=None)[source]¶

Save a dictionary to be shared by an separate application. This is a companion file to run_external_python().

Parameters: shared_dict – dictionary of parameters to save

New in version 9.1.

str_significant(value, n, mode=0)[source]¶

Return a formatted string to n significant figures.

Parameters

value – value to format
n – number of significant digits
mode – 0 round, 1 ceiling, -1 floor

Returns

string to n significant figures

time_stamp()[source]¶: current date-time as a string.

unique_name(name, invalid=None, separator='()', maxversion=1000)[source]¶

Build a unique name or file name.

Parameters

name – seed name, returns this if callback(name) is False the name in unique
invalid – callback function invalid(name), returns True if name is invalid. If a call-back is not provided a simple os.path.isfile(name) is used.
separator – single or two-character separator. The unique name is constructed by appending an increasing number to the seed name until a valid name is found. By default the number is enclosed in parentheses (e.g. some_name(4).txt). If a single separator character is defined the number is separted from the name by the single character (e.g. for separator=’_’, might return some_name_4.txt).
maxversion – maximum number to try, default is 1000. This protects against infinite loop should there be a bug in your callback.

Returns

unique name

New in version 9.3.1.

url_retrieve(url, filename=None, overwrite=False, reporthook=None)[source]¶

Retrieve a URL resource as a file.

Parameters

url – name of the URL resource
filename – name of file in which to place the resource, default is the resource base name.
overwrite – True to overwrite an existing file. Default is False, in which case if the file exists the filename is returned.
reporthook – a hook function that will be called once on establishment of the network connection and once after each block read thereafter. The hook will be passed three arguments; a count of blocks transferred so far, a block size in bytes, and the total size of the file.

Returns

filename of the file that is created.