README.md

polars-xdt

eXtra stuff for DateTimes

eXtra stuff for DateTimes in Polars.

• ✅ blazingly fast, written in Rust
• ✅ convert to and from multiple time zones
• ✅ format datetime in different locales
• ✅ convert to Julian Dates
• ✅ time-based EWMA (upstreamed to Polars itself)
• ✅ custom business-day arithmetic (upstreamed to Polars itself)

Installation

First, you need to install Polars.

Then, you'll need to install polars-xdt:

pip install polars-xdt

Read the documentation for a more examples and functionality.

Basic Example

Say we start with

from datetime import datetime

import polars as pl
import polars_xdt as xdt

df = pl.DataFrame(
    {
        "local_dt": [
            datetime(2020, 10, 10, 1),
            datetime(2020, 10, 10, 2),
            datetime(2020, 10, 9, 20),
        ],
        "timezone": [
            "Europe/London",
            "Africa/Kigali",
            "America/New_York",
        ],
    }
)

Let's localize each datetime to the given timezone and convert to UTC, all in one step:

result = df.with_columns(
    xdt.from_local_datetime(
        "local_dt", pl.col("timezone"), "UTC"
    ).alias("date")
)
print(result)

shape: (3, 3)
┌─────────────────────┬──────────────────┬─────────────────────────┐
│ local_dt            ┆ timezone         ┆ date                    │
│ ---                 ┆ ---              ┆ ---                     │
│ datetime[μs]        ┆ str              ┆ datetime[μs, UTC]       │
╞═════════════════════╪══════════════════╪═════════════════════════╡
│ 2020-10-10 01:00:00 ┆ Europe/London    ┆ 2020-10-10 00:00:00 UTC │
│ 2020-10-10 02:00:00 ┆ Africa/Kigali    ┆ 2020-10-10 00:00:00 UTC │
│ 2020-10-09 20:00:00 ┆ America/New_York ┆ 2020-10-10 00:00:00 UTC │
└─────────────────────┴──────────────────┴─────────────────────────┘

Read the documentation for more examples!

Logo

Thanks to Olha Urdeichuk for the illustration.