swpc-kit 0.3.0__py3-none-any.whl

swpc_kit/codes.py

@@ -0,0 +1,249 @@
+"""Catalogue of the SWPC space weather message codes.
+
+Each message of ``alerts.json`` carries two codes: a short ``product_id``
+such as ``K04W``, and a long code in its first line
+(``Space Weather Message Code: WARK04``), the one SWPC uses in its table of
+products (https://www.spaceweather.gov/content/subscription-services).
+
+Every entry says how it is known (see ``docs/FONTI.md``, section "Alerts"):
+
+- :attr:`Verification.VERIFIED`: everything in the entry is confirmed,
+  either by the text of the messages of the recorded fixture (the pair of
+  codes, meaning and scale) or by the official SWPC table of products (long
+  code, meaning and scale; the short code is then ``None`` if no message
+  showed it);
+- :attr:`Verification.DEDUCED`: long code, meaning and scale come from the
+  official table, but the short code was not seen in a message: it follows
+  the pattern of the verified ones and may be wrong.
+
+An unknown code is not an error: lookups return ``None`` and the message
+keeps its raw text.
+"""
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+# CATALOGUE stays out: its repr would fill the API reference; use lookup().
+__all__ = ["MessageCode", "Verification", "by_long", "by_short", "lookup"]
+
+
+class Verification(StrEnum):
+    """How a catalogue entry is known."""
+
+    VERIFIED = "verified"
+    DEDUCED = "deduced"
+
+
+@dataclass(frozen=True, slots=True)
+class MessageCode:
+    """One kind of space weather message.
+
+    Attributes:
+        long: Long code, as in ``Space Weather Message Code:``, e.g. ``WARK04``.
+        short: Short code, as in the ``product_id`` of ``alerts.json``, e.g.
+            ``K04W``; ``None`` when not known.
+        meaning: What the message announces, e.g.
+            ``"Warning: Geomagnetic K-index of 4 expected"``.
+        scale: NOAA scale level the message is about, e.g. ``"G1"``, or
+            ``None`` when the message has no scale level.
+        verification: Whether the entry was verified or deduced.
+    """
+
+    long: str
+    short: str | None
+    meaning: str
+    scale: str | None
+    verification: Verification
+
+
+_V = Verification.VERIFIED
+_D = Verification.DEDUCED
+
+CATALOGUE: tuple[MessageCode, ...] = (
+    # Geomagnetic K-index warnings and alerts.
+    MessageCode(
+        "WARK04", "K04W", "Warning: Geomagnetic K-index of 4 expected", None, _V
+    ),
+    MessageCode(
+        "WARK05", "K05W", "Warning: Geomagnetic K-index of 5 expected", "G1", _V
+    ),
+    MessageCode(
+        "WARK06", "K06W", "Warning: Geomagnetic K-index of 6 expected", "G2", _V
+    ),
+    MessageCode(
+        "WARK07",
+        "K07W",
+        "Warning: Geomagnetic K-index of 7 or greater expected",
+        "G3",
+        _V,
+    ),
+    MessageCode("ALTK04", "K04A", "Alert: Geomagnetic K-index of 4", None, _V),
+    MessageCode("ALTK05", "K05A", "Alert: Geomagnetic K-index of 5", "G1", _V),
+    MessageCode("ALTK06", "K06A", "Alert: Geomagnetic K-index of 6", "G2", _V),
+    MessageCode("ALTK07", "K07A", "Alert: Geomagnetic K-index of 7", "G3", _V),
+    MessageCode("ALTK08", "K08A", "Alert: Geomagnetic K-index of 8", "G4", _D),
+    MessageCode("ALTK09", "K09A", "Alert: Geomagnetic K-index of 9", "G5", _D),
+    # Geomagnetic storm watches.
+    MessageCode(
+        "WATA20", "A20F", "Watch: Geomagnetic Storm Category G1 Predicted", "G1", _V
+    ),
+    MessageCode(
+        "WATA30", "A30F", "Watch: Geomagnetic Storm Category G2 Predicted", "G2", _V
+    ),
+    MessageCode(
+        "WATA50", "A50F", "Watch: Geomagnetic Storm Category G3 Predicted", "G3", _D
+    ),
+    MessageCode(
+        "WATA99",
+        "A99F",
+        "Watch: Geomagnetic Storm Category G4 or Greater Predicted",
+        "G4",
+        _D,
+    ),
+    # Geomagnetic sudden impulse.
+    MessageCode(
+        "WARSUD", "SGIW", "Warning: Geomagnetic Sudden Impulse expected", None, _V
+    ),
+    MessageCode("SUMSUD", "MSIS", "Summary: Geomagnetic Sudden Impulse", None, _V),
+    # Electrons.
+    MessageCode(
+        "ALTEF3",
+        "EF3A",
+        "Alert: Electron 2MeV Integral Flux exceeded 1,000pfu",
+        None,
+        _V,
+    ),
+    # Protons (official table; short codes not seen in a message).
+    MessageCode(
+        "WARPX1",
+        None,
+        "Warning: Proton 10MeV Integral Flux above 10pfu expected",
+        "S1",
+        _V,
+    ),
+    MessageCode(
+        "WARPC0",
+        None,
+        "Warning: Proton 100MeV Integral Flux above 1pfu expected",
+        None,
+        _V,
+    ),
+    MessageCode(
+        "ALTPX1",
+        None,
+        "Alert: Proton Event 10MeV Integral Flux exceeded 10pfu",
+        "S1",
+        _V,
+    ),
+    MessageCode(
+        "SUMPX1",
+        None,
+        "Summary: Proton Event 10MeV Integral Flux exceeded 10pfu",
+        "S1",
+        _V,
+    ),
+    MessageCode(
+        "ALTPX2",
+        None,
+        "Alert: Proton Event 10MeV Integral Flux exceeded 100pfu",
+        "S2",
+        _V,
+    ),
+    MessageCode(
+        "SUMPX2",
+        None,
+        "Summary: Proton Event 10MeV Integral Flux exceeded 100pfu",
+        "S2",
+        _V,
+    ),
+    MessageCode(
+        "ALTPX3",
+        None,
+        "Alert: Proton Event 10MeV Integral Flux exceeded 1,000pfu",
+        "S3",
+        _V,
+    ),
+    MessageCode(
+        "SUMPX3",
+        None,
+        "Summary: Proton Event 10MeV Integral Flux exceeded 1,000pfu",
+        "S3",
+        _V,
+    ),
+    MessageCode(
+        "ALTPX4",
+        None,
+        "Alert: Proton Event 10MeV Integral Flux exceeded 10,000pfu",
+        "S4",
+        _V,
+    ),
+    MessageCode(
+        "SUMPX4",
+        None,
+        "Summary: Proton Event 10MeV Integral Flux exceeded 10,000pfu",
+        "S4",
+        _V,
+    ),
+    MessageCode(
+        "ALTPX5",
+        None,
+        "Alert: Proton Event 10MeV Integral Flux exceeded 100,000pfu",
+        "S5",
+        _V,
+    ),
+    MessageCode(
+        "SUMPX5",
+        None,
+        "Summary: Proton Event 10MeV Integral Flux exceeded 100,000pfu",
+        "S5",
+        _V,
+    ),
+    MessageCode(
+        "ALTPC0",
+        None,
+        "Alert: Proton Event 100MeV Integral Flux exceeded 1pfu",
+        None,
+        _V,
+    ),
+    MessageCode(
+        "SUMPC0",
+        None,
+        "Summary: Proton Event 100MeV Integral Flux exceeded 1pfu",
+        None,
+        _V,
+    ),
+    # X-rays.
+    MessageCode("ALTXMF", "XM5A", "Alert: X-Ray Flux exceeded M5", "R2", _V),
+    MessageCode("SUMXM5", "XM5S", "Summary: X-ray Event exceeded M5", "R2", _V),
+    MessageCode("SUMX01", None, "Summary: X-ray Event exceeded X1", "R3", _V),
+    MessageCode("SUMX10", None, "Summary: X-ray Event exceeded X10", "R4", _V),
+    MessageCode("SUMX20", None, "Summary: X-ray Event exceeded X20", "R5", _V),
+    # Radio.
+    MessageCode("ALTTP2", "TIIA", "Alert: Type II Radio Emission", None, _V),
+    MessageCode("ALTTP4", "TIVA", "Alert: Type IV Radio Emission", None, _V),
+    MessageCode("SUM10R", "BHIS", "Summary: 10cm Radio Burst", None, _V),
+)
+
+_BY_LONG = {c.long: c for c in CATALOGUE}
+_BY_SHORT = {c.short: c for c in CATALOGUE if c.short is not None}
+
+
+def by_long(code: str) -> MessageCode | None:
+    """Return the entry with long code ``code`` (e.g. ``WARK04``), or ``None``.
+
+    Case and surrounding spaces are ignored.
+    """
+    return _BY_LONG.get(code.strip().upper())
+
+
+def by_short(code: str) -> MessageCode | None:
+    """Return the entry with short code ``code`` (e.g. ``K04W``), or ``None``.
+
+    Case and surrounding spaces are ignored.
+    """
+    return _BY_SHORT.get(code.strip().upper())
+
+
+def lookup(code: str) -> MessageCode | None:
+    """Return the entry with ``code`` as its short or long code, or ``None``."""
+    return by_short(code) or by_long(code)

swpc_kit/errors.py

@@ -0,0 +1,135 @@
+"""Typed errors raised by swpc-kit.
+
+Every error derives from :class:`SwpcError`, so a caller can catch them all
+at once, or tell apart a transient state (:class:`SourceNotReady`) from a
+source that answered with something else (:class:`UnexpectedContent`) and
+from a known format with an inconsistent value (:class:`ParseError`).
+"""
+
+from datetime import datetime, timedelta
+
+
+class SwpcError(Exception):
+    """Base class for every error raised by swpc-kit.
+
+    Attributes:
+        product: Name of the product being fetched, such as
+            ``"planetary_k_index"``, when the error went through the client;
+            ``None`` from a parser called directly.
+        url: The URL being fetched, under the same condition.
+    """
+
+    product: str | None = None
+    url: str | None = None
+
+    def __str__(self) -> str:
+        text = super().__str__()
+        if self.product is None or self.url is None:
+            return text
+        if self.url in text:
+            return f"{text} [{self.product}]"
+        return f"{text} [{self.product} at {self.url}]"
+
+
+class SourceNotReady(SwpcError):
+    """The data is truncated or empty.
+
+    SWPC sometimes serves a file while rewriting it, so a JSON array may not
+    be closed or a text product may stop halfway. This is a transient state,
+    not a bug: the caller should try again later.
+    """
+
+
+class UnexpectedContent(SwpcError):
+    """The source answered with something other than the expected product.
+
+    For example an HTML page, a redirect to an announcement page, or a format
+    that no parser knows.
+
+    Args:
+        message: What came instead of the product.
+        status: The HTTP status, when the client got one other than ``200``.
+        location: The ``Location`` header of a redirect: where the product
+            may have moved.
+    """
+
+    def __init__(
+        self, message: str, *, status: int | None = None, location: str | None = None
+    ) -> None:
+        self.status = status
+        self.location = location
+        super().__init__(message)
+
+
+class ParseError(SwpcError):
+    """The format is the expected one, but a value is inconsistent.
+
+    The message names the offending field and where it is, when known.
+
+    The arguments are also attributes; ``reason`` is ``message``, without
+    the location.
+
+    Args:
+        message: What is wrong with the value.
+        field: Name of the offending field or column.
+        line: 1-based line number in a text product.
+        index: 0-based position of the offending record in a JSON array.
+
+    Raises:
+        ValueError: If ``line`` is not positive or ``index`` is negative.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        field: str | None = None,
+        line: int | None = None,
+        index: int | None = None,
+    ) -> None:
+        if line is not None and line < 1:
+            raise ValueError(f"line is 1-based, got {line}")
+        if index is not None and index < 0:
+            raise ValueError(f"index must not be negative, got {index}")
+        self.reason = message
+        self.field = field
+        self.line = line
+        self.index = index
+        where = []
+        if field is not None:
+            where.append(f"field {field!r}")
+        if line is not None:
+            where.append(f"line {line}")
+        if index is not None:
+            where.append(f"record {index}")
+        super().__init__(f"{message} ({', '.join(where)})" if where else message)
+
+
+class StaleData(SwpcError):
+    """The data is older than the maximum age the caller accepts.
+
+    Raised only by the client, and only when the caller passes ``max_age``.
+    The age is measured on the time the content declares, never on HTTP
+    metadata.
+
+    Args:
+        data_time: Most recent time declared by the content, in UTC.
+        max_age: Maximum age the caller accepts.
+        age: Age of the data when it was checked.
+
+    Raises:
+        ValueError: If ``data_time`` is not an aware datetime in UTC.
+    """
+
+    def __init__(
+        self, *, data_time: datetime, max_age: timedelta, age: timedelta
+    ) -> None:
+        if data_time.utcoffset() != timedelta(0):
+            raise ValueError(f"data_time must be in UTC, got {data_time!r}")
+        self.data_time = data_time
+        self.max_age = max_age
+        self.age = age
+        super().__init__(
+            f"data from {data_time.isoformat()} is {age} old, "
+            f"more than the allowed {max_age}"
+        )

swpc_kit/export/__init__.py

@@ -0,0 +1,12 @@
+"""Exports of the models: plain data, and the gridded products as maps.
+
+:func:`to_dict` and :func:`to_records` (plain data for JSON and for tables)
+and :func:`to_geojson` (OVATION, D-RAP) are re-exported here. GeoTIFF
+export lives in :mod:`swpc_kit.export.geotiff` (``write_geotiff``). All of
+them use only the standard library.
+"""
+
+from swpc_kit.export.data import to_dict, to_records
+from swpc_kit.export.geojson import to_geojson
+
+__all__ = ["to_dict", "to_geojson", "to_records"]

swpc_kit/export/_tiff.py

@@ -0,0 +1,64 @@
+"""The TIFF container behind :mod:`swpc_kit.export.geotiff`.
+
+:func:`encode` lays out a little-endian classic TIFF with one image: the
+header, one directory of tags, the tag values that do not fit in their
+entry, then the strips of pixel data. It knows nothing about GeoTIFF or
+GDAL: the caller chooses the tags and compresses the strips.
+"""
+
+import struct
+from collections.abc import Sequence
+
+__all__ = ["ASCII", "DOUBLE", "LONG", "SHORT", "STRIP_OFFSETS", "encode"]
+
+ASCII = 2
+SHORT = 3
+LONG = 4
+DOUBLE = 12
+
+STRIP_OFFSETS = 273
+"""The tag whose values :func:`encode` fills in: where each strip starts."""
+
+_FORMATS = {SHORT: "H", LONG: "I", DOUBLE: "d"}
+
+type Entry = tuple[int, int, Sequence[int] | Sequence[float] | str]
+"""A tag: its number, its TIFF type and its values (text for ``ASCII``)."""
+
+
+def _pack(kind: int, values: Sequence[int] | Sequence[float] | str) -> bytes:
+    if isinstance(values, str):
+        return values.encode("ascii") + b"\0"
+    return struct.pack(f"<{len(values)}{_FORMATS[kind]}", *values)
+
+
+def encode(entries: Sequence[Entry], strips: Sequence[bytes]) -> bytes:
+    """Return the bytes of a TIFF file with these tags and strips.
+
+    Args:
+        entries: The tags of the image, in any order. They must not include
+            :data:`STRIP_OFFSETS`, which is computed here.
+        strips: The pixel data, one compressed strip per item, top first.
+    """
+    placeholder: Entry = (STRIP_OFFSETS, LONG, [0] * len(strips))
+    tags = sorted([*entries, placeholder], key=lambda entry: entry[0])
+    directory_size = 2 + 12 * len(tags) + 4
+    # Tag values longer than four bytes go after the directory, each on an
+    # even offset; the strips follow them.
+    raws = [_pack(kind, values) for _, kind, values in tags]
+    spill = sum(len(raw) + len(raw) % 2 for raw in raws if len(raw) > 4)
+    start = 8 + directory_size + spill
+    offsets = [start + sum(map(len, strips[:i])) for i in range(len(strips))]
+
+    directory = bytearray(struct.pack("<H", len(tags)))
+    extra = bytearray()
+    for tag, kind, values in tags:
+        raw = _pack(kind, offsets if tag == STRIP_OFFSETS else values)
+        count = len(raw) if kind == ASCII else len(values)
+        if len(raw) <= 4:
+            directory += struct.pack("<HHI", tag, kind, count) + raw.ljust(4, b"\0")
+        else:
+            at = 8 + directory_size + len(extra)
+            directory += struct.pack("<HHII", tag, kind, count, at)
+            extra += raw + b"\0" * (len(raw) % 2)
+    directory += struct.pack("<I", 0)  # no next image
+    return b"II*\0" + struct.pack("<I", 8) + directory + extra + b"".join(strips)

swpc_kit/export/data.py

@@ -0,0 +1,167 @@
+"""Plain data from the models (standard library only).
+
+:func:`to_dict` turns any model into dicts, lists and plain values, ready
+for :func:`json.dumps`. :func:`to_records` turns a product into a list of
+flat rows, one per record, ready for :class:`csv.DictWriter` or for
+``pandas.DataFrame(...)``, without depending on pandas.
+
+Both give the fields of the models, nothing computed: ``data_time``,
+``flare_class`` and the other properties stay on the models.
+"""
+
+import types
+from collections.abc import Iterator, Mapping, Sequence
+from dataclasses import fields, is_dataclass
+from datetime import UTC, date, datetime
+from enum import Enum
+from functools import cache
+from typing import Any, Union, get_args, get_origin, get_type_hints
+
+from swpc_kit.models.alerts import Alerts
+from swpc_kit.models.bulletins import (
+    GeomagneticForecast,
+    ThreeDayForecast,
+    TwentySevenDayOutlook,
+)
+from swpc_kit.models.grids import Grid
+from swpc_kit.models.indices import NoaaScales
+
+__all__ = ["to_dict", "to_records"]
+
+# The products whose rows are not in ``values``.
+_ROWS: dict[type, str] = {
+    Alerts: "messages",
+    NoaaScales: "days",
+    TwentySevenDayOutlook: "days",
+    ThreeDayForecast: "kp",
+    GeomagneticForecast: "kp",
+}
+
+
+def _is_model(value: object) -> bool:
+    return is_dataclass(value) and not isinstance(value, type)
+
+
+def _iso(value: datetime) -> str:
+    return value.astimezone(UTC).isoformat().replace("+00:00", "Z")
+
+
+def _plain(value: Any) -> Any:
+    if _is_model(value):
+        return {f.name: _plain(getattr(value, f.name)) for f in fields(value)}
+    if isinstance(value, datetime):
+        return _iso(value)
+    if isinstance(value, date):
+        return value.isoformat()
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, Mapping):
+        return {str(key): _plain(item) for key, item in value.items()}
+    if isinstance(value, (tuple, list)):
+        return [_plain(item) for item in value]
+    return value
+
+
+def to_dict(model: object) -> dict[str, Any]:
+    """Return a model as plain data, ready for :func:`json.dumps`.
+
+    Every field of the model becomes a key, in the order of the fields;
+    nested models become dicts and tuples become lists. Times become ISO
+    8601 text in UTC with ``Z`` (``"2026-10-15T12:00:00Z"``), dates
+    ``"2026-10-15"``, and enum members their value.
+
+    Args:
+        model: Any model of :mod:`swpc_kit.models`: a product, a sample, a
+            grid, a ``SkippedRecord``.
+
+    Returns:
+        A dict of str, int, float, bool, ``None``, lists and dicts.
+
+    Raises:
+        TypeError: If ``model`` is not a model.
+    """
+    if not _is_model(model):
+        raise TypeError(f"to_dict takes a model, got {type(model).__name__}")
+    data: dict[str, Any] = _plain(model)
+    return data
+
+
+@cache
+def _nested(kind: type) -> dict[str, type]:
+    """The fields of ``kind`` that hold a model (or ``None``), by name."""
+    nested = {}
+    for name, hint in get_type_hints(kind).items():
+        if get_origin(hint) in (Union, types.UnionType):
+            options = [a for a in get_args(hint) if a is not type(None)]
+            hint = options[0] if len(options) == 1 else None
+        if isinstance(hint, type) and is_dataclass(hint):
+            nested[name] = hint
+    return nested
+
+
+def _flat(kind: type, value: object, prefix: str) -> Iterator[tuple[str, Any]]:
+    nested = _nested(kind)
+    for f in fields(kind):
+        item = None if value is None else getattr(value, f.name)
+        if f.name in nested:
+            yield from _flat(nested[f.name], item, f"{prefix}{f.name}_")
+        elif isinstance(item, Enum):
+            yield prefix + f.name, item.value
+        elif isinstance(item, (tuple, list)):
+            yield prefix + f.name, [_plain(element) for element in item]
+        else:
+            yield prefix + f.name, item
+
+
+def _rows(data: object) -> Sequence[Any]:
+    if _is_model(data):
+        rows = getattr(data, _ROWS.get(type(data), "values"), None)
+        if isinstance(rows, tuple):
+            return rows
+    elif isinstance(data, (tuple, list)) and all(_is_model(row) for row in data):
+        return data
+    raise TypeError(
+        "to_records takes a product, a grid or a sequence of records,"
+        f" got {type(data).__name__}"
+    )
+
+
+def to_records(data: object) -> list[dict[str, Any]]:
+    """Return the records of a product as flat rows.
+
+    One dict per record, with the same keys in the same order for every
+    row. Times stay aware UTC ``datetime`` objects (pandas reads them as
+    ``datetime64[ns, UTC]``), dates stay ``date``, enum members become
+    their value. A nested model is flattened with its field name as prefix
+    (``g_scale``, ``noaa_scale_level``), with ``None`` in each column when
+    it is absent. A field that holds a tuple, such as ``fields`` of an
+    alert, becomes a list.
+
+    The records of a product are its ``values``; for the alerts its
+    ``messages``; for the NOAA scales and the 27-day outlook its ``days``;
+    for the 3-day and geomagnetic forecasts the Kp periods (``kp``); for a
+    grid or a gridded product its cells, ``latitude``, ``longitude`` and
+    ``value``, with the longitudes as delivered.
+
+    Args:
+        data: A product, a grid, or a sequence of records of one kind (such
+            as ``wind.active_series()`` or ``kp.skipped``).
+
+    Returns:
+        A list of dicts, empty if there are no records.
+
+    Raises:
+        TypeError: If ``data`` is none of these, or mixes kinds of record.
+    """
+    grid = data if isinstance(data, Grid) else getattr(data, "grid", None)
+    if _is_model(data) and isinstance(grid, Grid):
+        return [
+            {"latitude": latitude, "longitude": longitude, "value": value}
+            for latitude, longitude, value in grid.cells()
+        ]
+    rows = _rows(data)
+    kinds = {type(row) for row in rows}
+    if len(kinds) > 1:
+        names = ", ".join(sorted(kind.__name__ for kind in kinds))
+        raise TypeError(f"to_records wants records of one kind, got {names}")
+    return [dict(_flat(type(row), row, "")) for row in rows]