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

>>> from spotforecast2_safe.utils.convert_to_utc import convert_to_utc
>>> df = pd.DataFrame({"value": [1, 2, 3]}, index=pd.to_datetime(["2022-01-01", "2022-01-02", "2022-01-03"]))
>>> convert_to_utc(df, "Europe/Berlin")
           value
2022-01-01 00:00:00+01:00
2022-01-02 00:00:00+01:00
2022-01-03 00:00:00+01:00

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

>>> from spotforecast2_safe.utils.convert_to_utc import to_utc_timestamp
>>> to_utc_timestamp("2024-01-01")
Timestamp('2024-01-01 00:00:00+0000', tz='UTC')
>>> import pandas as pd
>>> ts = pd.Timestamp("2024-06-15", tz="UTC")
>>> to_utc_timestamp(ts) is ts
True