In Python, the primary modules for handling dates and times are:

• datetime: The core module for date and time manipulation.
• time: Provides functions for working with time, often related to system time or measuring performance.
• calendar: Offers functions related to calendars, such as printing a calendar or determining leap years.
• pytz: A third-party module (not built-in) widely used for accurate timezone calculations and handling, which is crucial when working with time in different geographical locations.

---

🕰️ Key Built-in Modules

1. datetime

This is the most essential module. It provides classes for manipulating dates and times in both simple and complex ways.

Class	Description	Example Usage
date	A date (year, month, day).	date.today()
time	A time (hour, minute, second, microsecond, timezone info).	time(10, 30, 0)
datetime	A combination of a date and a time. This is the most commonly used class.	datetime.now()
timedelta	A duration expressing the difference between two date, time, or datetime instances.	timedelta(days=5)
tzinfo	An abstract base class for timezone objects (like UTC).	Used for defining timezone rules.

Export to Sheets

2. time

The time module works closer to the system’s clock and typically uses seconds since the Epoch (usually January 1, 1970, 00:00:00 UTC).

Function	Description
time()	Returns the current time as a floating-point number (seconds since the Epoch). Used for performance measurement.
sleep(secs)	Pauses the execution of the current thread for a given number of seconds.
ctime(secs)	Converts a time expressed in seconds since the Epoch to a human-readable string.
strftime()	Converts a time tuple or struct_time into a formatted time string.

Export to Sheets

3. calendar

This module provides useful functions and classes for working with calendars, such as:

• calendar.month(year, month): Returns a multiline string with a calendar for the given month.
• calendar.isleap(year): Checks if a year is a leap year.

---

🌐 Popular Third-Party Modules

While the built-in modules are powerful, two third-party libraries are essential for professional date/time handling, especially with timezones:

1. pytz (Python Timezone Library)

pytz is necessary for accurate and robust timezone calculations, as the standard datetime module’s tzinfo is often insufficient for real-world scenarios. It brings the IANA Time Zone Database (also known as zoneinfo) to Python.

2. dateutil (or python-dateutil)

A very comprehensive and powerful extension to the standard datetime module. Its main features include:

• Parsing unknown string formats (e.g., converting “next Thursday at 5:00 PM” into a datetime object).
• Relative timedelta functionality (like the difference between two dates).
• rrule (Recurrence Rule) support for generating events like “every Monday and Wednesday.”

Python time Module

The time module in Python provides various time-related functions for working with time, dates, and timestamps. It’s part of Python’s standard library and is useful for timing operations, working with timestamps, and handling time conversions.

Important Functions

1. Time Representation Functions

time.time()

Returns the current time in seconds since the epoch (January 1, 1970, 00:00:00 UTC) as a floating-point number.

python

import time

current_time = time.time()
print(f"Seconds since epoch: {current_time}")
# Output: Seconds since epoch: 1703501234.567890

time.ctime([seconds])

Converts a time expressed in seconds since the epoch to a string representing local time.

python

import time

# Current time as readable string
current_readable = time.ctime()
print(f"Current time: {current_readable}")
# Output: Current time: Mon Dec 25 14:30:45 2023

# Convert specific timestamp
timestamp = 1609459200  # January 1, 2021
converted = time.ctime(timestamp)
print(f"Converted time: {converted}")
# Output: Converted time: Fri Jan  1 00:00:00 2021

time.gmtime([seconds])

Converts a time expressed in seconds since the epoch to a struct_time in UTC.

python

import time

# Current UTC time
utc_time = time.gmtime()
print(utc_time)
# Output: time.struct_time(tm_year=2023, tm_mon=12, tm_mday=25, tm_hour=14, tm_min=30, tm_sec=45, tm_wday=0, tm_yday=359, tm_isdst=0)

print(f"UTC Year: {utc_time.tm_year}")
print(f"UTC Month: {utc_time.tm_mon}")
print(f"UTC Day: {utc_time.tm_mday}")

# Convert specific timestamp
specific_gmtime = time.gmtime(1609459200)
print(specific_gmtime.tm_year)  # 2021

time.localtime([seconds])

Like gmtime() but converts to local time.

python

import time

# Current local time
local_time = time.localtime()
print(local_time)
# Output: time.struct_time(tm_year=2023, tm_mon=12, tm_mday=25, tm_hour=16, tm_min=30, tm_sec=45, tm_wday=0, tm_yday=359, tm_isdst=0)

print(f"Local hour: {local_time.tm_hour}")
print(f"Day of week: {local_time.tm_wday}")  # 0=Monday, 6=Sunday

datetime.now() vs datetime.today() – Simple Explanation

Both methods give you the current date and time, but there are some important differences!

1. datetime.today()

Simple method that gives current local date and time

python

from datetime import datetime

# Get current local date and time
current_time = datetime.today()
print(current_time)
# Output: 2023-12-25 14:30:45.123456

print(f"Today is: {current_time}")
# Output: Today is: 2023-12-25 14:30:45.123456

Key points:

• Always returns local time (your computer’s time)
• Cannot handle timezones
• Simple to use

2. datetime.now()

More powerful method that can handle timezones

python

from datetime import datetime, timezone

# Get current local date and time (same as today())
current_local = datetime.now()
print(f"Local time: {current_local}")
# Output: Local time: 2023-12-25 14:30:45.123456

# Get current UTC time
current_utc = datetime.now(timezone.utc)
print(f"UTC time: {current_utc}")
# Output: UTC time: 2023-12-25 09:00:45.123456+00:00

Simple Examples

Example 1: Basic Usage

python

from datetime import datetime

# Both give same result for local time
time1 = datetime.today()
time2 = datetime.now()

print(f"Using today(): {time1}")
print(f"Using now(): {time2}")
# Both will show the same local time

Example 2: Timezone Difference

python

from datetime import datetime, timezone

# today() - only local time
local_only = datetime.today()
print(f"Local time: {local_only}")

# now() - can get different timezones
local_with_now = datetime.now()
utc_time = datetime.now(timezone.utc)

print(f"Local with now(): {local_with_now}")
print(f"UTC time: {utc_time}")

Example 3: Practical Use Cases

python

from datetime import datetime

# For simple logging
def log_message(message):
    timestamp = datetime.today()  # Simple local time
    print(f"[{timestamp}] {message}")

log_message("User logged in")
# Output: [2023-12-25 14:30:45.123456] User logged in

# For applications that need timezone support
def create_international_event():
    local_time = datetime.now()  # Could add timezone if needed
    utc_time = datetime.now(timezone.utc)
    
    print(f"Event created at:")
    print(f"Local: {local_time}")
    print(f"UTC: {utc_time}")

Quick Comparison Table

Method	Timezone Support	Use Case
datetime.today()	❌ No	Simple local time
datetime.now()	✅ Yes	Local time or timezone-aware

When to Use Which?

Use datetime.today() when:

• You just need simple current local time
• Working on small scripts
• Don’t care about timezones

python

# Quick and simple
current_date = datetime.today()
print(f"Report generated on: {current_date}")

Use datetime.now() when:

• You need UTC time
• Working with different timezones
• Building serious applications

python

# For professional applications
local_time = datetime.now()
utc_time = datetime.now(timezone.utc)
print(f"Local: {local_time}, UTC: {utc_time}")

Simple Rule to Remember:

• today() = Simple local time only
• now() = Local time OR timezone time (more powerful)

Both are useful, but now() is more flexible for real applications!