Datetime Operations

Date and time extraction and manipulation operations.

Overview

Datetime operations allow you to extract components from date/datetime columns, parse date strings, and perform date arithmetic.

from transformplan import TransformPlan

plan = (
    TransformPlan()
    .dt_parse("date_string", fmt="%Y-%m-%d")
    .dt_year("order_date", new_column="order_year")
    .dt_diff_days("end_date", "start_date", new_column="duration")
)

Class Reference

DatetimeOps

Mixin providing datetime operations on columns.

dt_year

dt_year(column: str, new_column: str | None = None) -> Self

Extract year from a datetime column.

Parameters:

Name	Type	Description	Default
column	str	Source datetime column.	required
new_column	str | None	Name for result column (None = modify in place).	None

Returns:

Type	Description
Self	Self for method chaining.

Source code in transformplan/ops/datetime.py

def dt_year(self, column: str, new_column: str | None = None) -> Self:
    """Extract year from a datetime column.

    Args:
        column: Source datetime column.
        new_column: Name for result column (None = modify in place).

    Returns:
        Self for method chaining.
    """
    return self._register(
        self._dt_year, {"column": column, "new_column": new_column or column}
    )

dt_month

dt_month(column: str, new_column: str | None = None) -> Self

Extract month from a datetime column.

Parameters:

Name	Type	Description	Default
column	str	Source datetime column.	required
new_column	str | None	Name for result column (None = modify in place).	None

Returns:

Type	Description
Self	Self for method chaining.

Source code in transformplan/ops/datetime.py

def dt_month(self, column: str, new_column: str | None = None) -> Self:
    """Extract month from a datetime column.

    Args:
        column: Source datetime column.
        new_column: Name for result column (None = modify in place).

    Returns:
        Self for method chaining.
    """
    return self._register(
        self._dt_month, {"column": column, "new_column": new_column or column}
    )

dt_day

dt_day(column: str, new_column: str | None = None) -> Self

Extract day from a datetime column.

Parameters:

Name	Type	Description	Default
column	str	Source datetime column.	required
new_column	str | None	Name for result column (None = modify in place).	None

Returns:

Type	Description
Self	Self for method chaining.

Source code in transformplan/ops/datetime.py

def dt_day(self, column: str, new_column: str | None = None) -> Self:
    """Extract day from a datetime column.

    Args:
        column: Source datetime column.
        new_column: Name for result column (None = modify in place).

    Returns:
        Self for method chaining.
    """
    return self._register(
        self._dt_day, {"column": column, "new_column": new_column or column}
    )

dt_week

dt_week(column: str, new_column: str | None = None) -> Self

Extract ISO week number from a datetime column.

Parameters:

Name	Type	Description	Default
column	str	Source datetime column.	required
new_column	str | None	Name for result column (None = modify in place).	None

Returns:

Type	Description
Self	Self for method chaining.

Source code in transformplan/ops/datetime.py

def dt_week(self, column: str, new_column: str | None = None) -> Self:
    """Extract ISO week number from a datetime column.

    Args:
        column: Source datetime column.
        new_column: Name for result column (None = modify in place).

    Returns:
        Self for method chaining.
    """
    return self._register(
        self._dt_week, {"column": column, "new_column": new_column or column}
    )

dt_quarter

dt_quarter(column: str, new_column: str | None = None) -> Self

Extract quarter (1-4) from a datetime column.

Parameters:

Name	Type	Description	Default
column	str	Source datetime column.	required
new_column	str | None	Name for result column (None = modify in place).	None

Returns:

Type	Description
Self	Self for method chaining.

Source code in transformplan/ops/datetime.py

def dt_quarter(self, column: str, new_column: str | None = None) -> Self:
    """Extract quarter (1-4) from a datetime column.

    Args:
        column: Source datetime column.
        new_column: Name for result column (None = modify in place).

    Returns:
        Self for method chaining.
    """
    return self._register(
        self._dt_quarter, {"column": column, "new_column": new_column or column}
    )

dt_year_month

dt_year_month(column: str, new_column: str, fmt: str = '%Y-%m') -> Self

Create a year-month string from a datetime column.

Parameters:

Name	Type	Description	Default
column	str	Source datetime column.	required
new_column	str	Name for result column.	required
fmt	str	Output format string.	'%Y-%m'

Returns:

Type	Description
Self	Self for method chaining.

Source code in transformplan/ops/datetime.py

def dt_year_month(self, column: str, new_column: str, fmt: str = "%Y-%m") -> Self:
    """Create a year-month string from a datetime column.

    Args:
        column: Source datetime column.
        new_column: Name for result column.
        fmt: Output format string.

    Returns:
        Self for method chaining.
    """
    return self._register(
        self._dt_year_month,
        {"column": column, "new_column": new_column, "fmt": fmt},
    )

dt_quarter_year

dt_quarter_year(column: str, new_column: str) -> Self

Create a quarter-year string (e.g., 'Q1-2024') from a datetime column.

Parameters:

Name	Type	Description	Default
column	str	Source datetime column.	required
new_column	str	Name for result column.	required

Returns:

Type	Description
Self	Self for method chaining.

Source code in transformplan/ops/datetime.py

def dt_quarter_year(self, column: str, new_column: str) -> Self:
    """Create a quarter-year string (e.g., 'Q1-2024') from a datetime column.

    Args:
        column: Source datetime column.
        new_column: Name for result column.

    Returns:
        Self for method chaining.
    """
    return self._register(
        self._dt_quarter_year, {"column": column, "new_column": new_column}
    )

dt_calendar_week

dt_calendar_week(column: str, new_column: str) -> Self

Create a year-week string (e.g., '2024-W05') from a datetime column.

Parameters:

Name	Type	Description	Default
column	str	Source datetime column.	required
new_column	str	Name for result column.	required

Returns:

Type	Description
Self	Self for method chaining.

Source code in transformplan/ops/datetime.py

def dt_calendar_week(self, column: str, new_column: str) -> Self:
    """Create a year-week string (e.g., '2024-W05') from a datetime column.

    Args:
        column: Source datetime column.
        new_column: Name for result column.

    Returns:
        Self for method chaining.
    """
    return self._register(
        self._dt_calendar_week, {"column": column, "new_column": new_column}
    )

dt_parse

dt_parse(
    column: str, fmt: str = "%Y-%m-%d", new_column: str | None = None
) -> Self

Parse a string column into a datetime.

Parameters:

Name	Type	Description	Default
column	str	Source string column.	required
fmt	str	Date format string.	'%Y-%m-%d'
new_column	str | None	Name for result column (None = modify in place).	None

Returns:

Type	Description
Self	Self for method chaining.

Source code in transformplan/ops/datetime.py

def dt_parse(
    self,
    column: str,
    fmt: str = "%Y-%m-%d",
    new_column: str | None = None,
) -> Self:
    """Parse a string column into a datetime.

    Args:
        column: Source string column.
        fmt: Date format string.
        new_column: Name for result column (None = modify in place).

    Returns:
        Self for method chaining.
    """
    return self._register(
        self._dt_parse,
        {"column": column, "fmt": fmt, "new_column": new_column or column},
    )

dt_format

dt_format(column: str, fmt: str, new_column: str | None = None) -> Self

Format a datetime column as a string.

Parameters:

Name	Type	Description	Default
column	str	Source datetime column.	required
fmt	str	Output format string.	required
new_column	str | None	Name for result column (None = modify in place).	None

Returns:

Type	Description
Self	Self for method chaining.

Source code in transformplan/ops/datetime.py

def dt_format(self, column: str, fmt: str, new_column: str | None = None) -> Self:
    """Format a datetime column as a string.

    Args:
        column: Source datetime column.
        fmt: Output format string.
        new_column: Name for result column (None = modify in place).

    Returns:
        Self for method chaining.
    """
    return self._register(
        self._dt_format,
        {"column": column, "fmt": fmt, "new_column": new_column or column},
    )

dt_diff_days

dt_diff_days(column_a: str, column_b: str, new_column: str) -> Self

Calculate difference in days between two date columns (a - b).

Parameters:

Name	Type	Description	Default
column_a	str	First date column.	required
column_b	str	Second date column.	required
new_column	str	Name for result column.	required

Returns:

Type	Description
Self	Self for method chaining.

Source code in transformplan/ops/datetime.py

def dt_diff_days(self, column_a: str, column_b: str, new_column: str) -> Self:
    """Calculate difference in days between two date columns (a - b).

    Args:
        column_a: First date column.
        column_b: Second date column.
        new_column: Name for result column.

    Returns:
        Self for method chaining.
    """
    return self._register(
        self._dt_diff_days,
        {"column_a": column_a, "column_b": column_b, "new_column": new_column},
    )

dt_age_years

dt_age_years(
    birth_column: str,
    reference_column: str | None = None,
    new_column: str = "age",
) -> Self

Calculate age in years from a birth date.

Parameters:

Name	Type	Description	Default
birth_column	str	Column containing birth dates.	required
reference_column	str | None	Column containing reference dates (None = today).	None
new_column	str	Name for result column.	'age'

Returns:

Type	Description
Self	Self for method chaining.

Source code in transformplan/ops/datetime.py

def dt_age_years(
    self,
    birth_column: str,
    reference_column: str | None = None,
    new_column: str = "age",
) -> Self:
    """Calculate age in years from a birth date.

    Args:
        birth_column: Column containing birth dates.
        reference_column: Column containing reference dates (None = today).
        new_column: Name for result column.

    Returns:
        Self for method chaining.
    """
    return self._register(
        self._dt_age_years,
        {
            "birth_column": birth_column,
            "reference_column": reference_column,
            "new_column": new_column,
        },
    )

dt_truncate

dt_truncate(column: str, every: str, new_column: str | None = None) -> Self

Truncate datetime to a specified precision.

Parameters:

Name	Type	Description	Default
column	str	Source datetime column.	required
every	str	Truncation interval ('1d', '1mo', '1y', '1h', etc.).	required
new_column	str | None	Name for result column (None = modify in place).	None

Returns:

Type	Description
Self	Self for method chaining.

Source code in transformplan/ops/datetime.py

def dt_truncate(
    self,
    column: str,
    every: str,
    new_column: str | None = None,
) -> Self:
    """Truncate datetime to a specified precision.

    Args:
        column: Source datetime column.
        every: Truncation interval ('1d', '1mo', '1y', '1h', etc.).
        new_column: Name for result column (None = modify in place).

    Returns:
        Self for method chaining.
    """
    return self._register(
        self._dt_truncate,
        {"column": column, "every": every, "new_column": new_column or column},
    )

dt_is_between

dt_is_between(
    column: str,
    start: str,
    end: str,
    new_column: str,
    closed: ClosedInterval = "both",
) -> Self

Check if date falls within a range.

Parameters:

Name	Type	Description	Default
column	str	Source datetime column.	required
start	str	Start date (string, will be parsed).	required
end	str	End date (string, will be parsed).	required
new_column	str	Name for boolean result column.	required
closed	ClosedInterval	Which endpoints to include ('both', 'left', 'right', 'none').	'both'

Returns:

Type	Description
Self	Self for method chaining.

Source code in transformplan/ops/datetime.py

def dt_is_between(
    self,
    column: str,
    start: str,
    end: str,
    new_column: str,
    closed: ClosedInterval = "both",
) -> Self:
    """Check if date falls within a range.

    Args:
        column: Source datetime column.
        start: Start date (string, will be parsed).
        end: End date (string, will be parsed).
        new_column: Name for boolean result column.
        closed: Which endpoints to include ('both', 'left', 'right', 'none').

    Returns:
        Self for method chaining.
    """
    return self._register(
        self._dt_is_between,
        {
            "column": column,
            "start": start,
            "end": end,
            "new_column": new_column,
            "closed": closed,
        },
    )

Examples

Extracting Date Components

# Extract year
plan = TransformPlan().dt_year("date", new_column="year")

# Extract month
plan = TransformPlan().dt_month("date", new_column="month")

# Extract day
plan = TransformPlan().dt_day("date", new_column="day")

# Extract week number
plan = TransformPlan().dt_week("date", new_column="week")

# Extract quarter
plan = TransformPlan().dt_quarter("date", new_column="quarter")

Formatted Date Strings

# Year-month string (e.g., "2024-01")
plan = TransformPlan().dt_year_month("date", new_column="year_month")

# Quarter-year string (e.g., "Q1-2024")
plan = TransformPlan().dt_quarter_year("date", new_column="quarter_year")

# Calendar week string (e.g., "2024-W05")
plan = TransformPlan().dt_calendar_week("date", new_column="calendar_week")

Parsing and Formatting

# Parse string to date
plan = TransformPlan().dt_parse(
    column="date_string",
    fmt="%Y-%m-%d",
    new_column="date"
)

# Format date to string
plan = TransformPlan().dt_format(
    column="date",
    fmt="%B %d, %Y",
    new_column="formatted_date"
)

Date Arithmetic

# Calculate difference in days
plan = TransformPlan().dt_diff_days(
    column_a="end_date",
    column_b="start_date",
    new_column="duration_days"
)

# Calculate age in years
plan = TransformPlan().dt_age_years(
    birth_column="birth_date",
    new_column="age"
)

# Age relative to reference column
plan = TransformPlan().dt_age_years(
    birth_column="birth_date",
    reference_column="event_date",
    new_column="age_at_event"
)

Truncation

# Truncate to month start
plan = TransformPlan().dt_truncate("timestamp", every="1mo")

# Truncate to day
plan = TransformPlan().dt_truncate("timestamp", every="1d")

# Truncate to year
plan = TransformPlan().dt_truncate("timestamp", every="1y")

Range Checks

# Check if date is within range
plan = TransformPlan().dt_is_between(
    column="order_date",
    start="2024-01-01",
    end="2024-12-31",
    new_column="is_2024_order",
    closed="both"  # or "left", "right", "none"
)