Skip to content

datetime

Helper methods for working with date/time representations.

date_str_to_days(date_str)

Convert an ISO-8601 formatted date to days from 1970-01-01.

Source code in pyiceberg/utils/datetime.py 
50
51
52
def date_str_to_days(date_str: str) -> int:
    """Convert an ISO-8601 formatted date to days from 1970-01-01."""
    return (date.fromisoformat(date_str) - EPOCH_DATE).days

date_to_days(date_val)

Convert a Python date object to days from 1970-01-01.

Source code in pyiceberg/utils/datetime.py 
55
56
57
def date_to_days(date_val: date) -> int:
    """Convert a Python date object to days from 1970-01-01."""
    return (date_val - EPOCH_DATE).days

datetime_to_micros(dt)

Convert a datetime to microseconds from 1970-01-01T00:00:00.000000.

Source code in pyiceberg/utils/datetime.py 
75
76
77
78
79
80
81
def datetime_to_micros(dt: datetime) -> int:
    """Convert a datetime to microseconds from 1970-01-01T00:00:00.000000."""
    if dt.tzinfo:
        delta = dt - EPOCH_TIMESTAMPTZ
    else:
        delta = dt - EPOCH_TIMESTAMP
    return (delta.days * 86400 + delta.seconds) * 1_000_000 + delta.microseconds

datetime_to_millis(dt)

Convert a datetime to milliseconds from 1970-01-01T00:00:00.000000.

Source code in pyiceberg/utils/datetime.py 
 94
 95
 96
 97
 98
 99
100
def datetime_to_millis(dt: datetime) -> int:
    """Convert a datetime to milliseconds from 1970-01-01T00:00:00.000000."""
    if dt.tzinfo:
        delta = dt - EPOCH_TIMESTAMPTZ
    else:
        delta = dt - EPOCH_TIMESTAMP
    return (delta.days * 86400 + delta.seconds) * 1_000 + delta.microseconds // 1_000

days_to_date(days)

Create a date from the number of days from 1970-01-01.

Source code in pyiceberg/utils/datetime.py 
60
61
62
def days_to_date(days: int) -> date:
    """Create a date from the number of days from 1970-01-01."""
    return EPOCH_DATE + timedelta(days)

micros_to_days(timestamp)

Convert a timestamp in microseconds to a date in days.

Source code in pyiceberg/utils/datetime.py 
36
37
38
def micros_to_days(timestamp: int) -> int:
    """Convert a timestamp in microseconds to a date in days."""
    return timedelta(microseconds=timestamp).days

micros_to_hours(micros)

Convert a timestamp in microseconds to hours from 1970-01-01T00:00.

Source code in pyiceberg/utils/datetime.py 
166
167
168
def micros_to_hours(micros: int) -> int:
    """Convert a timestamp in microseconds to hours from 1970-01-01T00:00."""
    return micros // 3_600_000_000

micros_to_time(micros)

Convert a timestamp in microseconds to a time.

Source code in pyiceberg/utils/datetime.py 
41
42
43
44
45
46
47
def micros_to_time(micros: int) -> time:
    """Convert a timestamp in microseconds to a time."""
    micros, microseconds = divmod(micros, 1000000)
    micros, seconds = divmod(micros, 60)
    micros, minutes = divmod(micros, 60)
    hours = micros
    return time(hour=hours, minute=minutes, second=seconds, microsecond=microseconds)

micros_to_timestamp(micros)

Convert microseconds from epoch to a timestamp.

Source code in pyiceberg/utils/datetime.py 
119
120
121
122
def micros_to_timestamp(micros: int) -> datetime:
    """Convert microseconds from epoch to a timestamp."""
    dt = timedelta(microseconds=micros)
    return EPOCH_TIMESTAMP + dt

micros_to_timestamptz(micros)

Convert microseconds from epoch to an utc timestamp.

Source code in pyiceberg/utils/datetime.py 
125
126
127
128
def micros_to_timestamptz(micros: int) -> datetime:
    """Convert microseconds from epoch to an utc timestamp."""
    dt = timedelta(microseconds=micros)
    return EPOCH_TIMESTAMPTZ + dt

millis_to_datetime(millis)

Convert milliseconds from epoch to a timestamp.

Source code in pyiceberg/utils/datetime.py 
103
104
105
106
def millis_to_datetime(millis: int) -> datetime:
    """Convert milliseconds from epoch to a timestamp."""
    dt = timedelta(milliseconds=millis)
    return EPOCH_TIMESTAMP + dt

time_str_to_micros(time_str)

Convert an ISO-8601 formatted time to microseconds from midnight.

Source code in pyiceberg/utils/datetime.py 
65
66
67
def time_str_to_micros(time_str: str) -> int:
    """Convert an ISO-8601 formatted time to microseconds from midnight."""
    return time_to_micros(time.fromisoformat(time_str))

time_to_micros(t)

Convert a datetime.time object to microseconds from midnight.

Source code in pyiceberg/utils/datetime.py 
70
71
72
def time_to_micros(t: time) -> int:
    """Convert a datetime.time object to microseconds from midnight."""
    return (((t.hour * 60 + t.minute) * 60) + t.second) * 1_000_000 + t.microsecond

timestamp_to_micros(timestamp_str)

Convert an ISO-9601 formatted timestamp without zone to microseconds from 1970-01-01T00:00:00.000000.

Source code in pyiceberg/utils/datetime.py 
84
85
86
87
88
89
90
91
def timestamp_to_micros(timestamp_str: str) -> int:
    """Convert an ISO-9601 formatted timestamp without zone to microseconds from 1970-01-01T00:00:00.000000."""
    if ISO_TIMESTAMP.fullmatch(timestamp_str):
        return datetime_to_micros(datetime.fromisoformat(timestamp_str))
    if ISO_TIMESTAMPTZ.fullmatch(timestamp_str):
        # When we can match a timestamp without a zone, we can give a more specific error
        raise ValueError(f"Zone offset provided, but not expected: {timestamp_str}")
    raise ValueError(f"Invalid timestamp without zone: {timestamp_str} (must be ISO-8601)")

timestamptz_to_micros(timestamptz_str)

Convert an ISO-8601 formatted timestamp with zone to microseconds from 1970-01-01T00:00:00.000000+00:00.

Source code in pyiceberg/utils/datetime.py 
109
110
111
112
113
114
115
116
def timestamptz_to_micros(timestamptz_str: str) -> int:
    """Convert an ISO-8601 formatted timestamp with zone to microseconds from 1970-01-01T00:00:00.000000+00:00."""
    if ISO_TIMESTAMPTZ.fullmatch(timestamptz_str):
        return datetime_to_micros(datetime.fromisoformat(timestamptz_str))
    if ISO_TIMESTAMP.fullmatch(timestamptz_str):
        # When we can match a timestamp without a zone, we can give a more specific error
        raise ValueError(f"Missing zone offset: {timestamptz_str} (must be ISO-8601)")
    raise ValueError(f"Invalid timestamp with zone: {timestamptz_str} (must be ISO-8601)")

to_human_day(day_ordinal)

Convert a DateType value to human string.

Source code in pyiceberg/utils/datetime.py 
141
142
143
def to_human_day(day_ordinal: int) -> str:
    """Convert a DateType value to human string."""
    return (EPOCH_DATE + timedelta(days=day_ordinal)).isoformat()

to_human_hour(hour_ordinal)

Convert a DateType value to human string.

Source code in pyiceberg/utils/datetime.py 
146
147
148
def to_human_hour(hour_ordinal: int) -> str:
    """Convert a DateType value to human string."""
    return (EPOCH_TIMESTAMP + timedelta(hours=hour_ordinal)).isoformat("-", "hours")

to_human_month(month_ordinal)

Convert a DateType value to human string.

Source code in pyiceberg/utils/datetime.py 
136
137
138
def to_human_month(month_ordinal: int) -> str:
    """Convert a DateType value to human string."""
    return f"{EPOCH_TIMESTAMP.year + month_ordinal // 12:0=4d}-{1 + month_ordinal % 12:0=2d}"

to_human_time(micros_from_midnight)

Convert a TimeType value to human string.

Source code in pyiceberg/utils/datetime.py 
151
152
153
def to_human_time(micros_from_midnight: int) -> str:
    """Convert a TimeType value to human string."""
    return micros_to_time(micros_from_midnight).isoformat()

to_human_timestamp(timestamp_micros)

Convert a TimestampType value to human string.

Source code in pyiceberg/utils/datetime.py 
161
162
163
def to_human_timestamp(timestamp_micros: int) -> str:
    """Convert a TimestampType value to human string."""
    return (EPOCH_TIMESTAMP + timedelta(microseconds=timestamp_micros)).isoformat()

to_human_timestamptz(timestamp_micros)

Convert a TimestamptzType value to human string.

Source code in pyiceberg/utils/datetime.py 
156
157
158
def to_human_timestamptz(timestamp_micros: int) -> str:
    """Convert a TimestamptzType value to human string."""
    return (EPOCH_TIMESTAMPTZ + timedelta(microseconds=timestamp_micros)).isoformat()

to_human_year(year_ordinal)

Convert a DateType value to human string.

Source code in pyiceberg/utils/datetime.py 
131
132
133
def to_human_year(year_ordinal: int) -> str:
    """Convert a DateType value to human string."""
    return f"{EPOCH_TIMESTAMP.year + year_ordinal:0=4d}"