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
datetimeobject). - Relative
timedeltafunctionality (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 onlynow()= Local time OR timezone time (more powerful)
Both are useful, but now() is more flexible for real applications!