Skip to content

topmark.utils.timestamp

topmark / utils / timestamp

Timestamp helpers used across TopMark.

This module centralizes timestamp sources and string formatting so that:

  • internal timestamps are consistently represented in UTC;
  • machine-readable output can use ISO-8601 strings; and
  • unified diff headers can use GNU diff / git-style timestamps.

Naming convention: - get_* functions return datetime objects (UTC). - format_* functions return strings in a specific, documented format.

get_utc_now 

get_utc_now()

Return the current time as an aware UTC datetime.

Source code in src/topmark/utils/timestamp.py 
41
42
43
def get_utc_now() -> datetime:
    """Return the current time as an aware UTC datetime."""
    return datetime.now(timezone.utc)

get_path_mtime_utc 

get_path_mtime_utc(*, path)

Return the file's modification time as an aware UTC datetime.

Falls back to get_utc_now() when the mtime cannot be read.

Parameters:

Name Type Description Default
path Path

Path to the file.

 required

Returns:

Type Description
datetime

The file's st_mtime as an aware UTC datetime, or get_utc_now() on failure.
Source code in src/topmark/utils/timestamp.py 
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
def get_path_mtime_utc(*, path: Path) -> datetime:
    """Return the file's modification time as an aware UTC datetime.

    Falls back to `get_utc_now()` when the mtime cannot be read.

    Args:
        path: Path to the file.

    Returns:
        The file's `st_mtime` as an aware UTC datetime, or `get_utc_now()` on failure.
    """
    try:
        ts: float = path.stat().st_mtime
        return datetime.fromtimestamp(ts, tz=timezone.utc)
    except OSError as e:
        logger.warning("Could not access mtime for %s: %s. Using 'now'.", path, e)
        return get_utc_now()

format_iso8601_timestamp 

format_iso8601_timestamp(*, dt=None)

Return an ISO-8601 timestamp string in UTC.

If dt is not set, uses the current time.

All timestamps are converted to UTC offset.

Parameters:

Name Type Description Default
dt datetime | None

An optional datetime (use now if not specified).

 None

Returns:

Type Description
str

ISO-8601 timestamp string in UTC (e.g. 2026-02-21T19:16:49.056550+00:00).
Source code in src/topmark/utils/timestamp.py 
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
def format_iso8601_timestamp(*, dt: datetime | None = None) -> str:
    """Return an ISO-8601 timestamp string in UTC.

    If `dt` is not set, uses the current time.

    All timestamps are converted to UTC offset.

    Args:
        dt: An optional `datetime` (use now if not specified).

    Returns:
        ISO-8601 timestamp string in UTC (e.g. `2026-02-21T19:16:49.056550+00:00`).
    """
    value: datetime = get_utc_now() if dt is None else dt.astimezone(timezone.utc)
    return value.isoformat()

format_gnu_diff_timestamp 

format_gnu_diff_timestamp(*, dt=None)

Return a GNU diff / git-style timestamp string in UTC.

This format is suitable for unified diff header date fields.

If dt is not set, uses the current time.

All timestamps are converted to UTC offset.

Parameters:

Name Type Description Default
dt datetime | None

An optional datetime (use now if not specified).

 None

Returns:

Type Description
str

A string representing the GNU diff timestamp (e.g., '2026-02-21 19:16:49 +0000').
Source code in src/topmark/utils/timestamp.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def format_gnu_diff_timestamp(*, dt: datetime | None = None) -> str:
    """Return a GNU diff / git-style timestamp string in UTC.

    This format is suitable for unified diff header date fields.

    If `dt` is not set, uses the current time.

    All timestamps are converted to UTC offset.

    Args:
        dt: An optional `datetime` (use now if not specified).

    Returns:
        A string representing the GNU diff timestamp (e.g., '2026-02-21 19:16:49 +0000').
    """
    value: datetime = get_utc_now() if dt is None else dt.astimezone(timezone.utc)
    return value.strftime(_GNU_DIFF_TIMESTAMP_FMT)