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 functions getUncaughtExceptionHandler and setUncaughtExceptionHandler are.

Version: 25.01.25

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.
 
getUncaughtExceptionHandler()
Get the currently installed uncaught ObjC/NSException handler.
 
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:
An Adict 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.

getUncaughtExceptionHandler()

 

Get the currently installed uncaught ObjC/NSException handler.

Returns:
The installed handler (callable) or None if no handler was or couldn't be installed (like on macOS 12.0.1 Monterey, for example).

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 that same error, an exiting status or None. In in former 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 to return that same error, an exiting status or None.
  • log - Print the error, an time stamp and -if avilable- the 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 or couldn't be installed.
Raises:
  • RuntimeError - Setting uncaught exception handlers unavailable, but only thrown if raiser=True.
  • TypeError - The handler is not callable.
Notes:
  • 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.
  • An uncaught ObjC/NSException always results in (graceful) termination of the process.
  • Uncaught ObjC/NSExceptions are not reported to an NSLog file (yet).

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