35from typing
import Dict, Any, Optional, Union
41 class_name: Union[Logging, str],
44 toml_content: Optional[Dict[str, Any]] =
None,
45 save_to_file: Optional[bool] =
None,
46 file_name: Optional[str] =
None,
47 file_descriptor: Optional[Any] =
None,
48 success: Optional[int] =
None,
49 error: Optional[int] =
None,
50 log_warning_when_present: Optional[bool] =
None,
51 log_errors_when_present: Optional[bool] =
None
54 @brief Initialise and return a configured Disp instance for a given class or module.
56 This factory function creates and returns a configured `Disp` instance (the library's
57 display/logger wrapper) using defaults from `TOML_CONF`, `SAVE_TO_FILE` and `FILE_NAME`
58 unless overridden by the provided keyword arguments. The `class_name` may be a
59 `Logging`-compatible object (an object exposing logging-like methods) or a simple string
60 used as a label for the logger.
62 @param class_name Union[Logging, str]
63 The logging owner (class instance or name) to attach to the returned `Disp` instance.
64 @param debug bool, optional
65 If True the returned `Disp` instance will run in debug mode (enable debug-level output).
67 @param toml_content Optional[Dict[str, Any]]
68 Optional override for TOML configuration content (defaults to module-level TOML_CONF).
69 @param save_to_file Optional[bool]
70 Optional override to enable saving output to a file (defaults to module-level SAVE_TO_FILE).
71 @param file_name Optional[str]
72 Optional override for the file name used when saving to file (defaults to FILE_NAME).
73 @param file_descriptor Optional[Any]
74 Optional open file-like object to use for output (will be passed to `Disp`).
75 @param success Optional[int]
76 Optional custom success return code for the `Disp` instance.
77 @param error Optional[int]
78 Optional custom error return code for the `Disp` instance.
79 @param log_warning_when_present Optional[bool]
80 Optional flag to control whether warnings are logged when present.
81 @param log_errors_when_present Optional[bool]
82 Optional flag to control whether errors are logged when present.
85 A configured `Disp` instance ready to use.
88 - Optional arguments are only applied when provided (truthy) except `save_to_file` which is explicitly converted to bool when passed.
89 - Use `file_descriptor` to reuse an open file handle instead of letting `Disp` open its own file.
90 - This function updates only configuration passed to `Disp` and does not change library global constants.
92 _toml_content = TOML_CONF
93 _save_to_file = SAVE_TO_FILE
94 _file_name = FILE_NAME
95 _optional_arg: Dict[str, Any] = {}
96 if toml_content
is not None:
97 _toml_content = toml_content
98 if save_to_file
is not None:
99 _save_to_file = bool(save_to_file)
100 if file_name
is not None:
101 _file_name = file_name
102 if file_descriptor
is not None:
103 _optional_arg[
"file_descriptor"] = file_descriptor
104 if success
is not None:
105 _optional_arg[
"success"] = success
106 if error
is not None:
107 _optional_arg[
"error"] = error
108 if log_warning_when_present
is not None:
109 _optional_arg[
"log_warning_when_present"] = log_warning_when_present
110 if log_errors_when_present
is not None:
111 _optional_arg[
"log_errors_when_present"] = log_errors_when_present
113 toml_content=_toml_content,
114 save_to_file=_save_to_file,
115 file_name=_file_name,
Disp initialise_logger(Union[Logging, str] class_name, bool debug=False, *, Optional[Dict[str, Any]] toml_content=None, Optional[bool] save_to_file=None, Optional[str] file_name=None, Optional[Any] file_descriptor=None, Optional[int] success=None, Optional[int] error=None, Optional[bool] log_warning_when_present=None, Optional[bool] log_errors_when_present=None)
1.12.0