Model elapsed time
Representing an elapsed interval such as a service-level duration or retry delay.
Pandas · Function
pd.Timedelta
pd.Timedelta creates a scalar duration from duration-like values, strings, integers with units, or named time components. It is pandas' duration type and interoperates with Python's datetime.timedelta.
How it works
pd.Timedelta constructs a pandas duration from another duration-like value, a string, an integer plus unit, or named components such as days and hours. The resulting object uses nanoseconds for its underlying .value representation.
Syntax
class pandas.Timedelta(*value=<object object>*, *unit=None*, ***kwargs*)Parameters
| Name | Type | Description |
|---|---|---|
value | Timedelta, timedelta, np.timedelta64, str, or int | Duration-like input: Timedelta, timedelta, np.timedelta64, string, or integer. |
unit | str, default 'ns' | Unit for an integer input; the documented default is ns. |
**kwargs | named duration components | Duration components accepted by the constructor: days, seconds, microseconds, milliseconds, minutes, hours, and weeks. |
Returns
A pandas Timedelta duration scalar.
Key points
- Use it for a scalar elapsed-time duration or for the difference between temporal values.
- It interoperates with Python's standard-library
datetime.timedeltain most situations. - When passing an integer, use
unitto specify whether it means days, hours, minutes, or another supported duration unit. - Named component construction supports weeks, days, hours, minutes, seconds, milliseconds, microseconds, and their combinations.
- The object's underlying integer value is consistently measured in nanoseconds.
Common mistakes
- Subnanosecond precision is discarded when the input has finer precision than nanoseconds.
- Provide either a value/unit combination or constructor keyword components; do not call the constructor without an input.
Example: Construct durations
import pandas as pd
elapsed = pd.Timedelta(days=2, hours=3, minutes=4)
scaled = pd.Timedelta(90, unit="minutes")
print(elapsed)
print(scaled.value)Creates durations using named components and an integer interpreted in an explicitly selected unit.
When to use it
Compose named components
Building a duration from readable components such as days, hours, and minutes.
Interpret numeric values
Converting numeric quantities into explicitly unit-labeled pandas durations.
Interview questions
QWhat does pd.Timedelta represent?
pd.Timedelta represents a duration or the difference between two dates or times. It is pandas' counterpart to Python's datetime.timedelta and is generally interchangeable with it.
Follow-up: How can an integer be interpreted correctly? Supply unit, because the unit argument denotes the unit of an integer input and defaults to nanoseconds.
QWhich kinds of input can construct a Timedelta?
The constructor accepts duration-like values such as Timedelta, timedelta, np.timedelta64, strings, and integers. It also accepts keyword components including days, seconds, microseconds, milliseconds, minutes, hours, and weeks.
Follow-up: What restriction applies to numeric construction? A numeric value should be paired with unit so its scale is explicit rather than relying on the default.
QWhat unit does the .value representation use?
The .value attribute exposes the duration's underlying integer representation in nanoseconds. Even when another input unit is supplied, this stored value is expressed in nanoseconds.
Follow-up: What happens to finer-than-nanosecond input? Its precision is truncated to nanoseconds.
Related
pandas.to_timedeltapandas.TimedeltaIndexpandas.timedelta_rangedatetime.timedeltanumpy.timedelta64