multigas 0.1.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.
multigas/__init__.py ADDED
@@ -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,5 @@
1
+ """Configuration package for multigas.
2
+
3
+ Placeholder for future configuration objects (e.g. default cache locations,
4
+ column-mapping presets, sensor thresholds). No public API is exposed yet.
5
+ """
@@ -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
multigas/core/io.py ADDED
@@ -0,0 +1,71 @@
1
+ """Convenience wrappers for one-call file loading."""
2
+
3
+ from pathlib import Path
4
+
5
+ from multigas.core import MultiGasData
6
+ from multigas.core.types import DatasetType
7
+ from multigas.data.loader import DataLoader
8
+
9
+
10
+ def read_file(
11
+ file_path: Path | str,
12
+ dataset_type: DatasetType | str,
13
+ drop_empty_columns: bool = False,
14
+ normalize: bool = True,
15
+ use_cache: bool = True,
16
+ output_dir: Path | str | None = None,
17
+ cache_dir: Path | str | None = None,
18
+ overwrite: bool = False,
19
+ verbose: bool = False,
20
+ ) -> MultiGasData:
21
+ """Load a data file and return a :class:`MultiGasData` result.
22
+
23
+ A thin wrapper around :class:`DataLoader` that constructs the loader,
24
+ calls :meth:`DataLoader.load`, and returns the result in one call.
25
+
26
+ Args:
27
+ file_path: Path to the source CSV or dat file.
28
+ dataset_type: Dataset type identifier — a :class:`DatasetType` member
29
+ or its string value (e.g. ``"1min"``).
30
+ drop_empty_columns: Drop columns that are entirely NaN after
31
+ normalisation. Defaults to ``False``.
32
+ normalize: Replace NAN sentinel strings with ``np.nan`` and coerce
33
+ object columns to numeric. Defaults to ``True``.
34
+ use_cache: Read from and write to the on-disk joblib cache when
35
+ ``normalize`` is also ``True``. Defaults to ``True``.
36
+ output_dir: Root output directory. String values are coerced to
37
+ :class:`~pathlib.Path`. Defaults to ``<cwd>/output``.
38
+ cache_dir: Directory for cached files. Defaults to
39
+ ``<output_dir>/cache``.
40
+ overwrite: Ignore any existing cache entry and re-load from source.
41
+ Defaults to ``False``.
42
+ verbose: Emit informational log messages during loading. Defaults to
43
+ ``False``.
44
+
45
+ Returns:
46
+ A :class:`MultiGasData` instance containing the DataFrame, dataset
47
+ type, and absolute source path.
48
+
49
+ Raises:
50
+ LoaderError: If the file does not exist or cannot be parsed.
51
+
52
+ Example:
53
+ >>> from multigas.core.io import read_file
54
+ >>> ds = read_file("data/site_a.dat", dataset_type="1min")
55
+ >>> ds.df.shape
56
+ (1440, 10)
57
+ """
58
+ mutigas_data = DataLoader(
59
+ output_dir=output_dir,
60
+ cache_dir=cache_dir,
61
+ overwrite=overwrite,
62
+ verbose=verbose,
63
+ ).load(
64
+ file_path=file_path,
65
+ dataset_type=dataset_type,
66
+ drop_empty_columns=drop_empty_columns,
67
+ normalize=normalize,
68
+ use_cache=use_cache,
69
+ )
70
+
71
+ return mutigas_data