dlt.common.time
precise_time
A precise timer using win_precise_time library on windows and time.time on other systems
MonotonicPreciseTime Objects
class MonotonicPreciseTime()
Wall-clock timer guaranteed to never go backward.
Reads wall clock on every call and tracks the highest value seen. When the wall clock jumps backward (NTP step corrections, VM/WSL clock drift) the previous high-water mark is returned instead.
Arguments:
-
strictly_increasing- every call returns a value strictly greater than the previous one by bumping withmath.nextafterwhen the wall clock does not advance. Use for callers that need unique timestamps.Not thread-safe. Use
LockedMonotonicPreciseTimefor shared instances.
LockedMonotonicPreciseTime Objects
class LockedMonotonicPreciseTime(MonotonicPreciseTime)
Thread-safe variant using a lock (one uncontended futex CAS).
timestamp_within
def timestamp_within(timestamp: float, min_exclusive: Optional[float],
max_inclusive: Optional[float]) -> bool
check if timestamp within range uniformly treating none and range inclusiveness
timestamp_before
def timestamp_before(timestamp: float, max_inclusive: Optional[float]) -> bool
check if timestamp is before max timestamp, inclusive
parse_iso_like_datetime
def parse_iso_like_datetime(value: str) -> Union[DateTime, Date, Time]
Parses ISO8601 string into pendulum datetime, date or time. Preserves timezone info.
Note: naive datetimes will be generated from string without timezone.
ensure_pendulum_date
def ensure_pendulum_date(value: TAnyDateTime) -> pendulum.Date
Coerce a date/time value to a pendulum.Date object.
UTC is assumed if the value is not timezone aware. Other timezones are shifted to UTC
Arguments:
value- The value to coerce. Can be a pendulum.DateTime, pendulum.Date, datetime, date or iso date/time str.
Returns:
A timezone aware pendulum.Date object.
ensure_pendulum_datetime_utc
def ensure_pendulum_datetime_utc(value: TAnyDateTime) -> pendulum.DateTime
Coerce a date/time value to a pendulum.DateTime object.
UTC is assumed if the value is not timezone aware. Other timezones are shifted to UTC
Arguments:
value- The value to coerce. Can be a pendulum.DateTime, pendulum.Date, datetime, date or iso date/time str.
Returns:
A timezone aware pendulum.DateTime object in UTC timezone.
ensure_pendulum_datetime_non_utc
def ensure_pendulum_datetime_non_utc(value: TAnyDateTime) -> pendulum.DateTime
Coerce a date/time value to a pendulum.DateTime object.
Tz-awareness is preserved. Naive datetimes remain naive. Tz-aware datetimes keep their original timezone. Dates are converted to naive datetimes as dates are naive
Arguments:
value- The value to coerce. Can be a pendulum.DateTime, pendulum.Date, datetime, date or iso date/time str.
Returns:
pendulum.DateTime object that preserver original timezone
normalize_timezone
def normalize_timezone(dt: pendulum.DateTime,
timezone: bool) -> pendulum.DateTime
Normalizes timezone in a pendulum instance according to dlt convention:
- naive datetimes represent UTC (system timezone is ignored) time zone
- tz-aware datetimes are always UTC
Following conversions will be made:
- when
timezoneis false: tz-aware tz is converted into UTC tz and then naive - when
timezoneis true: naive and aware datetimes are converted to UTC
ensure_pendulum_time
def ensure_pendulum_time(
value: Union[str, int, float, datetime.time,
timedelta]) -> pendulum.Time
Coerce a time-like value to a pendulum.Time object using timezone=False semantics.
this follows normalize_timezone(..., timezone=False): tz-aware inputs are converted to UTC and then made naive; naive values are treated as UTC and kept naive.
Arguments:
value- Time value to coerce. Supported types:- pendulum.Time or datetime.time
- ISO time string (e.g. "12:34:56", "12:34:56+02:00")
- timedelta representing seconds since midnight
Returns:
A naive pendulum.Time object that represents UTC time-of-day.
to_py_datetime
def to_py_datetime(value: datetime.datetime) -> datetime.datetime
Convert a pendulum.DateTime to a py datetime object.
Arguments:
value- The value to convert. Can be a pendulum.DateTime or datetime.
Returns:
A py datetime object
to_py_date
def to_py_date(value: datetime.date) -> datetime.date
Convert a pendulum.Date to a py date object.
Arguments:
value- The value to convert. Can be a pendulum.Date or date.
Returns:
A py date object
get_precision_from_datetime_unit
def get_precision_from_datetime_unit(unit: str) -> int
Convert PyArrow datetime unit to numeric precision.
Arguments:
unit- PyArrow datetime unit ("s", "ms", "us", "ns")
Returns:
Numeric precision (0, 3, 6, or 9)