pyModeS 3.5.0__tar.gz → 3.6.0__tar.gz

{pymodes-3.5.0 → pymodes-3.6.0}/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to pyModeS are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [3.6.0] — 2026-07-16
+
+### Added
+
+- `decode()`, `Message.decode()`, and `PipeDecoder` accept
+  `include_meteo=True` to opt into heuristic Comm-B BDS 4,4 routine
+  meteorological reports and BDS 4,5 meteorological hazard reports. The
+  default remains `False` because these payload patterns can overlap other
+  Comm-B registers.
+- The `modes decode`, `modes live`, and `scripts/stream_filtered.py` interfaces
+  expose the same behavior through `--include-meteo`.
+
 ## [3.5.0] — 2026-07-15
 
 ### Added

{pymodes-3.5.0 → pymodes-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyModeS
-Version: 3.5.0
+Version: 3.6.0
 Summary: Python Mode-S and ADS-B Decoder
 Project-URL: homepage, https://mode-s.org
 Project-URL: repository, https://github.com/junzis/pyModeS
@@ -199,6 +199,7 @@ the full command reference.
 - `full_dict=True` populates every key in the canonical 123-field
   schema for pandas / parquet workflows
 - `known=` aircraft state disambiguates Comm-B BDS 5,0/6,0 ambiguity
+- `include_meteo=True` opts into heuristic Comm-B BDS 4,4/4,5 inference
 - Airport ICAO database for surface CPR resolution (`surface_ref="EHAM"`)
 - Type-checked under mypy strict across all source files
 - Golden-file oracle regression test against `pyModeS 2.21.1`
@@ -228,6 +229,10 @@ the full command reference.
   - BDS 5,0: track and turn report
   - BDS 6,0: heading and speed report
 
+BDS 4,4 and 4,5 are heuristic and disabled by default. Enable them with
+`decode(..., include_meteo=True)` or `PipeDecoder(include_meteo=True)` when
+these meteorological registers are expected on the input feed.
+
 ## Migrating from pyModeS 2.x
 
 pyModeS 3 is **not backwards-compatible** with pyModeS 2.x. The

{pymodes-3.5.0 → pymodes-3.6.0}/README.md

@@ -172,6 +172,7 @@ the full command reference.
 - `full_dict=True` populates every key in the canonical 123-field
   schema for pandas / parquet workflows
 - `known=` aircraft state disambiguates Comm-B BDS 5,0/6,0 ambiguity
+- `include_meteo=True` opts into heuristic Comm-B BDS 4,4/4,5 inference
 - Airport ICAO database for surface CPR resolution (`surface_ref="EHAM"`)
 - Type-checked under mypy strict across all source files
 - Golden-file oracle regression test against `pyModeS 2.21.1`
@@ -201,6 +202,10 @@ the full command reference.
   - BDS 5,0: track and turn report
   - BDS 6,0: heading and speed report
 
+BDS 4,4 and 4,5 are heuristic and disabled by default. Enable them with
+`decode(..., include_meteo=True)` or `PipeDecoder(include_meteo=True)` when
+these meteorological registers are expected on the input feed.
+
 ## Migrating from pyModeS 2.x
 
 pyModeS 3 is **not backwards-compatible** with pyModeS 2.x. The

{pymodes-3.5.0 → pymodes-3.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyModeS"
-version = "3.5.0"
+version = "3.6.0"
 description = "Python Mode-S and ADS-B Decoder"
 authors = [{ name = "Junzi Sun", email = "git@junzis.com" }]
 license = { text = "GNU GPL v3" }

{pymodes-3.5.0 → pymodes-3.6.0}/scripts/README.md

@@ -13,16 +13,20 @@ through their names; generated benchmark reports live in
 
   ```bash
   uv run python scripts/stream_filtered.py \
-    --network airsquitter.lr.tudelft.nl:10006 > decoded.jsonl
+    --network airsquitter.lr.tudelft.nl:10006 \
+    --include-meteo > decoded.jsonl
   ```
 
+  `--include-meteo` is optional and enables heuristic Comm-B BDS 4,4/4,5
+  reports when the feed is expected to contain meteorological data.
+
 ## Benchmarks
 
-- `benchmark_mixed_traffic.py` — isolated v2.21.1, released v3.4.0, v3.5.0,
-  and prefiltered v3.5.0 comparison on mixed captured traffic. It measures
+- `benchmark_mixed_traffic.py` — isolated v2.21.1, released v3.5.0, v3.6.0,
+  and prefiltered v3.6.0 comparison on mixed captured traffic. It measures
   throughput, immediate streaming position yield, and coordinate agreement.
   By default it fails below 80% of v2 position yield, below 99% agreement
-  within 100 m, or when v3.5.0 yields fewer positions than v3.4.0. The two
+  within 100 m, or when v3.6.0 yields fewer positions than v3.5.0. The two
   percentage floors are configurable through command-line options. Writes
   `benchmark_results/mixed_traffic.md` by default.
 - `benchmark_pipe.py` — synthetic high-cardinality PipeDecoder comparison.

{pymodes-3.5.0 → pymodes-3.6.0}/src/pyModeS/__init__.py

@@ -21,6 +21,10 @@ For streaming workflows where references aren't known ahead of time,
 use :class:`PipeDecoder`. It establishes airborne positions from even/odd CPR
 pairs, then resolves later frames locally from the last validated airborne
 position. The optional ``surface_ref`` applies only to surface messages.
+
+Comm-B BDS 4,4/4,5 meteorological inference is heuristic and disabled by
+default. Pass ``include_meteo=True`` to :func:`decode` or
+:class:`PipeDecoder` when these reports are expected on the input feed.
 """
 
 from importlib.metadata import version as _version

{pymodes-3.5.0 → pymodes-3.6.0}/src/pyModeS/_pipe.py

@@ -104,6 +104,8 @@ class PipeDecoder(ValidationMixin):
         surface_ref: Optional surface-position CPR reference (ICAO airport
             code or (lat, lon) tuple). Used only for BDS 0,6 surface messages.
             See pyModeS.decode for details.
+        include_meteo: When True, Comm-B inference also considers the
+            heuristic BDS 4,4 and 4,5 meteorological registers. Default False.
         full_dict: When True, every decoded result is populated with
             every key from _FULL_SCHEMA.
         pair_window: Maximum age difference (seconds) between an even
@@ -129,6 +131,7 @@ class PipeDecoder(ValidationMixin):
         "_eviction_interval",
         "_eviction_ttl",
         "_full_dict",
+        "_include_meteo",
         "_local_ref_window",
         "_max_speed_kmps",
         "_motion_margin_km",
@@ -147,6 +150,7 @@ class PipeDecoder(ValidationMixin):
         self,
         *,
         surface_ref: str | tuple[float, float] | None = None,
+        include_meteo: bool = False,
         full_dict: bool = False,
         pair_window: float = 10.0,
         local_ref_window: float = 30.0,
@@ -156,6 +160,7 @@ class PipeDecoder(ValidationMixin):
         motion_margin_km: float = 2.0,
     ) -> None:
         self._surface_ref = surface_ref
+        self._include_meteo = include_meteo
         self._full_dict = full_dict
         self._pair_window = pair_window
         if local_ref_window < 0:
@@ -307,11 +312,22 @@ class PipeDecoder(ValidationMixin):
         else:
             known = None
 
-        result = message.decode(
-            surface_ref=self._surface_ref,
-            known=known,
-            full_dict=self._full_dict,
-        )
+        # Avoid forwarding a false opt-in flag on every message. Keyword
+        # dispatch is measurable in this hot path; only enabled streams need
+        # the additional Comm-B inference branch.
+        if self._include_meteo:
+            result = message.decode(
+                surface_ref=self._surface_ref,
+                known=known,
+                include_meteo=True,
+                full_dict=self._full_dict,
+            )
+        else:
+            result = message.decode(
+                surface_ref=self._surface_ref,
+                known=known,
+                full_dict=self._full_dict,
+            )
 
         self._stats["decoded"] += 1
         if result.get("crc_valid") is False:

{pymodes-3.5.0 → pymodes-3.6.0}/src/pyModeS/cli/_args.py

@@ -76,6 +76,11 @@ def _add_decode_parser(
         action="store_true",
         help="Populate every key in the canonical schema (missing = null).",
     )
+    decode_p.add_argument(
+        "--include-meteo",
+        action="store_true",
+        help="Include heuristic Comm-B BDS 4,4/4,5 meteorological inference.",
+    )
     decode_p.add_argument(
         "--reference",
         nargs=2,
@@ -132,6 +137,11 @@ def _add_live_parser(
         action="store_true",
         help="Emit every key in the canonical schema (missing = null).",
     )
+    live_p.add_argument(
+        "--include-meteo",
+        action="store_true",
+        help="Include heuristic Comm-B BDS 4,4/4,5 meteorological inference.",
+    )
     live_p.add_argument(
         "--dump-to",
         metavar="FILE",

{pymodes-3.5.0 → pymodes-3.6.0}/src/pyModeS/cli/decode.py

@@ -50,6 +50,7 @@ def _run_single(args: argparse.Namespace) -> int:
             args.message,
             reference=reference,
             surface_ref=surface_ref,
+            include_meteo=args.include_meteo,
             full_dict=args.full_dict,
         )
     except Exception as e:
@@ -131,6 +132,7 @@ def _emit_batch(
             hexes,
             timestamps=timestamps,
             surface_ref=surface_ref,
+            include_meteo=args.include_meteo,
             full_dict=args.full_dict,
         )
     except Exception as error:

{pymodes-3.5.0 → pymodes-3.6.0}/src/pyModeS/cli/live.py

@@ -55,7 +55,11 @@ def run(args: argparse.Namespace) -> int:
         )
         return 2
 
-    pipe = PipeDecoder(surface_ref=surface_ref, full_dict=args.full_dict)
+    pipe = PipeDecoder(
+        surface_ref=surface_ref,
+        include_meteo=args.include_meteo,
+        full_dict=args.full_dict,
+    )
 
     # TUI path takes its own branch — textual owns the event loop
     # and drives the source + pipe itself, so the sink pipeline

{pymodes-3.5.0 → pymodes-3.6.0}/src/pyModeS/core.py

@@ -25,6 +25,7 @@ def decode(
     reference: tuple[float, float] | None = None,
     surface_ref: str | tuple[float, float] | None = None,
     known: dict[str, Any] | None = None,
+    include_meteo: bool = False,
     full_dict: bool = False,
 ) -> Decoded: ...
 
@@ -35,6 +36,7 @@ def decode(
     *,
     timestamps: list[float] | None = None,
     surface_ref: str | tuple[float, float] | None = None,
+    include_meteo: bool = False,
     full_dict: bool = False,
 ) -> list[Decoded]: ...
 
@@ -48,6 +50,7 @@ def decode(
     reference: Any = None,
     surface_ref: Any = None,
     known: Any = None,
+    include_meteo: bool = False,
     full_dict: bool = False,
     timestamps: Any = None,
 ) -> Any:
@@ -79,6 +82,9 @@ def decode(
             Comm-B BDS inference to disambiguate BDS 5,0 vs 6,0
             when both heuristic validators pass. Ignored for
             non-Comm-B downlink formats.
+        include_meteo: When True, Comm-B inference also considers BDS 4,4
+            and 4,5 meteorological registers. Disabled by default because
+            their heuristic payload patterns can overlap other registers.
         full_dict: When True, the result dict is augmented with
             every key from `_FULL_SCHEMA`, defaulting missing keys
             to `None`. Useful for pandas/parquet workflows that
@@ -102,6 +108,7 @@ def decode(
             WARNING is logged — pair matching will still function
             but the synthesized values are not wall-clock times.
         surface_ref: Same as single-message mode.
+        include_meteo: Same as single-message mode.
         full_dict: Same as single-message mode.
 
     Batch mode returns a ``list[Decoded]`` of the same length as
@@ -140,6 +147,7 @@ def decode(
             msg,
             timestamps=timestamps,
             surface_ref=surface_ref,
+            include_meteo=include_meteo,
             full_dict=full_dict,
         )
 
@@ -164,6 +172,7 @@ def decode(
         reference=reference,
         surface_ref=surface_ref,
         known=known,
+        include_meteo=include_meteo,
         full_dict=full_dict,
     )
 
@@ -173,6 +182,7 @@ def _decode_batch(
     *,
     timestamps: list[float] | None,
     surface_ref: str | tuple[float, float] | None,
+    include_meteo: bool,
     full_dict: bool,
 ) -> list[Decoded]:
     """Run ``msgs`` through a transient PipeDecoder and return results."""
@@ -193,7 +203,11 @@ def _decode_batch(
             f"messages length {len(msgs)}"
         )
 
-    pipe = PipeDecoder(surface_ref=surface_ref, full_dict=full_dict)
+    pipe = PipeDecoder(
+        surface_ref=surface_ref,
+        include_meteo=include_meteo,
+        full_dict=full_dict,
+    )
     results = [
         pipe.decode(m, timestamp=t) for m, t in zip(msgs, timestamps, strict=True)
     ]

{pymodes-3.5.0 → pymodes-3.6.0}/src/pyModeS/decoder/commb.py

@@ -59,7 +59,12 @@ _COMMB_DISPATCH: dict[str, Callable[[int], dict[str, Any]]] = {
 class CommB(DecoderBase):
     """Decoder for DF20 Comm-B altitude replies and DF21 Comm-B identity replies."""
 
-    def decode(self, *, known: dict[str, Any] | None = None) -> Decoded:
+    def decode(
+        self,
+        *,
+        known: dict[str, Any] | None = None,
+        include_meteo: bool = False,
+    ) -> Decoded:
         result: Decoded = Decoded()
 
         # Header field: altitude for DF20, squawk for DF21.
@@ -75,7 +80,7 @@ class CommB(DecoderBase):
         # disambiguation of BDS 5,0 / 6,0 when the caller supplies
         # aircraft state.
         candidates = _infer.infer(
-            self._payload, self._df, include_meteo=False, known=known
+            self._payload, self._df, include_meteo=include_meteo, known=known
         )
         if not candidates:
             return result

{pymodes-3.5.0 → pymodes-3.6.0}/src/pyModeS/message.py

@@ -17,11 +17,14 @@ This module defines two public types:
 
 import json
 from functools import cached_property
-from typing import Any, Self
+from typing import TYPE_CHECKING, Any, Self, cast
 
 from pyModeS._bits import crc_remainder, extract_unsigned
 from pyModeS.errors import InvalidHexError, InvalidLengthError, UnknownDFError
 
+if TYPE_CHECKING:
+    from pyModeS.decoder.commb import CommB
+
 _HEX_CHARS = frozenset("0123456789abcdefABCDEF")
 _VALID_LENGTHS = (56, 112)
 _HEX_LENGTHS = (14, 28)
@@ -242,6 +245,7 @@ class Message:
         reference: tuple[float, float] | None = None,
         surface_ref: str | tuple[float, float] | None = None,
         known: dict[str, Any] | None = None,
+        include_meteo: bool = False,
         full_dict: bool = False,
     ) -> Decoded:
         """Decode every field of this message.
@@ -270,6 +274,10 @@ class Message:
                 Comm-B BDS inference to disambiguate BDS 5,0 vs 6,0
                 when both heuristic validators pass. Ignored for
                 non-Comm-B downlink formats.
+            include_meteo: When True, Comm-B inference also considers the
+                heuristic BDS 4,4 and 4,5 meteorological registers. Disabled
+                by default because their payloads can overlap other Comm-B
+                formats.
             full_dict: When True, the result dict is augmented with
                 every key from `_FULL_SCHEMA`, defaulting missing
                 keys to `None`. Useful for pandas/parquet workflows
@@ -291,7 +299,14 @@ class Message:
             decoder = decoder_cls(
                 self._n, df=self.df, icao=self.icao, length=self._length
             )
-            result.update(decoder.decode(known=known))
+            # Keep the common non-meteorological path free of an extra keyword
+            # dispatch. This matters for high-rate ADS-B streams, while the
+            # opt-in branch is relevant only to DF20/21 Comm-B decoders.
+            if include_meteo and self.df in (20, 21):
+                commb_decoder = cast("CommB", decoder)
+                result.update(commb_decoder.decode(known=known, include_meteo=True))
+            else:
+                result.update(decoder.decode(known=known))
 
         self._resolve_position(result, reference=reference, surface_ref=surface_ref)