Temporal Module¶
The rite.temporal module provides comprehensive date, time, and duration management utilities.
Overview¶
Temporal Module¶
Date, time, and timezone operations.
This module provides comprehensive utilities for working with dates, times, durations, timezones, calendars, and formatting using only Python's standard library.
Submodules¶
- datetime: Date and time operations
- duration: Time duration utilities
- timezone: Timezone conversions
- calendar: Calendar operations
- formatting: Date/time formatting
Examples¶
from rite.temporal import datetime_now, duration_from_hours now = datetime_now() dur = duration_from_hours(2)
Notes¶
Legacy classes Timestamp, Duration, and Timezone are still available for backward compatibility.
Modules¶
calendar
¶
Calendar Module¶
Calendar operations.
This submodule provides utilities for calendar operations like leap years, days in month, and weekday calculations.
Examples¶
from rite.temporal.calendar import calendar_is_leap_year from rite.temporal.calendar import calendar_month_days calendar_is_leap_year(2024) True calendar_month_days(2024, 2) 29
Modules¶
calendar_is_leap_year
¶
Calendar Is Leap Year¶
Check if year is leap year.
Examples¶
from rite.temporal.calendar import calendar_is_leap_year calendar_is_leap_year(2024) True
Functions¶
calendar_is_leap_year(year: int) -> bool
¶Check if year is a leap year.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
year
|
int
|
Year to check. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if leap year, False otherwise. |
Examples:
>>> calendar_is_leap_year(2024)
True
>>> calendar_is_leap_year(2023)
False
>>> calendar_is_leap_year(2000)
True
Notes
Uses calendar.isleap().
calendar_month_days
¶
Calendar Month Days¶
Get number of days in month.
Examples¶
from rite.temporal.calendar import calendar_month_days calendar_month_days(2024, 2) 29
Functions¶
calendar_month_days(year: int, month: int) -> int
¶Get number of days in month.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
year
|
int
|
Year. |
required |
month
|
int
|
Month (1-12). |
required |
Returns:
| Type | Description |
|---|---|
int
|
Number of days in month. |
Examples:
>>> calendar_month_days(2024, 2)
29
>>> calendar_month_days(2023, 2)
28
>>> calendar_month_days(2024, 4)
30
Notes
Uses calendar.monthrange().
calendar_weekday
¶
Calendar Weekday¶
Get weekday for date.
Examples¶
from rite.temporal.calendar import calendar_weekday calendar_weekday(2024, 12, 27) 4
Functions¶
calendar_weekday(year: int, month: int, day: int) -> int
¶Get weekday for date.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
year
|
int
|
Year. |
required |
month
|
int
|
Month (1-12). |
required |
day
|
int
|
Day of month. |
required |
Returns:
| Type | Description |
|---|---|
int
|
Weekday (0=Monday, 6=Sunday). |
Examples:
Notes
Uses calendar.weekday(). 0=Monday, 6=Sunday.
calendar_is_leap_year
¶
Calendar Is Leap Year¶
Check if year is leap year.
Examples¶
from rite.temporal.calendar import calendar_is_leap_year calendar_is_leap_year(2024) True
Functions¶
calendar_is_leap_year(year: int) -> bool
¶
Check if year is a leap year.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
year
|
int
|
Year to check. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if leap year, False otherwise. |
Examples:
>>> calendar_is_leap_year(2024)
True
>>> calendar_is_leap_year(2023)
False
>>> calendar_is_leap_year(2000)
True
Notes
Uses calendar.isleap().
calendar_month_days
¶
Calendar Month Days¶
Get number of days in month.
Examples¶
from rite.temporal.calendar import calendar_month_days calendar_month_days(2024, 2) 29
Functions¶
calendar_month_days(year: int, month: int) -> int
¶
Get number of days in month.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
year
|
int
|
Year. |
required |
month
|
int
|
Month (1-12). |
required |
Returns:
| Type | Description |
|---|---|
int
|
Number of days in month. |
Examples:
>>> calendar_month_days(2024, 2)
29
>>> calendar_month_days(2023, 2)
28
>>> calendar_month_days(2024, 4)
30
Notes
Uses calendar.monthrange().
calendar_weekday
¶
Calendar Weekday¶
Get weekday for date.
Examples¶
from rite.temporal.calendar import calendar_weekday calendar_weekday(2024, 12, 27) 4
Functions¶
calendar_weekday(year: int, month: int, day: int) -> int
¶
Get weekday for date.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
year
|
int
|
Year. |
required |
month
|
int
|
Month (1-12). |
required |
day
|
int
|
Day of month. |
required |
Returns:
| Type | Description |
|---|---|
int
|
Weekday (0=Monday, 6=Sunday). |
Examples:
Notes
Uses calendar.weekday(). 0=Monday, 6=Sunday.
datetime
¶
DateTime Module¶
Date and time operations.
This submodule provides utilities for working with datetime objects including creation, parsing, formatting, and conversions.
Examples¶
from rite.temporal.datetime import datetime_now, datetime_format now = datetime_now() datetime_format(now) '2024-12-27 15:30:00'
Modules¶
datetime_format
¶
DateTime Format¶
Format datetime to string.
Examples¶
from rite.temporal.datetime import datetime_format from datetime import datetime datetime_format(datetime.now())
Functions¶
datetime_format(dt: datetime, fmt: str = '%Y-%m-%d %H:%M:%S') -> str
¶Format datetime to string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime
|
Datetime object. |
required |
fmt
|
str
|
Format string. Defaults to "%Y-%m-%d %H:%M:%S". |
'%Y-%m-%d %H:%M:%S'
|
Returns:
| Type | Description |
|---|---|
str
|
Formatted datetime string. |
Examples:
>>> from datetime import datetime
>>> dt = datetime(2024, 12, 27, 15, 30)
>>> datetime_format(dt)
'2024-12-27 15:30:00'
>>> datetime_format(dt, "%d/%m/%Y")
'27/12/2024'
Notes
See strftime documentation for format codes.
datetime_from_timestamp
¶
DateTime From Timestamp¶
Create datetime from UNIX timestamp.
Examples¶
from rite.temporal.datetime import datetime_from_timestamp datetime_from_timestamp(1735315200)
Functions¶
datetime_from_timestamp(timestamp: int | float, tz: timezone | None = None) -> datetime
¶Create datetime from UNIX timestamp.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
timestamp
|
int | float
|
UNIX timestamp (seconds since epoch). |
required |
tz
|
timezone | None
|
Timezone. Defaults to UTC. |
None
|
Returns:
| Type | Description |
|---|---|
datetime
|
Datetime object. |
Examples:
>>> datetime_from_timestamp(1735315200)
datetime.datetime(2024, 12, 27, ...)
>>> datetime_from_timestamp(0, timezone.utc)
datetime.datetime(1970, 1, 1, 0, 0, tzinfo=...)
Notes
Handles both int and float timestamps. Defaults to UTC timezone.
datetime_now
¶
DateTime Now¶
Get current datetime.
Examples¶
from rite.temporal.datetime import datetime_now datetime_now() datetime.datetime(2025, 12, 27, ...)
Functions¶
datetime_now(tz: timezone | None = None) -> datetime
¶Get current datetime.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tz
|
timezone | None
|
Timezone. Defaults to UTC. |
None
|
Returns:
| Type | Description |
|---|---|
datetime
|
Current datetime object. |
Examples:
>>> datetime_now()
datetime.datetime(2025, 12, 27, ...)
>>> datetime_now(timezone.utc)
datetime.datetime(2025, 12, 27, ..., tzinfo=...)
Notes
Uses timezone-aware datetime. Defaults to UTC if no timezone provided.
datetime_parse
¶
DateTime Parse¶
Parse datetime from string.
Examples¶
from rite.temporal.datetime import datetime_parse datetime_parse("2024-12-27", "%Y-%m-%d")
Functions¶
datetime_parse(date_string: str, fmt: str = '%Y-%m-%d %H:%M:%S') -> datetime
¶Parse datetime from string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
date_string
|
str
|
Date/time string. |
required |
fmt
|
str
|
Format string. Defaults to "%Y-%m-%d %H:%M:%S". |
'%Y-%m-%d %H:%M:%S'
|
Returns:
| Type | Description |
|---|---|
datetime
|
Parsed datetime object. |
Examples:
>>> datetime_parse("2024-12-27", "%Y-%m-%d")
datetime.datetime(2024, 12, 27, 0, 0)
>>> datetime_parse("27/12/2024 15:30", "%d/%m/%Y %H:%M")
datetime.datetime(2024, 12, 27, 15, 30)
Notes
See strftime documentation for format codes. Returns naive datetime (no timezone).
datetime_to_iso
¶
DateTime To ISO¶
Convert datetime to ISO 8601 string.
Examples¶
from rite.temporal.datetime import datetime_to_iso from datetime import datetime datetime_to_iso(datetime.now())
Functions¶
datetime_to_iso(dt: datetime) -> str
¶Convert datetime to ISO 8601 string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime
|
Datetime object. |
required |
Returns:
| Type | Description |
|---|---|
str
|
ISO 8601 formatted string. |
Examples:
>>> from datetime import datetime, timezone
>>> dt = datetime(2024, 12, 27, 15, 30, tzinfo=timezone.utc)
>>> datetime_to_iso(dt)
'2024-12-27T15:30:00+00:00'
Notes
Uses isoformat() method. Includes timezone if present.
datetime_to_timestamp
¶
DateTime To Timestamp¶
Convert datetime to UNIX timestamp.
Examples¶
from rite.temporal.datetime import datetime_to_timestamp from datetime import datetime datetime_to_timestamp(datetime(2024, 12, 27))
Functions¶
datetime_to_timestamp(dt: datetime) -> int
¶Convert datetime to UNIX timestamp.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime
|
Datetime object. |
required |
Returns:
| Type | Description |
|---|---|
int
|
UNIX timestamp as integer. |
Examples:
>>> from datetime import datetime, timezone
>>> dt = datetime(1970, 1, 1, tzinfo=timezone.utc)
>>> datetime_to_timestamp(dt)
0
Notes
Returns integer (seconds). For milliseconds, use int(dt.timestamp() * 1000).
datetime_format
¶
DateTime Format¶
Format datetime to string.
Examples¶
from rite.temporal.datetime import datetime_format from datetime import datetime datetime_format(datetime.now())
Functions¶
datetime_format(dt: datetime, fmt: str = '%Y-%m-%d %H:%M:%S') -> str
¶
Format datetime to string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime
|
Datetime object. |
required |
fmt
|
str
|
Format string. Defaults to "%Y-%m-%d %H:%M:%S". |
'%Y-%m-%d %H:%M:%S'
|
Returns:
| Type | Description |
|---|---|
str
|
Formatted datetime string. |
Examples:
>>> from datetime import datetime
>>> dt = datetime(2024, 12, 27, 15, 30)
>>> datetime_format(dt)
'2024-12-27 15:30:00'
>>> datetime_format(dt, "%d/%m/%Y")
'27/12/2024'
Notes
See strftime documentation for format codes.
datetime_from_timestamp
¶
DateTime From Timestamp¶
Create datetime from UNIX timestamp.
Examples¶
from rite.temporal.datetime import datetime_from_timestamp datetime_from_timestamp(1735315200)
Functions¶
datetime_from_timestamp(timestamp: int | float, tz: timezone | None = None) -> datetime
¶
Create datetime from UNIX timestamp.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
timestamp
|
int | float
|
UNIX timestamp (seconds since epoch). |
required |
tz
|
timezone | None
|
Timezone. Defaults to UTC. |
None
|
Returns:
| Type | Description |
|---|---|
datetime
|
Datetime object. |
Examples:
>>> datetime_from_timestamp(1735315200)
datetime.datetime(2024, 12, 27, ...)
>>> datetime_from_timestamp(0, timezone.utc)
datetime.datetime(1970, 1, 1, 0, 0, tzinfo=...)
Notes
Handles both int and float timestamps. Defaults to UTC timezone.
datetime_now
¶
DateTime Now¶
Get current datetime.
Examples¶
from rite.temporal.datetime import datetime_now datetime_now() datetime.datetime(2025, 12, 27, ...)
Functions¶
datetime_now(tz: timezone | None = None) -> datetime
¶
Get current datetime.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tz
|
timezone | None
|
Timezone. Defaults to UTC. |
None
|
Returns:
| Type | Description |
|---|---|
datetime
|
Current datetime object. |
Examples:
>>> datetime_now()
datetime.datetime(2025, 12, 27, ...)
>>> datetime_now(timezone.utc)
datetime.datetime(2025, 12, 27, ..., tzinfo=...)
Notes
Uses timezone-aware datetime. Defaults to UTC if no timezone provided.
datetime_parse
¶
DateTime Parse¶
Parse datetime from string.
Examples¶
from rite.temporal.datetime import datetime_parse datetime_parse("2024-12-27", "%Y-%m-%d")
Functions¶
datetime_parse(date_string: str, fmt: str = '%Y-%m-%d %H:%M:%S') -> datetime
¶
Parse datetime from string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
date_string
|
str
|
Date/time string. |
required |
fmt
|
str
|
Format string. Defaults to "%Y-%m-%d %H:%M:%S". |
'%Y-%m-%d %H:%M:%S'
|
Returns:
| Type | Description |
|---|---|
datetime
|
Parsed datetime object. |
Examples:
>>> datetime_parse("2024-12-27", "%Y-%m-%d")
datetime.datetime(2024, 12, 27, 0, 0)
>>> datetime_parse("27/12/2024 15:30", "%d/%m/%Y %H:%M")
datetime.datetime(2024, 12, 27, 15, 30)
Notes
See strftime documentation for format codes. Returns naive datetime (no timezone).
datetime_to_iso
¶
DateTime To ISO¶
Convert datetime to ISO 8601 string.
Examples¶
from rite.temporal.datetime import datetime_to_iso from datetime import datetime datetime_to_iso(datetime.now())
Functions¶
datetime_to_iso(dt: datetime) -> str
¶
Convert datetime to ISO 8601 string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime
|
Datetime object. |
required |
Returns:
| Type | Description |
|---|---|
str
|
ISO 8601 formatted string. |
Examples:
>>> from datetime import datetime, timezone
>>> dt = datetime(2024, 12, 27, 15, 30, tzinfo=timezone.utc)
>>> datetime_to_iso(dt)
'2024-12-27T15:30:00+00:00'
Notes
Uses isoformat() method. Includes timezone if present.
datetime_to_timestamp
¶
DateTime To Timestamp¶
Convert datetime to UNIX timestamp.
Examples¶
from rite.temporal.datetime import datetime_to_timestamp from datetime import datetime datetime_to_timestamp(datetime(2024, 12, 27))
Functions¶
datetime_to_timestamp(dt: datetime) -> int
¶
Convert datetime to UNIX timestamp.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime
|
Datetime object. |
required |
Returns:
| Type | Description |
|---|---|
int
|
UNIX timestamp as integer. |
Examples:
>>> from datetime import datetime, timezone
>>> dt = datetime(1970, 1, 1, tzinfo=timezone.utc)
>>> datetime_to_timestamp(dt)
0
Notes
Returns integer (seconds). For milliseconds, use int(dt.timestamp() * 1000).
duration
¶
Duration Module¶
Time duration operations.
This submodule provides utilities for creating and manipulating time durations using timedelta objects.
Examples¶
from rite.temporal.duration import duration_from_hours from rite.temporal.duration import duration_to_seconds dur = duration_from_hours(2) duration_to_seconds(dur) 7200.0
Modules¶
duration_from_days
¶
Duration From Days¶
Create duration from days.
Examples¶
from rite.temporal.duration import duration_from_days duration_from_days(7) timedelta(days=7)
Functions¶
duration_from_days(days: int | float) -> timedelta
¶Create timedelta from days.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
days
|
int | float
|
Number of days. |
required |
Returns:
| Type | Description |
|---|---|
timedelta
|
Timedelta object. |
Examples:
>>> duration_from_days(7)
timedelta(days=7)
>>> duration_from_days(1.5)
timedelta(days=1, seconds=43200)
Notes
Standard timedelta constructor.
duration_from_hours
¶
Duration From Hours¶
Create duration from hours.
Examples¶
from rite.temporal.duration import duration_from_hours duration_from_hours(24) timedelta(days=1)
duration_from_minutes
¶
Duration From Minutes¶
Create duration from minutes.
Examples¶
from rite.temporal.duration import duration_from_minutes duration_from_minutes(60) timedelta(seconds=3600)
Functions¶
duration_from_minutes(minutes: int | float) -> timedelta
¶Create timedelta from minutes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
minutes
|
int | float
|
Number of minutes. |
required |
Returns:
| Type | Description |
|---|---|
timedelta
|
Timedelta object. |
Examples:
>>> duration_from_minutes(60)
timedelta(seconds=3600)
>>> duration_from_minutes(1.5)
timedelta(seconds=90)
Notes
Converts to seconds internally.
duration_from_seconds
¶
Duration From Seconds¶
Create duration from seconds.
Examples¶
from rite.temporal.duration import duration_from_seconds duration_from_seconds(3600) timedelta(seconds=3600)
Functions¶
duration_from_seconds(seconds: int | float) -> timedelta
¶Create timedelta from seconds.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
seconds
|
int | float
|
Number of seconds. |
required |
Returns:
| Type | Description |
|---|---|
timedelta
|
Timedelta object. |
Examples:
>>> duration_from_seconds(3600)
timedelta(seconds=3600)
>>> duration_from_seconds(90.5)
timedelta(seconds=90, microseconds=500000)
Notes
Supports both int and float values.
duration_to_seconds
¶
Duration To Seconds¶
Convert duration to total seconds.
Examples¶
from rite.temporal.duration import duration_to_seconds from datetime import timedelta duration_to_seconds(timedelta(hours=1)) 3600.0
Functions¶
duration_to_seconds(td: timedelta) -> float
¶Convert timedelta to total seconds.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
td
|
timedelta
|
Timedelta object. |
required |
Returns:
| Type | Description |
|---|---|
float
|
Total seconds as float. |
Examples:
>>> from datetime import timedelta
>>> duration_to_seconds(timedelta(hours=1))
3600.0
>>> duration_to_seconds(timedelta(days=1))
86400.0
Notes
Returns float for precision.
duration_from_days
¶
Duration From Days¶
Create duration from days.
Examples¶
from rite.temporal.duration import duration_from_days duration_from_days(7) timedelta(days=7)
Functions¶
duration_from_days(days: int | float) -> timedelta
¶
Create timedelta from days.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
days
|
int | float
|
Number of days. |
required |
Returns:
| Type | Description |
|---|---|
timedelta
|
Timedelta object. |
Examples:
>>> duration_from_days(7)
timedelta(days=7)
>>> duration_from_days(1.5)
timedelta(days=1, seconds=43200)
Notes
Standard timedelta constructor.
duration_from_hours
¶
Duration From Hours¶
Create duration from hours.
Examples¶
from rite.temporal.duration import duration_from_hours duration_from_hours(24) timedelta(days=1)
duration_from_minutes
¶
Duration From Minutes¶
Create duration from minutes.
Examples¶
from rite.temporal.duration import duration_from_minutes duration_from_minutes(60) timedelta(seconds=3600)
Functions¶
duration_from_minutes(minutes: int | float) -> timedelta
¶
Create timedelta from minutes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
minutes
|
int | float
|
Number of minutes. |
required |
Returns:
| Type | Description |
|---|---|
timedelta
|
Timedelta object. |
Examples:
>>> duration_from_minutes(60)
timedelta(seconds=3600)
>>> duration_from_minutes(1.5)
timedelta(seconds=90)
Notes
Converts to seconds internally.
duration_from_seconds
¶
Duration From Seconds¶
Create duration from seconds.
Examples¶
from rite.temporal.duration import duration_from_seconds duration_from_seconds(3600) timedelta(seconds=3600)
Functions¶
duration_from_seconds(seconds: int | float) -> timedelta
¶
Create timedelta from seconds.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
seconds
|
int | float
|
Number of seconds. |
required |
Returns:
| Type | Description |
|---|---|
timedelta
|
Timedelta object. |
Examples:
>>> duration_from_seconds(3600)
timedelta(seconds=3600)
>>> duration_from_seconds(90.5)
timedelta(seconds=90, microseconds=500000)
Notes
Supports both int and float values.
duration_to_seconds
¶
Duration To Seconds¶
Convert duration to total seconds.
Examples¶
from rite.temporal.duration import duration_to_seconds from datetime import timedelta duration_to_seconds(timedelta(hours=1)) 3600.0
Functions¶
duration_to_seconds(td: timedelta) -> float
¶
Convert timedelta to total seconds.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
td
|
timedelta
|
Timedelta object. |
required |
Returns:
| Type | Description |
|---|---|
float
|
Total seconds as float. |
Examples:
>>> from datetime import timedelta
>>> duration_to_seconds(timedelta(hours=1))
3600.0
>>> duration_to_seconds(timedelta(days=1))
86400.0
Notes
Returns float for precision.
format_human_readable
¶
Format Human Readable¶
Format datetime to human-readable string.
Examples¶
from rite.temporal.formatting import format_human_readable from datetime import datetime format_human_readable(datetime(2024, 12, 27, 15, 30))
Functions¶
format_human_readable(dt: datetime) -> str
¶
Format datetime to human-readable string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime
|
Datetime object. |
required |
Returns:
| Type | Description |
|---|---|
str
|
Human-readable formatted string. |
Examples:
>>> from datetime import datetime
>>> dt = datetime(2024, 12, 27, 15, 30)
>>> format_human_readable(dt)
'December 27, 2024 at 3:30 PM'
Notes
Uses strftime with full month name. 12-hour format with AM/PM.
format_iso8601
¶
Format ISO 8601¶
Format datetime to ISO 8601 string.
Examples¶
from rite.temporal.formatting import format_iso8601 from datetime import datetime, timezone format_iso8601(datetime(2024, 12, 27, tzinfo=timezone.utc))
Functions¶
format_iso8601(dt: datetime) -> str
¶
Format datetime to ISO 8601 string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime
|
Datetime object. |
required |
Returns:
| Type | Description |
|---|---|
str
|
ISO 8601 formatted string. |
Examples:
>>> from datetime import datetime, timezone
>>> dt = datetime(2024, 12, 27, 15, 30, tzinfo=timezone.utc)
>>> format_iso8601(dt)
'2024-12-27T15:30:00+00:00'
Notes
Same as datetime.isoformat().
format_rfc3339
¶
Format RFC 3339¶
Format datetime to RFC 3339 string.
Examples¶
from rite.temporal.formatting import format_rfc3339 from datetime import datetime, timezone format_rfc3339(datetime(2024, 12, 27, tzinfo=timezone.utc))
Functions¶
format_rfc3339(dt: datetime) -> str
¶
Format datetime to RFC 3339 string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime
|
Datetime object. |
required |
Returns:
| Type | Description |
|---|---|
str
|
RFC 3339 formatted string. |
Examples:
>>> from datetime import datetime, timezone
>>> dt = datetime(2024, 12, 27, 15, 30, tzinfo=timezone.utc)
>>> format_rfc3339(dt)
'2024-12-27T15:30:00+00:00'
Notes
RFC 3339 is profile of ISO 8601. Uses isoformat() with 'T' separator.
formatting
¶
Formatting Module¶
Date/time formatting utilities.
This submodule provides utilities for formatting datetime objects into various string representations.
Examples¶
from rite.temporal.formatting import format_iso8601 from datetime import datetime, timezone dt = datetime.now(timezone.utc) format_iso8601(dt)
Modules¶
format_human_readable
¶
Format Human Readable¶
Format datetime to human-readable string.
Examples¶
from rite.temporal.formatting import format_human_readable from datetime import datetime format_human_readable(datetime(2024, 12, 27, 15, 30))
Functions¶
format_human_readable(dt: datetime) -> str
¶Format datetime to human-readable string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime
|
Datetime object. |
required |
Returns:
| Type | Description |
|---|---|
str
|
Human-readable formatted string. |
Examples:
>>> from datetime import datetime
>>> dt = datetime(2024, 12, 27, 15, 30)
>>> format_human_readable(dt)
'December 27, 2024 at 3:30 PM'
Notes
Uses strftime with full month name. 12-hour format with AM/PM.
format_iso8601
¶
Format ISO 8601¶
Format datetime to ISO 8601 string.
Examples¶
from rite.temporal.formatting import format_iso8601 from datetime import datetime, timezone format_iso8601(datetime(2024, 12, 27, tzinfo=timezone.utc))
Functions¶
format_iso8601(dt: datetime) -> str
¶Format datetime to ISO 8601 string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime
|
Datetime object. |
required |
Returns:
| Type | Description |
|---|---|
str
|
ISO 8601 formatted string. |
Examples:
>>> from datetime import datetime, timezone
>>> dt = datetime(2024, 12, 27, 15, 30, tzinfo=timezone.utc)
>>> format_iso8601(dt)
'2024-12-27T15:30:00+00:00'
Notes
Same as datetime.isoformat().
format_rfc3339
¶
Format RFC 3339¶
Format datetime to RFC 3339 string.
Examples¶
from rite.temporal.formatting import format_rfc3339 from datetime import datetime, timezone format_rfc3339(datetime(2024, 12, 27, tzinfo=timezone.utc))
Functions¶
format_rfc3339(dt: datetime) -> str
¶Format datetime to RFC 3339 string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime
|
Datetime object. |
required |
Returns:
| Type | Description |
|---|---|
str
|
RFC 3339 formatted string. |
Examples:
>>> from datetime import datetime, timezone
>>> dt = datetime(2024, 12, 27, 15, 30, tzinfo=timezone.utc)
>>> format_rfc3339(dt)
'2024-12-27T15:30:00+00:00'
Notes
RFC 3339 is profile of ISO 8601. Uses isoformat() with 'T' separator.
timezone
¶
Timezone Module¶
Timezone operations.
This submodule provides utilities for working with timezones using the standard library zoneinfo module (Python 3.9+).
Examples¶
from rite.temporal.timezone import timezone_get, timezone_convert from datetime import datetime, timezone dt = datetime.now(timezone.utc) timezone_convert(dt, "Europe/Amsterdam")
Modules¶
timezone_convert
¶
Timezone Convert¶
Convert datetime to different timezone.
Examples¶
from rite.temporal.timezone import timezone_convert from datetime import datetime, timezone dt = datetime.now(timezone.utc) timezone_convert(dt, "America/New_York")
Functions¶
timezone_convert(dt: datetime, target_tz: str) -> datetime
¶Convert datetime to target timezone.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime
|
Datetime object (should be timezone-aware). |
required |
target_tz
|
str
|
Target timezone name (IANA). |
required |
Returns:
| Type | Description |
|---|---|
datetime
|
Datetime in target timezone. |
Examples:
>>> from datetime import datetime, timezone
>>> dt = datetime(2024, 12, 27, 12, 0, tzinfo=timezone.utc)
>>> timezone_convert(dt, "America/New_York")
datetime.datetime(2024, 12, 27, 7, 0, ...)
Notes
Input datetime should be timezone-aware. Returns new datetime object.
timezone_get
¶
Timezone Get¶
Get timezone object.
Examples¶
from rite.temporal.timezone import timezone_get timezone_get("UTC") ZoneInfo(key='UTC')
Functions¶
timezone_get(name: str = 'UTC') -> ZoneInfo
¶Get timezone object by name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Timezone name (IANA). Defaults to UTC. |
'UTC'
|
Returns:
| Type | Description |
|---|---|
ZoneInfo
|
ZoneInfo timezone object. |
Raises:
| Type | Description |
|---|---|
ZoneInfoNotFoundError
|
If timezone not found. |
Examples:
>>> timezone_get("UTC")
ZoneInfo(key='UTC')
>>> timezone_get("America/New_York")
ZoneInfo(key='America/New_York')
Notes
Uses IANA timezone database. Python 3.9+ required.
timezone_convert
¶
Timezone Convert¶
Convert datetime to different timezone.
Examples¶
from rite.temporal.timezone import timezone_convert from datetime import datetime, timezone dt = datetime.now(timezone.utc) timezone_convert(dt, "America/New_York")
Functions¶
timezone_convert(dt: datetime, target_tz: str) -> datetime
¶
Convert datetime to target timezone.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime
|
Datetime object (should be timezone-aware). |
required |
target_tz
|
str
|
Target timezone name (IANA). |
required |
Returns:
| Type | Description |
|---|---|
datetime
|
Datetime in target timezone. |
Examples:
>>> from datetime import datetime, timezone
>>> dt = datetime(2024, 12, 27, 12, 0, tzinfo=timezone.utc)
>>> timezone_convert(dt, "America/New_York")
datetime.datetime(2024, 12, 27, 7, 0, ...)
Notes
Input datetime should be timezone-aware. Returns new datetime object.
timezone_get
¶
Timezone Get¶
Get timezone object.
Examples¶
from rite.temporal.timezone import timezone_get timezone_get("UTC") ZoneInfo(key='UTC')
Functions¶
timezone_get(name: str = 'UTC') -> ZoneInfo
¶
Get timezone object by name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Timezone name (IANA). Defaults to UTC. |
'UTC'
|
Returns:
| Type | Description |
|---|---|
ZoneInfo
|
ZoneInfo timezone object. |
Raises:
| Type | Description |
|---|---|
ZoneInfoNotFoundError
|
If timezone not found. |
Examples:
>>> timezone_get("UTC")
ZoneInfo(key='UTC')
>>> timezone_get("America/New_York")
ZoneInfo(key='America/New_York')
Notes
Uses IANA timezone database. Python 3.9+ required.
options: show_root_heading: true show_source: false heading_level: 2
Submodules¶
DateTime Operations¶
Work with datetime objects.
DateTime Module¶
Date and time operations.
This submodule provides utilities for working with datetime objects including creation, parsing, formatting, and conversions.
Examples¶
from rite.temporal.datetime import datetime_now, datetime_format now = datetime_now() datetime_format(now) '2024-12-27 15:30:00'
Modules¶
datetime_format
¶
DateTime Format¶
Format datetime to string.
Examples¶
from rite.temporal.datetime import datetime_format from datetime import datetime datetime_format(datetime.now())
Functions¶
datetime_format(dt: datetime, fmt: str = '%Y-%m-%d %H:%M:%S') -> str
¶
Format datetime to string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime
|
Datetime object. |
required |
fmt
|
str
|
Format string. Defaults to "%Y-%m-%d %H:%M:%S". |
'%Y-%m-%d %H:%M:%S'
|
Returns:
| Type | Description |
|---|---|
str
|
Formatted datetime string. |
Examples:
>>> from datetime import datetime
>>> dt = datetime(2024, 12, 27, 15, 30)
>>> datetime_format(dt)
'2024-12-27 15:30:00'
>>> datetime_format(dt, "%d/%m/%Y")
'27/12/2024'
Notes
See strftime documentation for format codes.
datetime_from_timestamp
¶
DateTime From Timestamp¶
Create datetime from UNIX timestamp.
Examples¶
from rite.temporal.datetime import datetime_from_timestamp datetime_from_timestamp(1735315200)
Functions¶
datetime_from_timestamp(timestamp: int | float, tz: timezone | None = None) -> datetime
¶
Create datetime from UNIX timestamp.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
timestamp
|
int | float
|
UNIX timestamp (seconds since epoch). |
required |
tz
|
timezone | None
|
Timezone. Defaults to UTC. |
None
|
Returns:
| Type | Description |
|---|---|
datetime
|
Datetime object. |
Examples:
>>> datetime_from_timestamp(1735315200)
datetime.datetime(2024, 12, 27, ...)
>>> datetime_from_timestamp(0, timezone.utc)
datetime.datetime(1970, 1, 1, 0, 0, tzinfo=...)
Notes
Handles both int and float timestamps. Defaults to UTC timezone.
datetime_now
¶
DateTime Now¶
Get current datetime.
Examples¶
from rite.temporal.datetime import datetime_now datetime_now() datetime.datetime(2025, 12, 27, ...)
Functions¶
datetime_now(tz: timezone | None = None) -> datetime
¶
Get current datetime.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tz
|
timezone | None
|
Timezone. Defaults to UTC. |
None
|
Returns:
| Type | Description |
|---|---|
datetime
|
Current datetime object. |
Examples:
>>> datetime_now()
datetime.datetime(2025, 12, 27, ...)
>>> datetime_now(timezone.utc)
datetime.datetime(2025, 12, 27, ..., tzinfo=...)
Notes
Uses timezone-aware datetime. Defaults to UTC if no timezone provided.
datetime_parse
¶
DateTime Parse¶
Parse datetime from string.
Examples¶
from rite.temporal.datetime import datetime_parse datetime_parse("2024-12-27", "%Y-%m-%d")
Functions¶
datetime_parse(date_string: str, fmt: str = '%Y-%m-%d %H:%M:%S') -> datetime
¶
Parse datetime from string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
date_string
|
str
|
Date/time string. |
required |
fmt
|
str
|
Format string. Defaults to "%Y-%m-%d %H:%M:%S". |
'%Y-%m-%d %H:%M:%S'
|
Returns:
| Type | Description |
|---|---|
datetime
|
Parsed datetime object. |
Examples:
>>> datetime_parse("2024-12-27", "%Y-%m-%d")
datetime.datetime(2024, 12, 27, 0, 0)
>>> datetime_parse("27/12/2024 15:30", "%d/%m/%Y %H:%M")
datetime.datetime(2024, 12, 27, 15, 30)
Notes
See strftime documentation for format codes. Returns naive datetime (no timezone).
datetime_to_iso
¶
DateTime To ISO¶
Convert datetime to ISO 8601 string.
Examples¶
from rite.temporal.datetime import datetime_to_iso from datetime import datetime datetime_to_iso(datetime.now())
Functions¶
datetime_to_iso(dt: datetime) -> str
¶
Convert datetime to ISO 8601 string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime
|
Datetime object. |
required |
Returns:
| Type | Description |
|---|---|
str
|
ISO 8601 formatted string. |
Examples:
>>> from datetime import datetime, timezone
>>> dt = datetime(2024, 12, 27, 15, 30, tzinfo=timezone.utc)
>>> datetime_to_iso(dt)
'2024-12-27T15:30:00+00:00'
Notes
Uses isoformat() method. Includes timezone if present.
datetime_to_timestamp
¶
DateTime To Timestamp¶
Convert datetime to UNIX timestamp.
Examples¶
from rite.temporal.datetime import datetime_to_timestamp from datetime import datetime datetime_to_timestamp(datetime(2024, 12, 27))
Functions¶
datetime_to_timestamp(dt: datetime) -> int
¶
Convert datetime to UNIX timestamp.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime
|
Datetime object. |
required |
Returns:
| Type | Description |
|---|---|
int
|
UNIX timestamp as integer. |
Examples:
>>> from datetime import datetime, timezone
>>> dt = datetime(1970, 1, 1, tzinfo=timezone.utc)
>>> datetime_to_timestamp(dt)
0
Notes
Returns integer (seconds). For milliseconds, use int(dt.timestamp() * 1000).
Formatting Module¶
Date/time formatting utilities.
This submodule provides utilities for formatting datetime objects into various string representations.
Examples¶
from rite.temporal.formatting import format_iso8601 from datetime import datetime, timezone dt = datetime.now(timezone.utc) format_iso8601(dt)
Modules¶
format_human_readable
¶
Format Human Readable¶
Format datetime to human-readable string.
Examples¶
from rite.temporal.formatting import format_human_readable from datetime import datetime format_human_readable(datetime(2024, 12, 27, 15, 30))
Functions¶
format_human_readable(dt: datetime) -> str
¶
Format datetime to human-readable string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime
|
Datetime object. |
required |
Returns:
| Type | Description |
|---|---|
str
|
Human-readable formatted string. |
Examples:
>>> from datetime import datetime
>>> dt = datetime(2024, 12, 27, 15, 30)
>>> format_human_readable(dt)
'December 27, 2024 at 3:30 PM'
Notes
Uses strftime with full month name. 12-hour format with AM/PM.
format_iso8601
¶
Format ISO 8601¶
Format datetime to ISO 8601 string.
Examples¶
from rite.temporal.formatting import format_iso8601 from datetime import datetime, timezone format_iso8601(datetime(2024, 12, 27, tzinfo=timezone.utc))
Functions¶
format_iso8601(dt: datetime) -> str
¶
Format datetime to ISO 8601 string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime
|
Datetime object. |
required |
Returns:
| Type | Description |
|---|---|
str
|
ISO 8601 formatted string. |
Examples:
>>> from datetime import datetime, timezone
>>> dt = datetime(2024, 12, 27, 15, 30, tzinfo=timezone.utc)
>>> format_iso8601(dt)
'2024-12-27T15:30:00+00:00'
Notes
Same as datetime.isoformat().
format_rfc3339
¶
Format RFC 3339¶
Format datetime to RFC 3339 string.
Examples¶
from rite.temporal.formatting import format_rfc3339 from datetime import datetime, timezone format_rfc3339(datetime(2024, 12, 27, tzinfo=timezone.utc))
Functions¶
format_rfc3339(dt: datetime) -> str
¶
Format datetime to RFC 3339 string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime
|
Datetime object. |
required |
Returns:
| Type | Description |
|---|---|
str
|
RFC 3339 formatted string. |
Examples:
>>> from datetime import datetime, timezone
>>> dt = datetime(2024, 12, 27, 15, 30, tzinfo=timezone.utc)
>>> format_rfc3339(dt)
'2024-12-27T15:30:00+00:00'
Notes
RFC 3339 is profile of ISO 8601. Uses isoformat() with 'T' separator.
options: members: - format_iso8601 - format_rfc3339 - format_human_readable show_source: false heading_level: 3
Examples¶
Overview¶
This section introduces the temporal helpers conceptually. The detailed APIs are documented on the submodule pages.
Submodules¶
- Datetime: Work with aware and naive datetimes.
- Duration: Represent durations and time spans.
- Timezone: Timezone utilities.
- Calendar: Calendar and date range helpers.
- Formatting: Date and time formatting utilities.
Examples¶
```python from rite.temporal import datetime_now, duration_from_hours
now = datetime_now() three_hours = duration_from_hours(3)
```python from rite.temporal import ( datetime_now, show_root_heading: true show_source: false heading_level: 2 show_submodules: false
Submodules¶
- Datetime: Work with aware and naive datetimes.
- Duration: Represent durations and time spans.
- Timezone: Timezone utilities.
- Calendar: Calendar and date range helpers.
- Formatting: Date and time formatting utilities. three_hours = duration_from_hours(3)