Package pycocoa :: Module faults
[frames] | no frames]

Module faults

Handle uncaught ObjC/NSExceptions and other faults similar to standard module faulthandler available since Python 3.3.

By default, fault handling is not enabled. In Python 3.3 and later, the faulthandler may be enabled by (a) calling function faulthandler.enable or (b) setting environment variable PYTHONFAULTHANDLER to any no-empty string or (c) including option -X faulthandler on the python command line.

For other Python releases, fault handling by this module pycocoa.faults is enabled by either (a) calling function faults.enable or (b) setting environment variable PYTHONFAULTHANDLER to any no-empty string. Command line option -X faulthandler is not available in older Python versions.

NOTE, if in Python 3.3 or later, the environment variable is defined as PYTHONFAULTHANDLER=pycocoa, the Python faulthandler will be overridden by this module pycocoa.faults.


Note: Functions faults.disable, faults.enable, faults.exiting, faults.is_enabled and faults.SIGs_enabled are not exported publicly as pycocoa.disable, pycocoa.enable, pycocoa.exiting, etc., only function setUncaughtExceptionHandler is.

Version: 20.11.15

Functions
 
disable()
Disable fault handling and uninstall the signal handlers installed by faults.enable, like the faulthandler module in Python 3.3 and later.
 
enable(file=sys.stdout, **unused)
Enable fault handling similar to the faulthandler module available in Python 3.3 and later.
 
is_enabled(sig=None)
Check whether fault handling is enabled, similar to the faulthandler module available in Python 3.3 and later.
 
SIGs_enabled(*sigs)
Return the signals currently handled as fault.
 
exiting(status=None)
Get/set the exit and status to use after faults or uncaught ObjC/NSExceptions.
 
setUncaughtExceptionHandler(handler, log=True, raiser=False)
Install a callback to handle uncaught ObjC/NSExceptions.
Variables
  __all__ = _ALL_LAZY.faults
Function Details

disable()

 

Disable fault handling and uninstall the signal handlers installed by faults.enable, like the faulthandler module in Python 3.3 and later.

Returns:
None.

enable(file=sys.stdout, **unused)

 

Enable fault handling similar to the faulthandler module available in Python 3.3 and later.

Try to install handlers for the SIGABRT, SIGBUS, SIGFPE, SIGILL and SIGSEGV signals to dump a an ObjC call stack and Python traceback to file.

Raises:
  • TypeError - File file doesn't have callable write and flush attributes.

See Also: NSMain.stdlog.

is_enabled(sig=None)

 

Check whether fault handling is enabled, similar to the faulthandler module available in Python 3.3 and later.

Parameters:
  • sig - Check whether fault handling includes this signal (signal.SIG*).
Returns:
True if fault handling is currently enabled, False otherwise.

SIGs_enabled(*sigs)

 

Return the signals currently handled as fault.

Returns:
A dict with the SIG* name and value of the currently handled signals, if any.

exiting(status=None)

 

Get/set the exit and status to use after faults or uncaught ObjC/NSExceptions.

Parameters:
  • status - The exit "door" and status code to be used (small int) or None to leave unchanged. A negative status invokes os._exit(abs(status)) to terminate without normal exit processing, while a non-negative status uses sys.exit(status) after a fault.
Returns:
The previously set exiting code (int).

Note: The faulthandler module in Python 3.3 and later ignores all exiting settings.

setUncaughtExceptionHandler(handler, log=True, raiser=False)

 

Install a callback to handle uncaught ObjC/NSExceptions.

The handler(error) is called with one argument error, an NSExceptionError instance. It should return either None or that same error. In the latter case, that error will subsequently be raised as Python exception.

Parameters:
  • handler - A callable to be invoked with a single argument error, an NSExceptionError instance and returning None or that very error.
  • log - Print the error, time stamp, ObjC callstack and Python traceback prior to invoking the handler (bool).
  • raiser - Raise the NSExceptionError error, regardless of the return value from the handler.
Returns:
The previously installed uncaught ObjC/NSException handler or None if no handler was installed.
Raises:
  • TypeError - The handler is not callable.

Note: Faults like SIGILL, SIGSEGV, etc. do not throw uncaught ObjC/NSExceptions and will not invoke the given handler. However, those and several other signals can be handled as faults, see faults.enable, faults.disable and other functions module faults.

See Also: Dgelessus' pythonista_startup.py, Handling Exceptions and Error Handling Programming Guide.