Time Module

This module provides advanced time handling utilities with extended support for time zones, localization, and time-based operations.

Classes

TimeFormat

class true.time.TimeFormat(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Enum for different time formats.

An enumeration for different time formats.

  • HOUR_12: 12-hour format

  • HOUR_24: 24-hour format

  • ISO: ISO format

  • CUSTOM: Custom format

HOUR_12 = '12'
HOUR_24 = '24'
ISO = 'iso'
CUSTOM = 'custom'

TimeUnit

class true.time.TimeUnit(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Enum for time units.

An enumeration for time units.

  • MILLISECONDS: Milliseconds unit

  • SECONDS: Seconds unit

  • MINUTES: Minutes unit

  • HOURS: Hours unit

  • DAYS: Days unit

  • WEEKS: Weeks unit

  • MONTHS: Months unit

  • YEARS: Years unit

MILLISECONDS = 'milliseconds'
SECONDS = 'seconds'
MINUTES = 'minutes'
HOURS = 'hours'
DAYS = 'days'
WEEKS = 'weeks'
MONTHS = 'months'
YEARS = 'years'

TimeConfig

class true.time.TimeConfig(default_timezone='UTC', default_format=TimeFormat.HOUR_24, date_separator='-', time_separator=':', datetime_separator=' ')[source]

Bases: object

Configuration class for Time settings.

Configuration class for Time settings.

Parameters:

  • default_timezone – Default timezone (default: “UTC”)

  • default_format – Default time format (default: TimeFormat.HOUR_24)

  • date_separator – Separator for date components (default: “-“)

  • time_separator – Separator for time components (default: “:”)

  • datetime_separator – Separator between date and time (default: “ “)

default_timezone: str = 'UTC'
default_format: TimeFormat = '24'
date_separator: str = '-'
time_separator: str = ':'
datetime_separator: str = ' '
__init__(default_timezone='UTC', default_format=TimeFormat.HOUR_24, date_separator='-', time_separator=':', datetime_separator=' ')

Time

class true.time.Time(time_input=None, timezone_name=None, config=None)[source]

Bases: object

Advanced Time handling class with localization support and extended functionality.

Advanced Time handling class with localization support and extended functionality.

Key Features:

  • Time rounding, flooring, and ceiling based on time units

  • Time difference calculations with specified units

  • Conversion to different time zones

  • Flexible formatting with locale support

  • Support for checking if a time instance is within DST

  • Serialization to dictionary format

__init__(time_input=None, timezone_name=None, config=None)[source]

Initialize a Time object.

Parameters:
property datetime: datetime

Get datetime object.

property timezone: str

Get timezone name.

property quarter: int

Get year quarter (1-4).

floor(unit)[source]

Floor time to the nearest unit.

Return type:

Time

ceil(unit)[source]

Ceil time to the nearest unit.

Return type:

Time

round(unit)[source]

Round time to the nearest unit.

Return type:

Time

start_of(unit)[source]

Get start of time unit (alias for a floor).

Return type:

Time

end_of(unit)[source]

Get end-of-time unit.

Return type:

Time

is_between(start, end, inclusive=True)[source]

Check if time is between start and end times.

Return type:

bool

is_same(other, unit)[source]

Check if two times are in the same time unit.

Return type:

bool

classmethod min(*times)[source]

Get the earliest time from a sequence.

Return type:

Time

classmethod max(*times)[source]

Get the latest time from a sequence.

Return type:

Time

with_timezone(timezone_name)[source]

Return new Time instance with different timezone.

Return type:

Time

with_time(hour=0, minute=0, second=0, microsecond=0)[source]

Return new Time instance with specified time components.

Return type:

Time

with_date(year=None, month=None, day=None)[source]

Return new Time instance with specified date components.

Return type:

Time

static _parse_input(time_input)[source]

Parse various input formats to a datetime object.

Return type:

datetime

to_timezone(timezone_name)[source]

Convert time to different timezone.

Return type:

Time

format(format_type=TimeFormat.HOUR_24, custom_format=None, locale_name=None)[source]

Format time according to specified format and locale.

Parameters:

  • format_type (TimeFormat) – TimeFormat enum value

  • custom_format (Optional[str]) – Custom strftime format string

  • locale_name (Optional[str]) – Locale name (e.g., ‘en_US’)

Return type:

str

difference(other, unit=TimeUnit.SECONDS)[source]

Calculate time difference in specified unit.

Return type:

float

static get_available_timezones()[source]

Return list of available timezone names.

Return type:

List[str]

add(amount, unit)[source]

Add time duration to current time.

Return type:

Time

_add_months(months)[source]

Helper method to calculate the timedelta for adding months.

Return type:

timedelta

is_dst()[source]

Check if the current time is in DST.

Return type:

bool

to_dict()[source]

Convert a time object to dictionary representation.

Return type:

Dict

timer()[source]

A Timer context manager to calculate the time consumed inside a block of code.

classmethod now(timezone_name=None)[source]

Get current time in specified timezone.

Return type:

Time

__str__()[source]

String representation of a time object.

Return type:

str

__repr__()[source]

Detailed string representation of a time object.

Return type:

str

__add__(other)[source]

Add timedelta or seconds to Time instance.

Return type:

Time

__sub__(other)[source]

Subtract Time, timedelta, or seconds from Time instance.

Return type:

Union[Time, timedelta]

__eq__(other)[source]

Compare equality with another Time instance.

Return type:

bool

__lt__(other)[source]

Compare less than with another Time instance.

Return type:

bool

__le__(other)[source]

Compare less than or equal with another Time instance.

Event

class true.time.Event(name, start_time, end_time, description=None, recurrence=None, tags=None, priority=0, metadata=None)[source]

Bases: object

Represents a scheduled event with comprehensive time management capabilities.

Represents a scheduled event with comprehensive time management capabilities.

Parameters:

  • name – Event name

  • start_time – Event start time

  • end_time – Event end time

  • description – Optional event description

  • recurrence – Optional recurrence pattern

  • tags – Optional list of tags

  • priority – Event priority (default: 0)

  • metadata – Optional metadata dictionary

name: str
start_time: Time
end_time: Time
description: Optional[str] = None
recurrence: Optional[str] = None
tags: List[str] = None
priority: int = 0
metadata: Dict[str, Any] = None
__post_init__()[source]

Validate event data after initialization.

overlaps(other)[source]

Check if this event overlaps with another event.

Return type:

bool

duration(unit=TimeUnit.MINUTES)[source]

Get event duration in specified unit.

Return type:

float

is_recurring()[source]

Check if the event is recurring.

Return type:

bool

get_next_occurrence()[source]

Get the next occurrence of a recurring event.

Return type:

Optional[Event]

__init__(name, start_time, end_time, description=None, recurrence=None, tags=None, priority=0, metadata=None)

Schedule

class true.time.Schedule(timezone_name=None)[source]

Bases: object

Advanced scheduling system with support for complex time-based operations.

Features: - Event management (add, remove, update) - Conflict detection and resolution - Recurring events support - Event filtering and searching - Schedule optimization - Time block allocation - Schedule statistics and analytics

Advanced scheduling system with support for complex time-based operations.

Features:

  • Event management (add, remove, update)

  • Conflict detection and resolution

  • Recurring events support

  • Event filtering and searching

  • Schedule optimization

  • Time block allocation

  • Schedule statistics and analytics

__init__(timezone_name=None)[source]
add_event(event, check_conflicts=True)[source]

Add an event to the schedule with optional conflict checking.

Return type:

None

remove_event(event_name)[source]

Remove an event by name.

Return type:

Event

update_event(event_name, **kwargs)[source]

Update an existing event with new attributes.

Return type:

Event

get_events(start, end, tags=None, priority_min=None)[source]

Get events within a time range with optional filtering.

Return type:

List[Event]

find_free_slots(start, end, duration, unit=TimeUnit.MINUTES)[source]

Find available time slots of specified duration.

Return type:

List[Time]

get_statistics(start, end)[source]

Calculate comprehensive schedule statistics for a time period.

Return type:

Dict[str, Any]

_find_conflicts(new_event)[source]

Find all events that conflict with a given event.

Return type:

List[Event]

static _calculate_tags_distribution(events)[source]

Calculate the distribution of tags across events.

Return type:

Dict[str, int]

Functions

timeout

true.time.timeout(timeout_)[source]

Decorator that raises TimeoutError if function execution exceeds specified timeout in seconds.

Decorator that raises TimeoutError if function execution exceeds specified timeout in seconds.

Parameters:

timeout – Maximum execution time in seconds

Raises:

TimeoutError if execution time exceeds the specified timeout

timer

true.time.timer(func, per_counter=False)[source]

Decorator that measures and prints function execution time.

Decorator that measures and prints function execution time.

Parameters:

per_counter – Use performance counter for higher precision if True

Returns:

Wrapped function that prints execution time