lvtime 0.3.0__py3-none-any.whl

lvtime/__init__.py

@@ -0,0 +1,49 @@
+"""Lossless LabVIEW 128-bit timestamp to and from datetime, UTC, sub-microsecond preserved."""
+
+from __future__ import annotations
+
+from ._codec import ByteOrder
+from ._convert import (
+    LABVIEW_UNIX_EPOCH_OFFSET,
+    from_datetime,
+    from_float,
+    from_unix,
+    to_datetime,
+    to_float,
+    to_unix,
+)
+from ._exact import (
+    from_decimal,
+    from_unix_decimal,
+    to_decimal,
+    to_unix_decimal,
+)
+from ._timestamp import (
+    LVTimestamp,
+    read_timestamp,
+    read_timestamps,
+    write_timestamp,
+    write_timestamps,
+)
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "LABVIEW_UNIX_EPOCH_OFFSET",
+    "ByteOrder",
+    "LVTimestamp",
+    "from_datetime",
+    "from_decimal",
+    "from_float",
+    "from_unix",
+    "from_unix_decimal",
+    "read_timestamp",
+    "read_timestamps",
+    "to_datetime",
+    "to_decimal",
+    "to_float",
+    "to_unix",
+    "to_unix_decimal",
+    "write_timestamp",
+    "write_timestamps",
+]

lvtime/__main__.py

@@ -0,0 +1,10 @@
+"""Run the command line with ``python -m lvtime``."""
+
+from __future__ import annotations
+
+import sys
+
+from ._cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

lvtime/_cli.py

@@ -0,0 +1,97 @@
+"""The ``lvtime`` command line: decode and encode the 16-byte on-disk form."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+
+from . import __version__
+from ._codec import ByteOrder
+from ._timestamp import LVTimestamp, read_timestamp, write_timestamp
+
+_DESCRIPTION = "Decode and encode LabVIEW 128-bit timestamps (1904 epoch)."
+_EPILOG = """\
+examples:
+  lvtime decode 00000000e32589408000000000000000
+  echo 00000000e32589408000000000000000 | lvtime decode
+  lvtime decode --format fields 00000000e32589408000000000000000
+  lvtime decode --format decimal 00000000e32589408000000000000000
+  lvtime encode 2024-10-04T12:00:00.5+00:00
+  lvtime encode --byteorder little 2024-10-04T12:00:00Z
+"""
+
+
+def _read_arg(value: str | None) -> str:
+    text = sys.stdin.read() if value is None else value
+    text = text.strip()
+    if not text:
+        raise ValueError("no input given (pass an argument or pipe it on stdin)")
+    return text
+
+
+def _parse_iso(text: str) -> datetime:
+    dt = datetime.fromisoformat(text.replace("Z", "+00:00"))
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt
+
+
+def _decode(hex_text: str, byteorder: ByteOrder, fmt: str) -> str:
+    ts = read_timestamp(bytes.fromhex(hex_text), byteorder)
+    if fmt == "iso":
+        return ts.to_datetime().isoformat()
+    if fmt == "fields":
+        dt = ts.to_datetime()
+        return f"seconds={ts.seconds} frac={ts.frac} iso={dt.isoformat()} unix={ts.to_unix()!r}"
+    if fmt == "decimal":
+        return f"epoch1904={ts.to_decimal()} unix={ts.to_unix_decimal()}"
+    payload = {
+        "seconds": ts.seconds,
+        "frac": ts.frac,
+        "iso": ts.to_datetime().isoformat(),
+        "unix": ts.to_unix(),
+    }
+    return json.dumps(payload)
+
+
+def _encode(iso_text: str, byteorder: ByteOrder) -> str:
+    return write_timestamp(LVTimestamp.from_datetime(_parse_iso(iso_text)), byteorder).hex()
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="lvtime",
+        description=_DESCRIPTION,
+        epilog=_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"lvtime {__version__}")
+    subs = parser.add_subparsers(dest="command", required=True)
+
+    decode = subs.add_parser("decode", help="16-byte hex timestamp to an ISO datetime")
+    decode.add_argument("hex", nargs="?", help="32 hex chars; read from stdin if omitted")
+    decode.add_argument("--byteorder", choices=["big", "little"], default="big")
+    decode.add_argument("--format", choices=["iso", "fields", "json", "decimal"], default="iso")
+
+    encode = subs.add_parser("encode", help="ISO datetime to a 16-byte hex timestamp")
+    encode.add_argument("iso", nargs="?", help="ISO datetime (UTC if naive); stdin if omitted")
+    encode.add_argument("--byteorder", choices=["big", "little"], default="big")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the ``lvtime`` console script. Returns a process exit code."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "decode":
+            line = _decode(_read_arg(args.hex), args.byteorder, args.format)
+        else:
+            line = _encode(_read_arg(args.iso), args.byteorder)
+    except ValueError as error:
+        print(f"lvtime: {error}", file=sys.stderr)
+        return 1
+    print(line)
+    return 0

lvtime/_codec.py

@@ -0,0 +1,61 @@
+"""The 16-byte on-disk form of a LabVIEW timestamp, big- or little-endian.
+
+The default layout is the one LabVIEW "Flatten To String" and the timestamp
+channels in TDMS write: eight bytes of signed whole seconds followed by eight
+bytes of unsigned fraction, each most significant byte first. Pass ``"little"``
+for the byte-reversed form some payloads use.
+"""
+
+from __future__ import annotations
+
+import struct
+from typing import Literal
+
+ByteOrder = Literal["big", "little"]
+
+_LAYOUTS: dict[str, struct.Struct] = {
+    "big": struct.Struct(">qQ"),
+    "little": struct.Struct("<qQ"),
+}
+
+TIMESTAMP_SIZE = _LAYOUTS["big"].size
+
+
+def _layout(byteorder: ByteOrder) -> struct.Struct:
+    try:
+        return _LAYOUTS[byteorder]
+    except KeyError:
+        raise ValueError(f"byteorder must be 'big' or 'little', got {byteorder!r}") from None
+
+
+def pack(seconds: int, frac: int, byteorder: ByteOrder = "big") -> bytes:
+    """Encode a ``(seconds, frac)`` pair as 16 bytes in the given byte order."""
+    return _layout(byteorder).pack(seconds, frac)
+
+
+def unpack(data: bytes, byteorder: ByteOrder = "big") -> tuple[int, int]:
+    """Decode 16 bytes into a ``(seconds, frac)`` pair.
+
+    Raises :class:`ValueError` if the buffer is not exactly 16 bytes long.
+    """
+    if len(data) != TIMESTAMP_SIZE:
+        raise ValueError(f"expected {TIMESTAMP_SIZE} bytes, got {len(data)}")
+    seconds, frac = _layout(byteorder).unpack(data)
+    return seconds, frac
+
+
+def pack_many(pairs: list[tuple[int, int]], byteorder: ByteOrder = "big") -> bytes:
+    """Encode a list of ``(seconds, frac)`` pairs into one contiguous buffer."""
+    layout = _layout(byteorder)
+    return b"".join(layout.pack(seconds, frac) for seconds, frac in pairs)
+
+
+def unpack_many(data: bytes, byteorder: ByteOrder = "big") -> list[tuple[int, int]]:
+    """Decode a buffer of back-to-back 16-byte records into pairs.
+
+    Raises :class:`ValueError` if the length is not a multiple of 16 bytes.
+    """
+    if len(data) % TIMESTAMP_SIZE != 0:
+        raise ValueError(f"length must be a multiple of {TIMESTAMP_SIZE} bytes, got {len(data)}")
+    layout = _layout(byteorder)
+    return [layout.unpack_from(data, offset) for offset in range(0, len(data), TIMESTAMP_SIZE)]

lvtime/_convert.py

@@ -0,0 +1,98 @@
+"""Convert LabVIEW absolute time to and from datetime, Unix time and float seconds.
+
+LabVIEW absolute time counts from 1904-01-01 00:00:00 UTC. A value is a signed
+64-bit count of whole seconds plus an unsigned 64-bit fraction in units of
+2**-64 seconds. :mod:`datetime` resolves only to microseconds and a float holds
+about 52 bits of mantissa, so those two views round; the lossless path is the
+integer pair itself.
+"""
+
+from __future__ import annotations
+
+import math
+from datetime import datetime, timedelta, timezone
+
+# Seconds between the LabVIEW epoch (1904-01-01) and the Unix epoch (1970-01-01).
+LABVIEW_UNIX_EPOCH_OFFSET = 2082844800
+
+I64_MIN = -(2**63)
+I64_MAX = 2**63 - 1
+U64_MAX = 2**64 - 1
+
+_EPOCH = datetime(1904, 1, 1, tzinfo=timezone.utc)
+_MICROS_PER_SECOND = 1_000_000
+_FRAC_UNIT = 1 << 64
+_HALF_FRAC_UNIT = 1 << 63
+
+
+def check_seconds(seconds: int) -> None:
+    """Reject whole-second counts that do not fit a signed 64-bit integer."""
+    if not I64_MIN <= seconds <= I64_MAX:
+        raise ValueError(f"seconds must fit a signed 64-bit integer, got {seconds}")
+
+
+def check_frac(frac: int) -> None:
+    """Reject fractions outside the unsigned 64-bit range."""
+    if not 0 <= frac <= U64_MAX:
+        raise ValueError(f"frac must be in [0, 2**64), got {frac}")
+
+
+def to_datetime(seconds: int, frac: int = 0) -> datetime:
+    """Convert a LabVIEW timestamp to a UTC-aware :class:`datetime.datetime`.
+
+    ``seconds`` is whole seconds since 1904-01-01 UTC and ``frac`` the 2**-64 s
+    fraction. The fraction is rounded to the nearest microsecond. Raises
+    :class:`ValueError` if ``frac`` is out of range and :class:`OverflowError`
+    if the instant falls outside the range of :class:`datetime.datetime`.
+    """
+    check_frac(frac)
+    micros = (frac * _MICROS_PER_SECOND + _HALF_FRAC_UNIT) >> 64
+    return _EPOCH + timedelta(microseconds=seconds * _MICROS_PER_SECOND + micros)
+
+
+def from_datetime(dt: datetime) -> tuple[int, int]:
+    """Convert a timezone-aware :class:`datetime.datetime` to ``(seconds, frac)``.
+
+    The input must carry a timezone so the instant is unambiguous; a naive
+    datetime raises :class:`ValueError`. The microsecond field maps back to the
+    nearest 2**-64 s fraction, so a round trip is exact to the microsecond.
+    """
+    if dt.tzinfo is None or dt.tzinfo.utcoffset(dt) is None:
+        raise ValueError("dt must be timezone-aware")
+    delta = dt - _EPOCH
+    total_micros = (delta.days * 86400 + delta.seconds) * _MICROS_PER_SECOND + delta.microseconds
+    seconds, micro_remainder = divmod(total_micros, _MICROS_PER_SECOND)
+    frac = (micro_remainder * _FRAC_UNIT + _MICROS_PER_SECOND // 2) // _MICROS_PER_SECOND
+    check_seconds(seconds)
+    return seconds, frac
+
+
+def to_float(seconds: int, frac: int = 0) -> float:
+    """Return seconds since the 1904 epoch as a float (LabVIEW DBL coercion).
+
+    This matches wiring a LabVIEW timestamp into a double. A float keeps only
+    about 52 bits of mantissa, so sub-microsecond detail is lost.
+    """
+    check_frac(frac)
+    return seconds + frac / _FRAC_UNIT
+
+
+def from_float(value: float) -> tuple[int, int]:
+    """Convert seconds since the 1904 epoch (as a float) to ``(seconds, frac)``."""
+    seconds = math.floor(value)
+    frac = round((value - seconds) * _FRAC_UNIT)
+    if frac >= _FRAC_UNIT:
+        seconds += 1
+        frac -= _FRAC_UNIT
+    check_seconds(seconds)
+    return seconds, frac
+
+
+def to_unix(seconds: int, frac: int = 0) -> float:
+    """Return Unix time (float seconds since 1970-01-01 UTC), like :func:`time.time`."""
+    return to_float(seconds, frac) - LABVIEW_UNIX_EPOCH_OFFSET
+
+
+def from_unix(value: float) -> tuple[int, int]:
+    """Convert Unix time (float seconds since 1970-01-01 UTC) to ``(seconds, frac)``."""
+    return from_float(value + LABVIEW_UNIX_EPOCH_OFFSET)

lvtime/_exact.py

@@ -0,0 +1,66 @@
+"""Exact conversions through integers and :class:`~decimal.Decimal`, no float.
+
+A float keeps only about 52 bits of mantissa, so 0.8 s lands on
+``0xCCCCCCCCCCCCC000`` in 2**-64 units instead of its true ``0xCCCCCCCCCCCCCCCD``.
+These helpers never touch a float, so they reproduce the exact fixed-point value
+NI documents and keep the full 2**-64 s resolution end to end.
+"""
+
+from __future__ import annotations
+
+from decimal import ROUND_FLOOR, ROUND_HALF_EVEN, Context, Decimal, localcontext
+
+from ._convert import LABVIEW_UNIX_EPOCH_OFFSET, check_frac, check_seconds
+
+# 2**-64 = 5**64 * 10**-64 exactly, so a fraction scaled this way is exact.
+_FRAC_UNIT = 1 << 64
+_POW5_64 = 5**64
+# Enough precision for a 19-digit second count plus 64 fractional digits.
+_CONTEXT = Context(prec=96)
+
+ExactInput = Decimal | int | str
+
+
+def _as_decimal(value: ExactInput) -> Decimal:
+    if isinstance(value, float):  # pragma: no cover - guarded by typing too
+        raise TypeError("pass a Decimal, int or str, not a float, for an exact value")
+    return Decimal(value)
+
+
+def to_decimal(seconds: int, frac: int = 0) -> Decimal:
+    """Return seconds since the 1904 epoch as an exact :class:`~decimal.Decimal`."""
+    check_frac(frac)
+    with localcontext(_CONTEXT):
+        return Decimal(seconds) + Decimal(frac * _POW5_64).scaleb(-64)
+
+
+def from_decimal(value: ExactInput) -> tuple[int, int]:
+    """Convert exact seconds since the 1904 epoch to a ``(seconds, frac)`` pair.
+
+    Accepts a :class:`~decimal.Decimal`, :class:`int` or :class:`str`. A
+    :class:`float` is refused so a lossy value cannot slip in; use
+    :func:`lvtime.from_float` for the float path.
+    """
+    with localcontext(_CONTEXT):
+        total = _as_decimal(value)
+        seconds = int(total.to_integral_value(rounding=ROUND_FLOOR))
+        remainder = total - seconds
+        frac = int((remainder * _FRAC_UNIT).to_integral_value(rounding=ROUND_HALF_EVEN))
+    if frac == _FRAC_UNIT:
+        seconds += 1
+        frac = 0
+    check_seconds(seconds)
+    check_frac(frac)
+    return seconds, frac
+
+
+def to_unix_decimal(seconds: int, frac: int = 0) -> Decimal:
+    """Return exact Unix time (seconds since 1970-01-01 UTC) as a :class:`~decimal.Decimal`."""
+    with localcontext(_CONTEXT):
+        return to_decimal(seconds, frac) - LABVIEW_UNIX_EPOCH_OFFSET
+
+
+def from_unix_decimal(value: ExactInput) -> tuple[int, int]:
+    """Convert exact Unix time (seconds since 1970-01-01 UTC) to a ``(seconds, frac)`` pair."""
+    with localcontext(_CONTEXT):
+        return from_decimal(_as_decimal(value) + LABVIEW_UNIX_EPOCH_OFFSET)

lvtime/_timestamp.py

@@ -0,0 +1,120 @@
+"""The lossless :class:`LVTimestamp` integer pair and its byte and stream helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from decimal import Decimal
+
+from . import _codec, _convert, _exact
+from ._codec import ByteOrder
+from ._exact import ExactInput
+
+
+@dataclass(frozen=True)
+class LVTimestamp:
+    """A LabVIEW absolute time held without loss as two integers.
+
+    ``seconds`` is the signed 64-bit count of whole seconds since 1904-01-01
+    00:00:00 UTC; ``frac`` is the unsigned 64-bit fraction in units of 2**-64 s.
+    Both fields are validated on construction.
+    """
+
+    seconds: int
+    frac: int = 0
+
+    def __post_init__(self) -> None:
+        _convert.check_seconds(self.seconds)
+        _convert.check_frac(self.frac)
+
+    def to_datetime(self) -> datetime:
+        """Return this instant as a UTC-aware datetime, rounded to the microsecond."""
+        return _convert.to_datetime(self.seconds, self.frac)
+
+    @classmethod
+    def from_datetime(cls, dt: datetime) -> LVTimestamp:
+        """Build a timestamp from a timezone-aware datetime."""
+        seconds, frac = _convert.from_datetime(dt)
+        return cls(seconds, frac)
+
+    def to_unix(self) -> float:
+        """Return this instant as Unix time (float seconds since 1970-01-01 UTC)."""
+        return _convert.to_unix(self.seconds, self.frac)
+
+    @classmethod
+    def from_unix(cls, value: float) -> LVTimestamp:
+        """Build a timestamp from Unix time (float seconds since 1970-01-01 UTC)."""
+        seconds, frac = _convert.from_unix(value)
+        return cls(seconds, frac)
+
+    def to_float(self) -> float:
+        """Return seconds since the 1904 epoch as a float (LabVIEW DBL coercion)."""
+        return _convert.to_float(self.seconds, self.frac)
+
+    @classmethod
+    def from_float(cls, value: float) -> LVTimestamp:
+        """Build a timestamp from float seconds since the 1904 epoch."""
+        seconds, frac = _convert.from_float(value)
+        return cls(seconds, frac)
+
+    def to_decimal(self) -> Decimal:
+        """Return seconds since the 1904 epoch as an exact Decimal (no float)."""
+        return _exact.to_decimal(self.seconds, self.frac)
+
+    @classmethod
+    def from_decimal(cls, value: ExactInput) -> LVTimestamp:
+        """Build a timestamp from exact seconds since the epoch (Decimal, int or str)."""
+        seconds, frac = _exact.from_decimal(value)
+        return cls(seconds, frac)
+
+    def to_unix_decimal(self) -> Decimal:
+        """Return this instant as exact Unix time (Decimal seconds since 1970-01-01 UTC)."""
+        return _exact.to_unix_decimal(self.seconds, self.frac)
+
+    @classmethod
+    def from_unix_decimal(cls, value: ExactInput) -> LVTimestamp:
+        """Build a timestamp from exact Unix time (Decimal, int or str)."""
+        seconds, frac = _exact.from_unix_decimal(value)
+        return cls(seconds, frac)
+
+    def to_bytes(self, byteorder: ByteOrder = "big") -> bytes:
+        """Return the 16-byte on-disk form in the given byte order (default big)."""
+        return _codec.pack(self.seconds, self.frac, byteorder)
+
+    @classmethod
+    def from_bytes(cls, data: bytes, byteorder: ByteOrder = "big") -> LVTimestamp:
+        """Build a timestamp from its 16-byte on-disk form (default big-endian)."""
+        seconds, frac = _codec.unpack(data, byteorder)
+        return cls(seconds, frac)
+
+    def hex(self, byteorder: ByteOrder = "big") -> str:
+        """Return the 16-byte on-disk form as a 32-character hex string (default big)."""
+        return self.to_bytes(byteorder).hex()
+
+    @classmethod
+    def from_hex(cls, text: str, byteorder: ByteOrder = "big") -> LVTimestamp:
+        """Build a timestamp from a 32-character hex string (default big-endian)."""
+        return cls.from_bytes(bytes.fromhex(text), byteorder)
+
+
+def read_timestamp(data: bytes, byteorder: ByteOrder = "big") -> LVTimestamp:
+    """Read a :class:`LVTimestamp` from its 16-byte on-disk form (default big-endian)."""
+    return LVTimestamp.from_bytes(data, byteorder)
+
+
+def write_timestamp(timestamp: LVTimestamp, byteorder: ByteOrder = "big") -> bytes:
+    """Write a :class:`LVTimestamp` as its 16-byte on-disk form (default big-endian)."""
+    return timestamp.to_bytes(byteorder)
+
+
+def read_timestamps(data: bytes, byteorder: ByteOrder = "big") -> list[LVTimestamp]:
+    """Read back-to-back 16-byte records into a list of :class:`LVTimestamp`.
+
+    Raises :class:`ValueError` if the length is not a multiple of 16 bytes.
+    """
+    return [LVTimestamp(seconds, frac) for seconds, frac in _codec.unpack_many(data, byteorder)]
+
+
+def write_timestamps(timestamps: list[LVTimestamp], byteorder: ByteOrder = "big") -> bytes:
+    """Write a list of :class:`LVTimestamp` as one contiguous buffer of 16-byte records."""
+    return _codec.pack_many([(ts.seconds, ts.frac) for ts in timestamps], byteorder)

lvtime-0.3.0.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.5
+Name: lvtime
+Version: 0.3.0
+Summary: Lossless LabVIEW 128-bit timestamp (1904 epoch) to and from datetime, UTC, sub-microsecond preserved.
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/lvtime
+Project-URL: Issues, https://github.com/JaviLianes8/lvtime/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/lvtime/blob/main/CHANGELOG.md
+Project-URL: LinkedIn, https://www.linkedin.com/in/jlianes/
+Project-URL: Funding, https://buymeacoffee.com/jlianesglrs
+Author-email: Javier Lianes <javier@lianes8studio.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 1904,datetime,epoch,labview,ni,tdms,timestamp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lvtime
+
+Lossless LabVIEW 128-bit timestamp (1904 epoch) to and from datetime, UTC, sub-microsecond preserved.
+
+## Install
+
+```
+pip install lvtime
+```
+
+## Usage
+
+```python
+from datetime import datetime, timezone
+from lvtime import LVTimestamp, to_datetime, from_datetime, read_timestamp, write_timestamp
+
+# A LabVIEW absolute time is a signed 64-bit second count since 1904-01-01 UTC
+# plus an unsigned 64-bit fraction in units of 2**-64 s.
+ts = LVTimestamp(seconds=3810888000, frac=1 << 63)  # 2024-10-04 12:00:00.5 UTC
+ts.to_datetime()  # datetime(2024, 10, 4, 12, 0, 0, 500000, tzinfo=UTC)
+
+# Build one from an aware datetime (naive input is rejected).
+LVTimestamp.from_datetime(datetime(2024, 10, 4, tzinfo=timezone.utc))
+
+# Read and write the 16-byte big-endian on-disk form (TDMS / "Flatten To String").
+raw = write_timestamp(ts)  # 16 bytes: 8 signed seconds + 8 unsigned fraction
+read_timestamp(raw) == ts  # True, every bit preserved
+
+# The plain functions take and return the integer pair directly.
+to_datetime(3810888000, 1 << 63)
+seconds, frac = from_datetime(datetime(2024, 10, 4, tzinfo=timezone.utc))
+```
+
+`LVTimestamp` is the lossless carrier: it keeps the full 2**-64 s fraction, so two
+instants a single fraction unit apart stay distinct even though they collapse to the
+same microsecond when you ask for a `datetime`.
+
+### Unix time and float seconds
+
+```python
+ts.to_unix()  # 1728043200.5, float seconds since 1970-01-01 UTC
+LVTimestamp.from_unix(1728043200.5)
+ts.to_float()  # 3810888000.5, seconds since 1904 (LabVIEW coerce-to-double)
+LVTimestamp.from_float(3810888000.5)
+```
+
+Floats hold about 52 bits of mantissa, so these views are convenient but lossy below
+the microsecond. The integer pair stays exact.
+
+### Exact values with Decimal
+
+When you need the real value and not a float, convert through `Decimal` (or plain `int`
+or a `str`). This is the only way to reproduce NI's own documented bytes for a value
+like -5.2 s, which a float cannot represent:
+
+```python
+from decimal import Decimal
+from lvtime import LVTimestamp, to_decimal, from_decimal
+
+from_decimal("-5.2")  # (-6, 14757395258967641293) == {0xFFFFFFFFFFFFFFFA, 0xCCCCCCCCCCCCCCCD}
+LVTimestamp.from_decimal("-5.2").hex()  # 'fffffffffffffffacccccccccccccccd', the exact NI bytes
+
+LVTimestamp(10, 1 << 63).to_decimal()  # Decimal('10.5'), exact seconds since 1904
+to_decimal(0, 1)  # Decimal('5.42...E-20'), one 2**-64 fraction unit, held exactly
+```
+
+`from_decimal` refuses a `float` on purpose, so a lossy value cannot slip in unnoticed;
+reach for `from_float` when a float is really what you have. There are `to_unix_decimal`
+and `from_unix_decimal` for the Unix-epoch view, and `LVTimestamp.hex()` /
+`LVTimestamp.from_hex()` for the hex string you usually hold the flattened form as.
+
+### Endianness and batches
+
+```python
+ts.to_bytes("little")  # byte-reversed 16-byte form
+LVTimestamp.from_bytes(raw, "little")
+
+from lvtime import read_timestamps, write_timestamps
+
+blob = write_timestamps([ts, LVTimestamp(0, 0)])  # back-to-back 16-byte records
+read_timestamps(blob)  # [LVTimestamp(...), LVTimestamp(0, 0)]
+```
+
+## Command line
+
+Installing the package puts an `lvtime` command on the path (also runnable as
+`python -m lvtime`):
+
+```
+$ lvtime decode 00000000e32589408000000000000000
+2024-10-04T12:00:00.500000+00:00
+
+$ lvtime decode --format fields 00000000e32589408000000000000000
+seconds=3810888000 frac=9223372036854775808 iso=2024-10-04T12:00:00.500000+00:00 unix=1728043200.5
+
+$ lvtime encode 2024-10-04T12:00:00.5+00:00
+00000000e32589408000000000000000
+
+$ lvtime decode --format decimal 00000000e32589408000000000000000
+epoch1904=3810888000.5000... unix=1728043200.5000...
+
+$ echo 00000000e32589408000000000000000 | lvtime decode
+2024-10-04T12:00:00.500000+00:00
+```
+
+`decode` also takes `--format json`, `--format decimal` (exact seconds, no float) and
+`--byteorder little`; `encode` reads the ISO datetime from an argument or stdin and treats
+a naive datetime as UTC. `lvtime --version` prints the version, and a bad input goes to
+stderr with exit code 1. See `lvtime --help`.
+
+## How it works
+
+A LabVIEW absolute time is 128 bits of fixed point: a **signed** 64-bit count of whole
+seconds since **1904-01-01 00:00:00 UTC** followed by an **unsigned** 64-bit fraction in
+units of 2**-64 s. On disk ("Flatten To String", TDMS timestamp channels) the two fields
+are stored big-endian, most significant byte first, for 16 bytes total. Converting to a
+`datetime` means scaling the fraction to microseconds and adding to the 1904 epoch;
+converting back maps the microsecond field to the nearest fraction unit. The full integer
+pair is the only representation that keeps every bit.
+
+## Two caveats worth knowing
+
+The [NI timestamp overview](https://www.ni.com/en/support/documentation/supplemental/08/labview-timestamp-overview.html)
+lists example values. Two of them trip people up, and `lvtime` is built around the byte
+values rather than the labels:
+
+- **The 0.8 fraction only survives in fixed point.** 0.8 s is exactly
+  `0xCCCCCCCCCCCCCCCD` in 2**-64 units (so -5.2 s is `{0xFFFFFFFFFFFFFFFA, 0xCCCCCCCCCCCCCCCD}`).
+  Build that same fraction from a C `double` and it collapses to `0xCCCCCCCCCCCCC000`, losing
+  the low bits, which NI's own page notes. `from_float(-5.2)` reproduces the lossy
+  `0xCCCCCCCCCCCCC000`; `from_decimal("-5.2")` reproduces the exact `0xCCCCCCCCCCCCCCCD`. Use
+  the Decimal path when the bytes have to match.
+- **NI's page mislabels the 2002 row by a day.** It labels `{3092601600, 0}` (`0xB8555B00`)
+  as "01/01/2002 00:00:00 UTC", but 3092601600 seconds after the 1904 epoch is
+  2001-12-31 00:00:00 UTC, one day earlier. `lvtime` decodes the byte value, so it returns
+  the correct 2001-12-31.
+
+## Why
+
+LabVIEW stores absolute time as a 128-bit fixed-point value: a **signed** 64-bit count
+of whole seconds since **1904-01-01 00:00:00 UTC** and an **unsigned** 64-bit fraction in
+units of 2**-64 s ([NI, LabVIEW Timestamp Overview](https://www.ni.com/en/support/documentation/supplemental/08/labview-timestamp-overview.html)).
+Two things trip people up every time:
+
+- **The 1904 epoch.** The Unix offset is exactly `2082844800` seconds. Hand-rolled code
+  that re-derives or mistypes this constant lands "off by 300 years" or by a timezone, a
+  recurring complaint on the NI and LAVA forums.
+- **The precision.** The format resolves far below a nanosecond. Round-tripping through a
+  C `double` or a `datetime` throws most of that away (about a 0.5 microsecond step through
+  a double). npTDMS's default read path surfaces timestamps as NumPy `datetime64` truncated
+  to microseconds, which loses the fraction; it does expose the lossless pair with
+  `raw_timestamps=True`, but only for timestamps read from inside a TDMS file.
+
+Inside a TDMS file, then, npTDMS already covers the lossless case. What is missing is a
+standalone codec for the raw 16-byte form that is **not** part of a TDMS file: Flatten To
+String blobs, protocol payloads, anything where you hold the bytes directly. The LabVIEW-side
+toolkits (OpenG, VIPM/JKI) run inside LabVIEW and ship no Python reader. `lvtime` fills that
+gap: a tiny, typed, zero-dependency (stdlib only) library that keeps the exact integer pair
+with the correct signedness, reads and writes the 16-byte on-disk form (big- or little-endian)
+independent of any file container, and converts to a UTC-aware `datetime` only when you ask
+(rounded to the microsecond, which is all `datetime` can hold).
+
+## Scope
+
+`lvtime` handles the absolute-time value itself: the integer pair, the 16-byte record, the
+`datetime` conversion, and the Unix and float-seconds views. It does not parse whole TDMS or
+flattened-data files; it is the piece you reach for once you have the 16 raw bytes in hand, or
+the seconds-and-fraction pair you need to turn into a real instant. LabVIEW follows the
+Gregorian calendar and ignores leap seconds, and so does this library.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

lvtime-0.3.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+lvtime/__init__.py,sha256=Vehc5E1RveI-BoMy3hKl7rGxfkiiQLwtMDyHpSVvAFk,935
+lvtime/__main__.py,sha256=GrBOs3F9Jhl8hc0WZuuZas1n2nc-S7ln-iNHvWSpg_w,175
+lvtime/_cli.py,sha256=AYVCrMvUoYRXSyT6Sx71odl9bDlcEA3paP6RDjnbFZ0,3528
+lvtime/_codec.py,sha256=i1K3ciulqh_ZMIGxo113AJvDoUdt3I-f9J1u3udsHdw,2232
+lvtime/_convert.py,sha256=gpqNefQ5ORC_XJzB1fct7Mem-Jc5AoeENmFlzAzAOJo,3820
+lvtime/_exact.py,sha256=liZRB92qdDi3YwZcpkYnuD_uVo08xXeycCJ-HfW0ojM,2594
+lvtime/_timestamp.py,sha256=XeDUoYm1uZL2vGLZbiOuDd0iWtMgGMPdDGAQSWHMAlU,4892
+lvtime/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lvtime-0.3.0.dist-info/METADATA,sha256=IvEXQd8cIuzSWuypPI6sc-jfrBI5suK3wIcVhb7piho,9237
+lvtime-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+lvtime-0.3.0.dist-info/entry_points.txt,sha256=9ZbJqIXEQRtw_P78u_g4HOkW300hRCZb8uP73fvrZ44,44
+lvtime-0.3.0.dist-info/licenses/LICENSE,sha256=wirD5nCA2aQa5UusK_1YHLBogI3CGcw23xAnulp3L_U,1091
+lvtime-0.3.0.dist-info/RECORD,,

lvtime-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

lvtime-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lvtime = lvtime._cli:main

lvtime-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Lianes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.