gpf.loggers module

This module provides a standardized alternative to the built-in Python Logger (logging package).

class gpf.loggers.Logger(identity, {log_file}, {level}, {encoding}, {time_tag}, {max_name})

Standard logger class that logs to stdout (e.g. console) and optionally a file.

Params:

• identity (str, unicode):

  The name of the owner of this Logger, as it will appear in the log file entries.

• log_file (str, unicode, gpf.paths.Path):

  Optional log file name or path to the log file. If there’s already a log handler for this file, this handler will be used automatically.

  • If log_file does not have an extension, a .log extension will be added.
  • If log_file has an extension, but it’s not .txt or .log, it will be reset to .log.
  • If time_tag is True (default), a _YYMMDD_HHMMSS timestamp (current local time) will be added to the log file name automatically.
  • If log_file is just a name, the output directory will be set to the user temp directory.
  • If log_file is a relative path, it will be made absolute (relative to os.curdir).
  • If log_file is an absolute path, that path will be used as-is.
  • If the log directory of log_file does not exist, it will be created.

  When log_file is omitted, the Logger will only write to the stdout stream (e.g. console).

• level (int):

  The minimum log level of messages that should be logged. Defaults to INFO.

Keyword params:

• max_name (int):

  The maximum length of the logger name used in the log record. Defaults to 15.

• encoding (str):

  The encoding to use in log files. Defaults to the preferred system encoding.

• time_tag (bool):

  When set to True (default), a timestamp will be appended to the log file name.

file_path

Returns the (first) file path of the current Logger (if setup as file-based logger).

info(message: str, **kwargs)

Writes an info/standard message.

Parameters:

• message – The text to write.
• kwargs – Optional arguments (e.g. exc_info=True for exception stack trace logging).

warning(message: str, **kwargs)

Writes a warning message and increments the warning counter. Multi-line messages count as 1 warning.

Parameters:

• message – The text to write.
• kwargs – Optional arguments (e.g. exc_info=True for exception stack trace logging).

error(message: str, **kwargs)

Writes an error message and increments the error counter. Multi-line messages count as 1 error.

Parameters:

• message – The text to write.
• kwargs – Optional arguments (e.g. exc_info=True for exception stack trace logging).

critical(message: str, **kwargs)

Writes a critical error message and increments the error counter. Multi-line messages count as 1 error.

Parameters:

• message – The text to write.
• kwargs – Optional arguments (e.g. exc_info=True for exception stack trace logging).

exception(message: Union[str, Exception], **kwargs)

Writes a critical error message and increments the error counter. Multi-line messages count as 1 error.

Parameters:

• message – The text to write.
• kwargs – Optional arguments (e.g. exc_info=True for exception stack trace logging).

section(message: str = '', max_length: int = 80, symbol: str = '-')

Writes a centered message wrapped inside a section line to the log. When message exceeds max_length, it will be logged as-is.

Parameters:

• message – The text to put in the middle of the line (optional).
• max_length – The maximum length of the line.
• symbol – The character to generate the line.

status()

Writes a (final) status message to the log, telling the user how many errors and warnings were logged by this instance.

Example:

>>> l = Logger('test')
>>> l.error('message')
ERROR: message
>>> l.warning('message')
WARNING: message
>>> l.status()
Logged 1 error and 1 warning.
>>> l.reset_stats()
>>> l.status()
Logged 0 errors and 0 warnings.

time_elapsed(func: Callable = None, *args, **kwargs)

Logs a nicely printed message stating how much time has passed. If the callable func is specified, this function is executed and its execution time is logged. If no callable func has been given, the elapsed time (since init or last reset_stats call) is logged.

Parameters:

• func – The optional callable to execute.
• args – Positional arguments for func.
• kwargs – Keyword arguments for func.

reset_stats(time: bool = True)

Resets the error and warning counters. Optionally, the start time can also be reset.

Parameters:time (bool) – When True (default) the start time of the logger will also be reset (to local now()).

quit(error_msg: Union[Exception, str] = None)

Releases the current logger and shuts down the (main) logger.

Parameters:error_msg – Optional termination message (or Exception instance) for fatal errors.

..note:: No more logging can take place after this call.

Under normal circumstances, the user does not need to call this method, because it is automatically being called once the user application has exited.

class gpf.loggers.ArcLogger(identity, {log_file}, {level}, {encoding}, {time_tag}, {max_name})

Logger that forwards all messages to ArcGIS and optionally logs to a file. Forwarding messages to ArcGIS is only useful when logging from an ArcToolbox or GEONIS Python script.

Params:

• identity (str, unicode):

  The name of the owner of this Logger, as it will appear in the log file entries.

• log_file (str, unicode, gpf.paths.Path):

  Optional log file name or path to the log file. If there’s already a log handler for this file, this handler will be used automatically.

  • If log_file does not have an extension, a .log extension will be added.
  • If log_file has an extension, but it’s not .txt or .log, it will be reset to .log.
  • If time_tag is True (default = False), a _YYMMDD_HHMMSS timestamp (current local time) will be added to the log file name automatically.
  • If log_file is just a name, the output directory will be set to the user temp directory.
  • If log_file is a relative path, it will be made absolute (relative to os.curdir).
  • If log_file is an absolute path, that path will be used as-is.
  • If the log directory of log_file does not exist, it will be created.

  When log_file is omitted, the Logger will only write to the stdout stream (e.g. console).

• level (int):

  The minimum log level of messages that should be logged. Defaults to INFO.

Keyword params:

• max_name (int):

  The maximum length of the logger name used in the log record. Defaults to 15.

• encoding (str):

  The encoding to use in log files (only). Defaults to cp1252 on Windows.

• time_tag (bool):

  When set to True (default = False), a timestamp will be appended to the log file name.

critical(message: str, **kwargs)

Writes a critical error message and increments the error counter. Multi-line messages count as 1 error.

Parameters:

• message – The text to write.
• kwargs – Optional arguments (e.g. exc_info=True for exception stack trace logging).

error(message: str, **kwargs)

Writes an error message and increments the error counter. Multi-line messages count as 1 error.

Parameters:

• message – The text to write.
• kwargs – Optional arguments (e.g. exc_info=True for exception stack trace logging).

exception(message: Union[str, Exception], **kwargs)

Writes a critical error message and increments the error counter. Multi-line messages count as 1 error.

Parameters:

• message – The text to write.
• kwargs – Optional arguments (e.g. exc_info=True for exception stack trace logging).

file_path

Returns the (first) file path of the current Logger (if setup as file-based logger).

info(message: str, **kwargs)

Writes an info/standard message.

Parameters:

• message – The text to write.
• kwargs – Optional arguments (e.g. exc_info=True for exception stack trace logging).

quit(error_msg: Union[Exception, str] = None)

Releases the current logger and shuts down the (main) logger.

Parameters:error_msg – Optional termination message (or Exception instance) for fatal errors.

..note:: No more logging can take place after this call.

Under normal circumstances, the user does not need to call this method, because it is automatically being called once the user application has exited.

reset_stats(time: bool = True)

Resets the error and warning counters. Optionally, the start time can also be reset.

Parameters:time (bool) – When True (default) the start time of the logger will also be reset (to local now()).

section(message: str = '', max_length: int = 80, symbol: str = '-')

Writes a centered message wrapped inside a section line to the log. When message exceeds max_length, it will be logged as-is.

Parameters:

• message – The text to put in the middle of the line (optional).
• max_length – The maximum length of the line.
• symbol – The character to generate the line.

status()

Writes a (final) status message to the log, telling the user how many errors and warnings were logged by this instance.

Example:

>>> l = Logger('test')
>>> l.error('message')
ERROR: message
>>> l.warning('message')
WARNING: message
>>> l.status()
Logged 1 error and 1 warning.
>>> l.reset_stats()
>>> l.status()
Logged 0 errors and 0 warnings.

time_elapsed(func: Callable = None, *args, **kwargs)

Logs a nicely printed message stating how much time has passed. If the callable func is specified, this function is executed and its execution time is logged. If no callable func has been given, the elapsed time (since init or last reset_stats call) is logged.

Parameters:

• func – The optional callable to execute.
• args – Positional arguments for func.
• kwargs – Keyword arguments for func.

warning(message: str, **kwargs)

Writes a warning message and increments the warning counter. Multi-line messages count as 1 warning.

Parameters:

• message – The text to write.
• kwargs – Optional arguments (e.g. exc_info=True for exception stack trace logging).