Duration

The Duration class represents spans of time and time differences.

carbonic.core.duration.Duration dataclass

Duration(
    *,
    days: int | float = 0,
    hours: int | float = 0,
    minutes: int | float = 0,
    seconds: int | float = 0,
    microseconds: int | float = 0,
    milliseconds: int | float = 0,
    weeks: int | float = 0,
    months: int = 0,
    years: int = 0,
)

Immutable duration object representing a span of time.

Duration handles both calendar-aware components (months, years) and precise time components (days, hours, minutes, seconds, microseconds). All operations return new instances, maintaining immutability.

Attributes:

Name	Type	Description
_days	int	Number of days (aligned with datetime.timedelta)
_seconds	int	Number of seconds within the day (0-86399)
_microseconds	int	Number of microseconds within the second (0-999999)
_calendar_months	int	Calendar months component (for display/parsing)
_calendar_years	int	Calendar years component (for display/parsing)

Examples:

>>> duration = Duration(hours=2, minutes=30)
>>> duration.total_seconds()
9000.0

>>> long_duration = Duration(years=1, months=6, days=15)
>>> long_duration.humanize(max_units=3)
'1 year 6 months 15 days'

Create a Duration from individual time components.

Attributes

days property

days: int

The number of days in this duration.

Returns:

Type	Description
int	Number of days as integer

seconds property

seconds: int

The seconds component of this duration (0-86399, datetime.timedelta compatibility).

Returns:

Type	Description
int	Seconds within the current day, matching datetime.timedelta API

storage_seconds property

storage_seconds: int

Get seconds component of storage (0-86399, representing seconds within a day).

Returns:

Type	Description
int	Seconds within the current day (internal storage format)

microseconds property

microseconds: int

The microseconds component of this duration.

Returns:

Type	Description
int	Number of microseconds (0-999999)

milliseconds property

milliseconds: int

Get milliseconds component.

Returns:

Type	Description
int	Number of milliseconds derived from microseconds

hours property

hours: int

Get total hours for this duration (excluding calendar components).

weeks property

weeks: int

Get total weeks for this duration.

months property

months: int

Get calendar months component (for display purposes only).

years property

years: int

Get calendar years component (for display purposes only).

Functions

parse classmethod

parse(s: str) -> Duration

Parse ISO 8601 duration string or custom format.

Supports the following ISO 8601 duration formats: - P[n]Y[n]M[n]DT[n]H[n]M[n]S (full format) - P[n]Y[n]M[n]D (date only) - PT[n]H[n]M[n]S (time only) - P[n]W (weeks) - -P... (negative durations)

Examples:

Duration.parse("P1Y2M3DT4H5M6S") # 1 year, 2 months, 3 days, 4 hours, 5 minutes, 6 seconds Duration.parse("PT2H30M") # 2 hours, 30 minutes Duration.parse("P2W") # 2 weeks Duration.parse("-P1DT2H") # negative 1 day, 2 hours

total_seconds

total_seconds() -> float

Get total seconds for this duration (excluding calendar components).

Returns:

Type	Description
float	Total number of seconds as float, including fractional seconds
float	from microseconds. Calendar components (months, years) are not
float	included as they have variable length.

Examples:

>>> duration = Duration(hours=2, minutes=30, seconds=15)
>>> duration.total_seconds()
9015.0

in_seconds

in_seconds(*, whole: Literal[True]) -> int

in_seconds(*, whole: Literal[False] = False) -> float

in_seconds(*, whole: bool = False) -> int | float

Get total duration expressed as seconds.

Parameters:

Name	Type	Description	Default
whole	bool	If True, return integer (floor). If False, return float.	False

in_minutes

in_minutes(*, whole: Literal[True]) -> int

in_minutes(*, whole: Literal[False] = False) -> float

in_minutes(*, whole: bool = False) -> int | float

Get total duration expressed as minutes.

Parameters:

Name	Type	Description	Default
whole	bool	If True, return integer (floor). If False, return float.	False

in_hours

in_hours(*, whole: Literal[True]) -> int

in_hours(*, whole: Literal[False] = False) -> float

in_hours(*, whole: bool = False) -> int | float

Get total duration expressed as hours.

Parameters:

Name	Type	Description	Default
whole	bool	If True, return integer (floor). If False, return float.	False

in_days

in_days(*, whole: Literal[True]) -> int

in_days(*, whole: Literal[False] = False) -> float

in_days(*, whole: bool = False) -> int | float

Get total duration expressed as days.

Parameters:

Name	Type	Description	Default
whole	bool	If True, return integer (floor). If False, return float.	False

in_weeks

in_weeks(*, whole: Literal[True]) -> int

in_weeks(*, whole: Literal[False] = False) -> float

in_weeks(*, whole: bool = False) -> int | float

Get total duration expressed as weeks.

Parameters:

Name	Type	Description	Default
whole	bool	If True, return integer (floor). If False, return float.	False

in_milliseconds

in_milliseconds(*, whole: Literal[True]) -> int

in_milliseconds(*, whole: Literal[False] = False) -> float

in_milliseconds(*, whole: bool = False) -> int | float

Get total duration expressed as milliseconds.

Parameters:

Name	Type	Description	Default
whole	bool	If True, return integer (floor). If False, return float.	False

in_microseconds

in_microseconds(*, whole: Literal[True]) -> int

in_microseconds(*, whole: Literal[False] = False) -> float

in_microseconds(*, whole: bool = False) -> int | float

Get total duration expressed as microseconds.

Parameters:

Name	Type	Description	Default
whole	bool	If True, return integer (floor). If False, return float.	False

humanize

humanize(*, max_units: int = 2, locale: str | None = None) -> str

Return human-readable duration string.

Parameters:

Name	Type	Description	Default
max_units	int	Maximum number of time units to display (default: 2)	2
locale	str | None	Locale for localization (default: None for English)	None

Returns:

Type	Description
str	Human-readable string like "2 days 3 hours" or "1 year 6 months"

Examples:

Duration(days=2, hours=3).humanize() # "2 days 3 hours" Duration(minutes=90).humanize(max_units=1) # "1 hour" Duration(seconds=45).humanize(locale="pl") # "45 sekund" (if implemented)