Dates, times and time zones (IST included)

A weekly call at 19:30 in India is at 14:00 in London and 09:00 in New York, until March: then it moves to 10:00 in New York, and two or three weeks later to 15:00 in London. Python’s datetime module and its companion zoneinfo get such times right, as long as every time says which clock it belongs to.

datetime has four types for calendar work: date for a day, time for a clock reading, datetime for both and timedelta for a length of time. A datetime is naivenaive datetime: A datetime with no time zone: its tzinfo is None, so it is a clock reading that could belong to any place. When Python must convert one, it assumes the computer's local time. when it has no time zone and awareaware datetime: A datetime that carries a tzinfo giving its offset from UTC, so it names one exact moment. datetime.now(UTC) and a datetime made with tzinfo=ZoneInfo("Asia/Kolkata") are aware. when it has one, and only an aware value names one moment that the whole world agrees on. One habit prevents most bugs: make datetimes aware as soon as they enter the program, store and calculate in UTC, and convert to a local zone only to show a time to a person.

date, time and datetime check their values and never change

Each of the four types holds one kind of value, and the program below makes the first three of them:

from datetime import date, datetime, time

exam = date(2027, 3, 15)
print(exam, exam.year, exam.month, exam.day)
print(exam.strftime("%A"), exam.weekday(), exam.isoweekday())
print(exam.isocalendar())

start = time(9, 30)
slot = datetime.combine(exam, start)
print(slot, "|", slot.isoformat())
print(slot.replace(hour=14, minute=0))
print(date.fromisoformat("2027-03-15") == exam)

2027-03-15 2027 3 15
Monday 0 1
datetime.IsoCalendarDate(year=2027, week=11, weekday=1)
2027-03-15 09:30:00 | 2027-03-15T09:30:00
2027-03-15 14:00:00
True

• date(2027, 3, 15) checks its arguments, so a month 13 or a 31st day in April raises ValueError. Its parts are attributes; weekday() counts Monday as 0 and isoweekday() as 1, and isocalendar() gives the ISO 8601 week, week 11 here.
• datetime.combine() joins a date and a time. Dates and times are immutableimmutable: Unable to change once made. Strings, numbers and tuples are immutable: an operation that seems to change one, such as upper(), returns a new object instead. More in “Strings: literals, indexing and slicing”: they never change once made, so replace() returns a copy with some fields changed.
• isoformat() and fromisoformat() write and read the international form, year first, which also sorts correctly as text.

Real programs ask date.today() or datetime.now(zone) for the current day and time. The examples here fix their dates instead, so that their output never changes.

A timedelta counts days and seconds, never months

Subtracting one date from another gives a timedelta, and adding one moves a date. This program counts the days to an exam, adds up study sessions and steps through months:

import calendar
from datetime import date, timedelta

today = date(2027, 1, 20)  # a fixed day, so the output never changes
exam = date(2027, 3, 15)
left = exam - today
print(left, "|", left.days, "days")
print(left.days // 7, "weeks and", left.days % 7, "days")
print("revision starts", exam - timedelta(weeks=6))

study = timedelta(hours=2, minutes=45)
print(study * 30, "|", (study * 30) / timedelta(hours=1), "hours")
print(timedelta(hours=-1), "|", timedelta(days=1, minutes=90).total_seconds())


def add_months(day, months):
    """Move by whole months, keeping the day if the month has it, else its last day."""
    index = day.month - 1 + months
    year, month = day.year + index // 12, index % 12 + 1
    last = calendar.monthrange(year, month)[1]
    return day.replace(year=year, month=month, day=min(day.day, last))


print(add_months(date(2027, 1, 31), 1), add_months(date(2028, 1, 31), 1), add_months(date(2027, 11, 30), 3))
try:
    date(2027, 1, 31).replace(month=2)
except ValueError as error:
    print("ValueError:", error)

54 days, 0:00:00 | 54 days
7 weeks and 5 days
revision starts 2027-02-01
3 days, 10:30:00 | 82.5 hours
-1 day, 23:00:00 | 91800.0
2027-02-28 2028-02-29 2028-02-29
ValueError: day 31 must be in range 1..28 for month 2 in year 2027

• 54 days are left, and six weeks before the exam is 2027-02-01.
• A timedelta keeps only days, seconds and microseconds; weeks, hours and minutes are converted when you make one. total_seconds() gives the whole length in seconds, and dividing by another timedelta asks “how many of these”: 30 sessions of 2 hours 45 minutes come to 82.5 hours.
• Negative durations look odd: timedelta(hours=-1) prints as -1 day, 23:00:00, minus one day plus 23 hours, because only the days may be negative.
• A timedelta has no months, because a month has 28 to 31 days. add_months() above moves the month number, keeps the day if the new month has it and otherwise takes its last day, which calendar.monthrange() gives. replace(month=2) alone fails on date(2027, 1, 31), and the error says which days that February has.

The month arithmetic of add_months() is the one step a timedelta cannot do for you. Here it is at the top level of a program, so that every line can be stepped through, for 1 and 13 months after the last day of January:

from calendar import monthrange
from datetime import date

day = date(2027, 1, 31)
for months in [1, 13]:
    index = day.month - 1 + months
    year = day.year + index // 12
    month = index % 12 + 1
    last = monthrange(year, month)[1]
    keep = min(day.day, last)
    print(date(year, month, keep))

2027-02-28
2028-02-29

Both passes land on the last day of February, 28 in 2027 and 29 in the leap year 2028, where replace(month=2) would have raised ValueError.

The format, not the text, decides what a date means

strftime() and f-strings turn a date into text with format codesstrftime code: A code such as %d, %B or %H that stands for one part of a date or a time. It goes after the colon when an f-string formats a datetime, or into strftime(). More in “f-strings and the format mini-language”, and strptime() reads text with the same codes:

import warnings
from datetime import date, datetime

text = "04-10-2026"
day_first = datetime.strptime(text, "%d-%m-%Y").date()
month_first = datetime.strptime(text, "%m-%d-%Y").date()
print(day_first, "|", month_first)
print(date.strptime(text, "%d-%m-%Y"))  # new in Python 3.14
print(f"{day_first:%d %B %Y} | {day_first:%a %d/%m/%y}")

print(datetime.strptime("4-10-2026 9:05", "%d-%m-%Y %H:%M"))  # one-digit fields are accepted
for bad in ["31-04-2026", "2026-10-04"]:
    try:
        datetime.strptime(bad, "%d-%m-%Y")
    except ValueError as error:
        print("ValueError:", error)

# A day and month without a year: the default year, 1900, is not a leap year
with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    try:
        datetime.strptime("29-02", "%d-%m")
    except ValueError as error:
        print("ValueError:", error)
print(caught[0].category.__name__)

print(datetime.fromisoformat("2026-10-04T09:30:00+05:30"))
print(datetime.fromisoformat("2026-10-04T04:00:00Z"))

2026-10-04 | 2026-04-10
2026-10-04
04 October 2026 | Sun 04/10/26
2026-10-04 09:05:00
ValueError: day 31 must be in range 1..30 for month 4 in year 2026
ValueError: time data '2026-10-04' does not match format '%d-%m-%Y'
ValueError: day 29 must be in range 1..28 for month 2 in year 1900
DeprecationWarning
2026-10-04 09:30:00+05:30
2026-10-04 04:00:00+00:00

The same text can mean two days, and some texts mean none. The program’s own inputs, side by side:

• %d stands for the day, %m for the month’s number, %Y for the four-digit year, %B for the month’s name, %a for a short weekday and %H:%M for a 24-hour time. The codes, not the text, decide what each number means.
• date.strptime(), new in Python 3.14, returns a date straight away, and time.strptime() a time; on older versions, call datetime.strptime() and then .date().
• Parsing is strict about separators and about real dates, but it accepts days, months and hours written with one digit.
• Since Python 3.13 a format with a day but no year also raises DeprecationWarning, and the documentation warns that it may become an error: always parse a year.
• fromisoformat() reads ISO 8601ISO 8601: The international standard for writing dates and times year first, then month, day and time, with an offset such as +05:30 or Z for UTC. isoformat() writes it and fromisoformat() reads it. text with its offset, such as +05:30, and since Python 3.11 also the Z that means UTC.

Only an aware datetime names one moment

A naive datetime is a clock reading; an aware one adds the zone, and with it the moment. This program attaches a zone, converts, makes the most common mistake on purpose and compares the results:

import warnings
from datetime import UTC, datetime, timedelta, timezone

naive = datetime(2026, 10, 4, 9, 30)
print(naive, "|", naive.tzinfo, naive.utcoffset())

ist = timezone(timedelta(hours=5, minutes=30), "IST")
aware = naive.replace(tzinfo=ist)  # attach a zone: same wall time
print(aware, "|", aware.tzname(), aware.utcoffset())
print(aware.astimezone(UTC))       # convert: same moment, other clock
wrong = aware.replace(tzinfo=UTC)  # the bug: same wall time, another moment
print(wrong, "|", wrong.astimezone(ist))

print(naive == aware, aware == aware.astimezone(UTC))  # never equal; the same moment
try:
    naive < aware
except TypeError as error:
    print("TypeError:", error)

# The current time: datetime.now(UTC), not the deprecated utcnow()
with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    old = datetime.utcnow()
print(old.tzinfo, "|", caught[0].category.__name__)
print(datetime.now(UTC).tzinfo, datetime.now(ist).utcoffset())

2026-10-04 09:30:00 | None None
2026-10-04 09:30:00+05:30 | IST 5:30:00
2026-10-04 04:00:00+00:00
2026-10-04 09:30:00+00:00 | 2026-10-04 15:00:00+05:30
False True
TypeError: can't compare offset-naive and offset-aware datetimes
None | DeprecationWarning
UTC 5:30:00

Step through the first four lines of the output: what each call keeps, and what it changes.

• A naive datetime has tzinfo set to None: 09:30 could be on any clock in the world. When Python converts a naive value, in timestamp() or astimezone(), it assumes the computer’s local time, so the same code gives different answers on a laptop in India and on a server in Europe.
• replace(tzinfo=…) attaches a zone and keeps the clock reading; astimezone() converts to another zone and keeps the moment. Using one where the other was meant is the most common time-zone bug, the fourth line of the output.
• A fixed offset, timezone(timedelta(hours=5, minutes=30), "IST"), is all India needs for current dates. Zones with daylight saving time need zoneinfo, in the next section.
• A naive and an aware datetime are never equal, and comparing them with < raises TypeError, as does subtracting one from the other. Two aware values compare by their moment: 09:30 in India equals 04:00 in UTC.
• datetime.utcnow() returns the current UTC time as a naive value, and it has been deprecated since Python 3.12. Use datetime.now(UTC) (UTC is an alias of timezone.utc, since 3.11), or datetime.now(ZoneInfo("Asia/Kolkata")) for the time in India.

zoneinfo knows when each region changes its clocks

zoneinfo.ZoneInfo(key) loads a zone from the IANA time zone databaseIANA time zone database: The public record of the clock rules of every region, past and present, with keys such as Asia/Kolkata and Europe/London. zoneinfo reads it from the operating system or from the tzdata package., which records the offsets and the daylight-saving rules of places around the world, past and present. Keys name regions, never abbreviations: Asia/Kolkata, Europe/London, America/New_York. Here the weekly call at 19:30 in India meets two zones that change their clocks:

from datetime import datetime
from zoneinfo import ZoneInfo

KOLKATA = ZoneInfo("Asia/Kolkata")
OTHERS = {"London": ZoneInfo("Europe/London"), "New York": ZoneInfo("America/New_York")}

# A weekly call at 19:30 in India, on five Mondays around the clock changes
for day in (2, 9, 16, 23, 30):
    call = datetime(2026, 3, day, 19, 30, tzinfo=KOLKATA)
    local = [f"{city} {call.astimezone(zone):%H:%M %Z}" for city, zone in OTHERS.items()]
    print(f"{call:%a %d %b %H:%M %Z} | " + " | ".join(local))

# India keeps one offset all year, with no daylight saving time
for month in (1, 7):
    moment = datetime(2026, month, 15, 12, tzinfo=KOLKATA)
    print(f"{moment:%b}", moment.utcoffset(), moment.dst(), moment.tzname())

# A short name is not a zone: "IST" means three different offsets
for key, month in (("Asia/Kolkata", 1), ("Europe/Dublin", 7), ("Asia/Jerusalem", 1)):
    moment = datetime(2026, month, 15, 12, tzinfo=ZoneInfo(key))
    print(f"{key:15} {moment.tzname()} {moment.utcoffset()}")

Mon 02 Mar 19:30 IST | London 14:00 GMT | New York 09:00 EST
Mon 09 Mar 19:30 IST | London 14:00 GMT | New York 10:00 EDT
Mon 16 Mar 19:30 IST | London 14:00 GMT | New York 10:00 EDT
Mon 23 Mar 19:30 IST | London 14:00 GMT | New York 10:00 EDT
Mon 30 Mar 19:30 IST | London 15:00 BST | New York 10:00 EDT
Jan 5:30:00 0:00:00 IST
Jul 5:30:00 0:00:00 IST
Asia/Kolkata    IST 5:30:00
Europe/Dublin   IST 1:00:00
Asia/Jerusalem  IST 2:00:00

The United States starts its daylight saving timedaylight saving time: Moving the clocks forward by an hour in spring and back in autumn, as the United Kingdom and the United States do. India does not use it, so Asia/Kolkata keeps +05:30 all year., moving its clocks forward an hour, on the second Sunday of March, and the United Kingdom on the last Sunday, so for two or three weeks, depending on the year, New York is four hours behind London instead of five. In 2026, the year of the program, it is three. Step through the five Mondays on the three clocks:

The call moves an hour later in New York first and in London three weeks after, while in India it never moves: Asia/Kolkata shows +05:30 and no daylight-saving offset in January and in July alike. The last lines of the program show why you store the key and not the short name: IST stands for India Standard Time, for Irish Standard Time (Dublin in summer) and for Israel Standard Time, three different UTC offsetsUTC offset: How far a clock is ahead of or behind UTC, such as +05:30 for India Standard Time. A zone with daylight saving time has two offsets a year: Europe/London is +00:00 in winter and +01:00 in summer..

Adding a day across a clock change is not 24 hours

London’s clocks go forward on the last Sunday of March and back on the last Sunday of October. This program meets both nights:

from datetime import UTC, datetime, timedelta
from zoneinfo import ZoneInfo

LONDON = ZoneInfo("Europe/London")

# 1. Adding a day to an aware datetime keeps the wall clock, not 24 hours
before = datetime(2026, 3, 28, 12, 0, tzinfo=LONDON)
after = before + timedelta(days=1)
print(after, "|", after - before, "|", after.astimezone(UTC) - before.astimezone(UTC))

# 2. For elapsed time, do the arithmetic in UTC
print((before.astimezone(UTC) + timedelta(hours=24)).astimezone(LONDON))

# 3. In autumn, 01:30 happens twice: fold picks the first or the second
first = datetime(2026, 10, 25, 1, 30, tzinfo=LONDON)
second = first.replace(fold=1)
print(first, first.tzname(), "|", second, second.tzname())
print(second.astimezone(UTC) - first.astimezone(UTC))

# 4. In spring, 01:30 never happens: the round trip moves it
ghost = datetime(2026, 3, 29, 1, 30, tzinfo=LONDON)
print(ghost, "|", ghost.astimezone(UTC).astimezone(LONDON))

2026-03-29 12:00:00+01:00 | 1 day, 0:00:00 | 23:00:00
2026-03-29 13:00:00+01:00
2026-10-25 01:30:00+01:00 BST | 2026-10-25 01:30:00+00:00 GMT
1:00:00
2026-03-29 01:30:00+00:00 | 2026-03-29 02:30:00+01:00

Step through the spring night on a London clock and in UTC side by side; each row of the figure is one moment:

1. Adding timedelta(days=1) to an aware datetime moves the wall clock: noon on the day before the clocks go forward becomes noon the next day, and after - before says one day, but only 23 hours passed, as the subtraction in UTC shows. Python adjusts nothing for the time zone when it adds a timedelta, or when it subtracts two datetimes that share a tzinfo.
2. For elapsed time (“in 24 hours”, a token that lives for a day, a timeout), convert to UTC, add, and convert back: 13:00 in London, an hour later on the clock than noon.
3. When the clocks go back, 01:30 happens twice. The foldfold (datetime): The datetime attribute that picks one of two moments when a clock reading happens twice, as when the clocks go back: fold=0, the default, is the first, and fold=1 the second. attribute picks one: fold=0, the default, is the first, still in summer time (BST, +01:00), and fold=1 the second (GMT, +00:00), an hour later.
4. When the clocks go forward, 01:30 never happens. zoneinfo does not complain; it uses the offset from before the gap, and a round trip through UTC turns the time into 02:30 BST. Decide what such input should mean, and test it.

Store UTC, show local

A booking made in India is stored once and read in many places. This program stores it in UTC, reads it back and shows it on two clocks:

from datetime import UTC, datetime
from zoneinfo import ZoneInfo

KOLKATA = ZoneInfo("Asia/Kolkata")

booked = datetime(2026, 10, 4, 9, 30, tzinfo=KOLKATA)
stored = booked.astimezone(UTC).isoformat()  # what goes into the database
print(stored)

back = datetime.fromisoformat(stored)
print(back == booked, "|", back.astimezone(KOLKATA), "|", back.astimezone(ZoneInfo("Europe/London")))

stamp = booked.timestamp()  # seconds since 1970-01-01 00:00 UTC
print(stamp, "|", datetime.fromtimestamp(stamp, UTC))

# Old data: the database knows that India's offset was not always +05:30
print(datetime(1943, 6, 1, 12, tzinfo=KOLKATA).utcoffset())

2026-10-04T04:00:00+00:00
True | 2026-10-04 09:30:00+05:30 | 2026-10-04 05:00:00+01:00
1791086400.0 | 2026-10-04 04:00:00+00:00
6:30:00

The whole path of a time typed in India, from the text to each reader’s clock:

• Convert to UTC before storing, and write ISO 8601 with its offset: 2026-10-04T04:00:00+00:00 sorts correctly as text, names exactly one moment and reads back with fromisoformat() into an aware datetime equal to the original. Each reader then sees it on their own clock, 09:30 in India or 05:00 in London.
• A POSIX timestamp, the number of seconds since the start of 1970 in UTC, is the other common form, and datetime.fromtimestamp(stamp, UTC) turns it back into an aware datetime. Without the zone argument, fromtimestamp() returns the computer’s local time as a naive value.
• To measure how long something takes, use time.monotonic() or time.perf_counter() rather than two readings of datetime.now(): the wall clock can jump when the computer sets it, and a monotonic clock never goes backwards.

Practise: IST to UTC and working days

Convert times typed in India to UTC, then count the working days between two dates with a list of holidays, across the ends of months and years.

from datetime import UTC, date, datetime, timedelta, timezone

IST = timezone(timedelta(hours=5, minutes=30), "IST")  # India Standard Time: UTC+05:30 all year


def ist_to_utc(text):
    """Turn 'DD-MM-YYYY HH:MM' in Indian time into ISO 8601 text in UTC."""
    # Replace this line with your code.
    return text


def business_days_between(start, end, holidays):
    """Count Monday-to-Friday days from start up to end (not included) that are not holidays."""
    # Replace this line with your code.
    return 0

from datetime import date

from when import business_days_between, ist_to_utc


def test_morning_in_india():
    """converts a morning in India to UTC"""
    assert ist_to_utc("04-10-2026 09:30") == "2026-10-04T04:00:00+00:00"


def test_previous_day_in_utc():
    """moves times before 05:30 in India to the previous day, month and year in UTC"""
    assert ist_to_utc("01-01-2027 03:00") == "2026-12-31T21:30:00+00:00"
    assert ist_to_utc("01-03-2028 05:29") == "2028-02-29T23:59:00+00:00"


def test_late_evening():
    """keeps a late evening on the same day in UTC"""
    assert ist_to_utc("31-03-2026 23:45") == "2026-03-31T18:15:00+00:00"


def test_rejects_other_forms():
    """raises ValueError for text that is not DD-MM-YYYY HH:MM"""
    for text in ["2026-10-04 09:30", "31-04-2026 10:00", "04-10-2026"]:
        try:
            ist_to_utc(text)
        except ValueError:
            continue
        assert False, f"expected a ValueError for {text!r}"


def test_one_week():
    """counts five working days in a week from Thursday to Thursday"""
    assert business_days_between(date(2026, 10, 1), date(2026, 10, 8), []) == 5


def test_holidays():
    """skips holidays, and holidays at weekends change nothing"""
    week = (date(2026, 10, 1), date(2026, 10, 8))
    assert business_days_between(*week, [date(2026, 10, 2)]) == 4
    assert business_days_between(*week, {date(2026, 10, 3), date(2026, 10, 4)}) == 5


def test_across_month_and_year_ends():
    """counts across the end of a month and of a year"""
    assert business_days_between(date(2026, 1, 30), date(2026, 2, 3), []) == 2
    assert business_days_between(date(2026, 12, 24), date(2027, 1, 4), [date(2026, 12, 25), date(2027, 1, 1)]) == 5


def test_empty_ranges():
    """returns 0 when the end is not after the start"""
    assert business_days_between(date(2026, 10, 5), date(2026, 10, 5), []) == 0
    assert business_days_between(date(2026, 10, 9), date(2026, 10, 5), []) == 0

Then test yourself on the seven ideas of this lesson. The first question comes from the idea you have answered least well so far, a right answer brings a harder one, and every choice is explained the moment you pick it:

Interview questions

Fresher · What is the difference between a naive and an aware datetime in Python?

A naive datetime has no time zone: its tzinfo is None, so 09:30 could be 09:30 in Kolkata, London or anywhere else, and only the program knows which. An aware datetime carries a tzinfo that gives its offset from UTC, so it names one exact moment. Aware values convert with astimezone() and compare correctly across zones; a naive and an aware value are never equal, and ordering or subtracting them raises TypeError. When Python must convert a naive value, as in timestamp(), it assumes the computer’s local time, which is how bugs appear when code moves to a server elsewhere. Make values aware at the edge of the program, with datetime.now(UTC) or by attaching the right ZoneInfo, and keep them aware.

Key takeaways

• date, time and datetime check their values when they are made and never change; replace() returns a changed copy.
• A timedelta holds days, seconds and microseconds and no months, so step months with calendar.monthrange() and min().
• The format decides what a text means: parse day-first text with %d-%m-%Y, always with a year, and use date.strptime() on Python 3.14.
• Naive datetimes have no zone: replace(tzinfo=…) attaches one, astimezone() converts, and datetime.now(UTC) replaces the deprecated utcnow().
• Use ZoneInfo("Asia/Kolkata")-style keys, never abbreviations such as IST, which name three offsets, and install tzdata where the system has no database; adding a timedelta keeps the wall clock, so do elapsed-time arithmetic in UTC and pick repeated hours with fold.
• Store UTC as ISO 8601 with its offset, show local times, and measure durations with time.monotonic().