lvtime 0.3.0__tar.gz

lvtime-0.3.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

lvtime-0.3.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+buy_me_a_coffee: jlianesglrs

lvtime-0.3.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/

lvtime-0.3.0/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0]
+
+- Exact conversions through integer and `Decimal` arithmetic, never a float:
+  `to_decimal` / `from_decimal`, `to_unix_decimal` / `from_unix_decimal` and the matching
+  `LVTimestamp` methods. These reproduce NI's exact documented bytes for values a double
+  cannot hold, such as -5.2 s (`0xCCCCCCCCCCCCCCCD`), and keep the full 2**-64 s resolution.
+  `from_decimal` accepts `Decimal`, `int` or `str` and refuses `float` so a lossy value
+  cannot slip in.
+- `LVTimestamp.hex` / `LVTimestamp.from_hex`: round trip the 16-byte on-disk form as a
+  32-character hex string, byte-order aware.
+- CLI: `--version`, a `decode --format decimal` output (exact seconds since 1904 and since
+  the Unix epoch), and the console script entry point now resolves to `lvtime._cli:main`.
+- CLI errors now exit with code 1 (was 2) and still print to stderr.
+- Documented two NI caveats: the 0.8 fraction only survives in fixed point, and NI's own
+  page mislabels `{3092601600, 0}` as 2002 when the byte value is 2001-12-31 UTC.
+
+## [0.2.0]
+
+- `to_unix` / `from_unix` and `LVTimestamp.to_unix` / `LVTimestamp.from_unix`: convert
+  to and from Unix time (float seconds since 1970-01-01 UTC).
+- `to_float` / `from_float` and the matching `LVTimestamp` methods: seconds since the
+  1904 epoch as a float, the LabVIEW "coerce timestamp to double" view.
+- Little-endian support: every byte function and `LVTimestamp.to_bytes` / `from_bytes`
+  takes a `byteorder` argument (`"big"`, the default, or `"little"`).
+- `read_timestamps` / `write_timestamps`: batch read and write of back-to-back 16-byte
+  records.
+- `ByteOrder`: the `Literal["big", "little"]` type alias used by the byte functions.
+- `lvtime` command line (console script and `python -m lvtime`): `decode` a hex
+  timestamp to an ISO datetime (or `fields` / `json`) and `encode` an ISO datetime back,
+  reading from an argument or stdin.
+
+## [0.1.0]
+
+- First release.
+- `LVTimestamp`: a lossless, immutable integer pair (signed 64-bit seconds, unsigned
+  64-bit fraction of 2**-64 s) with range-checked construction.
+- `to_datetime` and `from_datetime`: convert between the integer pair and a UTC-aware
+  `datetime`, rounded to the microsecond, with the correct 1904 epoch and signedness.
+- `read_timestamp` and `write_timestamp`: read and write the 16-byte big-endian on-disk
+  form used by TDMS and "Flatten To String".
+- `LABVIEW_UNIX_EPOCH_OFFSET`: the exact 2082844800 s epoch constant.
+- Zero runtime dependencies; typed (`py.typed`), tested on the success and failure paths.

lvtime-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Thanks for taking the time. This project keeps a small, predictable shape.
+
+## Setup
+
+```
+pip install -r requirements-dev.txt
+```
+
+## Before you open a pull request
+
+- Keep public API in `src/lvtime/__init__.py`; internals live in `_`-prefixed modules.
+- Add a test for the behaviour you change. Tests inject time, disk and network; they
+  never touch the real thing.
+- Run `scripts/check.ps1` (format, lint, types, tests) and make sure it passes.
+- One logical change per commit, imperative subject line.
+
+Open an issue first if the change is large or shifts the public API.

lvtime-0.3.0/IMPROVEMENTS-round2.md

@@ -0,0 +1,70 @@
+# lvtime round 2: ranked improvements
+
+A ranked plan for the second substantial round on top of 0.2.0, driving the
+library toward a perfect, lossless LabVIEW timestamp codec. Every claim below was
+checked in a real Python REPL against the byte values published by NI before it
+was written down.
+
+## Ground truth
+
+The authoritative reference is NI's own documented value table (decimal and hex
+byte pairs), not the human-readable labels next to them:
+
+| Instant (value) | seconds | fraction (hex) |
+| --- | --- | --- |
+| epoch, 1904-01-01 00:00:00 UTC | 0 | 0x0 |
+| 0xB8555B00, 0x0 | 3092601600 | 0x0 |
+| -0.5 s | -1 (0xFFFFFFFFFFFFFFFF) | 0x8000000000000000 |
+| -5.2 s | -6 (0xFFFFFFFFFFFFFFFA) | 0xCCCCCCCCCCCCCCCD |
+
+Two caveats that fall straight out of this table drive the work:
+
+1. **NI's doc has an off-by-one-day label error.** The page labels
+   {3092601600, 0} as "01/01/2002 00:00:00.000 UTC", but 3092601600 seconds
+   after 1904-01-01 UTC is 2001-12-31 00:00:00 UTC, one day earlier. The byte
+   value is the truth; the label is wrong. `lvtime` already decodes this value to
+   2001-12-31, which is correct, and the contract test pins the byte value, not
+   NI's mislabel.
+2. **The 0.8 fraction only survives in fixed point.** 0.8 s is exactly
+   0xCCCCCCCCCCCCCCCD in 2**-64 units. Build that same fraction through a C
+   double and it collapses to 0xCCCCCCCCCCCCC000, losing the low bits. NI's page
+   says as much. So a float round trip cannot reproduce the real NI bytes; only
+   an exact integer or Decimal path can.
+
+## Ranked improvements
+
+1. **Exact Decimal path (no float in the round trip).** New `to_decimal`,
+   `from_decimal`, `to_unix_decimal`, `from_unix_decimal` and the matching
+   `LVTimestamp` methods. These convert through integer and `Decimal` arithmetic
+   only, so `from_decimal("-5.2")` returns the exact NI pair
+   (-6, 0xCCCCCCCCCCCCCCCD) that `from_float(-5.2)` cannot. This is the headline
+   feature: it is the only way to reproduce NI's published bytes for a value like
+   -5.2, and it keeps the full 2**-64 s resolution end to end. `from_decimal`
+   accepts `Decimal`, `int` or `str` on purpose and refuses `float`, so a lossy
+   float can never sneak in unnoticed.
+2. **Hex convenience on the type: `LVTimestamp.hex()` and `from_hex()`.** People
+   hold the flattened timestamp as a hex string far more often than as raw bytes
+   (logs, protocol dumps, the clipboard). A one-call round trip from and to hex,
+   byte-order aware, removes the `bytes.fromhex` / `.hex()` dance and backs the
+   CLI.
+3. **The NI rounding caveat, documented and tested.** A README section and a
+   contract test that assert both facts above: the exact-vs-double fraction for
+   0.8 and the real instant behind the mislabelled 2002 row. This turns a
+   footgun that bites LabVIEW users into a guarantee.
+4. **CLI polish.** Move the entry point to `lvtime._cli:main`, add `--version`,
+   and add a `--format decimal` output to `decode` that prints the exact Decimal
+   seconds since 1904 and since the Unix epoch. The console script already
+   decodes and encodes the raw 16-byte hex form; this rounds it out.
+5. **Golden contract and real end-to-end tests.** A contract test that asserts
+   the complete promise against the NI byte vectors, and an end-to-end test that
+   pip-installs the package editable and drives the real `lvtime` console script
+   through `subprocess`, asserting stdout and exit codes and that the NI values
+   round-trip exactly.
+
+## Already covered in 0.2.0 (kept, not re-done)
+
+- **Flatten / unflatten of the 16-byte big-endian form.** `read_timestamp` /
+  `write_timestamp` and `LVTimestamp.to_bytes` / `from_bytes` already do exactly
+  this, big-endian by default, matching "Flatten To String" and TDMS.
+- **Little-endian option, batch helpers, datetime and Unix and float views,
+  honest range errors, immutable typed dataclass.** All present since 0.2.0.

lvtime-0.3.0/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.

lvtime-0.3.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,179 @@
+# 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/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lvtime"
+version = "0.3.0"
+description = "Lossless LabVIEW 128-bit timestamp (1904 epoch) to and from datetime, UTC, sub-microsecond preserved."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Javier Lianes", email = "javier@lianes8studio.com" }]
+keywords = ["labview", "timestamp", "datetime", "tdms", "ni", "1904", "epoch"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.scripts]
+lvtime = "lvtime._cli:main"
+
+[project.optional-dependencies]
+dev = ["ruff", "mypy", "pytest", "build", "twine"]
+
+[project.urls]
+Homepage = "https://lianes8studio.com"
+Repository = "https://github.com/JaviLianes8/lvtime"
+Issues = "https://github.com/JaviLianes8/lvtime/issues"
+Changelog = "https://github.com/JaviLianes8/lvtime/blob/main/CHANGELOG.md"
+LinkedIn = "https://www.linkedin.com/in/jlianes/"
+Funding = "https://buymeacoffee.com/jlianesglrs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lvtime"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-q"

lvtime-0.3.0/requirements-dev.txt

@@ -0,0 +1,3 @@
+# Development dependencies: the package in editable mode plus its dev extras
+# (ruff, mypy, pytest, build, twine). Install with:  pip install -r requirements-dev.txt
+-e .[dev]

lvtime-0.3.0/scripts/check.ps1

@@ -0,0 +1,7 @@
+# Local quality gate. Run before every commit. No CI runs in the cloud.
+$ErrorActionPreference = "Stop"
+
+ruff format --check src tests
+ruff check src tests
+mypy src tests
+pytest

lvtime-0.3.0/scripts/release.ps1

@@ -0,0 +1,28 @@
+# Build and upload to PyPI. Run scripts/check.ps1 first.
+# The name must not already exist on PyPI; the token is read from a secret store, never git.
+$ErrorActionPreference = "Stop"
+
+# Works on both Windows PowerShell 5.1 and pwsh 7 (generic catch, no PS7-only types).
+$taken = $true
+try {
+    Invoke-WebRequest -UseBasicParsing "https://pypi.org/pypi/lvtime/json" | Out-Null
+} catch {
+    if ($_.Exception.Response.StatusCode.value__ -eq 404) { $taken = $false } else { throw }
+}
+if ($taken) { throw "The name 'lvtime' already exists on PyPI. Choose another before publishing." }
+
+$token = $env:PYPI_TOKEN
+if (-not $token -and (Test-Path "C:\secrets\pypi-token.txt")) {
+    $token = (Get-Content "C:\secrets\pypi-token.txt" -Raw).Trim()
+}
+if (-not $token) {
+    throw "No PyPI token. Set `$env:PYPI_TOKEN or save it to C:\secrets\pypi-token.txt (never commit it)."
+}
+
+Remove-Item -Recurse -Force dist -ErrorAction SilentlyContinue
+python -m build
+python -m twine check dist/*
+
+$env:TWINE_USERNAME = "__token__"
+$env:TWINE_PASSWORD = $token
+try { python -m twine upload dist/* } finally { Remove-Item Env:\TWINE_PASSWORD -ErrorAction SilentlyContinue }