type_bridge.attribute.duration

duration

Duration attribute type for TypeDB.

Duration

Duration(value)

Bases: Attribute

Duration attribute type that accepts ISO 8601 duration values.

This maps to TypeDB's 'duration' type, which represents calendar-aware time spans using months, days, and nanoseconds.

TypeDB duration format: ISO 8601 duration (e.g., P1Y2M3DT4H5M6.789S) Storage: 32-bit months, 32-bit days, 64-bit nanoseconds

Important notes: - Durations are partially ordered (P1M and P30D cannot be compared) - P1D ≠ PT24H (calendar day vs 24 hours) - P1M ≠ P30D (months vary in length) - Addition is not commutative with calendar components

Example

from datetime import timedelta

class SessionDuration(Duration): pass

class EventCadence(Duration): pass

From ISO 8601 string

cadence = EventCadence("P1M") # 1 month interval = SessionDuration("PT1H30M") # 1 hour 30 minutes

From timedelta (converted to Duration internally)

session = SessionDuration(timedelta(hours=2))

Complex duration

complex = EventCadence("P1Y2M3DT4H5M6.789S")

Initialize Duration attribute with a duration value.

Parameters:

Name	Type	Description	Default
value	str | timedelta | Duration	The duration value to store. Can be: - str: ISO 8601 duration string (e.g., "P1Y2M3DT4H5M6S") - timedelta: Python timedelta (converted to Duration) - isodate.Duration: Direct Duration object	required

Raises:

Type	Description
ValueError	If duration components exceed storage limits

Example

From ISO string

duration1 = Duration("P1M") # 1 month duration2 = Duration("PT1H30M") # 1 hour 30 minutes

From timedelta

from datetime import timedelta duration3 = Duration(timedelta(hours=2, minutes=30))

Complex duration

duration4 = Duration("P1Y2M3DT4H5M6.789S")

Source code in type_bridge/attribute/duration.py

def __init__(self, value: str | timedelta | IsodateDuration):
    """Initialize Duration attribute with a duration value.

    Args:
        value: The duration value to store. Can be:
            - str: ISO 8601 duration string (e.g., "P1Y2M3DT4H5M6S")
            - timedelta: Python timedelta (converted to Duration)
            - isodate.Duration: Direct Duration object

    Raises:
        ValueError: If duration components exceed storage limits

    Example:
        # From ISO string
        duration1 = Duration("P1M")  # 1 month
        duration2 = Duration("PT1H30M")  # 1 hour 30 minutes

        # From timedelta
        from datetime import timedelta
        duration3 = Duration(timedelta(hours=2, minutes=30))

        # Complex duration
        duration4 = Duration("P1Y2M3DT4H5M6.789S")
    """
    if isinstance(value, str):
        value = isodate.parse_duration(value)
    elif isinstance(value, timedelta) and not isinstance(value, IsodateDuration):
        # Convert plain timedelta to Duration for consistent handling
        value = _timedelta_to_duration(value)

    # Validate storage limits
    if isinstance(value, IsodateDuration):
        _validate_duration_limits(value)

    super().__init__(value)

value property

value

Get the stored duration value.

Returns:

Type	Description
Duration	isodate.Duration instance (zero duration if None)

to_iso8601

to_iso8601()

Convert duration to ISO 8601 string format.

Returns:

Type	Description
str	ISO 8601 duration string (e.g., "P1Y2M3DT4H5M6S")

Example

duration = Duration("P1M") assert duration.to_iso8601() == "P1M"

Source code in type_bridge/attribute/duration.py

def to_iso8601(self) -> str:
    """Convert duration to ISO 8601 string format.

    Returns:
        ISO 8601 duration string (e.g., "P1Y2M3DT4H5M6S")

    Example:
        duration = Duration("P1M")
        assert duration.to_iso8601() == "P1M"
    """
    return isodate.duration_isoformat(self.value)

__add__

__add__(other)

Add two durations.

Parameters:

Name	Type	Description	Default
other	Any	Another Duration to add	required

Returns:

Type	Description
Duration	New Duration with sum

Example

d1 = Duration("P1M") d2 = Duration("P15D") result = d1 + d2 # P1M15D

Source code in type_bridge/attribute/duration.py

def __add__(self, other: Any) -> "Duration":
    """Add two durations.

    Args:
        other: Another Duration to add

    Returns:
        New Duration with sum

    Example:
        d1 = Duration("P1M")
        d2 = Duration("P15D")
        result = d1 + d2  # P1M15D
    """
    if isinstance(other, Duration):
        # Both are Durations, add their components
        result = self.value + other.value
        return Duration(result)
    return NotImplemented

__radd__

__radd__(other)

Reverse addition for Duration.

Source code in type_bridge/attribute/duration.py

def __radd__(self, other: Any) -> "Duration":
    """Reverse addition for Duration."""
    return self.__add__(other)

__sub__

__sub__(other)

Subtract two durations.

Parameters:

Name	Type	Description	Default
other	Any	Another Duration to subtract	required

Returns:

Type	Description
Duration	New Duration with difference

Example

d1 = Duration("P1M") d2 = Duration("P15D") result = d1 - d2 # P1M-15D

Source code in type_bridge/attribute/duration.py

def __sub__(self, other: Any) -> "Duration":
    """Subtract two durations.

    Args:
        other: Another Duration to subtract

    Returns:
        New Duration with difference

    Example:
        d1 = Duration("P1M")
        d2 = Duration("P15D")
        result = d1 - d2  # P1M-15D
    """
    if isinstance(other, Duration):
        # Both are Durations, subtract their components
        result = self.value - other.value
        return Duration(result)
    return NotImplemented