pycocoa.faults

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

# Module faults

Handle uncaught `ObjC/NSExceptions` and other `fault`s 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: 21.11.04

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 `fault`s or uncaught `ObjC/NSException`s. |
getUncaughtExceptionHandler() Get the currently installed uncaught `ObjC/NSException` handler. |
setUncaughtExceptionHandler(handler, log=True, raiser=False) Install a callback to handle uncaught `ObjC/NSException`s. |

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 `fault`s or uncaught `ObjC/NSException`s. 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/NSException`s. 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/NSException`s and will not invoke the given `handler`. However, those and several other signals can be handled as `fault`s, see faults.enable, faults.disable and other functions module faults. An uncaught `ObjC/NSException` always results in (graceful) termination of the process. Uncaught `ObjC/NSException`s are not reported to an `NSLog` file (yet). See Also: Dgelessus' pythonista_startup.py, Handling Exceptions and Error Handling Programming Guide.