datetime
Practical date/time helpers over epoch seconds. Times are epoch seconds (double, from time/timestamp); formatting and component extraction use the C library calendar (local time, except utcnow).
import datetime
stamp = datetime.timestamp()
print(datetime.now()) # "YYYY-MM-DD HH:MM:SS"
print(datetime.format(stamp, "%Y-%m-%d"))
print(datetime.year(stamp), datetime.weekday(stamp))Functions
Current time / formatted strings:
timestamp()— current time as epoch seconds.now()— current local time,"YYYY-MM-DD HH:MM:SS".utcnow()— current UTC time,"YYYY-MM-DDTHH:MM:SSZ".today()— current local date,"YYYY-MM-DD".format(epoch, fmt)— strftime-style formatting of an epoch (local time).
Local-time components of an epoch:
year(epoch)/month(epoch)/day(epoch)— calendar date parts.hour(epoch)/minute(epoch)/second(epoch)— time-of-day parts.weekday(epoch)— Monday=0 .. Sunday=6 (Python convention).
Per-function docs (parameters, runtime complexity, heap behavior) are in datetime.hpp. Tested in ../tests/datetime_test.cpp; ASan + Valgrind clean via the QA gate (security/run-valgrind.sh).
Functions
Current time.
Reads the wall clock and returns fractional seconds since the Unix epoch (1970-01-01 UTC); the value tracks real time and can jump if the system clock is adjusted (NTP, manual changes).
seconds since the Unix epoch (system_clock).
O(1) time.
none.
DatetimeCompileRun.TimestampStdlibE2E.DatetimeCurrent local time as "YYYY-MM-DD HH:MM:SS".
Formats the current epoch in the host's local timezone (subject to DST), so the result differs from utcnow by the local UTC offset.
the formatted string.
O(1) time.
allocates the result string.
DatetimeCompileRun.NowStdlibE2E.DatetimeCurrent UTC time as "YYYY-MM-DDTHH:MM:SSZ".
Formats the current epoch in UTC (never local time) using ISO 8601 with a T separator and trailing Z, independent of the host timezone.
the formatted string.
O(1) time.
allocates the result string.
DatetimeCompileRun.UtcnowStdlibE2E.DatetimeCurrent local date as "YYYY-MM-DD".
Formats just the calendar date of the current epoch in the host's local timezone; near midnight this may differ by a day from the UTC date.
the formatted string.
O(1) time.
allocates the result string.
DatetimeCompileRun.TodayStdlibE2E.Datetimestrftime-style formatting of an epoch in local time (e.g.
fmt = "Y-m-d").
Converts epoch to local time and expands C strftime format codes (Y, m, d, H, etc.); the output is truncated to a 128-byte internal buffer, so very long expansions are cut short.
epoch | epoch seconds. |
fmt | a strftime format string. |
the formatted string.
O(fmt.size()) — the expansion is capped by the 128-byte internal buffer.
allocates a temporary std::string for fmt plus the result.
CheatahDatetime.FormatDatetimeCompileRun.FormatStdlibE2E.Datetime SystemApps.EventLogLocal-time year.
Converts epoch to the host's local timezone and returns the calendar year; the fractional part of epoch is truncated toward the epoch.
epoch | epoch seconds. |
the 4-digit year.
O(1) time.
none.
DatetimeCompileRun.YearStdlibE2E.DatetimeLocal-time month.
Returns the calendar month of epoch in the host's local timezone, already shifted to a 1-based value (January is 1, not the C tm_mon 0).
epoch | epoch seconds. |
the month, 1..12.
O(1) time.
none.
DatetimeCompileRun.MonthStdlibE2E.DatetimeLocal-time day of month.
Returns the day-of-month of epoch in the host's local timezone; this is the calendar day, not the day-of-year or weekday.
epoch | epoch seconds. |
the day, 1..31.
O(1) time.
none.
DatetimeCompileRun.DayStdlibE2E.DatetimeLocal-time hour.
Returns the hour of epoch in the host's local timezone on a 24-hour clock, so DST transitions can make hours repeat or be skipped.
epoch | epoch seconds. |
the hour, 0..23.
O(1) time.
none.
CheatahDatetime.TimeOfDayComponentsDatetimeCompileRun.HourStdlibE2E.DatetimeLocal-time minute.
Returns the minute-within-the-hour of epoch in the host's local timezone.
epoch | epoch seconds. |
the minute, 0..59.
O(1) time.
none.
CheatahDatetime.TimeOfDayComponentsDatetimeCompileRun.MinuteStdlibE2E.DatetimeLocal-time second.
Returns the whole second-within-the-minute of epoch (the fractional part of epoch is discarded); the value can reach 60 to represent a leap second.
epoch | epoch seconds. |
the second, 0..60 (leap).
O(1) time.
none.
CheatahDatetime.TimeOfDayComponentsDatetimeCompileRun.SecondStdlibE2E.DatetimeLocal-time weekday.
Returns the day of the week for epoch in the host's local timezone, remapped from the C tm_wday (Sunday=0) to Python's Monday=0 convention.
epoch | epoch seconds. |
Monday=0 .. Sunday=6 (Python convention).
O(1) time.
none.
DatetimeCompileRun.WeekdayStdlibE2E.Datetime