11#!/usr/bin/python3
2- """A library for WWVB timecodes"""
2+ """A package and CLI for WWVB timecodes
3+
4+ This is the full featured library suitable for use on 'real computers'.
5+ For a reduced version suitable for use on MicroPython & CircuitPython,
6+ see `uwwvb`.
7+
8+ This package also includes the commandline programs listed above,
9+ perhaps most importantly ``wwvbgen`` for generating WWVB timecodes.
10+ """
311
412# SPDX-FileCopyrightText: 2011-2024 Jeff Epler
513#
@@ -322,16 +330,17 @@ class DstStatus(enum.IntEnum):
322330 """Constants that describe the DST status of a minute"""
323331
324332 DST_NOT_IN_EFFECT = 0b00
333+ """DST not in effect today"""
325334 DST_STARTS_TODAY = 0b01
335+ """DST starts today at 0200 local standard time"""
326336 DST_ENDS_TODAY = 0b10
337+ """DST ends today at 0200 local standard time"""
327338 DST_IN_EFFECT = 0b11
339+ """DST in effect all day today"""
328340
329341
330342class _WWVBMinute (NamedTuple ):
331- """Uniquely identifies a minute of time in the WWVB system.
332-
333- To use ut1 and ls information from IERS, create a WWVBMinuteIERS value instead.
334- """
343+ """(implementation detail)"""
335344
336345 year : int
337346 """2-digit year within the WWVB epoch"""
@@ -361,7 +370,8 @@ class _WWVBMinute(NamedTuple):
361370class WWVBMinute (_WWVBMinute ):
362371 """Uniquely identifies a minute of time in the WWVB system.
363372
364- To use ut1 and ls information from IERS, create a WWVBMinuteIERS value instead.
373+ To use ``ut1`` and ``ls`` information from IERS, create a `WWVBMinuteIERS`
374+ object instead.
365375 """
366376
367377 epoch : int = 1970
@@ -377,7 +387,19 @@ def __new__( # noqa: PYI034
377387 ls : bool | None = None ,
378388 ly : bool | None = None ,
379389 ) -> WWVBMinute :
380- """Construct a WWVBMinute"""
390+ """Construct a WWVBMinute
391+
392+ :param year: The 2- or 4-digit year. This parameter is converted by the `full_year` method.
393+ :param days: 1-based day of year
394+
395+ :param hour: UTC hour of day
396+
397+ :param minute: Minute of hour
398+ :param dst: 2-bit DST code
399+ :param ut1: UT1 offset in units of 100ms, range -900 to +900ms
400+ :param ls: Leap second warning flag
401+ :param ly: Leap year flag
402+ """
381403 dst = cls .get_dst (year , days ) if dst is None else DstStatus (dst )
382404 if ut1 is None and ls is None :
383405 ut1 , ls = cls ._get_dut1_info (year , days )
@@ -425,7 +447,10 @@ def __str__(self) -> str:
425447 )
426448
427449 def as_datetime_utc (self ) -> datetime .datetime :
428- """Convert to a UTC datetime"""
450+ """Convert to a UTC datetime
451+
452+ The returned object has ``tzinfo=datetime.timezone.utc``.
453+ """
429454 d = datetime .datetime (self .year , 1 , 1 , tzinfo = datetime .timezone .utc )
430455 d += datetime .timedelta (self .days - 1 , self .hour * 3600 + self .min * 60 )
431456 return d
@@ -438,7 +463,18 @@ def as_datetime_local(
438463 * ,
439464 dst_observed : bool = True ,
440465 ) -> datetime .datetime :
441- """Convert to a local datetime according to the DST bits"""
466+ """Convert to a local datetime according to the DST bits
467+
468+ The returned object has ``tz=datetime.timezone(computed_offset)``.
469+
470+ :param standard_time_offset: The UTC offset of local standard time, in seconds west of UTC.
471+ The default value, ``7 * 3600``, is for Colorado, the source of the WWVB broadcast.
472+
473+ :param dst_observed: If ``True`` then the locale observes DST, and a
474+ one hour offset is applied according to WWVB rules. If ``False``, then
475+ the standard time offset is used at all times.
476+
477+ """
442478 u = self .as_datetime_utc ()
443479 offset = datetime .timedelta (seconds = - standard_time_offset )
444480 d = u - datetime .timedelta (seconds = standard_time_offset )
@@ -750,18 +786,25 @@ class AmplitudeModulation(enum.IntEnum):
750786 """Constants that describe an Amplitude Modulation value"""
751787
752788 ZERO = 0
789+ """A zero bit (reduced carrier during the first 200ms of the second)"""
753790 ONE = 1
791+ """A one bit (reduced carrier during the first 500ms of the second)"""
754792 MARK = 2
793+ """A mark bit (reduced carrier during the first 800ms of the second)"""
755794 UNSET = - 1
795+ """An unset or unknown amplitude modulation value"""
756796
757797
758798@enum .unique
759799class PhaseModulation (enum .IntEnum ):
760800 """Constants that describe a Phase Modulation value"""
761801
762802 ZERO = 0
803+ """A one bit (180° phase shift during the second)"""
763804 ONE = 1
805+ """A zero bit (No phase shift during the second)"""
764806 UNSET = - 1
807+ """An unset or unknown phase modulation value"""
765808
766809
767810class WWVBTimecode :
0 commit comments