swx-advisories 0.2.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.
Files changed (31) hide show
  1. swx_advisories-0.2.0/.gitignore +46 -0
  2. swx_advisories-0.2.0/.gitlab-ci.yml +41 -0
  3. swx_advisories-0.2.0/CHANGELOG.md +37 -0
  4. swx_advisories-0.2.0/PKG-INFO +470 -0
  5. swx_advisories-0.2.0/README.md +441 -0
  6. swx_advisories-0.2.0/pyproject.toml +65 -0
  7. swx_advisories-0.2.0/src/swx_advisories/__init__.py +81 -0
  8. swx_advisories-0.2.0/src/swx_advisories/adapters/__init__.py +19 -0
  9. swx_advisories-0.2.0/src/swx_advisories/adapters/dataframe.py +431 -0
  10. swx_advisories-0.2.0/src/swx_advisories/fetchers/__init__.py +14 -0
  11. swx_advisories-0.2.0/src/swx_advisories/fetchers/base.py +66 -0
  12. swx_advisories-0.2.0/src/swx_advisories/fetchers/icao.py +161 -0
  13. swx_advisories-0.2.0/src/swx_advisories/fetchers/noaa.py +748 -0
  14. swx_advisories-0.2.0/src/swx_advisories/models/__init__.py +35 -0
  15. swx_advisories-0.2.0/src/swx_advisories/models/advisory.py +246 -0
  16. swx_advisories-0.2.0/src/swx_advisories/models/enums.py +136 -0
  17. swx_advisories-0.2.0/src/swx_advisories/models/location.py +128 -0
  18. swx_advisories-0.2.0/src/swx_advisories/parsers/__init__.py +11 -0
  19. swx_advisories-0.2.0/src/swx_advisories/parsers/icao/__init__.py +17 -0
  20. swx_advisories-0.2.0/src/swx_advisories/parsers/icao/event_builder.py +229 -0
  21. swx_advisories-0.2.0/src/swx_advisories/parsers/icao/location_parser.py +284 -0
  22. swx_advisories-0.2.0/src/swx_advisories/parsers/icao/text_parser.py +474 -0
  23. swx_advisories-0.2.0/src/swx_advisories/parsers/noaa/__init__.py +7 -0
  24. swx_advisories-0.2.0/src/swx_advisories/parsers/noaa/parser.py +494 -0
  25. swx_advisories-0.2.0/tests/conftest.py +83 -0
  26. swx_advisories-0.2.0/tests/fixtures/noaa_alerts_sample.json +1 -0
  27. swx_advisories-0.2.0/tests/fixtures/sample_icao_advisories.txt +631 -0
  28. swx_advisories-0.2.0/tests/test_adapters.py +316 -0
  29. swx_advisories-0.2.0/tests/test_fetchers.py +215 -0
  30. swx_advisories-0.2.0/tests/test_icao_parser.py +198 -0
  31. swx_advisories-0.2.0/tests/test_noaa_parser.py +239 -0
@@ -0,0 +1,46 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+ *.so
6
+ .Python
7
+ build/
8
+ develop-eggs/
9
+ dist/
10
+ downloads/
11
+ eggs/
12
+ .eggs/
13
+ lib/
14
+ lib64/
15
+ parts/
16
+ sdist/
17
+ var/
18
+ wheels/
19
+ *.egg-info/
20
+ .installed.cfg
21
+ *.egg
22
+
23
+ # Virtual environments
24
+ .env
25
+ .venv
26
+ env/
27
+ venv/
28
+ ENV/
29
+
30
+ # IDE
31
+ .idea/
32
+ .vscode/
33
+ *.swp
34
+ *.swo
35
+ *~
36
+
37
+ # Testing
38
+ .pytest_cache/
39
+ .coverage
40
+ htmlcov/
41
+ .tox/
42
+ .nox/
43
+
44
+ # OS
45
+ .DS_Store
46
+ Thumbs.db
@@ -0,0 +1,41 @@
1
+ stages:
2
+ - test
3
+ - build
4
+ - publish
5
+
6
+ # Run tests on all pushes and merge requests
7
+ test:
8
+ stage: test
9
+ script:
10
+ - python3 -m pip install -e .[dev]
11
+ - python3 -m pytest tests/ -v --tb=short
12
+ rules:
13
+ - if: $CI_PIPELINE_SOURCE == "merge_request_event"
14
+ - if: $CI_COMMIT_BRANCH
15
+
16
+ # Build package on tags
17
+ build:
18
+ stage: build
19
+ script:
20
+ - python3 -m pip install build
21
+ - python3 -m build
22
+ artifacts:
23
+ paths:
24
+ - dist/
25
+ expire_in: 1 week
26
+ rules:
27
+ - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
28
+
29
+ # Publish to PyPI on version tags
30
+ publish-pypi:
31
+ stage: publish
32
+ script:
33
+ - python3 -m pip install twine
34
+ - python3 -m twine upload dist/*
35
+ dependencies:
36
+ - build
37
+ rules:
38
+ - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
39
+ variables:
40
+ TWINE_USERNAME: __token__
41
+ TWINE_PASSWORD: $PYPI_TOKEN
@@ -0,0 +1,37 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [0.2.0] - 2025-01-26
9
+
10
+ ### Added
11
+ - `FetchResult.events` property for ICAO fetcher - events are now built automatically during `fetch()` and available via `result.events`
12
+ - `build_events` parameter to `ICAOFetcher.fetch()` and `from_text()` to optionally disable event building
13
+ - `message_code` field to NOAA advisories (e.g., "ALTK06", "WATA50")
14
+ - `original_text` field to preserve raw advisory text
15
+ - `NOAAArchiveFetcher` for fetching from NOAA HTML and FTP archives
16
+ - Progress callbacks for long-running fetch operations
17
+ - All datetimes are now timezone-aware (UTC)
18
+ - Comprehensive documentation in README
19
+
20
+ ### Changed
21
+ - ICAO events are now built eagerly during `fetch()` instead of requiring separate `fetch_events()` call
22
+ - `ICAOEventBuilder` is no longer part of the public API (use `result.events` instead)
23
+
24
+ ### Removed
25
+ - `ICAOFetcher.fetch_events()` method (use `result.events` instead)
26
+ - `ICAOFetcher.build_events()` public method (now private `_build_events()`)
27
+
28
+ ## [0.1.0] - 2025-01-20
29
+
30
+ ### Added
31
+ - Initial release
32
+ - ICAO advisory parsing (fnxx01/fnxx02 files)
33
+ - NOAA alert parsing from SWPC API
34
+ - Event chain building for ICAO advisories
35
+ - DataFrame adapters (flat, timeline, HAPI formats)
36
+ - Support for latitude bands and polygon coordinates
37
+ - G/S/R scale extraction for NOAA alerts
@@ -0,0 +1,470 @@
1
+ Metadata-Version: 2.4
2
+ Name: swx-advisories
3
+ Version: 0.2.0
4
+ Summary: Parse and process space weather advisories from ICAO and NOAA/SWPC
5
+ Project-URL: Homepage, https://gitlab.com/KNMI-OSS/spaceweather/swx-advisories
6
+ Project-URL: Repository, https://gitlab.com/KNMI-OSS/spaceweather/swx-advisories
7
+ Author-email: KNMI <eelco.doornbos@knmi.nl>
8
+ License-Expression: Apache-2.0
9
+ Keywords: ICAO,NOAA,SWPC,advisories,alerts,aviation,space-weather
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Intended Audience :: Science/Research
12
+ Classifier: License :: OSI Approved :: Apache Software License
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
19
+ Requires-Python: >=3.10
20
+ Requires-Dist: httpx>=0.25
21
+ Requires-Dist: pandas>=2.0
22
+ Requires-Dist: pydantic>=2.0
23
+ Provides-Extra: dev
24
+ Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
25
+ Requires-Dist: pytest>=7.0; extra == 'dev'
26
+ Requires-Dist: respx>=0.20; extra == 'dev'
27
+ Requires-Dist: ruff>=0.1; extra == 'dev'
28
+ Description-Content-Type: text/markdown
29
+
30
+ # swx-advisories
31
+
32
+ A Python package for parsing and analyzing space weather advisories from ICAO and NOAA/SWPC sources.
33
+
34
+ ## Features
35
+
36
+ - **ICAO Advisory Parsing**: Parse ICAO space weather advisories (fnxx01/fnxx02 files) with support for:
37
+ - Blank-line and ZCZC/NNNN delimited formats
38
+ - Latitude bands (HNH, MNH, EQN, EQS, MSH, HSH) and polygon coordinates
39
+ - Event chain building via NR RPLC linking
40
+ - HF COM and GNSS effect types with MOD/SEV severity
41
+
42
+ - **NOAA Alert Parsing**: Parse NOAA Space Weather Prediction Center alerts with:
43
+ - Live API fetching from services.swpc.noaa.gov
44
+ - G/S/R scale extraction (geomagnetic, solar radiation, radio blackout)
45
+ - Message type classification (ALERT, WARNING, WATCH, SUMMARY)
46
+ - K-index, X-ray class, and proton flux metrics
47
+
48
+ - **DataFrame Adapters**: Convert advisories to pandas DataFrames in multiple formats:
49
+ - Flat format (one row per advisory/event)
50
+ - Timeline format (time-indexed for visualization)
51
+ - HAPI format (Heliophysics API compatible)
52
+
53
+ ## Installation
54
+
55
+ ```bash
56
+ pip install swx-advisories
57
+ ```
58
+
59
+ Or install from source:
60
+
61
+ ```bash
62
+ git clone https://gitlab.com/KNMI-OSS/spaceweather/swx-advisories.git
63
+ cd swx-advisories
64
+ pip install -e .
65
+ ```
66
+
67
+ ## Quick Start
68
+
69
+ ### ICAO Advisories
70
+
71
+ ```python
72
+ from swx_advisories import ICAOFetcher, to_dataframe
73
+
74
+ # Load advisories from a file or directory
75
+ fetcher = ICAOFetcher("/path/to/advisories/")
76
+ result = fetcher.fetch()
77
+
78
+ # Access advisories and events directly from the result
79
+ for advisory in result.advisories:
80
+ print(f"{advisory.advisory_id}: {advisory.effect}")
81
+
82
+ for event in result.events:
83
+ print(f"{event.event_id}: {event.effect} ({event.peak_severity})")
84
+ print(f" Duration: {event.duration}")
85
+ print(f" Advisories: {event.num_advisories}")
86
+
87
+ # Convert to DataFrames
88
+ df_advisories = to_dataframe(result.advisories)
89
+ df_events = to_dataframe(result.events)
90
+ ```
91
+
92
+ ### NOAA Alerts
93
+
94
+ ```python
95
+ from swx_advisories import NOAAFetcher
96
+
97
+ # Fetch from live NOAA API
98
+ fetcher = NOAAFetcher()
99
+ result = fetcher.fetch()
100
+
101
+ for alert in result:
102
+ print(f"{alert.advisory_id}: {alert.event_type.value}")
103
+ print(f" Scale: {alert.noaa_scale}")
104
+ print(f" Severity: {alert.severity}")
105
+ ```
106
+
107
+ ### Convert to DataFrame
108
+
109
+ ```python
110
+ from swx_advisories import ICAOFetcher, to_dataframe
111
+
112
+ fetcher = ICAOFetcher("/path/to/advisories/")
113
+ result = fetcher.fetch()
114
+
115
+ # Get pandas DataFrames
116
+ df_advisories = to_dataframe(result.advisories, format="flat")
117
+ df_events = to_dataframe(result.events, format="flat")
118
+ print(df_events[["event_id", "effect", "peak_severity", "duration_hours"]])
119
+ ```
120
+
121
+ ## ICAO Advisories
122
+
123
+ ICAO space weather advisories are issued by designated Space Weather Centers (SWXCs) to warn aviation of space weather impacts on HF communications and GNSS navigation.
124
+
125
+ ### Fetching Advisories
126
+
127
+ ```python
128
+ from swx_advisories import ICAOFetcher
129
+
130
+ # From a single file
131
+ fetcher = ICAOFetcher("/path/to/fnxx01_advisory.txt")
132
+ result = fetcher.fetch()
133
+
134
+ # From a directory (searches for fnxx01*.txt and fnxx02*.txt)
135
+ fetcher = ICAOFetcher("/path/to/advisory_directory/")
136
+ result = fetcher.fetch()
137
+
138
+ # Access advisories
139
+ for advisory in result:
140
+ print(f"{advisory.advisory_id}: {advisory.effect} - {advisory.severity}")
141
+
142
+ # Check for errors
143
+ if not result.success:
144
+ print(f"Errors: {result.errors}")
145
+ ```
146
+
147
+ ### Building Event Chains
148
+
149
+ Advisories are linked via the `NR RPLC` field. The fetcher automatically builds these into event chains:
150
+
151
+ ```python
152
+ from swx_advisories import ICAOFetcher
153
+
154
+ fetcher = ICAOFetcher("/path/to/advisories/")
155
+ result = fetcher.fetch()
156
+
157
+ # Events are automatically built and available on result.events
158
+ for event in result.events:
159
+ print(f"\nEvent: {event.event_id}")
160
+ print(f" Effect: {event.effect}")
161
+ print(f" Peak severity: {event.peak_severity}")
162
+ print(f" Start: {event.issue_start}")
163
+ print(f" End: {event.issue_end}")
164
+ print(f" Duration: {event.duration}")
165
+ print(f" Centers: {', '.join(event.centers)}")
166
+ print(f" Advisories in chain: {event.num_advisories}")
167
+
168
+ # Skip event building if not needed
169
+ result = fetcher.fetch(build_events=False)
170
+ assert result.events is None
171
+ ```
172
+
173
+ ### Advisory Structure
174
+
175
+ Each `ICAOAdvisory` contains:
176
+
177
+ ```python
178
+ advisory.advisory_id # e.g., "2026/0042"
179
+ advisory.center # e.g., "PECASUS", "ACFJ"
180
+ advisory.effect # "HF COM" or "GNSS"
181
+ advisory.severity # "MOD", "SEV", or None
182
+ advisory.issue_time # datetime
183
+ advisory.observation # TemporalObservation with time and location
184
+ advisory.forecasts # List of 4 Forecast objects (+6h, +12h, +18h, +24h)
185
+ advisory.replaces_id # ID of advisory this replaces, or None if opening
186
+ advisory.is_opening # True if this starts a new event chain
187
+ advisory.remark # Free-text remarks
188
+ ```
189
+
190
+ ### Parsing Raw Text
191
+
192
+ ```python
193
+ from swx_advisories import ICAOFetcher
194
+
195
+ text = """FNXX01 EFKL 201549
196
+ SWX ADVISORY
197
+ DTG: 20260120/1549Z
198
+ SWXC: PECASUS
199
+ SWX EFFECT: GNSS
200
+ ADVISORY NR: 2026/99
201
+ OBS SWX: 20/1542Z SEV N55 E055 - N85 E055 - N85 E005 - N55 E005 - N55 E055
202
+ FCST SWX +6 HR: 20/2200Z NOT AVBL
203
+ FCST SWX +12 HR: 21/0400Z NOT AVBL
204
+ FCST SWX +18 HR: 21/1000Z NOT AVBL
205
+ FCST SWX +24 HR: 21/1600Z NOT AVBL
206
+ RMK: SPACE WEATHER EVENT IN PROGRESS
207
+ NXT ADVISORY: NO FURTHER ADVISORIES=
208
+ """
209
+
210
+ result = ICAOFetcher.from_text(text)
211
+ for adv in result:
212
+ print(f"{adv.advisory_id}: {adv.effect}")
213
+ ```
214
+
215
+ ## NOAA Alerts
216
+
217
+ NOAA Space Weather Prediction Center (SWPC) issues alerts, warnings, and watches for space weather events using the G/S/R scale system.
218
+
219
+ ### Fetching from API
220
+
221
+ ```python
222
+ from swx_advisories import NOAAFetcher
223
+
224
+ # Fetch all recent alerts from NOAA API
225
+ fetcher = NOAAFetcher()
226
+ result = fetcher.fetch()
227
+
228
+ print(f"Fetched {result.count} alerts")
229
+ for alert in result:
230
+ print(f"{alert.advisory_id}: {alert.event_type.value} ({alert.noaa_scale})")
231
+ ```
232
+
233
+ ### Fetching from Local File
234
+
235
+ ```python
236
+ from swx_advisories import NOAAFetcher
237
+
238
+ # Load from a local JSON file (same format as NOAA API)
239
+ fetcher = NOAAFetcher(from_file="/path/to/alerts.json")
240
+ result = fetcher.fetch()
241
+ ```
242
+
243
+ ### Filtering Alerts
244
+
245
+ ```python
246
+ from swx_advisories import NOAAFetcher, EventType, MessageType
247
+
248
+ fetcher = NOAAFetcher()
249
+
250
+ # Filter by event type
251
+ geomag = fetcher.fetch_by_type(EventType.GEOMAGNETIC_STORM)
252
+ radio = fetcher.fetch_by_type(EventType.RADIO_BLACKOUT)
253
+
254
+ # Filter by message type
255
+ alerts = fetcher.fetch_active_alerts() # ALERT messages only
256
+ warnings = fetcher.fetch_warnings() # WARNING messages only
257
+ watches = fetcher.fetch_watches() # WATCH messages only
258
+ ```
259
+
260
+ ### Alert Structure
261
+
262
+ Each `SpaceWeatherAdvisory` contains:
263
+
264
+ ```python
265
+ alert.advisory_id # e.g., "ALTK06-690"
266
+ alert.event_type # EventType enum (GEOMAGNETIC_STORM, RADIO_BLACKOUT, etc.)
267
+ alert.message_type # MessageType enum (ALERT, WARNING, WATCH, SUMMARY)
268
+ alert.severity # Severity enum (MINOR, MODERATE, SEVERE, EXTREME)
269
+ alert.noaa_scale # e.g., "G2", "S1", "R3"
270
+ alert.issue_time # datetime
271
+ alert.begin_time # datetime (if available)
272
+ alert.end_time # datetime (if available)
273
+ alert.short_description # Brief description of the event
274
+ alert.potential_impacts # Description of potential impacts
275
+ ```
276
+
277
+ ### NOAA Scales
278
+
279
+ The package extracts NOAA space weather scales:
280
+
281
+ | Scale | Type | Levels |
282
+ |-------|------|--------|
283
+ | G | Geomagnetic Storm | G1 (Minor) to G5 (Extreme) |
284
+ | S | Solar Radiation Storm | S1 (Minor) to S5 (Extreme) |
285
+ | R | Radio Blackout | R1 (Minor) to R5 (Extreme) |
286
+
287
+ ## DataFrame Adapters
288
+
289
+ Convert advisories and events to pandas DataFrames for analysis and visualization.
290
+
291
+ ### Unified Interface
292
+
293
+ ```python
294
+ from swx_advisories import ICAOFetcher, NOAAFetcher, to_dataframe
295
+
296
+ # ICAO advisories and events to DataFrame
297
+ icao = ICAOFetcher("/path/to/advisories/")
298
+ result = icao.fetch()
299
+ df_advisories = to_dataframe(result.advisories, format="flat")
300
+ df_events = to_dataframe(result.events, format="flat")
301
+
302
+ # NOAA alerts to DataFrame
303
+ noaa = NOAAFetcher()
304
+ alerts = noaa.fetch().advisories
305
+ df = to_dataframe(alerts, format="flat")
306
+ ```
307
+
308
+ ### Output Formats
309
+
310
+ **Flat format** - One row per advisory or event:
311
+
312
+ ```python
313
+ from swx_advisories import icao_advisories_to_dataframe, icao_events_to_dataframe
314
+
315
+ # Advisories DataFrame
316
+ df = icao_advisories_to_dataframe(advisories)
317
+ # Columns: advisory_id, center, effect, severity, issue_time, obs_time,
318
+ # lat_min, lat_max, lon_min, lon_max, replaces_id, ...
319
+
320
+ # Events DataFrame
321
+ df = icao_events_to_dataframe(events)
322
+ # Columns: event_id, effect, peak_severity, num_advisories, duration_hours,
323
+ # issue_start, issue_end, centers, ...
324
+ ```
325
+
326
+ **Timeline format** - Time-indexed for visualization:
327
+
328
+ ```python
329
+ from swx_advisories.adapters.dataframe import icao_timeline_dataframe
330
+
331
+ df = icao_timeline_dataframe(events)
332
+ # Columns: time, event_id, effect, severity, is_start, is_end
333
+
334
+ # With resampling to regular intervals
335
+ df = icao_timeline_dataframe(events, resample="1h")
336
+ # Columns: time, event_id, effect, severity, is_active
337
+ ```
338
+
339
+ **HAPI format** - Heliophysics API compatible:
340
+
341
+ ```python
342
+ from swx_advisories.adapters.dataframe import to_hapi_format
343
+
344
+ df = to_hapi_format(events)
345
+ # Time-indexed DataFrame pivoted by event type
346
+ ```
347
+
348
+ ### NOAA DataFrames
349
+
350
+ ```python
351
+ from swx_advisories import noaa_alerts_to_dataframe
352
+ from swx_advisories.adapters.dataframe import noaa_timeline_dataframe
353
+
354
+ # Flat format
355
+ df = noaa_alerts_to_dataframe(alerts)
356
+ # Columns: advisory_id, event_type, message_type, severity, noaa_scale,
357
+ # issue_time, begin_time, end_time, short_description, ...
358
+
359
+ # Timeline format
360
+ df = noaa_timeline_dataframe(alerts)
361
+ # Columns: time, advisory_id, event_type, severity, noaa_scale, is_start, is_end
362
+ ```
363
+
364
+ ## Data Models
365
+
366
+ ### Enums
367
+
368
+ ```python
369
+ from swx_advisories import EventType, MessageType, Severity, Source
370
+
371
+ # Event types
372
+ EventType.HF_BLACKOUT # ICAO HF COM
373
+ EventType.GNSS_DEGRADATION # ICAO GNSS
374
+ EventType.GEOMAGNETIC_STORM # NOAA G-scale
375
+ EventType.SOLAR_RADIATION_STORM # NOAA S-scale
376
+ EventType.RADIO_BLACKOUT # NOAA R-scale
377
+ EventType.SOLAR_FLARE
378
+ EventType.CME
379
+
380
+ # Message types (NOAA)
381
+ MessageType.ALERT
382
+ MessageType.WARNING
383
+ MessageType.WATCH
384
+ MessageType.SUMMARY
385
+
386
+ # Severity levels
387
+ Severity.MINOR
388
+ Severity.MODERATE
389
+ Severity.SEVERE
390
+ Severity.EXTREME
391
+ ```
392
+
393
+ ### Location Models
394
+
395
+ ```python
396
+ from swx_advisories import GeographicRegion, LatitudeBand
397
+
398
+ # Latitude bands used in ICAO advisories
399
+ LatitudeBand.HNH # High Northern Hemisphere (60-90N)
400
+ LatitudeBand.MNH # Middle Northern Hemisphere (30-60N)
401
+ LatitudeBand.EQN # Equatorial Northern (0-30N)
402
+ LatitudeBand.EQS # Equatorial Southern (0-30S)
403
+ LatitudeBand.MSH # Middle Southern Hemisphere (30-60S)
404
+ LatitudeBand.HSH # High Southern Hemisphere (60-90S)
405
+
406
+ # Geographic region with bounds
407
+ region = GeographicRegion(
408
+ lat_min=-90, lat_max=90,
409
+ lon_min=-180, lon_max=180,
410
+ text="Global coverage"
411
+ )
412
+ ```
413
+
414
+ ## API Reference
415
+
416
+ ### Fetchers
417
+
418
+ | Class | Description |
419
+ |-------|-------------|
420
+ | `ICAOFetcher(path)` | Load ICAO advisories from file or directory |
421
+ | `NOAAFetcher(from_file=None)` | Fetch NOAA alerts from API or local file |
422
+ | `FetchResult` | Container with advisories, metadata, and errors |
423
+
424
+ ### Parsers
425
+
426
+ | Class | Description |
427
+ |-------|-------------|
428
+ | `ICAOTextParser` | Parse raw ICAO advisory text |
429
+ | `NOAAParser` | Parse NOAA JSON alert data |
430
+
431
+ ### Adapters
432
+
433
+ | Function | Description |
434
+ |----------|-------------|
435
+ | `to_dataframe(data, format)` | Auto-detect and convert to DataFrame |
436
+ | `icao_advisories_to_dataframe(advisories)` | ICAO advisories to flat DataFrame |
437
+ | `icao_events_to_dataframe(events)` | ICAO events to flat DataFrame |
438
+ | `icao_timeline_dataframe(events, resample)` | ICAO events to timeline DataFrame |
439
+ | `noaa_alerts_to_dataframe(alerts)` | NOAA alerts to flat DataFrame |
440
+ | `noaa_timeline_dataframe(alerts)` | NOAA alerts to timeline DataFrame |
441
+ | `to_hapi_format(data)` | Convert to HAPI-compatible format |
442
+
443
+ ## Development
444
+
445
+ ### Running Tests
446
+
447
+ ```bash
448
+ # Install dev dependencies
449
+ pip install -e ".[dev]"
450
+
451
+ # Run tests
452
+ pytest tests/ -v
453
+ ```
454
+
455
+ ### Test Coverage
456
+
457
+ The package includes 96 tests covering:
458
+ - ICAO text parsing and event building
459
+ - NOAA message parsing and alert extraction
460
+ - Fetcher functionality
461
+ - DataFrame adapter conversions
462
+
463
+ ## License
464
+
465
+ MIT License - see LICENSE file for details.
466
+
467
+ ## Acknowledgments
468
+
469
+ - ICAO for the space weather advisory format specification
470
+ - NOAA Space Weather Prediction Center for the alerts API