wwvb 4.1.0a0__py3-none-any.whl → 5.0.0__py3-none-any.whl

{leapseconddata → wwvb}/__version__.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '4.1.0a0'
-__version_tuple__ = version_tuple = (4, 1, 0)
+__version__ = version = '5.0.0'
+__version_tuple__ = version_tuple = (5, 0, 0)

wwvb/decode.py

@@ -0,0 +1,93 @@
+# SPDX-FileCopyrightText: 2021 Jeff Epler
+#
+# SPDX-License-Identifier: GPL-3.0-only
+"""A stateful decoder of WWVB signals"""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+import wwvb
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+# State 1: Unsync'd
+#  Marker: State 2
+#  Other: State 1
+# State 2: One marker
+#  Marker: State 3
+#  Other: State 1
+# State 3: Two markers
+#  Marker: State 3
+#  Other: State 4
+# State 4: Decoding a minute, starting in second 1
+#  Second
+
+always_zero = {4, 10, 11, 14, 20, 21, 34, 35, 44, 54}
+
+
+def wwvbreceive() -> Generator[wwvb.WWVBTimecode | None, wwvb.AmplitudeModulation, None]:
+    """Decode WWVB signals statefully."""
+    minute: list[wwvb.AmplitudeModulation] = []
+    state = 1
+
+    value = yield None
+    while True:
+        # print(state, value, len(minute), "".join(str(int(i)) for i in minute))
+        if state == 1:
+            minute = []
+            if value == wwvb.AmplitudeModulation.MARK:
+                state = 2
+            value = yield None
+
+        elif state == 2:
+            state = 3 if value == wwvb.AmplitudeModulation.MARK else 1
+            value = yield None
+
+        elif state == 3:
+            if value != wwvb.AmplitudeModulation.MARK:
+                state = 4
+                minute = [wwvb.AmplitudeModulation.MARK, value]
+            value = yield None
+
+        else:  #  state == 4:
+            minute.append(value)
+            if len(minute) % 10 == 0 and value != wwvb.AmplitudeModulation.MARK:
+                # print("MISSING MARK", len(minute), "".join(str(int(i)) for i in minute))
+                state = 1
+            elif len(minute) % 10 and value == wwvb.AmplitudeModulation.MARK:
+                # print("UNEXPECTED MARK")
+                state = 1
+            elif len(minute) - 1 in always_zero and value != wwvb.AmplitudeModulation.ZERO:
+                # print("UNEXPECTED NONZERO")
+                state = 1
+            elif len(minute) == 60:
+                # print("FULL MINUTE")
+                tc = wwvb.WWVBTimecode(60)
+                tc.am[:] = minute
+                minute = []
+                state = 2
+                value = yield tc
+            else:
+                value = yield None
+
+
+def main() -> None:
+    """Read symbols on stdin and print any successfully-decoded minutes"""
+    decoder = wwvbreceive()
+    next(decoder)
+    decoder.send(wwvb.AmplitudeModulation.MARK)
+    for s in sys.argv[1:]:
+        for c in s:
+            decoded = decoder.send(wwvb.AmplitudeModulation(int(c)))
+            if decoded:
+                print(decoded)
+                w = wwvb.WWVBMinute.from_timecode_am(decoded)
+                if w:
+                    print(w)
+
+
+if __name__ == "__main__":
+    main()

wwvb/dut1table.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+
+# SPDX-FileCopyrightText: 2021-2024 Jeff Epler
+#
+# SPDX-License-Identifier: GPL-3.0-only
+
+"""Print the table of historical DUT1 values"""
+
+from datetime import timedelta
+from itertools import groupby
+
+import wwvb
+
+from .iersdata import DUT1_DATA_START, DUT1_OFFSETS
+
+
+def main() -> None:
+    """Print the table of historical DUT1 values"""
+    date = DUT1_DATA_START
+    for key, it in groupby(DUT1_OFFSETS):
+        dut1_ms = (ord(key) - ord("k")) / 10.0
+        count = len(list(it))
+        end = date + timedelta(days=count - 1)
+        dut1_next = wwvb.get_dut1(date + timedelta(days=count), warn_outdated=False)
+        ls = f" LS on {end:%F} 23:59:60 UTC" if dut1_ms * dut1_next < 0 else ""
+        print(f"{date:%F} {dut1_ms: 3.1f} {count:4d}{ls}")
+        date += timedelta(days=count)
+    print(date)
+
+
+if __name__ == "__main__":
+    main()

wwvb/gen.py

@@ -0,0 +1,127 @@
+#!/usr/bin/python3
+"""A command-line program for generating wwvb timecodes"""
+
+# SPDX-FileCopyrightText: 2011-2024 Jeff Epler
+#
+# SPDX-License-Identifier: GPL-3.0-only
+
+from __future__ import annotations
+
+import datetime
+import sys
+from typing import Any
+
+import click
+import dateutil.parser
+
+from . import WWVBMinute, WWVBMinuteIERS, print_timecodes, print_timecodes_json, styles
+
+
+def parse_timespec(ctx: Any, param: Any, value: list[str]) -> datetime.datetime:  # noqa: ARG001
+    """Parse a time specifier from the commandline"""
+    try:
+        if len(value) == 5:
+            year, month, day, hour, minute = map(int, value)
+            return datetime.datetime(year, month, day, hour, minute, tzinfo=datetime.timezone.utc)
+        if len(value) == 4:
+            year, yday, hour, minute = map(int, value)
+            return datetime.datetime(year, 1, 1, hour, minute, tzinfo=datetime.timezone.utc) + datetime.timedelta(
+                days=yday - 1,
+            )
+        if len(value) == 1:
+            return dateutil.parser.parse(value[0])
+        if len(value) == 0:
+            return datetime.datetime.now(datetime.timezone.utc)
+        raise ValueError("Unexpected number of arguments")
+    except ValueError as e:
+        raise click.UsageError(f"Could not parse timespec: {e}") from e
+
+
+@click.command()
+@click.option(
+    "--iers/--no-iers",
+    "-i/-I",
+    default=True,
+    help="Whether to use IESR data for DUT1 and LS.  (Default: --iers)",
+)
+@click.option(
+    "--leap-second",
+    "-s",
+    "leap_second",
+    flag_value=1,
+    default=None,
+    help="Force a positive leap second at the end of the GMT month (Implies --no-iers)",
+)
+@click.option(
+    "--negative-leap-second",
+    "-n",
+    "leap_second",
+    flag_value=-1,
+    help="Force a negative leap second at the end of the GMT month (Implies --no-iers)",
+)
+@click.option(
+    "--no-leap-second",
+    "-S",
+    "leap_second",
+    flag_value=0,
+    help="Force no leap second at the end of the month (Implies --no-iers)",
+)
+@click.option("--dut1", "-d", type=int, help="Force the DUT1 value (Implies --no-iers)")
+@click.option("--minutes", "-m", default=10, help="Number of minutes to show (default: 10)")
+@click.option(
+    "--style",
+    default="default",
+    type=click.Choice(sorted(["json", *list(styles.keys())])),
+    help="Style of output",
+)
+@click.option(
+    "--all-timecodes/--no-all-timecodes",
+    "-t/-T",
+    default=False,
+    type=bool,
+    help="Show the 'WWVB timecode' line before each minute",
+)
+@click.option(
+    "--channel",
+    type=click.Choice(["amplitude", "phase", "both"]),
+    default="amplitude",
+    help="Modulation to show (default: amplitude)",
+)
+@click.argument("timespec", type=str, nargs=-1, callback=parse_timespec)
+def main(
+    *,
+    iers: bool,
+    leap_second: bool,
+    dut1: int,
+    minutes: int,
+    style: str,
+    channel: str,
+    all_timecodes: bool,
+    timespec: datetime.datetime,
+) -> None:
+    """Generate WWVB timecodes
+
+    TIMESPEC: one of "year yday hour minute" or "year month day hour minute", or else the current minute
+    """
+    if (leap_second is not None) or (dut1 is not None):
+        iers = False
+
+    newut1 = None
+    newls = None
+
+    if iers:
+        constructor: type[WWVBMinute] = WWVBMinuteIERS
+    else:
+        constructor = WWVBMinute
+        newut1 = -500 * (leap_second or 0) if dut1 is None else dut1
+        newls = bool(leap_second)
+
+    w = constructor.from_datetime(timespec, newls=newls, newut1=newut1)
+    if style == "json":
+        print_timecodes_json(w, minutes, channel, file=sys.stdout)
+    else:
+        print_timecodes(w, minutes, channel, style, all_timecodes=all_timecodes, file=sys.stdout)
+
+
+if __name__ == "__main__":
+    main()

wwvb/iersdata.json

@@ -0,0 +1 @@
+{"START": "1972-01-01", "OFFSETS_GZ": "H4sIAFEb/WYC/+2aa3LDMAiEL5uHLDuxnN5/pn/aTmfSSiAWhGR9J8gsywJylqVHPtqxZuH/7leeI0fKsGd5EngQ2WisJWKegrThDa6aJFnL0u4wYZkCE2UmSF0U+13vCveStC6JTfQyW3O86HLJf0SvDgy5u4FCI+WVKRuy0KMjJeXoULIvMDmEWgeRxAJtwXquPCIBqbLh/gbfv0mcxk3mHV9tYiATZP8W/zgw2wd5LpJnY+WErI8abJ3opaIW6592+YMbjSsNWQFlNVVtuhjhtQzSUh4MEpOdDrSW6qsUv+O+Dt+XkIONSrUwvWmTsmq5LO9xsZ+EgcDK+MIESDaYmxSxGlgbGOFjBXMjbV7lc6zlmQ0i48oH5P4+vK7i/AHc7tfTXDtffqFi3m6WhApPSTyDvArU5vUDhm7YaNQYGASVbbwLUBtI2PrhSiZNbvCRrtGUGu0GbjDhJ3aLCx5dQFjt0LFovmWB96e6tktqMenoULXajVS3asBibP3kYXrpmZxnsS2Yf2xRPrHbvQ2D9wjfL4C6b4PWV4otW0vWUYkeWE5M8M594oLbxP77xcl4NuBkG0dfM3xOUf/T0GF+ur+J5pljcODEUZkXg6vIdLYy7g3oZU3bPNDnc8qwGdJZMmAurUsRj6tOo95zP6fb9YPWp5OuZ5X7q2DrmsG/VCyTyaREnDRhnUxOjcmKM9b/R7R0+gQ5cs/LtEwAAA=="}

wwvb/iersdata.json.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: Public domain
+SPDX-License-Identifier: CC0-1.0

wwvb/iersdata.py

@@ -0,0 +1,37 @@
+# -*- python3 -*-
+"""Retrieve iers data, possibly from user or site data or from the wwvbpy distribution"""
+
+# SPDX-FileCopyrightText: 2011-2024 Jeff Epler
+#
+# SPDX-License-Identifier: GPL-3.0-only
+
+import binascii
+import datetime
+import gzip
+import importlib.resources
+import json
+
+import platformdirs
+
+__all__ = ["DUT1_DATA_START", "DUT1_OFFSETS", "start", "span", "end"]
+
+content: dict[str, str] = {"START": "1970-01-01", "OFFSETS_GZ": "H4sIAFNx1mYC/wMAAAAAAAAAAAA="}
+
+path = importlib.resources.files("wwvb") / "iersdata.json"
+content = json.loads(path.read_text(encoding="utf-8"))
+
+for location in [  # pragma no cover
+    platformdirs.user_data_path("wwvbpy", "unpythonic.net"),
+    platformdirs.site_data_path("wwvbpy", "unpythonic.net"),
+]:
+    path = location / "iersdata.json"
+    if path.exists():
+        content = json.loads(path.read_text(encoding="utf-8"))
+        break
+
+DUT1_DATA_START = datetime.date.fromisoformat(content["START"])
+DUT1_OFFSETS = gzip.decompress(binascii.a2b_base64(content["OFFSETS_GZ"])).decode("ascii")
+
+start = datetime.datetime.combine(DUT1_DATA_START, datetime.time(), tzinfo=datetime.timezone.utc)
+span = datetime.timedelta(days=len(DUT1_OFFSETS))
+end = start + span

wwvb/tz.py

@@ -0,0 +1,12 @@
+# -*- python -*-
+"""A library for WWVB timecodes"""
+
+# SPDX-FileCopyrightText: 2021-2024 Jeff Epler
+#
+# SPDX-License-Identifier: GPL-3.0-only
+
+from zoneinfo import ZoneInfo
+
+Mountain = ZoneInfo("America/Denver")
+
+__all__ = ["Mountain", "ZoneInfo"]

wwvb/updateiers.py

@@ -0,0 +1,161 @@
+#!/usr/bin/python3
+
+# SPDX-FileCopyrightText: 2021-2024 Jeff Epler
+#
+# SPDX-License-Identifier: GPL-3.0-only
+
+"""Update the DUT1 and LS data based on online sources"""
+
+from __future__ import annotations
+
+import binascii
+import csv
+import datetime
+import gzip
+import io
+import json
+import pathlib
+from typing import Callable
+
+import bs4
+import click
+import platformdirs
+import requests
+
+DIST_PATH = pathlib.Path(__file__).parent / "iersdata.json"
+
+IERS_URL = "https://datacenter.iers.org/data/csv/finals2000A.all.csv"
+IERS_PATH = pathlib.Path("finals2000A.all.csv")
+if IERS_PATH.exists():
+    IERS_URL = str(IERS_PATH)
+    print("using local", IERS_URL)
+NIST_URL = "https://www.nist.gov/pml/time-and-frequency-division/atomic-standards/leap-second-and-ut1-utc-information"
+
+
+def _get_text(url: str) -> str:
+    """Get a local file or a http/https URL"""
+    if url.startswith("http"):
+        with requests.get(url, timeout=30) as response:
+            return response.text
+    else:
+        return pathlib.Path(url).read_text(encoding="utf-8")
+
+
+def update_iersdata(  # noqa: PLR0915
+    target_path: pathlib.Path,
+) -> None:
+    """Update iersdata.py"""
+    offsets: list[int] = []
+    iersdata_text = _get_text(IERS_URL)
+    for r in csv.DictReader(io.StringIO(iersdata_text), delimiter=";"):
+        jd = float(r["MJD"])
+        offs_str = r["UT1-UTC"]
+        if not offs_str:
+            break
+        offs = int(round(float(offs_str) * 10))
+        if not offsets:
+            table_start = datetime.date(1858, 11, 17) + datetime.timedelta(jd)
+
+            when = min(datetime.date(1972, 1, 1), table_start)
+            # iers bulletin A doesn't cover 1972, so fake data for those
+            # leap seconds
+            while when < datetime.date(1972, 7, 1):
+                offsets.append(-2)
+                when = when + datetime.timedelta(days=1)
+            while when < datetime.date(1972, 11, 1):
+                offsets.append(8)
+                when = when + datetime.timedelta(days=1)
+            while when < datetime.date(1972, 12, 1):
+                offsets.append(0)
+                when = when + datetime.timedelta(days=1)
+            while when < datetime.date(1973, 1, 1):
+                offsets.append(-2)
+                when = when + datetime.timedelta(days=1)
+            while when < table_start:
+                offsets.append(8)
+                when = when + datetime.timedelta(days=1)
+
+            table_start = min(datetime.date(1972, 1, 1), table_start)
+
+        offsets.append(offs)
+
+    wwvb_text = _get_text(NIST_URL)
+    wwvb_data = bs4.BeautifulSoup(wwvb_text, features="html.parser")
+    wwvb_dut1_table = wwvb_data.findAll("table")[2]
+    assert wwvb_dut1_table
+    meta = wwvb_data.find("meta", property="article:modified_time")
+    assert isinstance(meta, bs4.Tag)
+    wwvb_data_stamp = datetime.datetime.fromisoformat(meta.attrs["content"]).replace(tzinfo=None).date()
+
+    def patch(patch_start: datetime.date, patch_end: datetime.date, val: int) -> None:
+        off_start = (patch_start - table_start).days
+        off_end = (patch_end - table_start).days
+        offsets[off_start:off_end] = [val] * (off_end - off_start)
+
+    wwvb_dut1: int | None = None
+    wwvb_start: datetime.date | None = None
+    for row in wwvb_dut1_table.findAll("tr")[1:][::-1]:
+        cells = row.findAll("td")
+        when = datetime.datetime.strptime(cells[0].text + "+0000", "%Y-%m-%d%z").date()
+        dut1 = cells[2].text.replace("s", "").replace(" ", "")
+        dut1 = int(round(float(dut1) * 10))
+        if wwvb_dut1 is not None:
+            assert wwvb_start is not None
+            patch(wwvb_start, when, wwvb_dut1)
+        wwvb_dut1 = dut1
+        wwvb_start = when
+
+    # As of 2021-06-14, NIST website incorrectly indicates the offset of -600ms
+    # persisted through 2009-03-12, causing an incorrect leap second inference.
+    # Assume instead that NIST started broadcasting +400ms on January 1, 2009,
+    # causing the leap second to occur on 2008-12-31.
+    patch(datetime.date(2009, 1, 1), datetime.date(2009, 3, 12), 4)
+
+    # this is the final (most recent) wwvb DUT1 value broadcast.  We want to
+    # extend it some distance into the future, but how far?  We will use the
+    # modified timestamp of the NIST data.
+    assert wwvb_dut1 is not None
+    assert wwvb_start is not None
+    patch(wwvb_start, wwvb_data_stamp + datetime.timedelta(days=1), wwvb_dut1)
+
+    table_end = table_start + datetime.timedelta(len(offsets) - 1)
+    base = ord("a") + 10
+    offsets_bin = bytes(base + ch for ch in offsets)
+
+    target_path.write_text(
+        json.dumps(
+            {
+                "START": table_start.isoformat(),
+                "OFFSETS_GZ": binascii.b2a_base64(gzip.compress(offsets_bin)).decode("ascii").strip(),
+            },
+        ),
+    )
+
+    print(f"iersdata covers {table_start} .. {table_end}")
+
+
+def iersdata_path(callback: Callable[[str, str], pathlib.Path]) -> pathlib.Path:
+    """Find out the path for this directory"""
+    return callback("wwvbpy", "unpythonic.net") / "iersdata.json"
+
+
+@click.command()
+@click.option(
+    "--user",
+    "location",
+    flag_value=iersdata_path(platformdirs.user_data_path),
+    default=iersdata_path(platformdirs.user_data_path),
+    type=pathlib.Path,
+)
+@click.option("--dist", "location", flag_value=DIST_PATH)
+@click.option("--site", "location", flag_value=iersdata_path(platformdirs.site_data_path))
+def main(location: str) -> None:
+    """Update DUT1 data"""
+    path = pathlib.Path(location)
+    print(f"will write to {location!r}")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    update_iersdata(path)
+
+
+if __name__ == "__main__":
+    main()

wwvb/wwvbtk.py

@@ -0,0 +1,146 @@
+#!/usr/bin/python3
+"""Visualize the WWVB signal in realtime"""
+
+# SPDX-FileCopyrightText: 2021-2024 Jeff Epler
+#
+# SPDX-License-Identifier: GPL-3.0-only
+from __future__ import annotations
+
+import functools
+import threading
+import time
+from tkinter import Canvas, TclError, Tk
+from typing import TYPE_CHECKING, Any
+
+import click
+
+import wwvb
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+
+@functools.cache
+def _app() -> Tk:
+    """Create the Tk application object lazily"""
+    return Tk()
+
+
+def validate_colors(ctx: Any, param: Any, value: str) -> list[str]:  # noqa: ARG001
+    """Check that all colors in a string are valid, splitting it to a list"""
+    app = _app()
+    colors = value.split()
+    if len(colors) not in (2, 3, 4, 6):
+        raise click.BadParameter(f"Give 2, 3, 4 or 6 colors (not {len(colors)}")
+    for c in colors:
+        try:
+            app.winfo_rgb(c)
+        except TclError as e:
+            raise click.BadParameter(f"Invalid color {c}") from e
+
+    if len(colors) == 2:
+        off, on = colors
+        return [off, off, off, on, on, on]
+    if len(colors) == 3:
+        return colors + colors
+    if len(colors) == 4:
+        off, c1, c2, c3 = colors
+        return [off, off, off, c1, c2, c3]
+    return colors
+
+
+DEFAULT_COLORS = "#3c3c3c #3c3c3c #3c3c3c #cc3c3c #88883c #3ccc3c"
+
+
+@click.command
+@click.option("--colors", callback=validate_colors, default=DEFAULT_COLORS)
+@click.option("--size", default=48)
+@click.option("--min-size", default=None)
+def main(colors: list[str], size: int, min_size: int | None) -> None:  # noqa: PLR0915
+    """Visualize the WWVB signal in realtime"""
+    if min_size is None:
+        min_size = size
+
+    def sleep_deadline(deadline: float) -> None:
+        """Sleep until a deadline"""
+        now = time.time()
+        if deadline > now:
+            time.sleep(deadline - now)
+
+    def wwvbtick() -> Generator[tuple[float, wwvb.AmplitudeModulation], None, None]:
+        """Yield consecutive values of the WWVB amplitude signal, going from minute to minute"""
+        timestamp = time.time() // 60 * 60
+
+        while True:
+            tt = time.gmtime(timestamp)
+            key = tt.tm_year, tt.tm_yday, tt.tm_hour, tt.tm_min
+            timecode = wwvb.WWVBMinuteIERS(*key).as_timecode()
+            for i, code in enumerate(timecode.am):
+                yield timestamp + i, code
+            timestamp = timestamp + 60
+
+    def wwvbsmarttick() -> Generator[tuple[float, wwvb.AmplitudeModulation], None, None]:
+        """Yield consecutive values of the WWVB amplitude signal
+
+        .. but deal with time progressing unexpectedly, such as when the
+        computer is suspended or NTP steps the clock backwards
+
+        When time goes backwards or advances by more than a minute, get a fresh
+        wwvbtick object; otherwise, discard time signals more than 1s in the past.
+        """
+        while True:
+            for stamp, code in wwvbtick():
+                now = time.time()
+                if stamp < now - 60:
+                    break
+                if stamp < now - 1:
+                    continue
+                yield stamp, code
+
+    app = _app()
+    app.wm_minsize(min_size, min_size)
+    canvas = Canvas(app, width=size, height=size, highlightthickness=0)
+    circle = canvas.create_oval(4, 4, 44, 44, outline="black", fill=colors[0])
+    canvas.pack(fill="both", expand=True)
+    app.wm_deiconify()
+
+    def resize_canvas(event: Any) -> None:
+        """Keep the circle filling the window when it is resized"""
+        sz = min(event.width, event.height) - 8
+        if sz < 0:
+            return
+        canvas.coords(
+            circle,
+            event.width // 2 - sz // 2,
+            event.height // 2 - sz // 2,
+            event.width // 2 + sz // 2,
+            event.height // 2 + sz // 2,
+        )
+
+    canvas.bind("<Configure>", resize_canvas)
+
+    def led_on(i: int) -> None:
+        """Turn the canvas's virtual LED on"""
+        canvas.itemconfigure(circle, fill=colors[i + 3])
+
+    def led_off(i: int) -> None:
+        """Turn the canvas's virtual LED off"""
+        canvas.itemconfigure(circle, fill=colors[i])
+
+    def thread_func() -> None:
+        """Update the canvas virtual LED"""
+        for stamp, code in wwvbsmarttick():
+            sleep_deadline(stamp)
+            led_on(code)
+            app.update()
+            sleep_deadline(stamp + 0.2 + 0.3 * int(code))
+            led_off(code)
+            app.update()
+
+    thread = threading.Thread(target=thread_func, daemon=True)
+    thread.start()
+    app.mainloop()
+
+
+if __name__ == "__main__":
+    main()