dlt.common.time
to_tzinfo
def to_tzinfo(timezone: str) -> datetime.tzinfo
Resolves an IANA name, rejecting anything zoneinfo and arrow cannot both use.
get_context_timezone
def get_context_timezone() -> datetime.tzinfo
Context timezone, the one dlt uses to normalize timestamps and to store in load packages
to_iana_name
def to_iana_name(tz: Optional[datetime.tzinfo]) -> Optional[str]
IANA name of tz, or None when it carries none, as a fixed offset does.
get_context_timezone_name
def get_context_timezone_name() -> str
IANA name of the context timezone.
Raises:
ValueError- The context timezone carries no IANA name.
set_context_timezone
def set_context_timezone(tz: Optional[datetime.tzinfo]) -> datetime.tzinfo
Installs the context timezone and returns the previous one.
Internal: called by TimezoneContext lifecycle hooks and by a launcher preparing a run.
Arguments:
tz- Timezone to install,Noneto fall back on the environment, itself UTC by default.
Returns:
The timezone that was installed before this call.
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,
tz: Optional[datetime.tzinfo] = None) -> pendulum.Date
Coerce a date/time value to the pendulum.Date it falls on in tz.
A naive value is taken to already be in tz, an aware value is converted to tz first.
Arguments:
value- The value to coerce. Can be a pendulum.DateTime, pendulum.Date, datetime, date or iso date/time str.tz- Timezone the day is taken in. Defaults to the context timezone, itself UTC unless aTimezoneContextis active.
Returns:
A pendulum.Date object.
ensure_pendulum_datetime
def ensure_pendulum_datetime(
value: TAnyDateTime,
tz: Optional[datetime.tzinfo] = None) -> pendulum.DateTime
Coerce a date/time value to a tz-aware pendulum.DateTime in tz.
The pendulum counterpart of ensure_datetime_in_tz.
Arguments:
value- The value to coerce. Can be a pendulum.DateTime, pendulum.Date, datetime, date or iso date/time str.tz- Timezone to put the value in. Defaults to the context timezone, itself UTC unless aTimezoneContextis active.
Returns:
A timezone aware pendulum.DateTime object.
ensure_datetime
def ensure_datetime(value: TAnyDateTime) -> datetime.datetime
Coerce a date/time value to a stdlib datetime.datetime, preserving original timezone.
Tz-awareness is preserved. Naive datetimes remain naive. Tz-aware datetimes keep their original timezone.
Arguments:
value- The value to coerce. Can be a pendulum.DateTime, pendulum.Date, datetime, date or iso date/time str.
Returns:
A stdlib datetime.datetime that preserves original timezone.
ensure_datetime_in_tz
def ensure_datetime_in_tz(
value: TAnyDateTime,
tz: Optional[datetime.tzinfo] = None) -> datetime.datetime
Coerce a date/time value to a tz-aware stdlib datetime.datetime in tz.
A naive input is taken to already be in tz, so the system timezone never takes part. An
aware input is converted to tz, keeping its instant.
Arguments:
value- The value to coerce. Can be a pendulum.DateTime, pendulum.Date, datetime, date or iso date/time str.tz- Target timezone. Defaults to the context timezone, itself UTC unless aTimezoneContextis active.
Returns:
A stdlib datetime.datetime with tzinfo being tz itself.
ensure_date
def ensure_date(value: TAnyDateTime,
tz: Optional[datetime.tzinfo] = None) -> datetime.date
Coerce a date/time value to the calendar day it falls on in tz.
A naive value is taken to already be in tz, an aware value is converted to tz first, so
the same instant can be a different day in a different timezone.
Arguments:
value- The value to coerce. Can be a pendulum.DateTime, pendulum.Date, datetime, date or iso date/time str.tz- Timezone the day is taken in. Defaults to the configured timezone, itself UTC unless aTimezoneContextis active.
Returns:
A stdlib datetime.date.
normalize_timezone
def normalize_timezone(
value: datetime.datetime,
timezone: bool,
tz: Optional[datetime.tzinfo] = None) -> datetime.datetime
Puts a datetime in the context timezone, per the timezone column hint.
A naive input is taken to already be in tz, so the system timezone never takes part.
Arguments:
value- An already parsed datetime. This runs per value while normalizing, so it does not coerce - callensure_datetime_in_tzfor anything else.timezone- The column'stimezonehint.Falsereturns a naive value.tz- Timezone to put the value in. Defaults to the context timezone, itself UTC unless aTimezoneContextis active.
Returns:
A tz-aware datetime in tz, naive when timezone is False. A value already in tz
is returned as is and keeps its own tzinfo object.
date_to_epoch_days
def date_to_epoch_days(value: datetime.date) -> int
Converts date value to number of days since Unix epoch.
parse_period_seconds
def parse_period_seconds(value: str) -> float
Parse a human period string (e.g. '5m', '1h', '30s') into seconds.
Also accepts bare numeric strings as seconds.
Raises:
ValueError- If the string cannot be parsed.
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.
Follows normalize_timezone(..., timezone=False): an aware input is converted to the
configured timezone and then made naive, a naive value is kept as it is.
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, its time-of-day in the configured timezone.
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
datetime_to_timestamp
def datetime_to_timestamp(moment: datetime.datetime) -> int
Converts a datetime to whole seconds since Unix epoch. Naive input is taken as UTC, never as the context timezone.
datetime_to_timestamp_ms
def datetime_to_timestamp_ms(moment: datetime.datetime) -> int
Converts a datetime to whole milliseconds since Unix epoch. Naive input is taken as UTC, never as the context timezone.
datetime_to_timestamp_us
def datetime_to_timestamp_us(moment: datetime.datetime) -> int
Converts a datetime to whole microseconds since Unix epoch. Naive input is taken as UTC, never as the context timezone.
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)