multigas 0.1.0__tar.gz
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.
- multigas-0.1.0/LICENSE +21 -0
- multigas-0.1.0/PKG-INFO +175 -0
- multigas-0.1.0/README.md +130 -0
- multigas-0.1.0/pyproject.toml +57 -0
- multigas-0.1.0/src/multigas/__init__.py +36 -0
- multigas-0.1.0/src/multigas/config/__init__.py +5 -0
- multigas-0.1.0/src/multigas/core/__init__.py +50 -0
- multigas-0.1.0/src/multigas/core/exceptions.py +215 -0
- multigas-0.1.0/src/multigas/core/io.py +71 -0
- multigas-0.1.0/src/multigas/core/query.py +412 -0
- multigas-0.1.0/src/multigas/core/types.py +290 -0
- multigas-0.1.0/src/multigas/data/__init__.py +18 -0
- multigas-0.1.0/src/multigas/data/loader.py +417 -0
- multigas-0.1.0/src/multigas/logging.py +170 -0
- multigas-0.1.0/src/multigas/utils/__init__.py +13 -0
- multigas-0.1.0/src/multigas/utils/cache.py +171 -0
- multigas-0.1.0/src/multigas/utils/dataframe.py +79 -0
- multigas-0.1.0/src/multigas/utils/path.py +33 -0
- multigas-0.1.0/src/multigas/utils/validation.py +156 -0
multigas-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Martanto
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
multigas-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
Metadata-Version: 2.3
|
|
2
|
+
Name: multigas
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Python package for multigas sensor
|
|
5
|
+
Keywords: multigas,volcano,gas,sensor,monitoring
|
|
6
|
+
Author: Martanto
|
|
7
|
+
Author-email: Martanto <martanto@live.com>
|
|
8
|
+
License: MIT License
|
|
9
|
+
|
|
10
|
+
Copyright (c) 2026 Martanto
|
|
11
|
+
|
|
12
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
13
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
14
|
+
in the Software without restriction, including without limitation the rights
|
|
15
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
16
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
17
|
+
furnished to do so, subject to the following conditions:
|
|
18
|
+
|
|
19
|
+
The above copyright notice and this permission notice shall be included in all
|
|
20
|
+
copies or substantial portions of the Software.
|
|
21
|
+
|
|
22
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
23
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
24
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
25
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
26
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
27
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
28
|
+
SOFTWARE.
|
|
29
|
+
Classifier: Development Status :: 3 - Alpha
|
|
30
|
+
Classifier: Intended Audience :: Science/Research
|
|
31
|
+
Classifier: Operating System :: OS Independent
|
|
32
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
33
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
34
|
+
Requires-Dist: joblib>=1.5.3
|
|
35
|
+
Requires-Dist: loguru>=0.7.3
|
|
36
|
+
Requires-Dist: numpy>=2.4.4
|
|
37
|
+
Requires-Dist: openpyxl>=3.1.5
|
|
38
|
+
Requires-Dist: pandas>=3.0.2
|
|
39
|
+
Requires-Dist: pandas-stubs~=3.0.2
|
|
40
|
+
Requires-Dist: python-dotenv>=1.2.2
|
|
41
|
+
Requires-Python: >=3.11
|
|
42
|
+
Project-URL: Homepage, https://github.com/martanto/multigas
|
|
43
|
+
Project-URL: Issues, https://github.com/martanto/multigas/issues
|
|
44
|
+
Description-Content-Type: text/markdown
|
|
45
|
+
|
|
46
|
+
# multigas
|
|
47
|
+
|
|
48
|
+
[](https://www.python.org/downloads/)
|
|
49
|
+
[](https://opensource.org/licenses/MIT)
|
|
50
|
+
|
|
51
|
+
**Python package for processing, analyzing, and visualizing multi-gas volcanic monitoring data.**
|
|
52
|
+
|
|
53
|
+
Developed through collaboration between CVGHM (Center for Volcanology and Geological Hazard Mitigation) and USGS for Campbell Scientific datalogger systems measuring volcanic gas emissions (CO2, SO2, H2S) and meteorological data.
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## Installation
|
|
58
|
+
|
|
59
|
+
### Requirements
|
|
60
|
+
|
|
61
|
+
- Python 3.11 or higher
|
|
62
|
+
- Windows, macOS, or Linux
|
|
63
|
+
|
|
64
|
+
### Install with uv (recommended)
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
# Install uv package manager
|
|
68
|
+
pip install uv
|
|
69
|
+
|
|
70
|
+
# Clone repository
|
|
71
|
+
git clone https://github.com/martanto/multigas.git
|
|
72
|
+
cd multigas
|
|
73
|
+
|
|
74
|
+
# Install with all dependencies
|
|
75
|
+
uv sync
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## Development
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
# Lint and auto-fix
|
|
84
|
+
uv run ruff check --fix src/
|
|
85
|
+
|
|
86
|
+
# Type check
|
|
87
|
+
uvx ty check src/
|
|
88
|
+
|
|
89
|
+
# Run all tests
|
|
90
|
+
uv run pytest tests/
|
|
91
|
+
|
|
92
|
+
# Run a single test file
|
|
93
|
+
uv run pytest tests/path/to/test_file.py
|
|
94
|
+
|
|
95
|
+
# Check for circular imports
|
|
96
|
+
uv run pytest tests/test_imports.py -v
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## Package Structure
|
|
102
|
+
|
|
103
|
+
```
|
|
104
|
+
src/multigas/
|
|
105
|
+
├── __init__.py # Version metadata
|
|
106
|
+
├── config/
|
|
107
|
+
│ └── logging.py # Logging setup (console + optional file handler)
|
|
108
|
+
└── core/
|
|
109
|
+
├── exceptions.py # Custom exception hierarchy
|
|
110
|
+
└── types.py # Shared type aliases, enums, and TypedDicts
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### Core types (`multigas.core.types`)
|
|
114
|
+
|
|
115
|
+
| Name | Kind | Description |
|
|
116
|
+
|---|---|---|
|
|
117
|
+
| `DateLike` | type alias | `str \| datetime \| pd.Timestamp` |
|
|
118
|
+
| `ColumnName` | type alias | `str` |
|
|
119
|
+
| `DatasetType` | `StrEnum` | Dataset sampling intervals as pandas frequency aliases: `ONE_SECOND="1s"`, `TWO_SECONDS="2s"`, `ONE_MINUTE="1min"`, `SIX_HOURS="6h"`, plus categorical modes `ZERO="zero"`, `SPAN="span"`, `WX="wx"` |
|
|
120
|
+
| `DatasetMetadataDict` | `TypedDict` | Station metadata from datalogger files |
|
|
121
|
+
| `LogLevel` | `StrEnum` | `DEBUG`, `INFO`, `WARN`, `ERROR` |
|
|
122
|
+
| `FileFormat` | `StrEnum` | `CSV`, `EXCEL`, `PARQUET`, `JSON` |
|
|
123
|
+
|
|
124
|
+
### Exceptions (`multigas.core.exceptions`)
|
|
125
|
+
|
|
126
|
+
```
|
|
127
|
+
MultigasException
|
|
128
|
+
├── DatasetError
|
|
129
|
+
│ ├── FilterError
|
|
130
|
+
│ ├── ColumnError
|
|
131
|
+
│ └── DateRangeError
|
|
132
|
+
├── ValidationError
|
|
133
|
+
├── CacheError
|
|
134
|
+
├── LoaderError
|
|
135
|
+
├── MetadataError
|
|
136
|
+
├── PlotError
|
|
137
|
+
└── ConfigError
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### Logging (`multigas.config.logging`)
|
|
141
|
+
|
|
142
|
+
```python
|
|
143
|
+
from multigas.config.logging import setup_logging, get_logger
|
|
144
|
+
from multigas.core.types import LogLevel
|
|
145
|
+
|
|
146
|
+
# Basic setup (console only)
|
|
147
|
+
logger = setup_logging(LogLevel.INFO)
|
|
148
|
+
|
|
149
|
+
# Enable file logging to logs/YYYY-MM-DD.log
|
|
150
|
+
logger = setup_logging(LogLevel.DEBUG, enable_file_log=True)
|
|
151
|
+
|
|
152
|
+
# Or set ENABLE_LOG=true in .env to enable file logging automatically
|
|
153
|
+
logger = setup_logging()
|
|
154
|
+
|
|
155
|
+
# Get a named child logger
|
|
156
|
+
logger = get_logger("multigas.reader")
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## Dependencies
|
|
162
|
+
|
|
163
|
+
| Package | Purpose |
|
|
164
|
+
|---|---|
|
|
165
|
+
| `pandas` | DataFrame operations |
|
|
166
|
+
| `numpy` | Numerical computing |
|
|
167
|
+
| `openpyxl` | Excel file I/O |
|
|
168
|
+
| `loguru` | Structured logging |
|
|
169
|
+
| `python-dotenv` | Environment variable loading |
|
|
170
|
+
|
|
171
|
+
---
|
|
172
|
+
|
|
173
|
+
## License
|
|
174
|
+
|
|
175
|
+
[MIT](LICENSE) — Copyright (c) 2026, Martanto
|
multigas-0.1.0/README.md
ADDED
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
# multigas
|
|
2
|
+
|
|
3
|
+
[](https://www.python.org/downloads/)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
5
|
+
|
|
6
|
+
**Python package for processing, analyzing, and visualizing multi-gas volcanic monitoring data.**
|
|
7
|
+
|
|
8
|
+
Developed through collaboration between CVGHM (Center for Volcanology and Geological Hazard Mitigation) and USGS for Campbell Scientific datalogger systems measuring volcanic gas emissions (CO2, SO2, H2S) and meteorological data.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## Installation
|
|
13
|
+
|
|
14
|
+
### Requirements
|
|
15
|
+
|
|
16
|
+
- Python 3.11 or higher
|
|
17
|
+
- Windows, macOS, or Linux
|
|
18
|
+
|
|
19
|
+
### Install with uv (recommended)
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
# Install uv package manager
|
|
23
|
+
pip install uv
|
|
24
|
+
|
|
25
|
+
# Clone repository
|
|
26
|
+
git clone https://github.com/martanto/multigas.git
|
|
27
|
+
cd multigas
|
|
28
|
+
|
|
29
|
+
# Install with all dependencies
|
|
30
|
+
uv sync
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## Development
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
# Lint and auto-fix
|
|
39
|
+
uv run ruff check --fix src/
|
|
40
|
+
|
|
41
|
+
# Type check
|
|
42
|
+
uvx ty check src/
|
|
43
|
+
|
|
44
|
+
# Run all tests
|
|
45
|
+
uv run pytest tests/
|
|
46
|
+
|
|
47
|
+
# Run a single test file
|
|
48
|
+
uv run pytest tests/path/to/test_file.py
|
|
49
|
+
|
|
50
|
+
# Check for circular imports
|
|
51
|
+
uv run pytest tests/test_imports.py -v
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## Package Structure
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
src/multigas/
|
|
60
|
+
├── __init__.py # Version metadata
|
|
61
|
+
├── config/
|
|
62
|
+
│ └── logging.py # Logging setup (console + optional file handler)
|
|
63
|
+
└── core/
|
|
64
|
+
├── exceptions.py # Custom exception hierarchy
|
|
65
|
+
└── types.py # Shared type aliases, enums, and TypedDicts
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### Core types (`multigas.core.types`)
|
|
69
|
+
|
|
70
|
+
| Name | Kind | Description |
|
|
71
|
+
|---|---|---|
|
|
72
|
+
| `DateLike` | type alias | `str \| datetime \| pd.Timestamp` |
|
|
73
|
+
| `ColumnName` | type alias | `str` |
|
|
74
|
+
| `DatasetType` | `StrEnum` | Dataset sampling intervals as pandas frequency aliases: `ONE_SECOND="1s"`, `TWO_SECONDS="2s"`, `ONE_MINUTE="1min"`, `SIX_HOURS="6h"`, plus categorical modes `ZERO="zero"`, `SPAN="span"`, `WX="wx"` |
|
|
75
|
+
| `DatasetMetadataDict` | `TypedDict` | Station metadata from datalogger files |
|
|
76
|
+
| `LogLevel` | `StrEnum` | `DEBUG`, `INFO`, `WARN`, `ERROR` |
|
|
77
|
+
| `FileFormat` | `StrEnum` | `CSV`, `EXCEL`, `PARQUET`, `JSON` |
|
|
78
|
+
|
|
79
|
+
### Exceptions (`multigas.core.exceptions`)
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
MultigasException
|
|
83
|
+
├── DatasetError
|
|
84
|
+
│ ├── FilterError
|
|
85
|
+
│ ├── ColumnError
|
|
86
|
+
│ └── DateRangeError
|
|
87
|
+
├── ValidationError
|
|
88
|
+
├── CacheError
|
|
89
|
+
├── LoaderError
|
|
90
|
+
├── MetadataError
|
|
91
|
+
├── PlotError
|
|
92
|
+
└── ConfigError
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Logging (`multigas.config.logging`)
|
|
96
|
+
|
|
97
|
+
```python
|
|
98
|
+
from multigas.config.logging import setup_logging, get_logger
|
|
99
|
+
from multigas.core.types import LogLevel
|
|
100
|
+
|
|
101
|
+
# Basic setup (console only)
|
|
102
|
+
logger = setup_logging(LogLevel.INFO)
|
|
103
|
+
|
|
104
|
+
# Enable file logging to logs/YYYY-MM-DD.log
|
|
105
|
+
logger = setup_logging(LogLevel.DEBUG, enable_file_log=True)
|
|
106
|
+
|
|
107
|
+
# Or set ENABLE_LOG=true in .env to enable file logging automatically
|
|
108
|
+
logger = setup_logging()
|
|
109
|
+
|
|
110
|
+
# Get a named child logger
|
|
111
|
+
logger = get_logger("multigas.reader")
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## Dependencies
|
|
117
|
+
|
|
118
|
+
| Package | Purpose |
|
|
119
|
+
|---|---|
|
|
120
|
+
| `pandas` | DataFrame operations |
|
|
121
|
+
| `numpy` | Numerical computing |
|
|
122
|
+
| `openpyxl` | Excel file I/O |
|
|
123
|
+
| `loguru` | Structured logging |
|
|
124
|
+
| `python-dotenv` | Environment variable loading |
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## License
|
|
129
|
+
|
|
130
|
+
[MIT](LICENSE) — Copyright (c) 2026, Martanto
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["uv_build >=0.11.0, <0.12"]
|
|
3
|
+
build-backend = "uv_build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "multigas"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
authors = [
|
|
9
|
+
{name = "Martanto", email = "martanto@live.com"},
|
|
10
|
+
]
|
|
11
|
+
description = "Python package for multigas sensor"
|
|
12
|
+
readme = "README.md"
|
|
13
|
+
license = {file = "LICENSE"}
|
|
14
|
+
keywords = ["multigas", "volcano", "gas", "sensor", "monitoring"]
|
|
15
|
+
requires-python = ">=3.11"
|
|
16
|
+
dependencies = [
|
|
17
|
+
"joblib>=1.5.3",
|
|
18
|
+
"loguru>=0.7.3",
|
|
19
|
+
"numpy>=2.4.4",
|
|
20
|
+
"openpyxl>=3.1.5",
|
|
21
|
+
"pandas>=3.0.2",
|
|
22
|
+
"pandas-stubs~=3.0.2",
|
|
23
|
+
"python-dotenv>=1.2.2",
|
|
24
|
+
]
|
|
25
|
+
|
|
26
|
+
classifiers = [
|
|
27
|
+
"Development Status :: 3 - Alpha",
|
|
28
|
+
"Intended Audience :: Science/Research",
|
|
29
|
+
"Operating System :: OS Independent",
|
|
30
|
+
"Programming Language :: Python :: 3.11",
|
|
31
|
+
"Programming Language :: Python :: 3.12",
|
|
32
|
+
]
|
|
33
|
+
|
|
34
|
+
[dependency-groups]
|
|
35
|
+
dev = [
|
|
36
|
+
"uv-build",
|
|
37
|
+
"ipykernel",
|
|
38
|
+
"notebook",
|
|
39
|
+
"ipywidgets",
|
|
40
|
+
"pandas-stubs>=3.0.0.260204",
|
|
41
|
+
{include-group = "lint"},
|
|
42
|
+
{include-group = "test"},
|
|
43
|
+
]
|
|
44
|
+
lint = [
|
|
45
|
+
"ruff",
|
|
46
|
+
"ty",
|
|
47
|
+
]
|
|
48
|
+
test = [
|
|
49
|
+
"pytest"
|
|
50
|
+
]
|
|
51
|
+
|
|
52
|
+
[tool.uv]
|
|
53
|
+
cache-dir = "./.cache/uv"
|
|
54
|
+
|
|
55
|
+
[project.urls]
|
|
56
|
+
Homepage = "https://github.com/martanto/multigas"
|
|
57
|
+
Issues = "https://github.com/martanto/multigas/issues"
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
#!/usr/bin/env python
|
|
2
|
+
"""multigas — Python package for processing multi-gas volcanic monitoring data.
|
|
3
|
+
|
|
4
|
+
Provides :class:`DataLoader` for reading, normalising, and caching CSV/Excel
|
|
5
|
+
files produced by Campbell Scientific dataloggers, and :func:`read_file` as a
|
|
6
|
+
convenient one-call entry point.
|
|
7
|
+
|
|
8
|
+
Example:
|
|
9
|
+
>>> from multigas import read_file
|
|
10
|
+
>>> ds = read_file("data/site_a.dat", dataset_type="1min")
|
|
11
|
+
>>> ds.df.head()
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from importlib.metadata import version
|
|
15
|
+
|
|
16
|
+
from multigas.core.io import read_file
|
|
17
|
+
from multigas.data.loader import DataLoader
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
__version__ = version("multigas")
|
|
21
|
+
__author__ = "Martanto"
|
|
22
|
+
__author_email__ = "martanto@live.com"
|
|
23
|
+
__license__ = "MIT"
|
|
24
|
+
__copyright__ = "Copyright (c) 2026, Martanto"
|
|
25
|
+
__url__ = "https://github.com/martanto/multigas"
|
|
26
|
+
|
|
27
|
+
__all__ = [
|
|
28
|
+
"__version__",
|
|
29
|
+
"__author__",
|
|
30
|
+
"__author_email__",
|
|
31
|
+
"__license__",
|
|
32
|
+
"__copyright__",
|
|
33
|
+
"__url__",
|
|
34
|
+
"read_file",
|
|
35
|
+
"DataLoader",
|
|
36
|
+
]
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
"""Core types, exceptions, and query infrastructure for multigas."""
|
|
2
|
+
|
|
3
|
+
from multigas.core.types import (
|
|
4
|
+
DateLike,
|
|
5
|
+
LogLevel,
|
|
6
|
+
ColumnName,
|
|
7
|
+
Comparator,
|
|
8
|
+
FileFormat,
|
|
9
|
+
DatasetType,
|
|
10
|
+
MultiGasData,
|
|
11
|
+
DatasetMetadataDict,
|
|
12
|
+
)
|
|
13
|
+
from multigas.core.exceptions import (
|
|
14
|
+
PlotError,
|
|
15
|
+
CacheError,
|
|
16
|
+
ColumnError,
|
|
17
|
+
ConfigError,
|
|
18
|
+
FilterError,
|
|
19
|
+
LoaderError,
|
|
20
|
+
DatasetError,
|
|
21
|
+
MetadataError,
|
|
22
|
+
DateRangeError,
|
|
23
|
+
ValidationError,
|
|
24
|
+
MultigasException,
|
|
25
|
+
)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
__all__ = [
|
|
29
|
+
# Types
|
|
30
|
+
"DateLike",
|
|
31
|
+
"LogLevel",
|
|
32
|
+
"ColumnName",
|
|
33
|
+
"Comparator",
|
|
34
|
+
"FileFormat",
|
|
35
|
+
"DatasetType",
|
|
36
|
+
"DatasetMetadataDict",
|
|
37
|
+
"MultiGasData",
|
|
38
|
+
# Exceptions
|
|
39
|
+
"PlotError",
|
|
40
|
+
"CacheError",
|
|
41
|
+
"ColumnError",
|
|
42
|
+
"ConfigError",
|
|
43
|
+
"FilterError",
|
|
44
|
+
"LoaderError",
|
|
45
|
+
"DatasetError",
|
|
46
|
+
"MetadataError",
|
|
47
|
+
"DateRangeError",
|
|
48
|
+
"ValidationError",
|
|
49
|
+
"MultigasException",
|
|
50
|
+
]
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
"""Exception hierarchy for the multigas package.
|
|
2
|
+
|
|
3
|
+
All exceptions derive from :class:`MultigasException` so callers can catch the
|
|
4
|
+
entire family with a single ``except MultigasException`` clause. Dataset-level
|
|
5
|
+
failures share a common :class:`DatasetError` ancestor, letting callers narrow
|
|
6
|
+
handling to filter / column / date-range problems without listing each type.
|
|
7
|
+
|
|
8
|
+
Every exception in this module auto-logs its message on construction via the
|
|
9
|
+
shared :mod:`multigas.logging` logger. The recorded frame points at the
|
|
10
|
+
``raise`` site, not this file, so log lines remain useful, and when an
|
|
11
|
+
exception is being handled at raise-time (i.e. ``raise ... from e``) the log
|
|
12
|
+
includes the full traceback with the ``__cause__`` chain. When
|
|
13
|
+
``ENABLE_LOG`` is unset the logger has no handlers and the auto-log is a
|
|
14
|
+
no-op.
|
|
15
|
+
|
|
16
|
+
The default log level is ``ERROR``. A subclass can override the class-level
|
|
17
|
+
``_log_level`` attribute to log at a different loguru level — useful for
|
|
18
|
+
soft-failure exceptions where ``WARNING`` is more honest than ``ERROR``.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
import sys
|
|
22
|
+
|
|
23
|
+
from multigas.logging import logger
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
class MultigasException(Exception):
|
|
27
|
+
"""Base class for every exception raised by the multigas package.
|
|
28
|
+
|
|
29
|
+
Catch this to intercept any package-specific failure without swallowing
|
|
30
|
+
unrelated built-in exceptions. On construction the message is
|
|
31
|
+
automatically logged through :mod:`multigas.logging` at the level named
|
|
32
|
+
by the class-level :attr:`_log_level` attribute (``"ERROR"`` by
|
|
33
|
+
default); every subclass inherits this behaviour and may override the
|
|
34
|
+
level.
|
|
35
|
+
|
|
36
|
+
Attributes:
|
|
37
|
+
_log_level (str): Loguru level name used for the auto-log —
|
|
38
|
+
``"DEBUG"``, ``"INFO"``, ``"WARNING"``, ``"ERROR"``, or
|
|
39
|
+
``"CRITICAL"``. Defaults to ``"ERROR"``. Override at the
|
|
40
|
+
subclass level to change severity without touching call sites.
|
|
41
|
+
|
|
42
|
+
Example:
|
|
43
|
+
>>> try:
|
|
44
|
+
... raise LoaderError("bad file")
|
|
45
|
+
... except MultigasException as exc:
|
|
46
|
+
... print(type(exc).__name__)
|
|
47
|
+
LoaderError
|
|
48
|
+
"""
|
|
49
|
+
|
|
50
|
+
_log_level: str = "ERROR"
|
|
51
|
+
|
|
52
|
+
def __init__(self, *args: object) -> None:
|
|
53
|
+
"""Initialise the exception and emit an auto-log line.
|
|
54
|
+
|
|
55
|
+
Delegates to :class:`Exception` for the standard ``args`` handling,
|
|
56
|
+
then logs the formatted message at :attr:`_log_level` via
|
|
57
|
+
:mod:`multigas.logging`. ``logger.opt(depth=1, exception=True)``
|
|
58
|
+
shifts the recorded frame one level up the stack so the log's
|
|
59
|
+
``{name}:{function}:{line}`` slot points at the ``raise`` site
|
|
60
|
+
rather than this ``__init__``, and attaches the current exception's
|
|
61
|
+
traceback (including the ``__cause__`` chain from
|
|
62
|
+
``raise ... from e``) when one is being handled. When no exception
|
|
63
|
+
is active the ``exception=True`` flag is a no-op.
|
|
64
|
+
|
|
65
|
+
Args:
|
|
66
|
+
*args (object): Positional arguments forwarded to
|
|
67
|
+
:class:`Exception`. The first argument, if any, becomes the
|
|
68
|
+
exception message.
|
|
69
|
+
|
|
70
|
+
Returns:
|
|
71
|
+
None
|
|
72
|
+
"""
|
|
73
|
+
super().__init__(*args)
|
|
74
|
+
# Only attach a traceback when an exception is genuinely being
|
|
75
|
+
# handled; otherwise loguru prints a bare "NoneType: None" tail.
|
|
76
|
+
attach_traceback = sys.exc_info()[0] is not None
|
|
77
|
+
logger.opt(depth=1, exception=attach_traceback).log(
|
|
78
|
+
self._log_level, f"{type(self).__name__}: {self}"
|
|
79
|
+
)
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
class DatasetError(MultigasException):
|
|
83
|
+
"""Raised for dataset-level operations that cannot complete.
|
|
84
|
+
|
|
85
|
+
Parent of :class:`FilterError`, :class:`ColumnError`, and
|
|
86
|
+
:class:`DateRangeError` — catch this to handle any dataset manipulation
|
|
87
|
+
failure regardless of subclass.
|
|
88
|
+
|
|
89
|
+
Example:
|
|
90
|
+
>>> raise DatasetError("dataset is empty")
|
|
91
|
+
Traceback (most recent call last):
|
|
92
|
+
...
|
|
93
|
+
multigas.core.exceptions.DatasetError: dataset is empty
|
|
94
|
+
"""
|
|
95
|
+
|
|
96
|
+
pass
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
class ValidationError(MultigasException):
|
|
100
|
+
"""Raised when input data fails a validation check.
|
|
101
|
+
|
|
102
|
+
Example:
|
|
103
|
+
>>> raise ValidationError("index is not monotonic")
|
|
104
|
+
Traceback (most recent call last):
|
|
105
|
+
...
|
|
106
|
+
multigas.core.exceptions.ValidationError: index is not monotonic
|
|
107
|
+
"""
|
|
108
|
+
|
|
109
|
+
pass
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
class CacheError(MultigasException):
|
|
113
|
+
"""Raised when reading from or writing to the on-disk cache fails.
|
|
114
|
+
|
|
115
|
+
Typically wraps a lower-level joblib or filesystem error.
|
|
116
|
+
|
|
117
|
+
Example:
|
|
118
|
+
>>> raise CacheError("cache file is corrupted")
|
|
119
|
+
Traceback (most recent call last):
|
|
120
|
+
...
|
|
121
|
+
multigas.core.exceptions.CacheError: cache file is corrupted
|
|
122
|
+
"""
|
|
123
|
+
|
|
124
|
+
pass
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
class LoaderError(MultigasException):
|
|
128
|
+
"""Raised when a source file cannot be located, parsed, or normalised.
|
|
129
|
+
|
|
130
|
+
Example:
|
|
131
|
+
>>> raise LoaderError("File not found: data/site_a.dat")
|
|
132
|
+
Traceback (most recent call last):
|
|
133
|
+
...
|
|
134
|
+
multigas.core.exceptions.LoaderError: File not found: data/site_a.dat
|
|
135
|
+
"""
|
|
136
|
+
|
|
137
|
+
pass
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
class MetadataError(MultigasException):
|
|
141
|
+
"""Raised when TOA5 (or equivalent) metadata cannot be extracted.
|
|
142
|
+
|
|
143
|
+
Example:
|
|
144
|
+
>>> raise MetadataError("missing station name in header")
|
|
145
|
+
Traceback (most recent call last):
|
|
146
|
+
...
|
|
147
|
+
multigas.core.exceptions.MetadataError: missing station name in header
|
|
148
|
+
"""
|
|
149
|
+
|
|
150
|
+
pass
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
class FilterError(DatasetError):
|
|
154
|
+
"""Raised when a filter expression is invalid or produces no rows.
|
|
155
|
+
|
|
156
|
+
Example:
|
|
157
|
+
>>> raise FilterError("unknown comparator '~='")
|
|
158
|
+
Traceback (most recent call last):
|
|
159
|
+
...
|
|
160
|
+
multigas.core.exceptions.FilterError: unknown comparator '~='
|
|
161
|
+
"""
|
|
162
|
+
|
|
163
|
+
pass
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
class ColumnError(DatasetError):
|
|
167
|
+
"""Raised for column-level failures — missing, duplicated, or wrong dtype.
|
|
168
|
+
|
|
169
|
+
Example:
|
|
170
|
+
>>> raise ColumnError("column 'CO2' is missing")
|
|
171
|
+
Traceback (most recent call last):
|
|
172
|
+
...
|
|
173
|
+
multigas.core.exceptions.ColumnError: column 'CO2' is missing
|
|
174
|
+
"""
|
|
175
|
+
|
|
176
|
+
pass
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
class DateRangeError(DatasetError):
|
|
180
|
+
"""Raised when a requested date range cannot be applied to the dataset.
|
|
181
|
+
|
|
182
|
+
Example:
|
|
183
|
+
>>> raise DateRangeError("start date is after end date")
|
|
184
|
+
Traceback (most recent call last):
|
|
185
|
+
...
|
|
186
|
+
multigas.core.exceptions.DateRangeError: start date is after end date
|
|
187
|
+
"""
|
|
188
|
+
|
|
189
|
+
pass
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
class PlotError(MultigasException):
|
|
193
|
+
"""Raised when a plotting routine cannot render its output.
|
|
194
|
+
|
|
195
|
+
Example:
|
|
196
|
+
>>> raise PlotError("no numeric columns to plot")
|
|
197
|
+
Traceback (most recent call last):
|
|
198
|
+
...
|
|
199
|
+
multigas.core.exceptions.PlotError: no numeric columns to plot
|
|
200
|
+
"""
|
|
201
|
+
|
|
202
|
+
pass
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
class ConfigError(MultigasException):
|
|
206
|
+
"""Raised when the package configuration is missing or invalid.
|
|
207
|
+
|
|
208
|
+
Example:
|
|
209
|
+
>>> raise ConfigError("cache_dir must be an absolute path")
|
|
210
|
+
Traceback (most recent call last):
|
|
211
|
+
...
|
|
212
|
+
multigas.core.exceptions.ConfigError: cache_dir must be an absolute path
|
|
213
|
+
"""
|
|
214
|
+
|
|
215
|
+
pass
|