enginir 1.0.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- enginir/__init__.py +55 -0
- enginir/_checks.py +165 -0
- enginir/_estimator.py +42 -0
- enginir/_logging.py +260 -0
- enginir/_resources/__init__.py +1 -0
- enginir/_resources/enginir.ico +0 -0
- enginir/_workflow.py +948 -0
- enginir/io/__init__.py +193 -0
- enginir/io/_common.py +56 -0
- enginir/io/_hdf5_groups.py +199 -0
- enginir/io/_types.py +61 -0
- enginir/io/csv_io.py +155 -0
- enginir/io/eiff_io.py +623 -0
- enginir/io/envi_io.py +330 -0
- enginir/io/hdf5_io.py +264 -0
- enginir/io/jcamp_io.py +219 -0
- enginir/io/project_store.py +988 -0
- enginir/io/spa_io.py +95 -0
- enginir/io/spc_io.py +252 -0
- enginir/modeling/__init__.py +22 -0
- enginir/modeling/_service.py +514 -0
- enginir/models/__init__.py +29 -0
- enginir/models/_common.py +50 -0
- enginir/models/classification.py +378 -0
- enginir/models/ml.py +272 -0
- enginir/models/pcr.py +164 -0
- enginir/models/pls.py +223 -0
- enginir/prediction/__init__.py +33 -0
- enginir/prediction/_service.py +757 -0
- enginir/preprocessing/__init__.py +33 -0
- enginir/preprocessing/_pipeline.py +182 -0
- enginir/preprocessing/baseline.py +212 -0
- enginir/preprocessing/derivatives.py +128 -0
- enginir/preprocessing/recipe.py +207 -0
- enginir/preprocessing/scatter.py +406 -0
- enginir/project/__init__.py +54 -0
- enginir/project/_hydration.py +291 -0
- enginir/project/_ids.py +19 -0
- enginir/project/_models.py +806 -0
- enginir/project/_signal_domain.py +366 -0
- enginir/project/_validation.py +181 -0
- enginir/utils.py +99 -0
- enginir/validation/__init__.py +41 -0
- enginir/validation/cross_val.py +425 -0
- enginir/validation/metrics.py +222 -0
- enginir/validation/outliers.py +214 -0
- enginir/viewer/__init__.py +427 -0
- enginir/viewer/__main__.py +321 -0
- enginir/viewer/_app.py +129 -0
- enginir/viewer/_attachment.py +126 -0
- enginir/viewer/_browser.py +266 -0
- enginir/viewer/_canvas.py +416 -0
- enginir/viewer/_data_helpers.py +40 -0
- enginir/viewer/_eda.py +620 -0
- enginir/viewer/_inspector.py +328 -0
- enginir/viewer/_jobs.py +181 -0
- enginir/viewer/_loading.py +135 -0
- enginir/viewer/_model_diagnostics.py +349 -0
- enginir/viewer/_modeling.py +1416 -0
- enginir/viewer/_panels.py +613 -0
- enginir/viewer/_prediction.py +1085 -0
- enginir/viewer/_recent.py +89 -0
- enginir/viewer/_state.py +1198 -0
- enginir/viewer/_theme.py +328 -0
- enginir/viewer/_ui_helpers.py +79 -0
- enginir/viewer/_viewer.py +1424 -0
- enginir/viewer/_welcome.py +245 -0
- enginir/viewer/themes/dark_indigo.xml +9 -0
- enginir/viewer/themes/light_indigo.xml +9 -0
- enginir/visualization/__init__.py +33 -0
- enginir/visualization/plots.py +562 -0
- enginir-1.0.0.dist-info/METADATA +141 -0
- enginir-1.0.0.dist-info/RECORD +76 -0
- enginir-1.0.0.dist-info/WHEEL +4 -0
- enginir-1.0.0.dist-info/entry_points.txt +3 -0
- enginir-1.0.0.dist-info/licenses/LICENSE +395 -0
enginir/__init__.py
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
"""
|
|
2
|
+
engiNIR top-level package.
|
|
3
|
+
|
|
4
|
+
`engiNIR` is the human-facing product name. The Python package name remains
|
|
5
|
+
``enginir``.
|
|
6
|
+
|
|
7
|
+
The package provides chemometric tools and project-backed workflows for
|
|
8
|
+
near-infrared spectra and hyperspectral imaging. The imports exposed here are
|
|
9
|
+
the high-level convenience surface for common loading, preprocessing, modeling,
|
|
10
|
+
and validation tasks.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from importlib.metadata import PackageNotFoundError, version as _metadata_version
|
|
14
|
+
|
|
15
|
+
from ._logging import disable_logging, enable_logging
|
|
16
|
+
from ._workflow import Project
|
|
17
|
+
from .io import load_spectra
|
|
18
|
+
from .models import LDAClassifier, PCR, PLSRegression, SIMCA
|
|
19
|
+
from .preprocessing import (Detrend, EMSC, MSC, PreprocessingRecipe, SNV, SavitzkyGolay,
|
|
20
|
+
Smoother)
|
|
21
|
+
from .validation import cross_validate, kennard_stone, metrics_report
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
try:
|
|
25
|
+
__version__ = _metadata_version("enginir")
|
|
26
|
+
except PackageNotFoundError: # running from a source tree that was never installed
|
|
27
|
+
__version__ = "0+unknown"
|
|
28
|
+
|
|
29
|
+
__all__ = [
|
|
30
|
+
"__version__",
|
|
31
|
+
# Project workflow
|
|
32
|
+
"Project",
|
|
33
|
+
"PreprocessingRecipe",
|
|
34
|
+
# Logging
|
|
35
|
+
"enable_logging",
|
|
36
|
+
"disable_logging",
|
|
37
|
+
# I/O
|
|
38
|
+
"load_spectra",
|
|
39
|
+
# Preprocessing
|
|
40
|
+
"SNV",
|
|
41
|
+
"MSC",
|
|
42
|
+
"EMSC",
|
|
43
|
+
"SavitzkyGolay",
|
|
44
|
+
"Detrend",
|
|
45
|
+
"Smoother",
|
|
46
|
+
# Models
|
|
47
|
+
"PLSRegression",
|
|
48
|
+
"PCR",
|
|
49
|
+
"SIMCA",
|
|
50
|
+
"LDAClassifier",
|
|
51
|
+
# Validation
|
|
52
|
+
"cross_validate",
|
|
53
|
+
"kennard_stone",
|
|
54
|
+
"metrics_report",
|
|
55
|
+
]
|
enginir/_checks.py
ADDED
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
"""Shared argument and array validation helpers.
|
|
2
|
+
|
|
3
|
+
engiNIR logs every error before raising it so that the persisted log is a
|
|
4
|
+
complete error report (see :mod:`enginir._logging`). The helpers in this module
|
|
5
|
+
implement that rule once: :func:`log_and_raise` writes the ERROR record and
|
|
6
|
+
raises, and the ``check_*`` / ``as_*`` helpers use it to validate common
|
|
7
|
+
parameter and array shapes.
|
|
8
|
+
|
|
9
|
+
Messages use :meth:`str.format` placeholders (``{}``, ``{!r}``), which is also
|
|
10
|
+
the placeholder style Loguru uses, so the logged and raised texts are identical.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
from collections.abc import Collection
|
|
16
|
+
from numbers import Integral, Real
|
|
17
|
+
from typing import Any, NoReturn
|
|
18
|
+
|
|
19
|
+
import numpy as np
|
|
20
|
+
from loguru import logger
|
|
21
|
+
|
|
22
|
+
__all__ = [
|
|
23
|
+
"as_float_array",
|
|
24
|
+
"as_float_matrix",
|
|
25
|
+
"as_float_vector",
|
|
26
|
+
"check_choice",
|
|
27
|
+
"check_integer",
|
|
28
|
+
"check_n_features",
|
|
29
|
+
"check_real",
|
|
30
|
+
"log_and_raise",
|
|
31
|
+
]
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def log_and_raise(
|
|
35
|
+
message: str,
|
|
36
|
+
*args: Any,
|
|
37
|
+
error: type[Exception] = ValueError,
|
|
38
|
+
cause: BaseException | None = None,
|
|
39
|
+
depth: int = 1,
|
|
40
|
+
) -> NoReturn:
|
|
41
|
+
"""Log ``message`` at ERROR level, then raise ``error`` with the same text.
|
|
42
|
+
|
|
43
|
+
Parameters
|
|
44
|
+
----------
|
|
45
|
+
message:
|
|
46
|
+
Message template with ``{}`` placeholders filled from ``args``.
|
|
47
|
+
*args:
|
|
48
|
+
Values substituted into ``message``.
|
|
49
|
+
error:
|
|
50
|
+
Exception class to raise. Defaults to :class:`ValueError`.
|
|
51
|
+
cause:
|
|
52
|
+
Optional exception to chain with ``raise ... from cause``.
|
|
53
|
+
depth:
|
|
54
|
+
Stack depth used to attribute the log record. The default attributes
|
|
55
|
+
it to the direct caller; helpers that validate on behalf of their own
|
|
56
|
+
caller pass ``depth=2``.
|
|
57
|
+
"""
|
|
58
|
+
logger.opt(depth=depth).error(message, *args)
|
|
59
|
+
text = message.format(*args) if args else message
|
|
60
|
+
if cause is None:
|
|
61
|
+
raise error(text)
|
|
62
|
+
raise error(text) from cause
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def check_integer(value: Any, name: str, *, minimum: int | None = None) -> int:
|
|
66
|
+
"""Return ``value`` as ``int`` after checking it is an integer ``>= minimum``.
|
|
67
|
+
|
|
68
|
+
Booleans are rejected even though ``bool`` subclasses ``int``.
|
|
69
|
+
"""
|
|
70
|
+
bound = "" if minimum is None else f" >= {minimum}"
|
|
71
|
+
if isinstance(value, bool) or not isinstance(value, Integral):
|
|
72
|
+
log_and_raise("{} must be an integer{}, got {!r}", name, bound, value, depth=2)
|
|
73
|
+
result = int(value)
|
|
74
|
+
if minimum is not None and result < minimum:
|
|
75
|
+
log_and_raise("{} must be an integer{}, got {!r}", name, bound, value, depth=2)
|
|
76
|
+
return result
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def check_real(value: Any, name: str, *, positive: bool = False) -> float:
|
|
80
|
+
"""Return ``value`` as a finite ``float``, optionally requiring ``> 0``.
|
|
81
|
+
|
|
82
|
+
Booleans are rejected even though ``bool`` subclasses ``int``.
|
|
83
|
+
"""
|
|
84
|
+
requirement = "a positive real number" if positive else "a finite real number"
|
|
85
|
+
if isinstance(value, bool) or not isinstance(value, Real):
|
|
86
|
+
log_and_raise("{} must be {}, got {!r}", name, requirement, value, depth=2)
|
|
87
|
+
result = float(value)
|
|
88
|
+
if not np.isfinite(result) or (positive and result <= 0.0):
|
|
89
|
+
log_and_raise("{} must be {}, got {!r}", name, requirement, value, depth=2)
|
|
90
|
+
return result
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def check_choice(value: Any, name: str, choices: Collection[str]) -> str:
|
|
94
|
+
"""Return ``value`` after checking it is one of ``choices``."""
|
|
95
|
+
try:
|
|
96
|
+
valid = value in choices
|
|
97
|
+
except TypeError: # unhashable value tested against a set or dict
|
|
98
|
+
valid = False
|
|
99
|
+
if not valid:
|
|
100
|
+
log_and_raise("{} must be one of {}, got {!r}", name, sorted(choices), value, depth=2)
|
|
101
|
+
return value
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def as_float_array(value: Any, name: str) -> np.ndarray:
|
|
105
|
+
"""Return ``value`` as a floating-point array.
|
|
106
|
+
|
|
107
|
+
``float32`` and ``float64`` are kept so that large hyperspectral cubes are
|
|
108
|
+
not silently doubled in memory. Integer, boolean and ``float16`` inputs
|
|
109
|
+
are converted to ``float32``, which represents raw sensor counts
|
|
110
|
+
(``uint16``) exactly. Complex, string, date and object arrays (e.g. lists
|
|
111
|
+
containing ``None``) are rejected.
|
|
112
|
+
"""
|
|
113
|
+
try:
|
|
114
|
+
arr = np.asarray(value)
|
|
115
|
+
except (TypeError, ValueError) as exc:
|
|
116
|
+
log_and_raise("{} must be a numeric array", name, cause=exc, depth=2)
|
|
117
|
+
if arr.dtype.kind not in "biuf":
|
|
118
|
+
log_and_raise("{} must be a real numeric array, got dtype {}", name, arr.dtype, depth=2)
|
|
119
|
+
if arr.dtype.kind != "f" or arr.dtype.itemsize < 4:
|
|
120
|
+
arr = arr.astype(np.float32)
|
|
121
|
+
return arr
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def as_float_matrix(value: Any, name: str) -> np.ndarray:
|
|
125
|
+
"""Return a non-empty, finite, 2-D floating array (see :func:`as_float_array`)."""
|
|
126
|
+
arr = as_float_array(value, name)
|
|
127
|
+
if arr.ndim != 2:
|
|
128
|
+
log_and_raise("{} must be 2-D, got shape {}", name, arr.shape, depth=2)
|
|
129
|
+
if arr.shape[0] == 0 or arr.shape[1] == 0:
|
|
130
|
+
log_and_raise(
|
|
131
|
+
"{} must contain at least one sample and one feature, got shape {}",
|
|
132
|
+
name,
|
|
133
|
+
arr.shape,
|
|
134
|
+
depth=2,
|
|
135
|
+
)
|
|
136
|
+
if not np.all(np.isfinite(arr)):
|
|
137
|
+
log_and_raise("{} must contain only finite values", name, depth=2)
|
|
138
|
+
return arr
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
def as_float_vector(value: Any, name: str, *, size: int | None = None) -> np.ndarray:
|
|
142
|
+
"""Return a finite 1-D floating array, optionally of length ``size``.
|
|
143
|
+
|
|
144
|
+
The result never aliases ``value``, so callers may store it as fitted state.
|
|
145
|
+
"""
|
|
146
|
+
arr = as_float_array(value, name)
|
|
147
|
+
if arr.ndim != 1:
|
|
148
|
+
log_and_raise("{} must be 1-D, got shape {}", name, arr.shape, depth=2)
|
|
149
|
+
if size is not None and arr.shape[0] != size:
|
|
150
|
+
log_and_raise("{} has {} values but X has {} features", name, arr.shape[0], size, depth=2)
|
|
151
|
+
if not np.all(np.isfinite(arr)):
|
|
152
|
+
log_and_raise("{} must contain only finite values", name, depth=2)
|
|
153
|
+
return arr.copy()
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
def check_n_features(X: np.ndarray, n_features_in: int, owner: str) -> None:
|
|
157
|
+
"""Check that ``X`` has the number of columns ``owner`` was fitted with."""
|
|
158
|
+
if X.shape[1] != n_features_in:
|
|
159
|
+
log_and_raise(
|
|
160
|
+
"X has {} features, but {} was fitted with {} features",
|
|
161
|
+
X.shape[1],
|
|
162
|
+
owner,
|
|
163
|
+
n_features_in,
|
|
164
|
+
depth=2,
|
|
165
|
+
)
|
enginir/_estimator.py
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
"""Base class of engiNIR estimators and transformers: version-checked pickles."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
6
|
+
from typing import Any
|
|
7
|
+
|
|
8
|
+
from sklearn.base import BaseEstimator
|
|
9
|
+
|
|
10
|
+
from ._checks import log_and_raise
|
|
11
|
+
|
|
12
|
+
__all__ = ["EnginirEstimator"]
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def _enginir_version() -> str:
|
|
16
|
+
try:
|
|
17
|
+
return version("enginir")
|
|
18
|
+
except PackageNotFoundError: # a source tree that was never installed
|
|
19
|
+
return "0+unknown"
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class EnginirEstimator(BaseEstimator):
|
|
23
|
+
"""A scikit-learn estimator whose pickles record the engiNIR version.
|
|
24
|
+
|
|
25
|
+
Fitted state of engiNIR 1.0 is not compatible with earlier releases (for
|
|
26
|
+
example, the PLS intercept now applies to uncentred spectra). A pickle
|
|
27
|
+
without a recorded version therefore comes from before 1.0 and is refused
|
|
28
|
+
instead of silently giving wrong results: fit the model again.
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
def __getstate__(self) -> dict[str, Any]:
|
|
32
|
+
base = super().__getstate__()
|
|
33
|
+
state: dict[str, Any] = dict(base) if isinstance(base, dict) else {}
|
|
34
|
+
state["_enginir_version"] = _enginir_version()
|
|
35
|
+
return state
|
|
36
|
+
|
|
37
|
+
def __setstate__(self, state: dict[str, Any]) -> None:
|
|
38
|
+
if "_enginir_version" not in state:
|
|
39
|
+
log_and_raise("This {} was saved by engiNIR before 1.0, whose fitted state means "
|
|
40
|
+
"something else; fit it again with engiNIR {}",
|
|
41
|
+
type(self).__name__, _enginir_version())
|
|
42
|
+
super().__setstate__(state)
|
enginir/_logging.py
ADDED
|
@@ -0,0 +1,260 @@
|
|
|
1
|
+
"""Logging configuration for engiNIR.
|
|
2
|
+
|
|
3
|
+
engiNIR logs through `Loguru <https://github.com/Delgan/loguru>`_. Following
|
|
4
|
+
Loguru's guidance for libraries, logging is **disabled when the package is
|
|
5
|
+
imported**: importing :mod:`enginir` adds no sinks, creates no files and
|
|
6
|
+
installs no exception hooks, so it never changes the logging of the program
|
|
7
|
+
that uses it.
|
|
8
|
+
|
|
9
|
+
Applications opt in with :func:`enable_logging`. The HSI viewer does so at
|
|
10
|
+
startup (warnings to stderr, INFO and above to a rotating log file, and logging
|
|
11
|
+
of uncaught exceptions). Scripts and notebooks can do the same::
|
|
12
|
+
|
|
13
|
+
import enginir
|
|
14
|
+
enginir.enable_logging("INFO", file="analysis.log")
|
|
15
|
+
|
|
16
|
+
Modules obtain their logger with ``logger = get_logger(__name__)`` and use
|
|
17
|
+
Loguru's ``{}`` placeholders.
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
from __future__ import annotations
|
|
21
|
+
|
|
22
|
+
import os
|
|
23
|
+
import sys
|
|
24
|
+
import threading
|
|
25
|
+
from dataclasses import dataclass, field
|
|
26
|
+
from pathlib import Path
|
|
27
|
+
from typing import Any
|
|
28
|
+
|
|
29
|
+
from loguru import logger
|
|
30
|
+
|
|
31
|
+
__all__ = [
|
|
32
|
+
"add_log_sink",
|
|
33
|
+
"default_log_files",
|
|
34
|
+
"disable_logging",
|
|
35
|
+
"enable_logging",
|
|
36
|
+
"get_logger",
|
|
37
|
+
"log_file_path",
|
|
38
|
+
"logging_enabled",
|
|
39
|
+
"remove_log_sink",
|
|
40
|
+
]
|
|
41
|
+
|
|
42
|
+
_PACKAGE = "enginir"
|
|
43
|
+
|
|
44
|
+
_STDERR_FORMAT = (
|
|
45
|
+
"<level>{level:<7}</level> | "
|
|
46
|
+
"<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> | "
|
|
47
|
+
"{message}"
|
|
48
|
+
)
|
|
49
|
+
_FILE_FORMAT = "{time:YYYY-MM-DD HH:mm:ss.SSS} | {level:<7} | {name}:{function}:{line} | {message}"
|
|
50
|
+
|
|
51
|
+
# Library code must never log at import time without opt-in.
|
|
52
|
+
logger.disable(_PACKAGE)
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
@dataclass
|
|
56
|
+
class _LoggingState:
|
|
57
|
+
"""Sinks and hooks installed by :func:`enable_logging`, removed by :func:`disable_logging`."""
|
|
58
|
+
|
|
59
|
+
sink_ids: list[int] = field(default_factory=list)
|
|
60
|
+
log_file: Path | None = None
|
|
61
|
+
previous_hooks: tuple[Any, Any] | None = None
|
|
62
|
+
own_hooks: tuple[Any, Any] | None = None
|
|
63
|
+
default_handler_rerouted: bool = False
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
_state = _LoggingState()
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def _is_enginir_record(record: Any) -> bool:
|
|
70
|
+
name = record["name"] or ""
|
|
71
|
+
return name == _PACKAGE or name.startswith(_PACKAGE + ".")
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def _is_enginir_console_record(record: Any) -> bool:
|
|
75
|
+
# Uncaught exceptions are printed by the chained interpreter hook already.
|
|
76
|
+
return _is_enginir_record(record) and not record["extra"].get("uncaught", False)
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def get_logger(name: str) -> Any:
|
|
80
|
+
"""Return the Loguru logger with records attributed to module ``name``.
|
|
81
|
+
|
|
82
|
+
Call once per module as ``logger = get_logger(__name__)``.
|
|
83
|
+
"""
|
|
84
|
+
return logger.patch(lambda record: record.update(name=name))
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def default_log_files() -> list[Path]:
|
|
88
|
+
"""Return the default log file locations in order of preference.
|
|
89
|
+
|
|
90
|
+
``$ENGINIR_LOG_FILE`` (if set), ``~/.enginir/enginir.log`` and
|
|
91
|
+
``/tmp/enginir/enginir.log``; the first writable one is used.
|
|
92
|
+
"""
|
|
93
|
+
candidates = [Path.home() / ".enginir" / "enginir.log", Path("/tmp/enginir/enginir.log")]
|
|
94
|
+
configured = os.environ.get("ENGINIR_LOG_FILE")
|
|
95
|
+
return [Path(configured), *candidates] if configured else candidates
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def enable_logging(
|
|
99
|
+
level: str = "WARNING",
|
|
100
|
+
*,
|
|
101
|
+
file: bool | str | os.PathLike[str] = False,
|
|
102
|
+
file_level: str = "INFO",
|
|
103
|
+
catch_uncaught: bool = False,
|
|
104
|
+
) -> Path | None:
|
|
105
|
+
"""Turn on engiNIR log output.
|
|
106
|
+
|
|
107
|
+
Calling the function again replaces the previous configuration.
|
|
108
|
+
|
|
109
|
+
Parameters
|
|
110
|
+
----------
|
|
111
|
+
level:
|
|
112
|
+
Minimum level of engiNIR messages printed to stderr, e.g. ``"DEBUG"``,
|
|
113
|
+
``"INFO"`` or ``"WARNING"`` (default).
|
|
114
|
+
file:
|
|
115
|
+
``False`` (default) for no log file, ``True`` for the first writable
|
|
116
|
+
location of :func:`default_log_files`, or a path. The file rotates at 10 MB and
|
|
117
|
+
keeps three old files.
|
|
118
|
+
file_level:
|
|
119
|
+
Minimum level written to the log file. Default ``"INFO"``.
|
|
120
|
+
catch_uncaught:
|
|
121
|
+
If ``True``, uncaught exceptions of the whole process (main thread and
|
|
122
|
+
other threads) are also logged at CRITICAL level before the previous
|
|
123
|
+
exception hooks run. Intended for applications such as the viewer.
|
|
124
|
+
|
|
125
|
+
Returns
|
|
126
|
+
-------
|
|
127
|
+
pathlib.Path or None
|
|
128
|
+
The log file in use, or ``None``.
|
|
129
|
+
|
|
130
|
+
Notes
|
|
131
|
+
-----
|
|
132
|
+
If Loguru's default stderr handler (id 0) is still installed, it is
|
|
133
|
+
replaced, once per process, by an identical handler that skips engiNIR
|
|
134
|
+
records, so that engiNIR messages are not printed twice and other Loguru
|
|
135
|
+
users keep their output. :func:`disable_logging` does not bring back
|
|
136
|
+
handler id 0.
|
|
137
|
+
|
|
138
|
+
If the configuration fails (e.g. an unknown level), nothing stays
|
|
139
|
+
installed and engiNIR remains muted.
|
|
140
|
+
"""
|
|
141
|
+
disable_logging()
|
|
142
|
+
try:
|
|
143
|
+
logger.enable(_PACKAGE)
|
|
144
|
+
_reroute_default_handler()
|
|
145
|
+
_state.sink_ids.append(
|
|
146
|
+
logger.add(
|
|
147
|
+
sys.stderr,
|
|
148
|
+
level=level,
|
|
149
|
+
format=_STDERR_FORMAT,
|
|
150
|
+
filter=_is_enginir_console_record,
|
|
151
|
+
diagnose=False,
|
|
152
|
+
)
|
|
153
|
+
)
|
|
154
|
+
if file is True:
|
|
155
|
+
for candidate in default_log_files():
|
|
156
|
+
if _add_file_sink(candidate, file_level):
|
|
157
|
+
break
|
|
158
|
+
elif file:
|
|
159
|
+
_add_file_sink(Path(file), file_level)
|
|
160
|
+
if catch_uncaught:
|
|
161
|
+
_install_exception_hooks()
|
|
162
|
+
except BaseException:
|
|
163
|
+
disable_logging()
|
|
164
|
+
raise
|
|
165
|
+
return _state.log_file
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def disable_logging() -> None:
|
|
169
|
+
"""Undo :func:`enable_logging`: remove its sinks and hooks and mute engiNIR again."""
|
|
170
|
+
for sink_id in _state.sink_ids:
|
|
171
|
+
logger.remove(sink_id)
|
|
172
|
+
_state.sink_ids.clear()
|
|
173
|
+
_state.log_file = None
|
|
174
|
+
if _state.previous_hooks is not None:
|
|
175
|
+
# Restore a hook only if it is still ours; a hook installed after ours stays.
|
|
176
|
+
previous_hook, previous_thread_hook = _state.previous_hooks
|
|
177
|
+
own_hook, own_thread_hook = _state.own_hooks or (None, None)
|
|
178
|
+
if sys.excepthook is own_hook:
|
|
179
|
+
sys.excepthook = previous_hook
|
|
180
|
+
if threading.excepthook is own_thread_hook:
|
|
181
|
+
threading.excepthook = previous_thread_hook
|
|
182
|
+
_state.previous_hooks = None
|
|
183
|
+
logger.disable(_PACKAGE)
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
def logging_enabled() -> bool:
|
|
187
|
+
"""Return ``True`` while a configuration from :func:`enable_logging` is active."""
|
|
188
|
+
return bool(_state.sink_ids)
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
def log_file_path() -> Path | None:
|
|
192
|
+
"""Return the active log file, or ``None`` if no file is being written."""
|
|
193
|
+
return _state.log_file
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
def add_log_sink(*args: Any, **kwargs: Any) -> int:
|
|
197
|
+
"""Add a sink to the Loguru logger (passed to :meth:`loguru.logger.add`) and return its id."""
|
|
198
|
+
return logger.add(*args, **kwargs)
|
|
199
|
+
|
|
200
|
+
|
|
201
|
+
def remove_log_sink(sink_id: int) -> None:
|
|
202
|
+
"""Remove a sink added with :func:`add_log_sink`."""
|
|
203
|
+
logger.remove(sink_id)
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
def _reroute_default_handler() -> None:
|
|
207
|
+
if _state.default_handler_rerouted:
|
|
208
|
+
return
|
|
209
|
+
_state.default_handler_rerouted = True
|
|
210
|
+
try:
|
|
211
|
+
logger.remove(0)
|
|
212
|
+
except ValueError:
|
|
213
|
+
return # The application already configured Loguru itself.
|
|
214
|
+
logger.add(sys.stderr, filter=lambda record: not _is_enginir_record(record))
|
|
215
|
+
|
|
216
|
+
|
|
217
|
+
def _add_file_sink(path: Path, level: str) -> bool:
|
|
218
|
+
try:
|
|
219
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
220
|
+
sink_id = logger.add(
|
|
221
|
+
str(path),
|
|
222
|
+
level=level,
|
|
223
|
+
format=_FILE_FORMAT,
|
|
224
|
+
filter=_is_enginir_record,
|
|
225
|
+
rotation="10 MB",
|
|
226
|
+
retention=3,
|
|
227
|
+
encoding="utf-8",
|
|
228
|
+
diagnose=False,
|
|
229
|
+
)
|
|
230
|
+
except OSError as exc:
|
|
231
|
+
logger.warning("Cannot write the log file {}: {}", path, exc)
|
|
232
|
+
return False
|
|
233
|
+
_state.sink_ids.append(sink_id)
|
|
234
|
+
_state.log_file = path
|
|
235
|
+
return True
|
|
236
|
+
|
|
237
|
+
|
|
238
|
+
def _install_exception_hooks() -> None:
|
|
239
|
+
previous_hook, previous_thread_hook = sys.excepthook, threading.excepthook
|
|
240
|
+
_state.previous_hooks = (previous_hook, previous_thread_hook)
|
|
241
|
+
uncaught_logger = logger.bind(uncaught=True)
|
|
242
|
+
|
|
243
|
+
def log_uncaught(exc_type: Any, exc: Any, traceback: Any) -> None:
|
|
244
|
+
if not issubclass(exc_type, KeyboardInterrupt):
|
|
245
|
+
uncaught_logger.opt(exception=(exc_type, exc, traceback)).critical(
|
|
246
|
+
"Uncaught exception"
|
|
247
|
+
)
|
|
248
|
+
previous_hook(exc_type, exc, traceback)
|
|
249
|
+
|
|
250
|
+
def log_uncaught_in_thread(args: Any) -> None:
|
|
251
|
+
# Like Python's default thread hook, a thread ending with SystemExit is not an error.
|
|
252
|
+
if not issubclass(args.exc_type, SystemExit):
|
|
253
|
+
uncaught_logger.opt(
|
|
254
|
+
exception=(args.exc_type, args.exc_value, args.exc_traceback)
|
|
255
|
+
).critical("Uncaught exception in thread {}", getattr(args.thread, "name", "?"))
|
|
256
|
+
previous_thread_hook(args)
|
|
257
|
+
|
|
258
|
+
sys.excepthook = log_uncaught
|
|
259
|
+
threading.excepthook = log_uncaught_in_thread
|
|
260
|
+
_state.own_hooks = (log_uncaught, log_uncaught_in_thread)
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Bundled runtime resources for engiNIR package components."""
|
|
Binary file
|