utils.convert_to_utc

utils.convert_to_utc

Utility functions for timezone conversion.

Functions

Name Description
convert_to_utc Convert DataFrame index timezone to UTC.
to_utc_timestamp Coerce a string or Timestamp to a UTC-aware pandas.Timestamp.

convert_to_utc

utils.convert_to_utc.convert_to_utc(df, timezone)

Convert DataFrame index timezone to UTC.

Parameters

Name Type Description Default
df pd.DataFrame DataFrame with DatetimeIndex. required
timezone Optional[str] Optional timezone string. Required if index has no timezone. required

Returns

Name Type Description
pd.DataFrame DataFrame with UTC timezone index.

Raises

Name Type Description
ValueError If index is not DatetimeIndex or has no timezone and timezone is None.

Examples

import pandas as pd

from spotforecast2_safe.utils.convert_to_utc import convert_to_utc

# Scenario 1: tz-naive index → localise to Europe/Berlin then convert to UTC
df_naive = pd.DataFrame(
    {"value": [1, 2, 3]},
    index=pd.to_datetime(["2022-01-01", "2022-01-02", "2022-01-03"]),
)
result_naive = convert_to_utc(df_naive, "Europe/Berlin")
print("tz-naive result:")
print(result_naive)
assert str(result_naive.index.tz) == "UTC"
# 2022-01-01 CET = UTC+1, so midnight Berlin = 23:00 UTC previous day
assert result_naive.index[0] == pd.Timestamp("2021-12-31 23:00:00", tz="UTC")
tz-naive result:
                           value
2021-12-31 23:00:00+00:00      1
2022-01-01 23:00:00+00:00      2
2022-01-02 23:00:00+00:00      3
import pandas as pd

from spotforecast2_safe.utils.convert_to_utc import convert_to_utc

# Scenario 2: non-UTC tz-aware index (US/Eastern) → converted to UTC
idx = pd.date_range("2022-06-01", periods=3, freq="h", tz="US/Eastern")
df_eastern = pd.DataFrame({"value": [10, 20, 30]}, index=idx)
result_eastern = convert_to_utc(df_eastern, timezone=None)
print("US/Eastern → UTC result:")
print(result_eastern)
assert str(result_eastern.index.tz) == "UTC"
# US/Eastern is UTC-4 in June (EDT), so 00:00 Eastern = 04:00 UTC
assert result_eastern.index[0] == pd.Timestamp("2022-06-01 04:00:00", tz="UTC")
US/Eastern → UTC result:
                           value
2022-06-01 04:00:00+00:00     10
2022-06-01 05:00:00+00:00     20
2022-06-01 06:00:00+00:00     30

to_utc_timestamp

utils.convert_to_utc.to_utc_timestamp(value)

Coerce a string or Timestamp to a UTC-aware pandas.Timestamp.

Strings are parsed with utc=True; existing Timestamps are returned unchanged. This deduplicates the same three-line pattern repeated across public feature builders in this package.

Parameters

Name Type Description Default
value Union[str, pd.Timestamp] A date/time string or an existing pandas.Timestamp. required

Returns

Name Type Description
pd.Timestamp A UTC-aware pandas.Timestamp.

Examples

import pandas as pd

from spotforecast2_safe.utils.convert_to_utc import to_utc_timestamp

# Date-only string → UTC-aware Timestamp
result = to_utc_timestamp("2024-01-01")
print(result)
assert result.tz is not None
assert str(result.tz) == "UTC"
assert result == pd.Timestamp("2024-01-01", tz="UTC")

# Datetime string with offset → UTC-aware Timestamp
result2 = to_utc_timestamp("2024-06-15 12:00:00+02:00")
print(result2)
assert str(result2.tz) == "UTC"
assert result2 == pd.Timestamp("2024-06-15 10:00:00", tz="UTC")

# Pre-existing UTC Timestamp → returned unchanged (identity)
ts = pd.Timestamp("2024-06-15", tz="UTC")
assert to_utc_timestamp(ts) is ts
print("pass-through identity: ok")
2024-01-01 00:00:00+00:00
2024-06-15 10:00:00+00:00
pass-through identity: ok