Skip to content

Datetime reference

Datetime converter

Classes

Functions

timeless.converters.datetime_converter.from_datetime(dt: _datetime, zone: str = 'UTC') -> Datetime

Convert a datetime object to a timeless.Datetime.

Parameters:

  • dt (_datetime) –

    Python's default datetime object.

  • zone (Union[ZoneInfo, str], optional) –

    Timezone, by default ZoneInfo("UTC")

Returns:

Source code in timeless/converters/datetime_converter.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
def from_datetime(dt: _datetime, zone: str = "UTC") -> Datetime:
    """
    Convert a datetime object to a timeless.Datetime.

    Parameters
    ----------
    dt : _datetime
        Python's default datetime object.
    zone : Union[ZoneInfo, str], optional
        Timezone, by default ZoneInfo("UTC")

    Returns
    -------
    Datetime
        Timeless datetime
    """
    return Datetime(
        year=dt.year,
        month=dt.month,
        day=dt.day,
        hour=dt.hour,
        minute=dt.minute,
        second=dt.second,
        microsecond=dt.microsecond,
        zone=zone,
    )

timeless.converters.datetime_converter.to_datetime(dt: Datetime) -> _datetime

Convert a timeless.Datetime to a datetime object.

Parameters:

  • dt (Datetime) –

    Timeless datetime to convert to.

Returns:

  • _datetime –

    Python's default datetime object.

Source code in timeless/converters/datetime_converter.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
def to_datetime(dt: Datetime) -> _datetime:
    """
    Convert a timeless.Datetime to a datetime object.

    Parameters
    ----------
    dt : Datetime
        Timeless datetime to convert to.

    Returns
    -------
    _datetime
        Python's default datetime object.
    """
    return _datetime(
        year=dt.year,
        month=dt.month,
        day=dt.day,
        hour=dt.hour,
        minute=dt.minute,
        second=dt.second,
        microsecond=dt.microsecond,
        tzinfo=dt.tzinfo,
    )

Numpy converter

Classes

Functions

timeless.converters.numpy_converter.from_np_datetime64(dt: np.datetime64, zone: str = 'UTC') -> Datetime

Convert a Numpy datetime64 instance to a Timeless Datetime instance.

Only avaible if Numpy is installed.

Run 'pip install timeless --extras converters'

Parameters:

  • dt (np.datetime64) –

    Numpy Datetime64 instance.

Returns:

  • Datetime –

    Timeless Datetime instance.

Source code in timeless/converters/numpy_converter.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
def from_np_datetime64(dt: np.datetime64, zone: str = "UTC") -> Datetime:
    """
    Convert a Numpy datetime64 instance to a Timeless Datetime instance.

    Only avaible if Numpy is installed.

    Run 'pip install timeless --extras converters'

    Parameters
    ----------
    dt : np.datetime64
        Numpy Datetime64 instance.

    Returns
    -------
    Datetime
        Timeless Datetime instance.
    """
    unix_epoch = np.datetime64(0, "s")
    one_second = np.timedelta64(1, "s")
    seconds_since_epoch = float((dt - unix_epoch) / one_second)
    _dt_datetime = _datetime.utcfromtimestamp(seconds_since_epoch)
    dt_datetime = from_datetime(_dt_datetime)

    if zone != "UTC":
        dt_datetime_zone = dt_datetime.set(zone=zone)
        offset = dt_datetime_zone.get_utc_offset()
        dt_datetime = dt_datetime_zone.add(hours=offset)

    return dt_datetime

timeless.converters.numpy_converter.to_np_datetime64(dt: Datetime) -> np.datetime64

Convert a Datetime instance to a Numpy datetime64 instance.

Internally a datetime64 represents a moment in time as a value since the UNIX epoch (1970-01-01) - not counting leap seaconds.

Therefore, time zones are not preserved. If you pass in a time zone offset, it will apply it to determine the correct UTC time. If you don't pass one, it will use the local machine's time zone. Regardless of input, on output it uses the local machine's time zone to project the UTC time to a local time with offset.

Only avaible if Numpy is installed.

Run 'pip install timeless --extras converters'

Parameters:

  • dt (Datetime) –

    Datetime or Period instance.

Returns:

  • np.datetime64 –

    Numpy time instances.

Source code in timeless/converters/numpy_converter.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
def to_np_datetime64(dt: Datetime) -> np.datetime64:
    """
    Convert a Datetime instance to a Numpy datetime64 instance.

    Internally a datetime64 represents a moment in time as a value since the
    UNIX epoch (1970-01-01) - not counting leap seaconds.

    Therefore, time zones are not preserved. If you pass in a time zone offset,
    it will apply it to determine the correct UTC time. If you don't pass one,
    it will use the local machine's time zone. Regardless of input, on output
    it uses the local machine's time zone to project the UTC time to a local
    time with offset.

    Only avaible if Numpy is installed.

    Run 'pip install timeless --extras converters'

    Parameters
    ----------
    dt : Datetime
        Datetime or Period instance.

    Returns
    -------
    np.datetime64
        Numpy time instances.
    """
    offset = dt.get_utc_offset() * -1
    dt_conv = dt.set(zone="UTC").add(hours=offset).format(r"%Y-%m-%dT%H:%M:%S.%f")
    return np.datetime64(dt_conv)

Pandas converter

Classes

Functions

timeless.converters.pandas_converter.from_pd_datetimeindex(dt: pd.DatetimeIndex) -> Period

Pandas DatetimeIndex to Period.

Only avaible if Pandas is installed.

Run 'pip install timeless --extras converters'

Source code in timeless/converters/pandas_converter.py 
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
def from_pd_datetimeindex(dt: pd.DatetimeIndex) -> Period:  # type: ignore
    """
    Pandas DatetimeIndex to Period.

    Only avaible if Pandas is installed.

    Run 'pip install timeless --extras converters'
    """
    freq = None

    if dt.freq:
        freq = parse_pandas_offset_freq(dt.freq.name)

    if freq is None:
        warnings.warn("No frequency found in DatetimeIndex: assuming 'days'.")
        freq = "days"

    _start = dt.min().to_pydatetime()
    _end = dt.max().to_pydatetime()

    try:
        _ = _start.tzinfo.zone
    except AttributeError:
        _start = _start.astimezone(ZoneInfo("UTC"))
        _end = _end.astimezone(ZoneInfo("UTC"))

    start = Datetime(
        _start.year,
        _start.month,
        _start.day,
        _start.hour,
        _start.minute,
        _start.second,
        _start.microsecond,
        _start.tzinfo.key,
    )
    end = Datetime(
        _end.year,
        _end.month,
        _end.day,
        _end.hour,
        _end.minute,
        _end.second,
        _end.microsecond,
        _end.tzinfo.key,
    )

    return Period(start, end, freq)

timeless.converters.pandas_converter.from_pd_timestamp(dt: pd.Timestamp) -> Datetime

Pandas Timestamp to Datetime.

If no timezone info is offered, UTC is assumed. If just fixed hour offset exists, the time value is converted to UTC (thus the offset is apllyed).

Only avaible if Pandas is installed.

Run 'pip install timeless --extras converters'

Parameters:

  • dt (pd.Timestamp) –

    Pandas Timestamp.

Returns:

Source code in timeless/converters/pandas_converter.py 
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
def from_pd_timestamp(dt: pd.Timestamp) -> Datetime:
    """
    Pandas Timestamp to Datetime.

    If no timezone info is offered, UTC is assumed. If just fixed hour offset exists,
    the time value is converted to UTC (thus the offset is apllyed).

    Only avaible if Pandas is installed.

    Run 'pip install timeless --extras converters'

    Parameters
    ----------
    dt : pd.Timestamp
        Pandas Timestamp.

    Returns
    -------
    Datetime
        Timeless Datetime
    """
    # No timezone info (fixed offset or timezone name)
    if not hasattr(dt.tz, "zone"):
        dt = dt.tz_localize("UTC")
        dt = dt.tz_convert("UTC")

    datetime_obj = dt.to_pydatetime()

    zone = str(datetime_obj.tzinfo) if datetime_obj.tzinfo else "UTC"

    try:
        _ = ZoneInfo(zone)
    # Some timezone info, but unamed fixed offset
    except ZoneInfoNotFoundError:
        zone = "UTC"
        datetime_obj = dt.tz_convert("UTC").to_pydatetime()

    return Datetime(
        datetime_obj.year,
        datetime_obj.month,
        datetime_obj.day,
        datetime_obj.hour,
        datetime_obj.minute,
        datetime_obj.second,
        datetime_obj.microsecond,
        zone,
    )

timeless.converters.pandas_converter.parse_pandas_offset_freq(offset: str) -> Optional[str]

Map pandas offset strings to timeless.Datetime strings.

Parameters:

  • offset (str) –

    Pandas offset string.

Returns:

  • Optional[str] –

    Timeless offset string.

Raises:

  • ValueError –

    Invalid or unknown offset string.

Source code in timeless/converters/pandas_converter.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
def parse_pandas_offset_freq(offset: str) -> Optional[str]:
    """
    Map pandas offset strings to timeless.Datetime strings.

    Parameters
    ----------
    offset : str
        Pandas offset string.

    Returns
    -------
    Optional[str]
        Timeless offset string.

    Raises
    ------
    ValueError
        Invalid or unknown offset string.
    """
    offsets = {
        "B": None,
        "C": None,
        "D": "days",
        "W": "weeks",
        "M": "months",
        "SM": None,
        "BM": None,
        "CBM": None,
        "MS": "months",
        "SMS": None,
        "BMS": None,
        "CBMS": None,
        "Q": None,
        "BQ": None,
        "QS": None,
        "BQS": None,
        "A": "years",
        "Y": "years",
        "BA": None,
        "BY": None,
        "AS": "years",
        "YS": "years",
        "BAS": None,
        "BYS": None,
        "BH": None,
        "H": "hours",
        "T": "minutes",
        "min": "minutes",
        "S": "seconds",
        "L": None,
        "ms": None,
        "U": "microseconds",
        "US": "microseconds",
        "N": None,
    }

    if offset not in offsets or offsets[offset] is None:
        raise ValueError(f"Unknown offset: {offset}")

    return offsets[offset]

timeless.converters.pandas_converter.to_pd_timestamp(dt: Datetime) -> pd.Timestamp

Create a pandas.Timestamp instance from a Datetime.

Parameters:

Returns:

  • pd.Timestamp –

    Pandas Timestamp.

Source code in timeless/converters/pandas_converter.py 
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
def to_pd_timestamp(dt: Datetime) -> pd.Timestamp:  # type: ignore
    """
    Create a pandas.Timestamp instance from a Datetime.

    Parameters
    ----------
    dt : Datetime
        Timeless Datetime.

    Returns
    -------
    pd.Timestamp
        Pandas Timestamp.
    """
    return pd.Timestamp(dt)