:py:mod:`python.odpy.common` ============================ .. py:module:: python.odpy.common .. autoapi-nested-parse:: Common tools for odpy package Copyright (C) dGB Beheer B.V.; (LICENSE) http://opendtect.org/OpendTect_license.txt * AUTHOR : A. Huck * DATE : July 2018 Module Summary ############### odpy.common is the main important module in odpy. Allows for basic interactions with the OpendTect software and database KEY methods ------------- * getODsoftwareDir() * gets the root directory of the Opendtect installation * getBinSubDir() * binary sub directory for executables in an OpendTect installation * returns information on the release type * getODargs() * get dict containing information about the Opendtect executable, project database path and current survey name Example -------- >>> import odpy.common as odcommon >>> odcommon.getODSoftwareDir() 'C:\PROGRA~1\OPENDT~1\new\6683E8~1.0' >>> odcommon.getBinSubDir() 'Release' >>> odcommon.getODArgs() {'dtectexec': ['C:\PROGRA~1\OPENDT~1\new\6683E8~1.0\bin\win64\Release'], 'dtectdata': ['C:\Users\OLAWALE IBRAHIM\DTECT_DATA'], 'survey': ['F3_Demo_2020']} Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: python.odpy.common.Timer Functions ~~~~~~~~~ .. autoapisummary:: python.odpy.common.sTimeUnitString python.odpy.common.initLogging python.odpy.common.set_log_file python.odpy.common.get_log_logger python.odpy.common.get_std_logger python.odpy.common.mergeArgs python.odpy.common.std_msg python.odpy.common.log_msg python.odpy.common.has_file_handlers python.odpy.common.has_stdlog_file python.odpy.common.has_log_file python.odpy.common.get_handler_stream python.odpy.common.get_handler_filename python.odpy.common.get_std_stream python.odpy.common.get_log_stream python.odpy.common.get_stdlog_file python.odpy.common.get_log_file python.odpy.common.reset_log_file python.odpy.common.redirect_stdout python.odpy.common.restore_stdout python.odpy.common.isWin python.odpy.common.isLux python.odpy.common.isMac python.odpy.common.getPlfSubDir python.odpy.common.getBinSubDir python.odpy.common.getODSoftwareDir python.odpy.common.getODBinaryDir python.odpy.common.getExecPlfDir python.odpy.common.get_settings_dir python.odpy.common.get_settings_filename python.odpy.common.get_base_datadir python.odpy.common.get_surveydir python.odpy.common.get_data_dir python.odpy.common.add_user_dtectdata python.odpy.common.add_user_survey python.odpy.common.getODArgs python.odpy.common.getIconFp python.odpy.common.tail python.odpy.common.batchIsFinished python.odpy.common.writeFile Attributes ~~~~~~~~~~ .. autoapisummary:: python.odpy.common.logconfig python.odpy.common.syslog_logger python.odpy.common.proclog_logger python.odpy.common.handler python.odpy.common.handler python.odpy.common.storedstdout python.odpy.common.storedstderr .. py:function:: sTimeUnitString(ismilli=False, abbr=True) OpendTect-like time stamp Parameters: * ismilli (bool, optional): Include millisecond (default is False) * abbr (bool, optional): Abbreviated (default is True) Returns: * str: Time stamp string formatted like done by OpendTect Examples: >>> sTimeUnitString() 'Mon 20 Apr 2020, 13:59:54' >>> sTimeUnitString( True ) 'Mon 20 Apr 2020, 13:59:54.001245' >>> sTimeUnitString( True, True ) 'Mon 20 Apr 2020, 13:59:54.001245' >>> sTimeUnitString( True, False ) 'Monday 20 April 2020, 13:59:54' .. py:data:: logconfig .. py:data:: syslog_logger .. py:data:: proclog_logger .. py:data:: handler .. py:data:: handler .. py:function:: initLogging(args) odpy Logger initialization Parameters: * args (dict): The members 'logfile' and 'sysout' from the input dictionary are supposed to contain existing filenames which are used to setup the module loggers proclog_logger and syslog_logger .. py:function:: set_log_file(filenm, logger) Sets log file with the handler based on the filename Parameters: * filenm (str): log file name * logger (object): log object Returns: Nothing. Removes past handlers if any and sets new log handler type based on file name .. py:function:: get_log_logger() Returns logger .. py:function:: get_std_logger() Returns module logger .. py:function:: mergeArgs(a, b=None, c=None, d=None, e=None, f=None) Concatenates input strings and objects if more than one as single string Parameters: * a (object or string): Message to be printed * b-f (object or string, optional): Message to be printed Returns: * str: Concatenated string Notes: * All objects are formatted to strings using the str() function * All outputs are automatically separated by spaces. .. py:function:: std_msg(a, b=None, c=None, d=None, e=None, f=None) Print to odpy standard logger Parameters: * a (object or string): Message to be printed * b-f (object or string, optional): Message to be printed Prints: * str: Concatenated string Notes: * All objects are formatted to strings using the str() function * All outputs are automatically separated by spaces. * Reserved for standard logging information. .. py:function:: log_msg(a, b=None, c=None, d=None, e=None, f=None) Print to odpy processing logger Parameters: * a (object or string): Message to be printed * b-f (object or string, optional): Message to be printed Returns: * str: Concatenated string Notes: * All objects are formatted to strings using the str() function * All outputs are automatically separated by spaces. * Reserved for processing logging information, * i.e. to report progress on a task .. py:function:: has_file_handlers(logger) To check if a log file has a file handler Parameters: * logger (object): Logger file object Returns: * bool: True if logger is a file handler logger .. py:function:: has_stdlog_file() Checks if module log has a file handler Returns * bool: True if module log file has a File handler and False if otherwise .. py:function:: has_log_file() Checks if log (odproclog) has a file handler Returns: * bool: True if log file (odproclog) has a File handler and False if otherwise .. py:function:: get_handler_stream(logger) Gets log handler stream Parameters: * logger (object): log file object Returns: * str: where log info streams to if log handler exist, returns None if handler level is not set .. py:function:: get_handler_filename(logger) Gets logger filename Parameters: * logger (object): log file object Returns: * str: Log file name if any, None if not .. py:function:: get_std_stream() Gets current module stream handler Returns: * str: log stream handler name .. py:function:: get_log_stream() Gets odpy.commom log stream handler Returns: * str: log stream handler name .. py:function:: get_stdlog_file() Full log file path for current module Returs: * str: Path to log file for current module .. py:function:: get_log_file() Full log file path for odpy.common Returs: * str: Path to log file for odpy.common .. py:function:: reset_log_file(keeplines=0) Log file reset Parameters: * keeplines (int, optional): Number of lines from the top of the file to keep (default is 0) Empty the log file pointed at by the processing logger, for instance before starting a new task. .. py:data:: storedstdout .. py:data:: storedstderr .. py:function:: redirect_stdout() Stdout-stderr redirection * Forces stdout to point to odpy.proclog_logger * Forces stderr to point to odpy.syslog_logger Notes: * Changes the value of sys.stdout and sys.stderr * Should be avoided as much as possible: To be used only when one cannot redirect in any other way. .. py:function:: restore_stdout() Stdout-stderr restore Undo operation of redirect_stdout .. py:function:: isWin() Is platform Windows? Returns: * True if running on any Windows platform .. py:function:: isLux() Is platform Linux? Returns: * True if running on any Linux platform .. py:function:: isMac() Is platform Mac? Returns: * True if running on any Mac-OS platform .. py:function:: getPlfSubDir() Platform sub-directory Platform specific sub-directory as existing in an OpendTect software installation Returns: * str: string like: 'lux64', 'win64', 'mac'. None if the platform is not supported by OpendTect .. py:function:: getBinSubDir() Binary sub-directory Sub-directory containing the executables in an OpendTect installation Returns: * str: string like: 'Debug', 'Release', 'RelWithDebInfo'. None if no such sub-directory is found. Notes: Assumes that the OpendTect installation contains the executable 'od_FileBrowser', and that this installation can be located by the function getODSoftwareDir() .. py:function:: getODSoftwareDir(args=None) OpendTect sofware directory Parameters: * args (dict, optional): Dictionary with the member 'dtectexec'. The value for that member should point to the executables folder of the requested application Returns: * str: Full path to the OpendTect software installation Notes: * Retrieved from either the input dictionary or from the current environment by reading the 'DTECT_APPL' or 'DTECT_WINAPPL' variables which are set by OpendTect at runtime. * Neither dictionary nor environment variables need to be set if the current module is placed within an OpendTect installation Examples: >>> getODSoftwareDir() 'C:\Program Files\OpendTect\6.6.0' .. py:function:: getODBinaryDir(srcpath) Get the binary directory from the source directory Only useful for development environments Parameters ---------- srcpath : Full path to a directory Path to the OpendTect source directory, configured with cmake Returns ------- Full path to OpendTect binary directory .. py:function:: getExecPlfDir(args=None) OpendTect executables directory Parameters: * args (dict, optional): Dictionary with the member 'dtectexec'. The value for that member should point to the executables folder of the requested application Returns: * str: Full path to the binaries of an OpendTect installation Notes: * Assumes that the software installation can be located with getODSoftwareDir() and that python is running on a platform supported by OpendTect. Examples: >>> getExecPlfDir() 'C:\Program Files\OpendTect\6.6.0\bin\win64\Release' .. py:function:: get_settings_dir() Directory with the OpendTect user settings Parameters ------ Can be overruled by setting the environment variable DTECT_PERSONAL_DIR Returns ------ Full path to $HOME/.od .. py:function:: get_settings_filename(filenm='settings') Get file path to an OpendTect settings file Parameters ---------- * filenm (string, optional): base file name inside .od folder default is 'settings' Will be influenced by the environment variable DTECT_USER if set. Returns ------ Full path to $HOME/.od/filenm[.DTECT_USER] .. py:function:: get_base_datadir() Get the OpendTect Survey Data Root directory Parameters ---------- Can be overruled by setting the environment variable DTECT_DATA Returns ------ Full path to the Opendtect Survey Data Root as written inside from get_settings_filename() .. py:function:: get_surveydir() Get the OpendTect Current Survey directory Returns ------- Directory name of the current survey as written inside get_settings_filename( 'survey' ) .. py:function:: get_data_dir() Full path to the current OpendTect Survey directory Returns ------ Full path to the current survey as retrieved by get_base_datadir() and get_surveydir() .. py:function:: add_user_dtectdata(args=None) Returns the OpendTect Survey Data Root in a dictionary Parameters ---------- * args (dict, optional) Dictionary where the returned value is added/updated Returns ------- Dictionary with the member 'dtectdata'. The value for that member should point to the return of get_base_datadir() .. py:function:: add_user_survey(args=None) Returns the OpendTect Survey Directory in a dictionary Parameters ---------- * args (dict, optional) Dictionary where the returned value is added/updated Returns ------- Dictionary with the member 'survey'. The value for that member should point to the return of get_surveydir() .. py:function:: getODArgs(args=None) OpendTect arguments dictionary Create a dictionary that contains typical OpendTect command line arguments and the files from this module' loggers Parameters: * args (dict, optional): Dictionary with the member 'dtectexec'. The value for that member should point to the executables folder of the requested application Returns: * dict: A dictionary with the following key-values: * 'dtectexec' : Full path to the OpendTect installation (see getExecPlfDir) * 'dtectdata' : The root projects directory name * 'survey' : The survey directory name * 'proclog' : The log file from proclog_logger if applicable * 'syslog' : The log file frol syslog_logger if applicable .. py:function:: getIconFp(nm, args=None) Path to an OpendTect icon file Parameters: * nm (string): Icon file basename (without extension) * args (dict, optional) Dictionary with the member 'dtectexec'. The value for that member should point to the executables folder of the requested application Returns: * str: Full path to the icon folder of the OpendTect installation Notes: Assumes that the software installation can be located with getODSoftwareDir() Examples: >>> getIconFp( 'dgbpro' ) 'C:\Program Files\OpendTect\6.6.0\data\icons.Default\dgbpro.png' .. py:function:: tail(fp, lines=1, strip_empty=False, _buffer=4098) Returns the last line(s) from a file Parameters: * fp (object): opened log file * lines (int): number of last lines in a file to be printed strip_empty (bool): removes empty new lines if True buffer (int): .. py:function:: batchIsFinished(logfile) OpendTect batch processing status Checks if an OpendTect batch process reached completion by parsing its log file. Parameters: logfile (str): Full path to an existing OpendTect log file. Returns: * bool: True if the file exists and contains 'Finished batch processing' at its tail. Notes: Instantaneous status. To monitor if the processing finishes, the user must repeatedly call this function. .. py:function:: writeFile(fnm, content) Creates a new file with contents Parameters: fnm (str): name of file to be created/written to content (str): content to be added to the file Returns: * bool: True if file has been successfully created False if file isn't created due to an error .. py:class:: Timer(interval, function, args=None, kwargs=None) Bases: :py:obj:`threading.Timer` Repeated timer Timer that restarts automatically after each interval .. py:method:: run(self) Method representing the thread's activity. You may override this method in a subclass. The standard run() method invokes the callable object passed to the object's constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.