fix(pcapng): keep out-of-range if_tzone as captured and catch every fromtimestamp failure (#1340)

[JarryShaw]

• Searched for similar pull requests

• Followed the coding style (make pylint, make mypy, make isort) — Makefile flags on the two pcapng.py files; isort clean, no mypy/pylint finding on a changed line (5 pre-existing mypy errors)

• make test passes, and a test case covers the change — legs below, not the full suite

• Added a changelog entry — N/A — centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

• fix — corrects a defect

---

Value	origin/main	this PR
if_tzone ±86400, −2³¹, 2³¹−1	ValueError from datetime.timezone	kept as a timedelta + ProtocolWarning; packets render in UTC; IDB rebuilds byte-exact
if_tzone ±86399	timezone	unchanged
if_tsoffset ±2⁶², −2⁶³	OSError	existing invalid timestamp warning, epoch-0 datetime, epoch Decimal kept
if_tsoffset 2⁶³−1	OverflowError	same as above

This follows the existing _read_timestamp fallback and the "kept as captured" precedent (#1412, #1425). A ProtocolError would drop the whole IDB and could not round-trip. IF_TZoneOption.timezone is widened to timezone | timedelta. The timedelta only appears for values that used to raise, so this is not marked breaking.

The new tests/protocols/misc/test_pcapng_tzone_tsoffset_range_1340_unit.py has 5 tests and 26 subtests, covering the min, max and just-out-of-range values plus the largest EPB timestamp on top of a ±2⁶³ offset. Without the fix it fails 12 (6 ValueError, 4 OSError, 2 OverflowError). Legs: each tests/protocols/misc module run separately, all passed; run_unittest_leg.py protocols --exclude protocols/internet 1081 OK; tests/project 404 passed.

Closes #1340

[JarryShaw]

Verdict: GOOD TO GO at fba8a2b59 (Sonnet cross-review; the author ran on Opus).

• Tests bite, re-derived by me: the new module passes 5/5 (26 subtests) on this head. With only the two pcapng source files put back to main, 12 subtests error.
• if_tzone:
  • On main, −2³¹, ±86400, ±86401 and 2³¹−1 raise ValueError. On this head they are kept as a timedelta with a ProtocolWarning, and the IDB rebuilds byte-exact in both byte orders.
  • ±86399, ±3600 and 0 are unchanged, with no warning.
• UTC fallback is right: datetime.timezone cannot hold ≥24h, and if_tzone only affects rendering. The instant and the Decimal epoch are unchanged, and later EPBs rebuild byte-exact.
• if_tsoffset:
  • On main, −2⁶³ and ±2⁶² raise OSError and 2⁶³−1 raises OverflowError, each also tried with the max EPB timestamp. On this head each warns, falls back to epoch-0 UTC and rebuilds byte-exact.
  • Catching OSError is safe: the try at pcapng.py:1742-1746 holds only the division and fromtimestamp.
• Consumers: _make_option_if_tzone and the dumper (dumpkit/common.py:430) already handle a timedelta. extract to json, tree and plist succeeds on these files.
• Not breaking: a timedelta only appears for inputs that used to raise.
• Neighbours: 16 tests/protocols/misc modules, the dpkt pcapng interfaces test and tests/project (404 passed) all pass.
• Out of scope, checked: pcap/frame.py:271 is not reachable. ts_sec and ts_usec are UInt32Field, so the epoch tops out at 2106-02-07, which is within range.

[github-actions]

Coverage: 89.45% (unit tier, Python 3.14, fba8a2b59, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	4	20	4	93.55%
pcapkit/const	18791	968	2352	869	90.90%
pcapkit/corekit	2038	89	634	25	94.76%
pcapkit/dumpkit	234	2	84	2	98.74%
pcapkit/foundation	2637	98	928	48	94.78%
pcapkit/interface	112	7	40	5	92.11%
pcapkit/protocols	16621	221	4474	185	98.04%
pcapkit/toolkit	539	74	168	3	84.58%
pcapkit/utilities	429	4	122	4	98.55%
pcapkit/vendor	4409	2342	1006	157	43.25%

Per-file detail: the coverage-html artifact of this run.