Skip to content
al-falak

Timezone Handling

Timezone Handling

Section titled “Timezone Handling”

Al-Falak returns timezone-aware UTC datetime objects by default. You can convert to any timezone using the time_zone parameter.

Default behavior (UTC)

Section titled “Default behavior (UTC)”
from datetime import datetime
from alfalak import PrayerTimes, CalculationMethod


pt = PrayerTimes(
    (35.7750, -78.6336),
    datetime.now(),
    CalculationMethod.NORTH_AMERICA,
)
print(pt.fajr.tzinfo)  # UTC

With a specific timezone

Section titled “With a specific timezone”
from zoneinfo import ZoneInfo


tz = ZoneInfo("America/New_York")
pt = PrayerTimes(
    (35.7750, -78.6336),
    datetime.now(),
    CalculationMethod.NORTH_AMERICA,
    time_zone=tz,
)
print(pt.fajr.tzinfo)  # America/New_York

Converting after creation

Section titled “Converting after creation”
from zoneinfo import ZoneInfo


pt = PrayerTimes(coordinates, datetime.now(), CalculationMethod.NORTH_AMERICA)
local_time = pt.fajr.astimezone(ZoneInfo("Europe/London"))

DST transitions

Section titled “DST transitions”

Al-Falak handles DST correctly:

  • All internal calculations use UTC
  • Sunnah times use absolute elapsed time (not wall-clock subtraction)
  • Returned datetimes carry the correct ZoneInfo with DST offset
from zoneinfo import ZoneInfo


# US springs forward on 2025-03-09
tz = ZoneInfo("America/New_York")
pt = PrayerTimes(
    (35.7750, -78.6336),
    datetime(2025, 3, 9),
    CalculationMethod.MUSLIM_WORLD_LEAGUE,
    time_zone=tz,
)
sunnah = SunnahTimes(pt)
# Markers are correct despite the 1-hour DST jump

Windows note

Section titled “Windows note”

On Windows, install the tzdata package for IANA timezone support:

Terminal window
pip install tzdata

See also

Section titled “See also”