[python] Support time travel by timestamp and watermark in TimeTravelUtil

[JunRuiLee]

Purpose

Currently pypaimon's TimeTravelUtil only supports time travel by scan.tag-name and scan.snapshot-id. This PR adds support for three additional time travel modes that are available on the Java side:

• scan.timestamp-millis: Travel to the latest snapshot with commit time <= the given timestamp (milliseconds)
• scan.timestamp: Same as above but accepts a human-readable timestamp string (e.g. '2023-12-01 12:00:00')
• scan.watermark: Travel to the first snapshot with watermark >= the given value

[JingsongLi]

Review: [python] Support time travel by timestamp and watermark in TimeTravelUtil

Overall well-structured. The refactoring of table_scan.py to delegate all time-travel logic to TimeTravelUtil is a clean separation of concerns.

Correctness

1. later_or_equal_watermark binary search relies on monotonically non-decreasing watermarks. If a snapshot has watermark = None, the code does earliest = mid + 1 (treats it as "too small"). This is correct under Paimon's guarantee, but a brief comment noting the invariant assumption would help future readers.

2. Gap handling degrades binary search to O(n) in worst case. When get_snapshot_by_id(mid) returns None, the linear scan from mid+1 to latest could be expensive if many consecutive snapshot IDs have been expired. Consistent with existing earlier_or_equal_time_mills but worth noting.

3. Dead-code defensiveness in table_scan.py. The check "if snapshot is None: raise ValueError(...)" after try_travel_to_snapshot is unreachable when has_time_travel is True, because all paths inside either return a valid snapshot or raise. A comment would clarify intent.

Minor / Style

4. Error message formatting -- "point-in-time scan options: %s" % SCAN_KEYS renders the list with Python repr syntax. Consider ", ".join(SCAN_KEYS) for cleaner output.

5. No direct unit test for binary search edge cases -- The tests use _StubSnapshotManager with simple linear implementation. Consider a focused test for later_or_equal_watermark with gaps in snapshot IDs and None watermarks.

Design

6. Good alignment with Java side. The _parse_timestamp_to_millis using naive datetime is consistent with Java's TimeZone.getDefault() semantics.

Nice work overall -- test cases are thorough and code is readable.

[JingsongLi]

+1