type_bridge.attribute.datetimetz

datetimetz

DateTimeTZ attribute type for TypeDB.

DateTimeTZ

DateTimeTZ(value)

Bases: Attribute

DateTimeTZ attribute type that accepts timezone-aware datetime values.

This maps to TypeDB's 'datetime-tz' type, which requires timezone information. The datetime must have tzinfo set (e.g., using datetime.timezone.utc or zoneinfo).

Example

from datetime import datetime, timezone

class CreatedAt(DateTimeTZ): pass

Usage with timezone

event = Event(created_at=CreatedAt(datetime(2024, 1, 15, 10, 30, 45, tzinfo=timezone.utc)))

Convert to DateTime

naive_dt = created_at.strip_timezone() # Implicit: just strip tz naive_dt_jst = created_at.strip_timezone(timezone(timedelta(hours=9))) # Explicit: convert to JST, then strip

Initialize DateTimeTZ attribute with a timezone-aware datetime value.

Parameters:

Name	Type	Description	Default
value	datetime	The timezone-aware datetime value to store	required

Raises:

Type	Description
ValueError	If the datetime does not have timezone information

Source code in type_bridge/attribute/datetimetz.py

def __init__(self, value: datetime_type):
    """Initialize DateTimeTZ attribute with a timezone-aware datetime value.

    Args:
        value: The timezone-aware datetime value to store

    Raises:
        ValueError: If the datetime does not have timezone information
    """
    if value.tzinfo is None:
        raise ValueError(
            "DateTimeTZ requires timezone-aware datetime. "
            "Use DateTime for naive datetime or add tzinfo (e.g., datetime.timezone.utc)"
        )
    super().__init__(value)

value property

value

Get the stored datetime value.

strip_timezone

strip_timezone(tz=None)

Convert DateTimeTZ to DateTime by stripping timezone information.

Implicit conversion (tz=None): Just strip timezone as-is Explicit conversion (tz provided): Convert to specified timezone first, then strip

Parameters:

Name	Type	Description	Default
tz	timezone | None	Optional timezone to convert to before stripping. If None, strips timezone without conversion. If provided, converts to that timezone first.	None

Returns:

Type	Description
DateTime	DateTime instance with naive datetime

Example

Implicit: strip timezone as-is

naive = dt_tz.strip_timezone()

Explicit: convert to JST (+9), then strip

from datetime import timezone, timedelta jst = timezone(timedelta(hours=9)) naive_jst = dt_tz.strip_timezone(jst)

Source code in type_bridge/attribute/datetimetz.py

def strip_timezone(self, tz: timezone_type | None = None) -> "DateTime":
    """Convert DateTimeTZ to DateTime by stripping timezone information.

    Implicit conversion (tz=None): Just strip timezone as-is
    Explicit conversion (tz provided): Convert to specified timezone first, then strip

    Args:
        tz: Optional timezone to convert to before stripping.
            If None, strips timezone without conversion.
            If provided, converts to that timezone first.

    Returns:
        DateTime instance with naive datetime

    Example:
        # Implicit: strip timezone as-is
        naive = dt_tz.strip_timezone()

        # Explicit: convert to JST (+9), then strip
        from datetime import timezone, timedelta
        jst = timezone(timedelta(hours=9))
        naive_jst = dt_tz.strip_timezone(jst)
    """
    from type_bridge.attribute.datetime import DateTime

    dt_value = self.value
    if tz is not None:
        # Explicit: convert to specified timezone first
        dt_value = dt_value.astimezone(tz)

    # Strip timezone info
    naive_dt = dt_value.replace(tzinfo=None)
    return DateTime(naive_dt)

__add__

__add__(other)

Add a Duration to this DateTimeTZ.

Parameters:

Name	Type	Description	Default
other	Any	A Duration to add to this timezone-aware datetime	required

Returns:

Type	Description
DateTimeTZ	New DateTimeTZ with the duration added

Note

Duration addition respects timezone changes (DST, etc.)

Example

from type_bridge import Duration from datetime import datetime, timezone dt = DateTimeTZ(datetime(2024, 1, 31, 14, 0, 0, tzinfo=timezone.utc)) duration = Duration("P1M") result = dt + duration # DateTimeTZ(2024-02-28 14:00:00+00:00)

Source code in type_bridge/attribute/datetimetz.py

def __add__(self, other: Any) -> "DateTimeTZ":
    """Add a Duration to this DateTimeTZ.

    Args:
        other: A Duration to add to this timezone-aware datetime

    Returns:
        New DateTimeTZ with the duration added

    Note:
        Duration addition respects timezone changes (DST, etc.)

    Example:
        from type_bridge import Duration
        from datetime import datetime, timezone
        dt = DateTimeTZ(datetime(2024, 1, 31, 14, 0, 0, tzinfo=timezone.utc))
        duration = Duration("P1M")
        result = dt + duration  # DateTimeTZ(2024-02-28 14:00:00+00:00)
    """
    from type_bridge.attribute.duration import Duration

    if isinstance(other, Duration):
        # Add duration to timezone-aware datetime
        # isodate handles timezone-aware datetime + duration correctly
        new_dt = self.value + other.value
        return DateTimeTZ(new_dt)
    return NotImplemented

__radd__

__radd__(other)

Reverse addition for Duration + DateTimeTZ.

Source code in type_bridge/attribute/datetimetz.py

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