wwvb 3.0.8__py3-none-any.whl → 4.0.0__py3-none-any.whl

wwvb/__init__.py

@@ -6,25 +6,24 @@
 #
 # SPDX-License-Identifier: GPL-3.0-only
 
-import collections
+from __future__ import annotations
+
 import datetime
 import enum
 import json
 import warnings
-from typing import Dict, Generator, List, Optional, TextIO, Tuple, TypeVar, Union
+from typing import Any, Generator, NamedTuple, TextIO, TypeVar
 
 from . import iersdata
 from .tz import Mountain
 
 HOUR = datetime.timedelta(seconds=3600)
 SECOND = datetime.timedelta(seconds=1)
-DateOrDatetime = TypeVar("DateOrDatetime", datetime.date, datetime.datetime)
 T = TypeVar("T")
 
 
-def require(x: Optional[T]) -> T:
-    """Assert that an Optional value is not None, and then return the value,
-    giving a hint to the type system."""
+def _require(x: T | None) -> T:
+    """Check an Optional item is not None."""
     assert x is not None
     return x
 
@@ -35,24 +34,28 @@ def _removeprefix(s: str, p: str) -> str:
     return s
 
 
-def _date(dt: DateOrDatetime) -> datetime.date:
+def _date(dt: datetime.date) -> datetime.date:
     """Return the date object itself, or the date property of a datetime"""
     if isinstance(dt, datetime.datetime):
         return dt.date()
     return dt
 
 
-def _maybe_warn_update(dt: datetime.date) -> None:
+def _maybe_warn_update(dt: datetime.date, stacklevel: int = 1) -> None:
     """Maybe print a notice to run updateiers, if it seems useful to do so."""
     # We already know this date is not covered.
-    # If the date is less than 330 days after today, there should be (possibly)
+    # If the date is less than 300 days after today, there should be (possibly)
     # prospective available now.
-    today = datetime.date.today()
+    today = datetime.datetime.now(tz=datetime.timezone.utc).date()
+    print(f"_mwu {today=!r} {dt=!r} {iersdata.end=!r}")
     if _date(dt) < today + datetime.timedelta(days=330):
-        warnings.warn("Note: Running `updateiers` may provide better DUT1 and LS information")
+        warnings.warn(
+            "Note: Running `updateiers` may provide better DUT1 and LS information",
+            stacklevel=stacklevel + 1,
+        )
 
 
-def get_dut1(dt: DateOrDatetime, *, warn_outdated: bool = True) -> float:
+def get_dut1(dt: datetime.date, *, warn_outdated: bool = True) -> float:
     """Return the DUT1 number for the given timestamp"""
     date = _date(dt)
     i = (date - iersdata.DUT1_DATA_START).days
@@ -60,7 +63,7 @@ def get_dut1(dt: DateOrDatetime, *, warn_outdated: bool = True) -> float:
         v = iersdata.DUT1_OFFSETS[0]
     elif i >= len(iersdata.DUT1_OFFSETS):
         if warn_outdated:
-            _maybe_warn_update(dt)
+            _maybe_warn_update(dt, stacklevel=2)
         v = iersdata.DUT1_OFFSETS[-1]
     else:
         v = iersdata.DUT1_OFFSETS[i]
@@ -74,7 +77,7 @@ def isly(year: int) -> bool:
     return d1.year == d2.year
 
 
-def isls(t: DateOrDatetime) -> bool:
+def isls(t: datetime.date) -> bool:
     """Return True if a leap second occurs at the end of this month"""
     dut1_today = get_dut1(t)
     month_today = t.month
@@ -86,11 +89,11 @@ def isls(t: DateOrDatetime) -> bool:
 
 def isdst(t: datetime.date, tz: datetime.tzinfo = Mountain) -> bool:
     """Return true if daylight saving time is active at the start of the given UTC day"""
-    t = datetime.datetime(t.year, t.month, t.day, tzinfo=datetime.timezone.utc)
-    return bool(t.astimezone(tz).dst())
+    utc_daystart = datetime.datetime(t.year, t.month, t.day, tzinfo=datetime.timezone.utc)
+    return bool(utc_daystart.astimezone(tz).dst())
 
 
-def first_sunday_on_or_after(dt: DateOrDatetime) -> DateOrDatetime:
+def _first_sunday_on_or_after(dt: datetime.date) -> datetime.date:
     """Return the first sunday on or after the reference time"""
     days_to_go = 6 - dt.weekday()
     if days_to_go:
@@ -98,17 +101,17 @@ def first_sunday_on_or_after(dt: DateOrDatetime) -> DateOrDatetime:
     return dt
 
 
-def first_sunday_in_month(y: int, m: int) -> datetime.date:
+def _first_sunday_in_month(y: int, m: int) -> datetime.date:
     """Find the first sunday in a given month"""
-    return first_sunday_on_or_after(datetime.datetime(y, m, 1))
+    return _first_sunday_on_or_after(datetime.datetime(y, m, 1, tzinfo=datetime.timezone.utc))
 
 
-def is_dst_change_day(t: datetime.date, tz: datetime.tzinfo = Mountain) -> bool:
+def _is_dst_change_day(t: datetime.date, tz: datetime.tzinfo = Mountain) -> bool:
     """Return True if the day is a DST change day"""
     return isdst(t, tz) != isdst(t + datetime.timedelta(1), tz)
 
 
-def get_dst_change_hour(t: DateOrDatetime, tz: datetime.tzinfo = Mountain) -> Optional[int]:
+def _get_dst_change_hour(t: datetime.date, tz: datetime.tzinfo = Mountain) -> int | None:
     """Return the hour when DST changes"""
     lt0 = datetime.datetime(t.year, t.month, t.day, hour=0, tzinfo=tz)
     dst0 = lt0.dst()
@@ -122,28 +125,29 @@ def get_dst_change_hour(t: DateOrDatetime, tz: datetime.tzinfo = Mountain) -> Op
     return None
 
 
-def get_dst_change_date_and_row(
-    d: DateOrDatetime, tz: datetime.tzinfo = Mountain
-) -> Tuple[Optional[datetime.date], Optional[int]]:
+def _get_dst_change_date_and_row(
+    d: datetime.date,
+    tz: datetime.tzinfo = Mountain,
+) -> tuple[datetime.date | None, int | None]:
     """Classify DST information for the WWVB phase modulation signal"""
     if isdst(d, tz):
-        n = first_sunday_in_month(d.year, 11)
+        n = _first_sunday_in_month(d.year, 11)
         for offset in range(-28, 28, 7):
             d1 = n + datetime.timedelta(days=offset)
-            if is_dst_change_day(d1, tz):
+            if _is_dst_change_day(d1, tz):
                 return d1, (offset + 28) // 7
     else:
-        m = first_sunday_in_month(d.year + (d.month > 3), 3)
+        m = _first_sunday_in_month(d.year + (d.month > 3), 3)
         for offset in range(0, 52, 7):
             d1 = m + datetime.timedelta(days=offset)
-            if is_dst_change_day(d1, tz):
+            if _is_dst_change_day(d1, tz):
                 return d1, offset // 7
 
     return None, None
 
 
 # "Table 8", likely with transcrption errors
-dsttable = [
+_dsttable = [
     [
         [
             0b110001,
@@ -211,19 +215,17 @@ dsttable = [
 ]
 
 
-def lfsr_gen(x: List[int]) -> None:
-    """Generate the 127-bit sequence used in the extended 6-minute codes
-    except generate 255 bits so that we can simply use any range of [x:x+127]
-    bits"""
+def _lfsr_gen(x: list[int]) -> None:
+    """Generate the next bit of the 6-minute codes sequence"""
     x.append(x[-7] ^ x[-6] ^ x[-5] ^ x[-2])
 
 
-lfsr_seq = [1] * 7
-while len(lfsr_seq) < 255:
-    lfsr_gen(lfsr_seq)
+_lfsr_seq = [1] * 7
+while len(_lfsr_seq) < 255:
+    _lfsr_gen(_lfsr_seq)
 
 # Table 12 - Fixed 106-bit timing word
-ftw = [
+_ftw = [
     int(c)
     for c in "1101000111"
     "0101100101"
@@ -239,11 +241,11 @@ ftw = [
 ]
 
 
-def get_dst_next(d: DateOrDatetime, tz: datetime.tzinfo = Mountain) -> int:
+def _get_dst_next(d: datetime.date, tz: datetime.tzinfo = Mountain) -> int:
     """Find the "dst next" value for the phase modulation signal"""
     dst_now = isdst(d, tz)  # dst_on[1]
-    dst_midwinter = isdst(datetime.datetime(d.year, 1, 1), tz)
-    dst_midsummer = isdst(datetime.datetime(d.year, 7, 1), tz)
+    dst_midwinter = isdst(datetime.datetime(d.year, 1, 1, tzinfo=datetime.timezone.utc), tz)
+    dst_midsummer = isdst(datetime.datetime(d.year, 7, 1, tzinfo=datetime.timezone.utc), tz)
 
     if dst_midwinter and dst_midsummer:
         return 0b101111
@@ -254,19 +256,19 @@ def get_dst_next(d: DateOrDatetime, tz: datetime.tzinfo = Mountain) -> int:
     if dst_midwinter or not dst_midsummer:
         return 0b100011
 
-    dst_change_date, dst_next_row = get_dst_change_date_and_row(d, tz)
+    dst_change_date, dst_next_row = _get_dst_change_date_and_row(d, tz)
     if dst_change_date is None:
         return 0b100011
     assert dst_next_row is not None
 
-    dst_change_hour = get_dst_change_hour(dst_change_date, tz)
+    dst_change_hour = _get_dst_change_hour(dst_change_date, tz)
     if dst_change_hour is None:
         return 0b100011
 
-    return dsttable[dst_now][dst_change_hour][dst_next_row]
+    return _dsttable[dst_now][dst_change_hour][dst_next_row]
 
 
-hamming_weight = [
+_hamming_weight = [
     [23, 21, 20, 17, 16, 15, 14, 13, 9, 8, 6, 5, 4, 2, 0],
     [24, 22, 21, 18, 17, 16, 15, 14, 10, 9, 7, 6, 5, 3, 1],
     [25, 23, 22, 19, 18, 17, 16, 15, 11, 10, 8, 7, 6, 4, 2],
@@ -281,25 +283,26 @@ SYNC_T = 0x768
 SYNC_M = 0x1A3A
 
 
-def extract_bit(v: int, p: int) -> bool:
+def _extract_bit(v: int, p: int) -> bool:
     """Extract bit 'p' from integer 'v' as a bool"""
     return bool((v >> p) & 1)
 
 
-def hamming_parity(value: int) -> int:
+def _hamming_parity(value: int) -> int:
     """Compute the "hamming parity" of a 26-bit number, such as the minute-of-century
 
-    For more details, see Enhanced WWVB Broadcast Format 4.3"""
+    For more details, see Enhanced WWVB Broadcast Format 4.3
+    """
     parity = 0
     for i in range(4, -1, -1):
         bit = 0
-        for j in range(0, 15):
-            bit ^= extract_bit(value, hamming_weight[i][j])
+        for j in range(15):
+            bit ^= _extract_bit(value, _hamming_weight[i][j])
         parity = (parity << 1) | bit
     return parity
 
 
-dst_ls_lut = [
+_dst_ls_lut = [
     0b01000,
     0b10101,
     0b10110,
@@ -318,35 +321,57 @@ dst_ls_lut = [
     0b11111,
 ]
 
-_WWVBMinute = collections.namedtuple("_WWVBMinute", "year days hour min dst ut1 ls ly")
 
-
-class WWVBMinute(_WWVBMinute):
+class _WWVBMinute(NamedTuple):
     """Uniquely identifies a minute of time in the WWVB system.
 
-    To use ut1 and ls information from IERS, create a WWVBMinuteIERS value instead."""
+    To use ut1 and ls information from IERS, create a WWVBMinuteIERS value instead.
+    """
 
     year: int
+    """2-digit year within the WWVB epoch"""
+
+    days: int
+    """1-based day of year"""
+
     hour: int
-    minute: int
+    """UTC hour of day"""
+
+    min: int
+    """Minute of hour"""
+
     dst: int
+    """2-bit DST code """
+
     ut1: int
-    ly: bool
+    """UT1 offset in units of 100ms, range -900 to +900ms"""
+
     ls: bool
+    """Leap second warning flag"""
+
+    ly: bool
+    """Leap year flag"""
+
+
+class WWVBMinute(_WWVBMinute):
+    """Uniquely identifies a minute of time in the WWVB system.
+
+    To use ut1 and ls information from IERS, create a WWVBMinuteIERS value instead.
+    """
 
     epoch: int = 1970
 
-    def __new__(
+    def __new__(  # noqa: PYI034
         cls,
         year: int,
         days: int,
         hour: int,
         minute: int,
-        dst: Optional[int] = None,
-        ut1: Optional[int] = None,
-        ls: Optional[bool] = None,
-        ly: Optional[bool] = None,
-    ) -> "WWVBMinute":
+        dst: int | None = None,
+        ut1: int | None = None,
+        ls: bool | None = None,
+        ly: bool | None = None,
+    ) -> WWVBMinute:
         """Construct a WWVBMinute"""
         if dst is None:
             dst = cls.get_dst(year, days)
@@ -383,7 +408,7 @@ class WWVBMinute(_WWVBMinute):
     @staticmethod
     def get_dst(year: int, days: int) -> int:
         """Get the 2-bit WWVB DST value for the given day"""
-        d0 = datetime.datetime(year, 1, 1) + datetime.timedelta(days - 1)
+        d0 = datetime.datetime(year, 1, 1, tzinfo=datetime.timezone.utc) + datetime.timedelta(days - 1)
         d1 = d0 + datetime.timedelta(1)
         dst0 = isdst(d0)
         dst1 = isdst(d1)
@@ -405,7 +430,12 @@ class WWVBMinute(_WWVBMinute):
 
     as_datetime = as_datetime_utc
 
-    def as_datetime_local(self, standard_time_offset: int = 7 * 3600, dst_observed: bool = True) -> datetime.datetime:
+    def as_datetime_local(
+        self,
+        standard_time_offset: int = 7 * 3600,
+        *,
+        dst_observed: bool = True,
+    ) -> datetime.datetime:
         """Convert to a local datetime according to the DST bits"""
         u = self.as_datetime_utc()
         offset = datetime.timedelta(seconds=-standard_time_offset)
@@ -426,11 +456,6 @@ class WWVBMinute(_WWVBMinute):
             offset += datetime.timedelta(seconds=3600)
         return u.astimezone(datetime.timezone(offset))
 
-    def is_ly(self) -> bool:
-        """Return True if minute is during a leap year"""
-        warnings.warn("Deprecated, use ly property instead", DeprecationWarning)
-        return self.ly
-
     def _is_end_of_month(self) -> bool:
         """Return True if minute is the last minute in a month"""
         d = self.as_datetime()
@@ -449,18 +474,18 @@ class WWVBMinute(_WWVBMinute):
             return 59
         return 61
 
-    def as_timecode(self) -> "WWVBTimecode":
+    def as_timecode(self) -> WWVBTimecode:
         """Fill a WWVBTimecode structure representing this minute.  Fills both the amplitude and phase codes."""
         t = WWVBTimecode(self.minute_length())
 
-        self.fill_am_timecode(t)
-        self.fill_pm_timecode(t)
+        self._fill_am_timecode(t)
+        self._fill_pm_timecode(t)
 
         return t
 
     @property
-    def leap_sec(self) -> int:
-        """Return the 2-bit leap_sec value used by the PM code"""
+    def _leap_sec(self) -> int:
+        """Return the 2-bit _leap_sec value used by the PM code"""
         if not self.ls:
             return 0
         if self.ut1 < 0:
@@ -477,7 +502,7 @@ class WWVBMinute(_WWVBMinute):
             // 60
         )
 
-    def fill_am_timecode(self, t: "WWVBTimecode") -> None:
+    def _fill_am_timecode(self, t: WWVBTimecode) -> None:
         """Fill the amplitude (AM) portion of a timecode object"""
         for i in [0, 9, 19, 29, 39, 49]:
             t.am[i] = AmplitudeModulation.MARK
@@ -499,7 +524,7 @@ class WWVBMinute(_WWVBMinute):
         t.am[56] = AmplitudeModulation(self.ls)
         t._put_am_bcd(self.dst, 57, 58)
 
-    def fill_pm_timecode_extended(self, t: "WWVBTimecode") -> None:
+    def _fill_pm_timecode_extended(self, t: WWVBTimecode) -> None:
         """During minutes 10..15 and 40..45, the amplitude signal holds 'extended information'"""
         assert 10 <= self.min < 16 or 40 <= self.min < 46
         minno = self.min % 10
@@ -520,103 +545,99 @@ class WWVBMinute(_WWVBMinute):
                 seqno = seqno + 90
             else:
                 seqno = seqno + 1
-        else:  # dst == 1
-            if self.hour < 4:
-                seqno = seqno + 1
-            elif self.hour < 11:
-                seqno = seqno + 91
+        elif self.hour < 4:
+            seqno = seqno + 1
+        elif self.hour < 11:
+            seqno = seqno + 91
 
-        info_seq = lfsr_seq[seqno : seqno + 127]
-        full_seq = info_seq + ftw + info_seq[::-1]
+        info_seq = _lfsr_seq[seqno : seqno + 127]
+        full_seq = info_seq + _ftw + info_seq[::-1]
         assert len(full_seq) == 360
 
         offset = minno * 60
         for i in range(60):
             t._put_pm_bit(i, full_seq[i + offset])
 
-    def fill_pm_timecode_regular(self, t: "WWVBTimecode") -> None:
+    def _fill_pm_timecode_regular(self, t: WWVBTimecode) -> None:  # noqa: PLR0915
         """Except during minutes 10..15 and 40..45, the amplitude signal holds 'regular information'"""
         t._put_pm_bin(0, 13, SYNC_T)
 
         moc = self.minute_of_century
-        leap_sec = self.leap_sec
+        _leap_sec = self._leap_sec
         dst_on = self.dst
-        dst_ls = dst_ls_lut[dst_on | (leap_sec << 2)]
-        dst_next = get_dst_next(self.as_datetime())
-        t._put_pm_bin(13, 5, hamming_parity(moc))
-        t._put_pm_bit(18, extract_bit(moc, 25))
-        t._put_pm_bit(19, extract_bit(moc, 0))
-        t._put_pm_bit(20, extract_bit(moc, 24))
-        t._put_pm_bit(21, extract_bit(moc, 23))
-        t._put_pm_bit(22, extract_bit(moc, 22))
-        t._put_pm_bit(23, extract_bit(moc, 21))
-        t._put_pm_bit(24, extract_bit(moc, 20))
-        t._put_pm_bit(25, extract_bit(moc, 19))
-        t._put_pm_bit(26, extract_bit(moc, 18))
-        t._put_pm_bit(27, extract_bit(moc, 17))
-        t._put_pm_bit(28, extract_bit(moc, 16))
-        t._put_pm_bit(29, False)  # Reserved
-        t._put_pm_bit(30, extract_bit(moc, 15))
-        t._put_pm_bit(31, extract_bit(moc, 14))
-        t._put_pm_bit(32, extract_bit(moc, 13))
-        t._put_pm_bit(33, extract_bit(moc, 12))
-        t._put_pm_bit(34, extract_bit(moc, 11))
-        t._put_pm_bit(35, extract_bit(moc, 10))
-        t._put_pm_bit(36, extract_bit(moc, 9))
-        t._put_pm_bit(37, extract_bit(moc, 8))
-        t._put_pm_bit(38, extract_bit(moc, 7))
-        t._put_pm_bit(39, True)  # Reserved
-        t._put_pm_bit(40, extract_bit(moc, 6))
-        t._put_pm_bit(41, extract_bit(moc, 5))
-        t._put_pm_bit(42, extract_bit(moc, 4))
-        t._put_pm_bit(43, extract_bit(moc, 3))
-        t._put_pm_bit(44, extract_bit(moc, 2))
-        t._put_pm_bit(45, extract_bit(moc, 1))
-        t._put_pm_bit(46, extract_bit(moc, 0))
-        t._put_pm_bit(47, extract_bit(dst_ls, 4))
-        t._put_pm_bit(48, extract_bit(dst_ls, 3))
-        t._put_pm_bit(49, True)  # Notice
-        t._put_pm_bit(50, extract_bit(dst_ls, 2))
-        t._put_pm_bit(51, extract_bit(dst_ls, 1))
-        t._put_pm_bit(52, extract_bit(dst_ls, 0))
-        t._put_pm_bit(53, extract_bit(dst_next, 5))
-        t._put_pm_bit(54, extract_bit(dst_next, 4))
-        t._put_pm_bit(55, extract_bit(dst_next, 3))
-        t._put_pm_bit(56, extract_bit(dst_next, 2))
-        t._put_pm_bit(57, extract_bit(dst_next, 1))
-        t._put_pm_bit(58, extract_bit(dst_next, 0))
+        dst_ls = _dst_ls_lut[dst_on | (_leap_sec << 2)]
+        dst_next = _get_dst_next(self.as_datetime())
+        t._put_pm_bin(13, 5, _hamming_parity(moc))
+        t._put_pm_bit(18, _extract_bit(moc, 25))
+        t._put_pm_bit(19, _extract_bit(moc, 0))
+        t._put_pm_bit(20, _extract_bit(moc, 24))
+        t._put_pm_bit(21, _extract_bit(moc, 23))
+        t._put_pm_bit(22, _extract_bit(moc, 22))
+        t._put_pm_bit(23, _extract_bit(moc, 21))
+        t._put_pm_bit(24, _extract_bit(moc, 20))
+        t._put_pm_bit(25, _extract_bit(moc, 19))
+        t._put_pm_bit(26, _extract_bit(moc, 18))
+        t._put_pm_bit(27, _extract_bit(moc, 17))
+        t._put_pm_bit(28, _extract_bit(moc, 16))
+        t._put_pm_bit(29, False)  # noqa: FBT003 # Reserved
+        t._put_pm_bit(30, _extract_bit(moc, 15))
+        t._put_pm_bit(31, _extract_bit(moc, 14))
+        t._put_pm_bit(32, _extract_bit(moc, 13))
+        t._put_pm_bit(33, _extract_bit(moc, 12))
+        t._put_pm_bit(34, _extract_bit(moc, 11))
+        t._put_pm_bit(35, _extract_bit(moc, 10))
+        t._put_pm_bit(36, _extract_bit(moc, 9))
+        t._put_pm_bit(37, _extract_bit(moc, 8))
+        t._put_pm_bit(38, _extract_bit(moc, 7))
+        t._put_pm_bit(39, True)  # noqa: FBT003 # Reserved
+        t._put_pm_bit(40, _extract_bit(moc, 6))
+        t._put_pm_bit(41, _extract_bit(moc, 5))
+        t._put_pm_bit(42, _extract_bit(moc, 4))
+        t._put_pm_bit(43, _extract_bit(moc, 3))
+        t._put_pm_bit(44, _extract_bit(moc, 2))
+        t._put_pm_bit(45, _extract_bit(moc, 1))
+        t._put_pm_bit(46, _extract_bit(moc, 0))
+        t._put_pm_bit(47, _extract_bit(dst_ls, 4))
+        t._put_pm_bit(48, _extract_bit(dst_ls, 3))
+        t._put_pm_bit(49, True)  # noqa: FBT003 # Notice
+        t._put_pm_bit(50, _extract_bit(dst_ls, 2))
+        t._put_pm_bit(51, _extract_bit(dst_ls, 1))
+        t._put_pm_bit(52, _extract_bit(dst_ls, 0))
+        t._put_pm_bit(53, _extract_bit(dst_next, 5))
+        t._put_pm_bit(54, _extract_bit(dst_next, 4))
+        t._put_pm_bit(55, _extract_bit(dst_next, 3))
+        t._put_pm_bit(56, _extract_bit(dst_next, 2))
+        t._put_pm_bit(57, _extract_bit(dst_next, 1))
+        t._put_pm_bit(58, _extract_bit(dst_next, 0))
         if len(t.phase) > 59:
             t._put_pm_bit(59, PhaseModulation.ZERO)
         if len(t.phase) > 60:
             t._put_pm_bit(60, PhaseModulation.ZERO)
 
-    def fill_pm_timecode(self, t: "WWVBTimecode") -> None:
+    def _fill_pm_timecode(self, t: WWVBTimecode) -> None:
         """Fill the phase portion of a timecode object"""
         if 10 <= self.min < 16 or 40 <= self.min < 46:
-            self.fill_pm_timecode_extended(t)
+            self._fill_pm_timecode_extended(t)
         else:
-            self.fill_pm_timecode_regular(t)
+            self._fill_pm_timecode_regular(t)
 
-    def next_minute(self, newut1: Optional[int] = None, newls: Optional[bool] = None) -> "WWVBMinute":
+    def next_minute(self, newut1: int | None = None, newls: bool | None = None) -> WWVBMinute:
         """Return an object representing the next minute"""
         d = self.as_datetime() + datetime.timedelta(minutes=1)
         return self.from_datetime(d, newut1, newls, self)
 
-    def previous_minute(self, newut1: Optional[int] = None, newls: Optional[bool] = None) -> "WWVBMinute":
+    def previous_minute(self, newut1: int | None = None, newls: bool | None = None) -> WWVBMinute:
         """Return an object representing the previous minute"""
         d = self.as_datetime() - datetime.timedelta(minutes=1)
         return self.from_datetime(d, newut1, newls, self)
 
     @classmethod
-    def _get_dut1_info(cls: type, year: int, days: int, old_time: "Optional[WWVBMinute]" = None) -> Tuple[int, bool]:
+    def _get_dut1_info(cls: type, year: int, days: int, old_time: WWVBMinute | None = None) -> tuple[int, bool]:  # noqa: ARG003
         """Return the DUT1 information for a given day, possibly propagating information from a previous timestamp"""
         if old_time is not None:
             if old_time.minute_length() != 60:
                 newls = False
-                if old_time.ut1 < 0:
-                    newut1 = old_time.ut1 + 1000
-                else:
-                    newut1 = old_time.ut1 - 1000
+                newut1 = old_time.ut1 + 1000 if old_time.ut1 < 0 else old_time.ut1 - 1000
             else:
                 newls = old_time.ls
                 newut1 = old_time.ut1
@@ -624,10 +645,10 @@ class WWVBMinute(_WWVBMinute):
         return 0, False
 
     @classmethod
-    def fromstring(cls, s: str) -> "WWVBMinute":
+    def fromstring(cls, s: str) -> WWVBMinute:
         """Construct a WWVBMinute from a string representation created by print_timecodes"""
         s = _removeprefix(s, "WWVB timecode: ")
-        d: Dict[str, int] = {}
+        d: dict[str, int] = {}
         for part in s.split():
             k, v = part.split("=")
             if k == "min":
@@ -637,8 +658,8 @@ class WWVBMinute(_WWVBMinute):
         days = d.pop("days")
         hour = d.pop("hour")
         minute = d.pop("minute")
-        dst: Optional[int] = d.pop("dst", None)
-        ut1: Optional[int] = d.pop("ut1", None)
+        dst: int | None = d.pop("dst", None)
+        ut1: int | None = d.pop("ut1", None)
         ls = d.pop("ls", None)
         d.pop("ly", None)
         if d:
@@ -649,10 +670,10 @@ class WWVBMinute(_WWVBMinute):
     def from_datetime(
         cls,
         d: datetime.datetime,
-        newut1: Optional[int] = None,
-        newls: Optional[bool] = None,
-        old_time: Optional["WWVBMinute"] = None,
-    ) -> "WWVBMinute":
+        newut1: int | None = None,
+        newls: bool | None = None,
+        old_time: WWVBMinute | None = None,
+    ) -> WWVBMinute:
         """Construct a WWVBMinute from a datetime, possibly specifying ut1/ls data or propagating it from an old time"""
         u = d.utctimetuple()
         if newls is None and newut1 is None:
@@ -660,7 +681,7 @@ class WWVBMinute(_WWVBMinute):
         return cls(u.tm_year, u.tm_yday, u.tm_hour, u.tm_min, ut1=newut1, ls=newls)
 
     @classmethod
-    def from_timecode_am(cls, t: "WWVBTimecode") -> Optional["WWVBMinute"]:
+    def from_timecode_am(cls, t: WWVBTimecode) -> WWVBMinute | None:
         """Construct a WWVBMinute from a WWVBTimecode"""
         for i in (0, 9, 19, 29, 39, 49, 59):
             if t.am[i] != AmplitudeModulation.MARK:
@@ -694,7 +715,7 @@ class WWVBMinute(_WWVBMinute):
         if days > 366 or (not ly and days > 365):
             return None
         ls = bool(t.am[56])
-        dst = require(t._get_am_bcd(57, 58))
+        dst = _require(t._get_am_bcd(57, 58))
         return cls(year, days, hour, minute, dst, ut1, ls, ly)
 
 
@@ -702,12 +723,12 @@ class WWVBMinuteIERS(WWVBMinute):
     """A WWVBMinute that uses a database of DUT1 information"""
 
     @classmethod
-    def _get_dut1_info(cls, year: int, days: int, old_time: Optional[WWVBMinute] = None) -> Tuple[int, bool]:
-        d = datetime.datetime(year, 1, 1) + datetime.timedelta(days - 1)
+    def _get_dut1_info(cls, year: int, days: int, old_time: WWVBMinute | None = None) -> tuple[int, bool]:  # noqa: ARG003
+        d = datetime.datetime(year, 1, 1, tzinfo=datetime.timezone.utc) + datetime.timedelta(days - 1)
         return int(round(get_dut1(d) * 10)) * 100, isls(d)
 
 
-def bcd_bits(n: int) -> Generator[bool, None, None]:
+def _bcd_bits(n: int) -> Generator[bool, None, None]:
     """Return the bcd representation of n, starting with the least significant bit"""
     while True:
         d = n % 10
@@ -738,18 +759,23 @@ class PhaseModulation(enum.IntEnum):
 class WWVBTimecode:
     """Represent the amplitude and/or phase signal, usually over 1 minute"""
 
-    am: List[AmplitudeModulation]
-    phase: List[PhaseModulation]
+    am: list[AmplitudeModulation]
+    """The amplitude modulation data"""
+
+    phase: list[PhaseModulation]
+    """The phase modulation data"""
 
     def __init__(self, sz: int) -> None:
+        """Construct a WWVB timecode ``sz`` seconds long"""
         self.am = [AmplitudeModulation.UNSET] * sz
         self.phase = [PhaseModulation.UNSET] * sz
 
-    def _get_am_bcd(self, *poslist: int) -> Optional[int]:
+    def _get_am_bcd(self, *poslist: int) -> int | None:
         """Convert AM data to BCD
 
         The the bits ``self.am[poslist[i]]`` in MSB order are converted from
-        BCD to integer"""
+        BCD to integer
+        """
         pos = reversed(poslist)
         val = [bool(self.am[p]) for p in pos]
         result = 0
@@ -769,28 +795,29 @@ class WWVBTimecode:
 
         The bits at ``self.am[poslist[i]]`` in MSB order are filled with
         the conversion of `v` to BCD
-        Treating 'poslist' as a sequence of indices, update the AM signal with the value as a BCD number"""
+        Treating 'poslist' as a sequence of indices, update the AM signal with the value as a BCD number
+        """
         pos = list(poslist)[::-1]
-        for p, b in zip(pos, bcd_bits(v)):
+        for p, b in zip(pos, _bcd_bits(v)):
             if b:
                 self.am[p] = AmplitudeModulation.ONE
             else:
                 self.am[p] = AmplitudeModulation.ZERO
 
-    def _put_pm_bit(self, i: int, v: Union[PhaseModulation, int, bool]) -> None:
+    def _put_pm_bit(self, i: int, v: PhaseModulation | int | bool) -> None:
         """Update a bit of the Phase Modulation signal"""
         self.phase[i] = PhaseModulation(v)
 
     def _put_pm_bin(self, st: int, n: int, v: int) -> None:
         """Update an n-digit binary number in the Phase Modulation signal"""
         for i in range(n):
-            self._put_pm_bit(st + i, extract_bit(v, (n - i - 1)))
+            self._put_pm_bit(st + i, _extract_bit(v, (n - i - 1)))
 
     def __str__(self) -> str:
-        """implement str()"""
+        """Implement str()"""
         undefined = [i for i in range(len(self.am)) if self.am[i] == AmplitudeModulation.UNSET]
         if undefined:
-            warnings.warn(f"am{undefined} is unset")
+            warnings.warn(f"am{undefined} is unset", stacklevel=1)
 
         def convert_one(am: AmplitudeModulation, phase: PhaseModulation) -> str:
             if phase is PhaseModulation.UNSET:
@@ -802,20 +829,20 @@ class WWVBTimecode:
         return "".join(convert_one(i, j) for i, j in zip(self.am, self.phase))
 
     def __repr__(self) -> str:
-        """implement repr()"""
+        """Implement repr()"""
         return "<WWVBTimecode " + str(self) + ">"
 
-    def to_am_string(self, charset: List[str]) -> str:
+    def to_am_string(self, charset: list[str]) -> str:
         """Convert the amplitude signal to a string"""
         return "".join(charset[i] for i in self.am)
 
     to_string = to_am_string
 
-    def to_pm_string(self, charset: List[str]) -> str:
+    def to_pm_string(self, charset: list[str]) -> str:
         """Convert the phase signal to a string"""
         return "".join(charset[i] for i in self.phase)
 
-    def to_both_string(self, charset: List[str]) -> str:
+    def to_both_string(self, charset: list[str]) -> str:
         """Convert both channels to a string"""
         return "".join(charset[i + j * 3] for i, j in zip(self.am, self.phase))
 
@@ -847,7 +874,7 @@ def print_timecodes(
         if first or all_timecodes:
             if not first:
                 print(file=file)
-            print(f"WWVB timecode: {str(w)}{channel_text}{style_text}", file=file)
+            print(f"WWVB timecode: {w!s}{channel_text}{style_text}", file=file)
         first = False
         pfx = f"{w.year:04d}-{w.days:03d} {w.hour:02d}:{w.min:02d} "
         tc = w.as_timecode()
@@ -872,10 +899,24 @@ def print_timecodes_json(
     channel: str,
     file: TextIO,
 ) -> None:
-    """Print a range of timecodes with a header.  This header is in a format understood by WWVBMinute.fromstring"""
+    """Print a range of timecodes in JSON format.
+
+    The result is a json array of minute data. Each minute data is an object with the following members:
+
+        * year (int)
+        * days (int)
+        * hour (int)
+        * minute (int)
+        * amplitude (string; only if channel is amplitude or both)
+        * phase: (string; only if channel is phase or both)
+
+    The amplitude and phase strings are of length 60 during most minutes, length 61
+    during a minute that includes a (positive) leap second, and theoretically
+    length 59 in the case of a negative leap second.
+    """
     result = []
     for _ in range(minutes):
-        data = {
+        data: dict[str, Any] = {
             "year": w.year,
             "days": w.days,
             "hour": w.hour,