Skip to content
New: Star-import, signal unraveling, Python 3.12 support, and more

#
datetime_ module

Utilities for working with dates and time.

## fuzzy_freq_str_config HybridConfig

Config for fuzzy frequency mapping.

    HybridConfig(
        ns='ns',
        nano='ns',
        nanos='ns',
        nanosecond='ns',
        nanoseconds='ns',
        us='us',
        micro='us',
        micros='us',
        microsecond='us',
        microseconds='us',
        ms='ms',
        milli='ms',
        millis='ms',
        millisecond='ms',
        milliseconds='ms',
        s='s',
        sec='s',
        secs='s',
        second='s',
        seconds='s',
        t='m',
        min='m',
        mins='m',
        minute='m',
        minutes='m',
        h='h',
        hour='h',
        hours='h',
        hourly='h',
        d='d',
        day='d',
        days='d',
        daily='d',
        w='W',
        wk='W',
        wks='W',
        week='W',
        weeks='W',
        weekly='W',
        mo='M',
        month='M',
        months='M',
        monthly='M',
        q='Q',
        quarter='Q',
        quarters='Q',
        quarterly='Q',
        y='Y',
        year='Y',
        years='Y',
        yearly='Y',
        annual='Y',
        annually='Y'
    )

## sharp_freq_str_config HybridConfig

Config for sharp frequency mapping.

    HybridConfig(
        m='m',
        M='M'
    )

## auto_detect_freq function

    auto_detect_freq(
        index
    )

Auto-detect frequency from a datetime index.

Returns the minimal frequency if it's being encountered in most of the index.

## convert_naive_time function

    convert_naive_time(
        t,
        tz_out
    )

Return as naive time.

`datetime.time` must not have `tzinfo` set.

## convert_tzaware_time function

    convert_tzaware_time(
        t,
        tz_out
    )

Return as non-naive time.

`datetime.time` must have `tzinfo` set.

## date_range function

    date_range(
        start=None,
        end=None,
        *,
        periods=None,
        freq=None,
        tz=None,
        inclusive='left',
        timestamp_kwargs=None,
        freq_kwargs=None,
        timezone_kwargs=None,
        **kwargs
    )

Same as `pd.date_range` but preprocesses `start` and `end` with to_timestamp(), `freq` with to_freq(), and `tz` with to_timezone().

If `start` and `periods` are None, will set `start` to the beginning of the Unix epoch. Same if pf `periods` is not None but `start` and `end` are None.

If `end` and `periods` are None, will set `end` to the current date and time.

## datetime_to_ms function

    datetime_to_ms(
        dt
    )

Convert a datetime to milliseconds.

## fix_timedelta_precision function

    fix_timedelta_precision(
        freq
    )

Fix the precision of timedelta.

## freq_depends_on_index function

    freq_depends_on_index(
        freq
    )

Return whether frequency depends on index.

## get_dt_index_gaps function

    get_dt_index_gaps(
        index,
        freq=None,
        skip_index=None,
        **kwargs
    )

Get gaps in a datetime index.

Returns two indexes: start indexes (inclusive) and end indexes (exclusive).

Keyword arguments are passed to prepare_dt_index().

## get_local_tz function

    get_local_tz(
        **kwargs
    )

Get local timezone.

## get_rangebreaks function

    get_rangebreaks(
        index,
        **kwargs
    )

Get `rangebreaks` based on get_dt_index_gaps().

## get_utc_tz function

    get_utc_tz(
        **kwargs
    )

Get UTC timezone.

## infer_index_freq function

    infer_index_freq(
        index,
        freq=None,
        allow_offset=True,
        allow_numeric=True,
        freq_from_n=None
    )

Infer frequency of a datetime index if `freq` is None, otherwise convert `freq`.

If `freq` is "auto", uses auto_detect_freq(). If `freq` is "index_[method_name]", applies the method to the `pd.TimedeltaIndex` resulting from the difference between each pair of index points. If `freq_from_n` is a positive or negative number, limits the index to the first or the last N index points respectively.

For defaults, see datetime.

## interval_to_ms function

    interval_to_ms(
        interval
    )

Convert an interval string to milliseconds.

## is_tz_aware function

    is_tz_aware(
        dt
    )

Whether datetime is timezone-aware.

## naive_to_tzaware_time function

    naive_to_tzaware_time(
        t,
        tz_out
    )

Return as non-naive time.

`datetime.time` must not have `tzinfo` set.

## offset_to_timedelta function

    offset_to_timedelta(
        offset
    )

Convert offset to a timedelta.

## parse_index_freq function

    parse_index_freq(
        index
    )

Parse frequency from a datetime index.

## prepare_dt_index function

    prepare_dt_index(
        index,
        parse_index=None,
        parse_with_dateparser=None,
        dateparser_kwargs=None,
        **kwargs
    )

Try converting an index to a datetime index.

If `parse_index` is True and the object has an object data type, will parse with Pandas (`parse_index` must be True) and dateparser (in addition `parse_with_dateparser` must be True).

`dateparser_kwargs` are passed to `dateparser.parse` while `**kwargs` are passed to `pd.to_datetime`.

For defaults, see datetime.

## prepare_offset_str function

    prepare_offset_str(
        offset_str,
        allow_space=False
    )

Prepare offset frequency string.

To include multiple units, separate them with comma, semicolon, or space if `allow_space` is True. The output becomes comma-separated.

## prepare_timedelta_str function

    prepare_timedelta_str(
        timedelta_str,
        allow_space=False
    )

Prepare timedelta frequency string.

To include multiple units, separate them with comma, semicolon, or space if `allow_space` is True. The output becomes comma-separated.

## split_freq_str function

    split_freq_str(
        freq_str,
        sharp_mapping=None,
        fuzzy_mapping=None
    )

Split (human-readable) frequency into multiplier and unambiguous unit.

Can be used both as offset and timedelta.

For mappings, see sharp_freq_str_config and fuzzy_freq_str_config. Sharp (case-sensitive) mappings are considered first, fuzzy (case-insensitive) mappings second. If a mapping returns None, will return the original unit.

The following case-sensitive units are returned: * "ns" for nanosecond * "us" for microsecond * "ms" for millisecond * "s" for second * "m" for minute * "h" for hour * "d" for day * "W" for week * "M" for month * "Q" for quarter * "Y" for year

If a unit isn't recognized, will return the original unit.

## time_to_timedelta function

    time_to_timedelta(
        t,
        **kwargs
    )

Convert a time-like object into `pd.Timedelta`.

## to_datetime function

    to_datetime(
        dt,
        **kwargs
    )

Parse the datetime as a `datetime.datetime`.

Uses to_timestamp().

## to_freq function

    to_freq(
        freq,
        allow_offset=True,
        keep_offset=False
    )

Convert a frequency-like object to `pd.DateOffset` or `pd.Timedelta`.

## to_naive_datetime function

    to_naive_datetime(
        dt,
        **kwargs
    )

Parse the datetime as a timezone-naive `datetime.datetime`.

Uses to_naive_timestamp().

## to_naive_timestamp function

    to_naive_timestamp(
        dt,
        **kwargs
    )

Parse the datetime as a timezone-naive `pd.Timestamp`.

## to_ns function

    to_ns(
        obj
    )

Convert a datetime, timedelta, integer, or any array-like object to nanoseconds since Unix Epoch.

## to_offset function

    to_offset(
        freq
    )

Convert a frequency-like object to `pd.DateOffset`.

## to_timedelta function

    to_timedelta(
        freq,
        approximate=False
    )

Convert a frequency-like object to `pd.Timedelta`.

## to_timedelta64 function

    to_timedelta64(
        freq
    )

Convert a frequency-like object to `np.timedelta64`.

## to_timestamp function

    to_timestamp(
        dt,
        parse_with_dateparser=None,
        dateparser_kwargs=None,
        unit='ns',
        tz=None,
        to_fixed_offset=None,
        **kwargs
    )

Parse the datetime as a `pd.Timestamp`.

If the object is a string, will parse with Pandas and dateparser (`parse_with_dateparser` must be True).

`dateparser_kwargs` are passed to `dateparser.parse` while `**kwargs` are passed to `pd.Timestamp`.

For defaults, see datetime.

## to_timezone function

    to_timezone(
        tz,
        to_fixed_offset=None,
        parse_with_dateparser=None,
        dateparser_kwargs=None
    )

Parse the timezone.

If the object is a string, will parse with Pandas and dateparser (`parse_with_dateparser` must be True).

If `to_fixed_offset` is set to True, will convert to `datetime.timezone`. See global settings.

`dateparser_kwargs` are passed to `dateparser.parse`.

For defaults, see datetime.

## to_tzaware_datetime function

    to_tzaware_datetime(
        dt,
        **kwargs
    )

Parse the datetime as a timezone-aware `datetime.datetime`.

Uses to_tzaware_timestamp().

## to_tzaware_timestamp function

    to_tzaware_timestamp(
        dt,
        naive_tz=None,
        tz=None,
        **kwargs
    )

Parse the datetime as a timezone-aware `pd.Timestamp`.

Uses to_timestamp().

Raw timestamps are localized to UTC, while naive datetime is localized to `naive_tz`. Set `naive_tz` to None to use the default value defined under datetime. To explicitly convert the datetime to a timezone, use `tz` (uses to_timezone()).

For defaults, see datetime.

## try_align_dt_to_index function

    try_align_dt_to_index(
        dt,
        target_index,
        **kwargs
    )

Try aligning a datetime-like object to another datetime index.

Keyword arguments are passed to to_timestamp().

## try_align_to_dt_index function

    try_align_to_dt_index(
        source_index,
        target_index,
        **kwargs
    )

Try aligning an index to another datetime index.

Keyword arguments are passed to prepare_dt_index().

## tzaware_to_naive_time function

    tzaware_to_naive_time(
        t,
        tz_out
    )

Return as naive time.

`datetime.time` must have `tzinfo` set.

## DTC class

    DTC(
        year=None,
        month=None,
        day=None,
        weekday=None,
        hour=None,
        minute=None,
        second=None,
        nanosecond=None
    )

Class representing one or more datetime components.

Method generated by attrs for class DTC.

### day class variable

Day of month.

### from_date class method

    DTC.from_date(
        d
    )

Get DTC instance from a `datetime.date` object.

### from_datetime class method

    DTC.from_datetime(
        dt
    )

Get DTC instance from a `datetime.datetime` object.

### from_namedtuple class method

    DTC.from_namedtuple(
        dtc
    )

Get DTC instance from a named tuple of the type DTCNT.

### from_time class method

    DTC.from_time(
        t
    )

Get DTC instance from a `datetime.time` object.

### has_date method

    DTC.has_date()

Whether any date component is set.

### has_full_date method

    DTC.has_full_date()

Whether all date components are set.

### has_full_datetime method

    DTC.has_full_datetime()

Whether all components are set.

### has_full_time method

    DTC.has_full_time()

Whether all time components are set.

### has_time method

    DTC.has_time()

Whether any time component is set.

### has_weekday method

    DTC.has_weekday()

Whether the weekday component is set.

### hour class variable

Hour.

### is_not_none method

    DTC.is_not_none()

Check whether any component is set.

### is_parsable class method

    DTC.is_parsable(
        dtc,
        check_func=None,
        **parse_kwargs
    )

Check whether a datetime-component-like object is parsable.

### minute class variable

Minute.

### month class variable

Month.

### nanosecond class variable

Nanosecond.

### parse class method

    DTC.parse(
        dtc,
        **parse_kwargs
    )

Parse DTC instance from a datetime-component-like object.

### parse_time_str class method

    DTC.parse_time_str(
        time_str,
        **parse_kwargs
    )

Parse DTC instance from a time string.

### second class variable

Second.

### to_namedtuple method

    DTC.to_namedtuple()

Convert to a named tuple.

### to_time method

    DTC.to_time()

Convert to a `datetime.time` instance.

Fields that are None will become 0.

### weekday class variable

Day of week.

### year class variable

Year.

## DTCNT class

    DTCNT(
        year,
        month,
        day,
        weekday,
        hour,
        minute,
        second,
        nanosecond
    )

DTCNT(year, month, day, weekday, hour, minute, second, nanosecond)

Superclasses

- `builtins.tuple`

### day method-wrapper

Alias for field number 2

### hour method-wrapper

Alias for field number 4

### minute method-wrapper

Alias for field number 5

### month method-wrapper

Alias for field number 1

### nanosecond method-wrapper

Alias for field number 7

### second method-wrapper

Alias for field number 6

### weekday method-wrapper

Alias for field number 3

### year method-wrapper

Alias for field number 0

#### Cookie consent

We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.

- Google Analytics
- GitHub

Manage settings