Errors API
Purpose
This module handles error handling and exception management in RDEToolKit. It provides functionality for custom exception classes, error message management, exception capture and processing.
Key Features
Exception Management
- Exception capture and appropriate handling
- Simplified traceback display
- Dedicated handling for structured errors
Error Handling
- Standardization of error messages
- Creation of job error log files
- Generic error processing functionality
src.rdetoolkit.errors.catch_exception_with_message(*, error_message=None, error_code=None, eobj=None, verbose=False)
A decorator that catches exceptions and re-raises a StructuredError with a customized message and error code.
This decorator catches exceptions thrown within the decorated function. If a StructuredError is raised, it re-raises it with the specified error message, error code, and optional additional error object. For other exceptions, it re-raises them as standard Exceptions. The verbosity level of the error message can be controlled via the verbose parameter.
引数:
| 名前 | タイプ | デスクリプション | デフォルト |
|---|---|---|---|
error_message
|
Optional[str]
|
Customized message to be used in case of an error. Defaults to None. |
None
|
error_code
|
Optional[int]
|
Error code to be used in case of an error. Defaults to None. |
None
|
eobj
|
Optional[Any]
|
Additional object to include in the error. Defaults to None. |
None
|
verbose
|
bool
|
If set to True, provides detailed error messages. Defaults to False. |
False
|
戻り値:
| 名前 | タイプ | デスクリプション |
|---|---|---|
Callable |
Callable
|
A function decorator that provides customized error handling on exception occurrence. |
src.rdetoolkit.errors.format_simplified_traceback(tb_list)
Formats a simplified version of the traceback information.
This function takes a list of traceback frame summaries and constructs a formatted string representing the call stack. The formatted string includes indentation and node characters to indicate the call path, highlighting the file, line number, and function name. The final line of the traceback is marked with a fire emoji.
引数:
| 名前 | タイプ | デスクリプション | デフォルト |
|---|---|---|---|
tb_list
|
list[FrameSummary]
|
A list of traceback frame summaries to format. |
必須 |
戻り値:
| 名前 | タイプ | デスクリプション |
|---|---|---|
str |
str
|
A formatted string representing the simplified traceback information. |
src.rdetoolkit.errors.handle_exception(e, error_message=None, error_code=None, eobj=None, verbose=False, config=None)
Handles exceptions and formats them into a StructuredError with optional custom message, error code, and additional object.
This function captures the exception type and traceback, then formats a simplified version of the traceback. It constructs a custom error message, optionally including the full original traceback if verbose mode is enabled. The function returns a StructuredError containing the error message, error code, optional additional object, and simplified traceback information.
引数:
| 名前 | タイプ | デスクリプション | デフォルト |
|---|---|---|---|
e
|
Exception
|
The exception to handle. |
必須 |
error_message
|
Optional[str]
|
Customized message to be used in case of an error. Defaults to the exception message. |
None
|
error_code
|
Optional[int]
|
Error code to be used in case of an error. Defaults to 1. |
None
|
eobj
|
Optional[Any]
|
Additional object to include in the error. Defaults to None. |
None
|
verbose
|
bool
|
If set to True, includes the original traceback in the error message. Defaults to False. |
False
|
config
|
Config | None
|
Optional configuration object whose |
None
|
戻り値:
| 名前 | タイプ | デスクリプション |
|---|---|---|
StructuredError |
StructuredError
|
A structured error object containing the error message, error code, additional object, |
StructuredError
|
and simplified traceback information. |
src.rdetoolkit.errors.handle_and_exit_on_structured_error(e, logger, config=None)
Catch StructuredError and write to log file.
引数:
| 名前 | タイプ | デスクリプション | デフォルト |
|---|---|---|---|
e
|
StructuredError
|
StructuredError instance |
必須 |
logger
|
Logger
|
Logger instance |
必須 |
config
|
Config | None
|
Optional configuration object whose |
None
|
src.rdetoolkit.errors.handle_generic_error(e, logger, config=None)
Catch a generic (non-StructuredError) exception, emit a formatted traceback, log it, and exit.
This helper
- Formats the exception into a structured traceback (compact or python style depending on settings).
- Writes the formatted traceback to stderr.
- Writes a generic job error file with a fixed error code (999) to assist external supervisors.
- Logs the exception (including stack trace) via the provided logger.
- Exits the process with status code 1.
引数:
| 名前 | タイプ | デスクリプション | デフォルト |
|---|---|---|---|
e
|
Exception
|
The caught exception instance. |
必須 |
logger
|
Logger
|
Logger used to record the exception ( |
必須 |
config
|
Config | None
|
Optional configuration object. If provided and it contains traceback settings,
those settings control whether a compact traceback, a standard Python traceback, or both are generated.
If omitted, traceback settings are resolved from the environment (see |
None
|
Side Effects
- Writes structured traceback text to stderr.
- Creates/overwrites an error marker file via
write_job_errorlog_file(default filename: job.failed) with code=999. - Emits an ERROR-level log entry with stack trace.
- Terminates the interpreter with
sys.exit(1).
戻り値:
| タイプ | デスクリプション |
|---|---|
None
|
None. (The function does not return; it terminates the process.) |
src.rdetoolkit.errors.write_job_errorlog_file(code, message, *, filename='job.failed')
Write the error log to a file.
This function writes the given error code and message to a specified file.
The file will be saved in a directory determined by StorageDir.get_datadir(False).
引数:
| 名前 | タイプ | デスクリプション | デフォルト |
|---|---|---|---|
code
|
int
|
The error code to be written to the log file. |
必須 |
message
|
str
|
The error message to be written to the log file. |
必須 |
filename
|
str
|
The name of the file to which the error log will be written. Defaults to "job.failed". |
'job.failed'
|
Example
1 | |
Practical Usage
Using Exception Capture Decorator
| exception_decorator.py | |
|---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | |
Using Simplified Traceback
| simplified_traceback.py | |
|---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | |
Structured Error Handling
| structured_error_handling.py | |
|---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | |
Creating Error Log Files
| error_logging.py | |
|---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 | |
Comprehensive Error Handling System
| comprehensive_error_handling.py | |
|---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 | |