Timedelta

class Timedelta

Represents a duration, the difference between two dates or times.

Example

import pandasCore as pd

# Create Timedelta
obj = pd.Timedelta(...)

Attributes

Attribute	Description	Example
components	Return a tuple of components.	View
days	Return the days component	View
delta	Return the internal value in nanoseconds (alias for value)
hours	Return the hours component (0-23)	View
microseconds	Return the microseconds component (0-999)
milliseconds	Return the milliseconds component (0-999)
minutes	Return the minutes component (0-59)	View
nanoseconds	Return the nanoseconds component (0-999)
seconds	Return the seconds component (0-59)	View
total_days	Total days in the duration
total_hours	Total hours in the duration
total_minutes	Total minutes in the duration
total_nanoseconds	Total nanoseconds in the duration
value	Return the internal value in nanoseconds	View

Construction

Method	Description	Example
__init__() (value: object = None, unit: object = None, **kwargs)	Create a Timedelta.	View

Arithmetic

Method	Description	Example
__abs__() ()
__add__() (arg0: pandasCore.Timedelta)
__floordiv__() (*args, **kwargs) | (arg0: typing.SupportsInt) | (arg0: pandasCore.Timedelta)
__mod__() (arg0: pandasCore.Timedelta)
__mul__() (*args, **kwargs) | (arg0: typing.SupportsInt) | (arg0: typing.SupportsFloat)
__neg__() ()
__pos__() ()
__sub__() (arg0: pandasCore.Timedelta)
__truediv__() (*args, **kwargs) | (arg0: typing.SupportsInt) | (arg0: typing.SupportsFloat) | (arg0: pandasCore.Timedelta)

Comparison

Method	Description	Example
__eq__() (arg0: pandasCore.Timedelta)
__ge__() (arg0: pandasCore.Timedelta)
__gt__() (arg0: pandasCore.Timedelta)
__le__() (arg0: pandasCore.Timedelta)
__lt__() (arg0: pandasCore.Timedelta)
__ne__() (arg0: pandasCore.Timedelta)

I/O

Method	Description	Example
to_numpy() (dtype: object = None, copy: bool = False)	Return the value as nanoseconds (for numpy compatibility)
to_pytimedelta() ()	Convert to Python datetime.timedelta object.	View
to_timedelta64() ()	Convert to numpy timedelta64.

Conversion

Method	Description	Example
view() (dtype: object)	View the Timedelta as a different dtype.

Datetime Methods

Method	Description	Example
ceil() (freq: str)	Round up the Timedelta to the specified resolution.	View
floor() (freq: str)	Round down the Timedelta to the specified resolution.	View
round() (freq: str)	Round the Timedelta to the specified resolution.	View

Other Methods

Method	Description	Example
__hash__() ()
__repr__() ()
__str__() ()
as_unit() (unit: str, round_ok: bool = True)	Convert Timedelta to target unit resolution.
components_str() ()	Return a string representation of components
isnat() ()	Return True if the Timedelta is NaT (Not-a-Timedelta)
isoformat() ()	Return ISO 8601 duration format string.	View
total_seconds() ()	Total seconds in the duration.	View

Code Examples

The following examples are extracted from the test suite.

components (test_timedelta.py:534)

        f_print_error(f"Exception: {e}")
        return False


def test_components():
    """Test Timedelta components property"""
    f_print_header("Test: Timedelta components")

    try:
        td = pandasCore.Timedelta("1 days 02:30:45")
        components = td.components

        if components is not None and len(components) == 7:
            f_print_success(f"components: {components}")
            # (days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds)
            if components[0] == 1 and components[1] == 2 and components[2] == 30 and components[3] == 45:
                f_print_success("Components values are correct")
            else:
                f_print_error(f"Components values wrong: {components}")
                return False
        else:

days (test_timedelta.py:88)

def test_construction_from_string():
    """Test Timedelta construction from string"""
    f_print_header("Test: Timedelta Construction from String")

    try:
        # Create Timedelta from string
        td = pandasCore.Timedelta("1 days 02:30:00")
        f_print_success("Created Timedelta from string '1 days 02:30:00'")

        # Check days component
        if td.days == 1:
            f_print_success(f"days is correct: {td.days}")
        else:
            f_print_error(f"days is wrong: {td.days}, expected 1")
            return False

        # Check hours component
        if td.hours == 2:
            f_print_success(f"hours is correct: {td.hours}")
        else:
            f_print_error(f"hours is wrong: {td.hours}, expected 2")

hours (test_timedelta.py:95)

        f_print_success("Created Timedelta from string '1 days 02:30:00'")

        # Check days component
        if td.days == 1:
            f_print_success(f"days is correct: {td.days}")
        else:
            f_print_error(f"days is wrong: {td.days}, expected 1")
            return False

        # Check hours component
        if td.hours == 2:
            f_print_success(f"hours is correct: {td.hours}")
        else:
            f_print_error(f"hours is wrong: {td.hours}, expected 2")
            return False

        # Check minutes component
        if td.minutes == 30:
            f_print_success(f"minutes is correct: {td.minutes}")
        else:
            f_print_error(f"minutes is wrong: {td.minutes}, expected 30")

minutes (test_timedelta.py:102)

            return False

        # Check hours component
        if td.hours == 2:
            f_print_success(f"hours is correct: {td.hours}")
        else:
            f_print_error(f"hours is wrong: {td.hours}, expected 2")
            return False

        # Check minutes component
        if td.minutes == 30:
            f_print_success(f"minutes is correct: {td.minutes}")
        else:
            f_print_error(f"minutes is wrong: {td.minutes}, expected 30")
            return False

        # Check repr
        repr_str = repr(td)
        f_print_info(f"repr: {repr_str}")

        # Test short format

seconds (test_timedelta.py:201)

            return False

        # Check minutes
        if td.minutes == 30:
            f_print_success(f"minutes: {td.minutes}")
        else:
            f_print_error(f"minutes wrong: {td.minutes}, expected 30")
            return False

        # Check seconds
        if td.seconds == 45:
            f_print_success(f"seconds: {td.seconds}")
        else:
            f_print_error(f"seconds wrong: {td.seconds}, expected 45")
            return False

        return True

    except Exception as e:
        f_print_error(f"Exception: {e}")
        return False

value (test_timedelta.py:37)

def test_construction_default():
    """Test default Timedelta construction (zero duration)"""
    f_print_header("Test: Timedelta Default Construction")

    try:
        # Create default Timedelta (zero duration)
        td = pandasCore.Timedelta()
        f_print_success("Created default Timedelta")

        # Check value is 0
        if td.value == 0:
            f_print_success(f"value is correct: {td.value}")
        else:
            f_print_error(f"value is wrong: {td.value}, expected 0")
            return False

        # Check repr
        repr_str = repr(td)
        f_print_info(f"repr: {repr_str}")

        return True

__init__ (test_timedelta.py:33)

import pandasCore
import pandas as pd


def test_construction_default():
    """Test default Timedelta construction (zero duration)"""
    f_print_header("Test: Timedelta Default Construction")

    try:
        # Create default Timedelta (zero duration)
        td = pandasCore.Timedelta()
        f_print_success("Created default Timedelta")

        # Check value is 0
        if td.value == 0:
            f_print_success(f"value is correct: {td.value}")
        else:
            f_print_error(f"value is wrong: {td.value}, expected 0")
            return False

        # Check repr

to_pytimedelta (test_timedelta.py:495)

        f_print_error(f"Exception: {e}")
        return False


def test_to_pytimedelta():
    """Test Timedelta to_pytimedelta conversion"""
    f_print_header("Test: Timedelta to_pytimedelta")

    try:
        td = pandasCore.Timedelta("1 days 02:30:45")
        py_td = td.to_pytimedelta()

        # Check if it's a Python timedelta
        import datetime
        if isinstance(py_td, datetime.timedelta):
            f_print_success(f"to_pytimedelta returned: {py_td}")
        else:
            f_print_error(f"to_pytimedelta should return datetime.timedelta, got: {type(py_td)}")
            return False

        # Check days

ceil (test_timedelta.py:285)

        # Floor to hour
        td_floor = td.floor("h")
        if td_floor.hours == 12 and td_floor.minutes == 0:
            f_print_success(f"floor('h'): {td_floor}")
        else:
            f_print_error(f"floor('h') wrong: hours={td_floor.hours}, minutes={td_floor.minutes}")
            return False

        # Ceil to hour
        td_ceil = td.ceil("h")
        if td_ceil.hours == 13 and td_ceil.minutes == 0:
            f_print_success(f"ceil('h'): {td_ceil}")
        else:
            f_print_error(f"ceil('h') wrong: hours={td_ceil.hours}, minutes={td_ceil.minutes}")
            return False

        # Round to hour (30:30 should round up to 13)
        td_round = td.round("h")
        if td_round.hours == 13:
            f_print_success(f"round('h'): {td_round}")

floor (test_timedelta.py:277)

def test_rounding_methods():
    """Test Timedelta rounding methods"""
    f_print_header("Test: Timedelta Rounding Methods")

    try:
        # Create Timedelta: 1 day, 12 hours, 30 minutes, 30 seconds
        td = pandasCore.Timedelta("1 days 12:30:30")

        # Floor to hour
        td_floor = td.floor("h")
        if td_floor.hours == 12 and td_floor.minutes == 0:
            f_print_success(f"floor('h'): {td_floor}")
        else:
            f_print_error(f"floor('h') wrong: hours={td_floor.hours}, minutes={td_floor.minutes}")
            return False

        # Ceil to hour
        td_ceil = td.ceil("h")
        if td_ceil.hours == 13 and td_ceil.minutes == 0:
            f_print_success(f"ceil('h'): {td_ceil}")

round (test_timedelta.py:293)

        # Ceil to hour
        td_ceil = td.ceil("h")
        if td_ceil.hours == 13 and td_ceil.minutes == 0:
            f_print_success(f"ceil('h'): {td_ceil}")
        else:
            f_print_error(f"ceil('h') wrong: hours={td_ceil.hours}, minutes={td_ceil.minutes}")
            return False

        # Round to hour (30:30 should round up to 13)
        td_round = td.round("h")
        if td_round.hours == 13:
            f_print_success(f"round('h'): {td_round}")
        else:
            f_print_error(f"round('h') wrong: hours={td_round.hours}")
            return False

        return True

    except Exception as e:
        f_print_error(f"Exception: {e}")

isoformat (test_timedelta.py:252)

        f_print_error(f"Exception: {e}")
        return False


def test_isoformat():
    """Test Timedelta isoformat method"""
    f_print_header("Test: Timedelta isoformat")

    try:
        td = pandasCore.Timedelta("1 days 02:30:00")
        iso_str = td.isoformat()

        # Should contain P (period) and D (days)
        if "P" in iso_str and "D" in iso_str:
            f_print_success(f"isoformat: {iso_str}")
        else:
            f_print_error(f"isoformat wrong: {iso_str}")
            return False

        return True

total_seconds (test_timedelta.py:64)

def test_construction_from_nanoseconds():
    """Test Timedelta construction from nanoseconds"""
    f_print_header("Test: Timedelta Construction from Nanoseconds")

    try:
        # Create Timedelta from nanoseconds (1 second = 1e9 nanoseconds)
        td = pandasCore.Timedelta(1000000000)
        f_print_success("Created Timedelta from nanoseconds")

        # Check total_seconds
        total_sec = td.total_seconds()
        if abs(total_sec - 1.0) < 0.0001:
            f_print_success(f"total_seconds is correct: {total_sec}")
        else:
            f_print_error(f"total_seconds is wrong: {total_sec}, expected 1.0")
            return False

        return True

    except Exception as e:
        f_print_error(f"Exception: {e}")