wwvb 4.0.0a0__py3-none-any.whl → 4.1.0a0__py3-none-any.whl

leapseconddata/__init__.py

@@ -0,0 +1,342 @@
+#!/usr/bin/env python3
+
+# SPDX-FileCopyrightText: 2021 Jeff Epler
+#
+# SPDX-License-Identifier: GPL-3.0-only
+
+"""Use the list of known and scheduled leap seconds
+
+For example, to retrieve the UTC-TAI offset on January 1, 2011:
+
+.. code-block:: python
+    :emphasize-lines: 2,3,5
+
+    >>> import datetime
+    >>> import leapseconddata
+    >>> ls = leapseconddata.LeapSecondData.from_standard_source()
+    >>> when = datetime.datetime(2011, 1, 1, tzinfo=datetime.timezone.utc)
+    >>> ls.tai_offset(when).total_seconds()
+    34.0
+
+"""
+
+from __future__ import annotations
+
+import datetime
+import hashlib
+import io
+import logging
+import pathlib
+import re
+import urllib.request
+from dataclasses import dataclass, field
+from typing import BinaryIO
+
+tai = datetime.timezone(datetime.timedelta(0), "TAI")
+
+NTP_EPOCH = datetime.datetime(1900, 1, 1, tzinfo=datetime.timezone.utc)
+
+
+@dataclass(frozen=True)
+class LeapSecondInfo:
+    """Information about a particular leap second"""
+
+    start: datetime.datetime
+    """The UTC timestamp just after the insertion of the leap second.
+
+    The leap second is actually the 61th second of the previous minute (xx:xx:60)"""
+
+    tai_offset: datetime.timedelta
+    """The new TAI-UTC offset.  Positive numbers indicate that TAI is ahead of UTC"""
+
+
+class ValidityError(ValueError):
+    """The leap second information is not valid for the given timestamp"""
+
+
+class InvalidHashError(ValueError):
+    """The file hash could not be verified"""
+
+
+def _from_ntp_epoch(value: int) -> datetime.datetime:
+    return NTP_EPOCH + datetime.timedelta(seconds=value)
+
+
+def datetime_is_tai(when: datetime.datetime) -> bool:
+    """Return true if the datetime is in the TAI timescale"""
+    return when.tzname() == "TAI"
+
+
+@dataclass(frozen=True)
+class LeapSecondData:
+    """Represent the list of known and scheduled leapseconds
+
+    :param List[LeapSecondInfo] leap_seconds: A list of leap seconds
+    :param Optional[datetime.datetime] valid_until: The expiration of the data
+    :param Optional[datetime.datetime] updated: The last update time of the data
+    """
+
+    leap_seconds: list[LeapSecondInfo]
+    """All known and scheduled leap seconds"""
+
+    valid_until: datetime.datetime | None = field(default=None)
+    """The list is valid until this UTC time"""
+
+    last_updated: datetime.datetime | None = field(default=None)
+    """The last time the list was updated to add a new upcoming leap second"""
+
+    def _check_validity(self, when: datetime.datetime | None) -> str | None:
+        if when is None:
+            when = datetime.datetime.now(datetime.timezone.utc)
+        if not self.valid_until:
+            return "Data validity unknown"
+        if when > self.valid_until:
+            return f"Data only valid until {self.valid_until:%Y-%m-%d}"
+        return None
+
+    def valid(self, when: datetime.datetime | None = None) -> bool:
+        """Return True if the data is valid at given datetime
+
+        If `when` is none, the validity for the current moment is checked.
+
+        :param when: Moment to check for validity
+        """
+        return self._check_validity(when) is None
+
+    @staticmethod
+    def _utc_datetime(when: datetime.datetime) -> datetime.datetime:
+        if when.tzinfo is not None and when.tzinfo is not datetime.timezone.utc:
+            when = when.astimezone(datetime.timezone.utc)
+        return when
+
+    def tai_offset(self, when: datetime.datetime, *, check_validity: bool = True) -> datetime.timedelta:
+        """For a given datetime, return the TAI-UTC offset
+
+        :param when: Moment in time to find offset for
+        :param check_validity: Check whether the database is valid for the given moment
+
+        For times before the first leap second, a zero offset is returned.
+        For times after the end of the file's validity, an exception is raised
+        unless `check_validity=False` is passed.  In this case, it will return
+        the offset of the last list entry.
+        """
+        is_tai = datetime_is_tai(when)
+        if not is_tai:
+            when = self._utc_datetime(when)
+        if check_validity:
+            message = self._check_validity(when)
+            if message is not None:
+                raise ValidityError(message)
+
+        if not self.leap_seconds:
+            return datetime.timedelta(0)
+
+        old_tai = datetime.timedelta()
+        for leap_second in self.leap_seconds:
+            start = leap_second.start
+            if is_tai:
+                start += leap_second.tai_offset - datetime.timedelta(seconds=1)
+            if when < start:
+                return old_tai
+            old_tai = leap_second.tai_offset
+        return self.leap_seconds[-1].tai_offset
+
+    def to_tai(self, when: datetime.datetime, *, check_validity: bool = True) -> datetime.datetime:
+        """Convert the given datetime object to TAI.
+
+        :param when: Moment in time to convert.  If naive, it is assumed to be in UTC.
+        :param check_validity: Check whether the database is valid for the given moment
+
+        Naive timestamps are assumed to be UTC.  A TAI timestamp is returned unchanged.
+        """
+        if datetime_is_tai(when):
+            return when
+        when = self._utc_datetime(when)
+        return (when + self.tai_offset(when, check_validity=check_validity)).replace(tzinfo=tai)
+
+    def tai_to_utc(self, when: datetime.datetime, *, check_validity: bool = True) -> datetime.datetime:
+        """Convert the given datetime object to UTC
+
+        For a leap second, the ``fold`` property of the returned time is True.
+
+        :param when: Moment in time to convert.  If not naive, its ``tzinfo`` must be `tai`.
+        :param check_validity: Check whether the database is valid for the given moment
+        """
+        if when.tzinfo is not None and when.tzinfo is not tai:
+            raise ValueError("Input timestamp is not TAI or naive")
+        if when.tzinfo is None:
+            when = when.replace(tzinfo=tai)
+        result = (when - self.tai_offset(when, check_validity=check_validity)).replace(tzinfo=datetime.timezone.utc)
+        if self.is_leap_second(when, check_validity=check_validity):
+            result = result.replace(fold=True)
+        return result
+
+    def is_leap_second(self, when: datetime.datetime, *, check_validity: bool = True) -> bool:
+        """Return True if the given timestamp is the leap second.
+
+        :param when: Moment in time to check.  If naive, it is assumed to be in UTC.
+        :param check_validity: Check whether the database is valid for the given moment
+
+        For a TAI timestamp, it returns True for the leap second (the one that
+        would be shown as :60 in UTC).  For a UTC timestamp, it returns True
+        for the :59 second if ``fold``, since the :60 second cannot be
+        represented.
+        """
+        if when.tzinfo is not tai:
+            when = self.to_tai(when, check_validity=check_validity) + datetime.timedelta(seconds=when.fold)
+        tai_offset1 = self.tai_offset(when, check_validity=check_validity)
+        tai_offset2 = self.tai_offset(when - datetime.timedelta(seconds=1), check_validity=check_validity)
+        return tai_offset1 != tai_offset2
+
+    @classmethod
+    def from_standard_source(
+        cls,
+        when: datetime.datetime | None = None,
+        *,
+        check_hash: bool = True,
+    ) -> LeapSecondData:
+        """Get the list of leap seconds from a standard source.
+
+        :param when: Check that the data is valid for this moment
+        :param check_hash: Whether to check the embedded hash
+
+        Using a list of standard sources, including network sources, find a
+        leap-second.list data valid for the given timestamp, or the current
+        time (if unspecified)
+        """
+        for location in [  # pragma no branch
+            "file:///usr/share/zoneinfo/leap-seconds.list",  # Debian Linux
+            "file:///var/db/ntpd.leap-seconds.list",  # FreeBSD
+            "https://raw.githubusercontent.com/eggert/tz/main/leap-seconds.list",
+            "https://www.meinberg.de/download/ntp/leap-seconds.list",
+        ]:
+            logging.debug("Trying leap second data from %s", location)
+            try:
+                candidate = cls.from_url(location, check_hash=check_hash)
+            except InvalidHashError:  # pragma no cover
+                logging.warning("Invalid hash while reading %s", location)
+                continue
+            if candidate is None:  # pragma no cover
+                continue
+            if candidate.valid(when):  # pragma no branch
+                logging.info("Using leap second data from %s", location)
+                return candidate
+            logging.warning("Validity expired for %s", location)  # pragma no cover
+
+        raise ValidityError("No valid leap-second.list file could be found")  # pragma no cover
+
+    @classmethod
+    def from_file(
+        cls,
+        filename: str = "/usr/share/zoneinfo/leap-seconds.list",
+        *,
+        check_hash: bool = True,
+    ) -> LeapSecondData:
+        """Retrieve the leap second list from a local file.
+
+        :param filename: Local filename to read leap second data from.  The
+            default is the standard location for the file on Debian systems.
+        :param check_hash: Whether to check the embedded hash
+        """
+        with pathlib.Path(filename).open("rb") as open_file:  # pragma no cover
+            return cls.from_open_file(open_file, check_hash=check_hash)
+
+    @classmethod
+    def from_url(
+        cls,
+        url: str = "https://raw.githubusercontent.com/eggert/tz/main/leap-seconds.list",
+        *,
+        check_hash: bool = True,
+    ) -> LeapSecondData | None:
+        """Retrieve the leap second list from a local file
+
+        :param filename: URL to read leap second data from.  The
+            default is maintained by the tzdata authors
+        :param check_hash: Whether to check the embedded hash
+        """
+        try:
+            with urllib.request.urlopen(url) as open_file:
+                return cls.from_open_file(open_file, check_hash=check_hash)
+        except urllib.error.URLError:  # pragma no cover
+            return None
+
+    @classmethod
+    def from_data(
+        cls,
+        data: bytes | str,
+        *,
+        check_hash: bool = True,
+    ) -> LeapSecondData:
+        """Retrieve the leap second list from local data
+
+        :param data: Data to parse as a leap second list
+        :param check_hash: Whether to check the embedded hash
+        """
+        if isinstance(data, str):
+            data = data.encode("ascii", "replace")
+        return cls.from_open_file(io.BytesIO(data), check_hash=check_hash)
+
+    @staticmethod
+    def _parse_content_hash(row: bytes) -> str:
+        """Transform the SHA1 content into a string that matches `hexdigest()`
+
+        The SHA1 hash of the leap second content is stored in an unusual way.
+        """
+        parts = row.split()
+        hash_parts = [int(s, 16) for s in parts[1:]]
+        return "".join(f"{i:08x}" for i in hash_parts)
+
+    @classmethod
+    def from_open_file(cls, open_file: BinaryIO, *, check_hash: bool = True) -> LeapSecondData:
+        """Retrieve the leap second list from an open file-like object
+
+        :param open_file: Binary IO object containing the leap second list
+        :param check_hash: Whether to check the embedded hash
+        """
+        leap_seconds: list[LeapSecondInfo] = []
+        valid_until = None
+        last_updated = None
+        content_to_hash = []
+        content_hash = None
+
+        hasher = hashlib.sha1()
+
+        for row in open_file:
+            row = row.strip()  # noqa: PLW2901
+            if row.startswith(b"#h"):
+                content_hash = cls._parse_content_hash(row)
+                continue
+
+            if row.startswith(b"#@"):
+                parts = row.split()
+                hasher.update(parts[1])
+                valid_until = _from_ntp_epoch(int(parts[1]))
+                continue
+
+            if row.startswith(b"#$"):
+                parts = row.split()
+                hasher.update(parts[1])
+                last_updated = _from_ntp_epoch(int(parts[1]))
+                continue
+
+            row = row.split(b"#")[0].strip()  # noqa: PLW2901
+            content_to_hash.extend(re.findall(rb"\d+", row))
+
+            parts = row.split()
+            if len(parts) != 2:  # noqa: PLR2004
+                continue
+            hasher.update(parts[0])
+            hasher.update(parts[1])
+
+            when = _from_ntp_epoch(int(parts[0]))
+            tai_offset = datetime.timedelta(seconds=int(parts[1]))
+            leap_seconds.append(LeapSecondInfo(when, tai_offset))
+
+        if check_hash:
+            if content_hash is None:
+                raise InvalidHashError("No #h line found")
+            digest = hasher.hexdigest()
+            if digest != content_hash:
+                raise InvalidHashError(f"Hash didn't match.  Expected {content_hash[:8]}..., got {digest[:8]}...")
+
+        return LeapSecondData(leap_seconds, valid_until, last_updated)

leapseconddata/__main__.py

@@ -0,0 +1,169 @@
+# SPDX-FileCopyrightText: 2022 Jeff Epler
+#
+# SPDX-License-Identifier: GPL-3.0-only
+
+"""Commandline interface to leap second data"""
+
+from __future__ import annotations
+
+import datetime
+import logging
+import typing
+from dataclasses import dataclass
+
+import click
+
+from . import LeapSecondData, tai
+
+utc = datetime.timezone.utc
+
+
+def utcnow() -> datetime.datetime:
+    """Return the current time in UTC, with tzinfo=utc"""
+    return datetime.datetime.now(utc)
+
+
+class UTCDateTime(click.DateTime):
+    """Click option class for date time in UTC"""
+
+    def convert(
+        self,
+        value: typing.Any,
+        param: click.Parameter | None,
+        ctx: click.Context | None,
+    ) -> typing.Any:
+        """Convert the value then attach the utc timezone"""
+        converted = super().convert(value, param, ctx)
+        if converted is not None:
+            return converted.replace(tzinfo=utc)
+        return converted  # pragma no cover
+
+
+@dataclass
+class State:
+    """State shared across sub-commands"""
+
+    leap_second_data: LeapSecondData
+
+
+@click.group()
+@click.option(
+    "--url",
+    type=str,
+    default=None,
+    help="URL for leap second data (unspecified to use default source)",
+)
+@click.option("--debug/--no-debug", type=bool)
+@click.pass_context
+def cli(ctx: click.Context, *, url: str, debug: bool) -> None:
+    """Access leap second database information"""
+    if debug:  # pragma no cover
+        logging.getLogger().setLevel(logging.DEBUG)
+    if ctx.find_object(LeapSecondData) is None:  # pragma no branch
+        if url is None:
+            ctx.obj = LeapSecondData.from_standard_source()
+        else:  # pragma no cover
+            ctx.obj = LeapSecondData.from_url(url)
+
+
+@cli.command()
+@click.pass_context
+def info(ctx: click.Context) -> None:
+    """Show information about leap second database"""
+    leap_second_data = ctx.obj
+    print(f"Last updated: {leap_second_data.last_updated:%Y-%m-%d}")
+    print(f"Valid until:  {leap_second_data.valid_until:%Y-%m-%d}")
+    # The first leap_seconds entry
+    print(f"{len(leap_second_data.leap_seconds)-1} leap seconds")
+
+
+@cli.command()
+@click.pass_context
+@click.option("--tai/--utc", "is_tai", default=False)
+@click.argument("timestamp", type=UTCDateTime(), default=utcnow(), metavar="TIMESTAMP")
+def offset(ctx: click.Context, *, is_tai: bool, timestamp: datetime.datetime) -> None:
+    """Get the UTC offset for a given moment, in seconds"""
+    leap_second_data = ctx.obj
+    if is_tai:
+        timestamp = timestamp.replace(tzinfo=tai)
+    print(f"{leap_second_data.tai_offset(timestamp).total_seconds():.0f}")
+
+
+@cli.command()
+@click.pass_context
+@click.option("--to-tai/--to-utc", default=True)
+@click.argument("timestamp", type=UTCDateTime(), default=None, required=False, metavar="TIMESTAMP")
+def convert(ctx: click.Context, *, to_tai: bool, timestamp: datetime.datetime | None = None) -> None:
+    """Convert timestamps between TAI and UTC"""
+    leap_second_data = ctx.obj
+    if to_tai:
+        if timestamp is None:
+            timestamp = utcnow()
+        when_tai = leap_second_data.to_tai(timestamp)
+        print(f"{when_tai:%Y-%m-%d %H:%M:%S} TAI")
+    else:
+        if timestamp is None:  # pragma no cover
+            raise click.UsageError("--to-utc requires explicit timestamp", ctx)
+        when_utc = leap_second_data.tai_to_utc(timestamp.replace(tzinfo=tai))
+        if when_utc.fold:
+            print(f"{when_utc:%Y-%m-%d %H:%M:60} UTC")
+        else:
+            print(f"{when_utc:%Y-%m-%d %H:%M:%S} UTC")
+
+
+@cli.command()
+@click.pass_context
+@click.argument("timestamp", type=UTCDateTime(), default=utcnow(), metavar="TIMESTAMP")
+def next_leapsecond(ctx: click.Context, *, timestamp: datetime.datetime) -> None:
+    """Get the next leap second after a given UTC timestamp"""
+    leap_second_data = ctx.obj
+    ls = min(
+        (ls for ls in leap_second_data.leap_seconds if ls.start > timestamp),
+        default=None,
+        key=lambda x: x.start,
+    )
+    if ls is None:
+        print("None")
+    else:
+        print(f"{ls.start:%Y-%m-%d %H:%M:%S} UTC")
+
+
+@cli.command()
+@click.pass_context
+@click.argument("timestamp", type=UTCDateTime(), default=utcnow(), metavar="TIMESTAMP")
+def previous_leapsecond(ctx: click.Context, *, timestamp: datetime.datetime) -> None:
+    """Get the last leap second before a given UTC timestamp"""
+    leap_second_data = ctx.obj
+    ls = max(
+        (ls for ls in leap_second_data.leap_seconds if ls.start < timestamp),
+        default=None,
+        key=lambda x: x.start,
+    )
+    if ls is None:
+        print("None")
+    else:
+        print(f"{ls.start:%Y-%m-%d %H:%M:%S} UTC")
+
+
+@cli.command()
+@click.argument(
+    "start",
+    type=UTCDateTime(),
+    default=datetime.datetime(1972, 1, 1, tzinfo=utc),
+    metavar="START-TIMESTAMP",
+)
+@click.argument("end", type=UTCDateTime(), default=utcnow(), metavar="[END-TIMESTAMP]")
+@click.pass_context
+def table(ctx: click.Context, *, start: datetime.datetime, end: datetime.datetime) -> None:
+    """Print information about leap seconds"""
+    leap_second_data = ctx.obj
+    for leap_second in leap_second_data.leap_seconds:  # pragma no branch
+        if leap_second.start < start:
+            continue
+        if leap_second.start > end:
+            break
+        print(f"{leap_second.start:%Y-%m-%d}: {leap_second.tai_offset.total_seconds():.0f}")
+
+
+if __name__ == "__main__":  # pragma no cover
+    cli()

{wwvb → leapseconddata}/__version__.py

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

wwvb-4.1.0a0.dist-info/METADATA

@@ -0,0 +1,60 @@
+Metadata-Version: 2.1
+Name: wwvb
+Version: 4.1.0a0
+Summary: Use the list of known and scheduled leap seconds
+Author-email: Jeff Epler <jepler@gmail.com>
+Project-URL: Source, https://github.com/jepler/leapseconddata
+Project-URL: Documentation, https://leapseconddata.readthedocs.io/en/latest/
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: click
+
+<!--
+SPDX-FileCopyrightText: 2021 Jeff Epler
+
+SPDX-License-Identifier: GPL-3.0-only
+-->
+[![Test leapseconddata](https://github.com/jepler/leapseconddata/actions/workflows/test.yml/badge.svg)](https://github.com/jepler/leapseconddata/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/leapseconddata)](https://pypi.org/project/leapseconddata)
+[![Documentation Status](https://readthedocs.org/projects/leapseconddata/badge/?version=latest)](https://leapseconddata.readthedocs.io/en/latest/?badge=latest)
+
+# Python Leap Second List
+
+Leap seconds are corrections applied irregularly so that the UTC day stays
+fixed to the earth's rotation.
+
+This module provides a class for parsing and validating the standard
+`leap-seconds.list` file.  Once parsed, it is possible to retrieve the
+full list of leap seconds, or find the TAI-UTC offset for any UTC time.
+
+# `leapsecond` program
+
+Access leap second data from the command line.
+
+```
+Usage: leapsecond [OPTIONS] COMMAND [ARGS]...
+
+  Access leap second database information
+
+Options:
+  --url TEXT            URL for leap second data (unspecified to use default
+                        source)
+  --debug / --no-debug
+  --help                Show this message and exit.
+
+Commands:
+  convert              Convert timestamps between TAI and UTC
+  info                 Show information about leap second database
+  next-leapsecond      Get the next leap second after a given UTC timestamp
+  offset               Get the UTC offset for a given moment, in seconds
+  previous-leapsecond  Get the last leap second before a given UTC timestamp
+  table                Print information about leap seconds
+```

wwvb-4.1.0a0.dist-info/RECORD

@@ -0,0 +1,9 @@
+leapseconddata/__init__.py,sha256=UyHCvvcJjbIugNEEQDf45HmhzFiIe77fNVGRMm7eNdg,13017
+leapseconddata/__main__.py,sha256=c26T1gFoVwh1goK0_mRCQ3-lAsz8eCFYf8aFi0nESf8,5405
+leapseconddata/__version__.py,sha256=XeG8WsGuH3HJ5DBhMc289w1eiYW9-G0-4h58Y3MV650,413
+leapseconddata/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wwvb-4.1.0a0.dist-info/METADATA,sha256=KmLslzML53yHVtNANGMbfuL4t4Xu5OvevkIC85tnWEw,2496
+wwvb-4.1.0a0.dist-info/WHEEL,sha256=Z4pYXqR_rTB7OWNDYFOm1qRk0RX6GFP2o8LgvP453Hk,91
+wwvb-4.1.0a0.dist-info/entry_points.txt,sha256=Ca5FvuhALDcLhQrO8H7l91Bg0hjkxkzLEwLU-9qY9dk,59
+wwvb-4.1.0a0.dist-info/top_level.txt,sha256=82tQRfAH4hrno1b9AR-UhFUHrbBxENUJ2aUtEH-ctTs,15
+wwvb-4.1.0a0.dist-info/RECORD,,

wwvb-4.1.0a0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+leapsecond = leapseconddata.__main__:cli

wwvb-4.1.0a0.dist-info/top_level.txt

@@ -0,0 +1 @@
+leapseconddata