Python datetime timestamp() Method

Usage

The timestamp() method is part of the datetime module in Python. Its primary function is to convert a datetime object into a POSIX timestamp, also known as Unix timestamp.

Syntax

datetime.timestamp()

Return Value

The timestamp() method returns a floating-point number representing the seconds since the epoch.

Module Import

To use the timestamp() method, you need to import the datetime module first.

from datetime import datetime

Example 1: Current Timestamp

Here’s a simple example that demonstrates how to use the timestamp() method. The code below retrieves the current local date and time as a datetime object with the datetime.now() method, and then applies the timestamp() method to this object to convert it into a Unix timestamp.

from datetime import datetime

# Get current datetime object
current_datetime = datetime.now()

# Convert datetime object to timestamp
current_timestamp = current_datetime.timestamp()
print("Current Timestamp:", current_timestamp)
# Current Timestamp: 1709624677.911529

Example 2: Timezone Considerations

Python’s datetime objects can be classified into two categories: naive and aware. A naive datetime object doesn’t include any information about time zones. Whereas, a timezone-aware datetime object explicitly carries time zone information, meaning it knows its offset from UTC.

When you use the timestamp() method on a datetime object to convert it to a Unix timestamp:

• If the datetime object is naive, it is treated as if it were in the local timezone.
• If the datetime object is timezone-aware, the timestamp() method takes timezone information into account before calculating the timestamp. This ensures that the timestamp accurately reflects the universal moment in time, regardless of the local timezone.

So it’s important to understand the difference between naive and timezone-aware datetime objects when working with timestamps, especially if your application deals with dates and times across multiple timezones. Incorrect handling of timezones can result in errors in how time is interpreted and compared.

Let’s illustrate this with an example. The code below demonstrates how Python handles timestamps for both naive and timezone-aware datetime objects.

from datetime import datetime, timezone

# Naive datetime 
naive_dt = datetime(2024, 3, 6, 10, 0)  

# Timezone aware datetime (UTC)
utc_dt = datetime(2024, 3, 6, 10, 0, tzinfo=timezone.utc) 

naive_timestamp = naive_dt.timestamp()
utc_timestamp = utc_dt.timestamp()

print("Naive Timestamp:", naive_timestamp)  # Output: 1709699400.0
print("UTC Timestamp:", utc_timestamp)      # Output: 1709719200.0

The code prints two timestamps. The naive timestamp reflects your local timezone’s offset from UTC, while the UTC timestamp is directly based on Coordinated Universal Time.

Example 3: Timestamp Difference

The code below calculates the time difference between two events directly using their timestamps.

from datetime import datetime

# Some specific dates and times
event1 = datetime(2024, 3, 10, 15, 0)
event2 = datetime(2024, 3, 5, 9, 30)

timestamp1 = event1.timestamp()
timestamp2 = event2.timestamp()

difference_in_seconds = timestamp1 - timestamp2 

print("Event 1 Timestamp:", timestamp1)     # Event 1 Timestamp: 1710063000.0
print("Event 2 Timestamp:", timestamp2)     # Event 2 Timestamp: 1709611200.0
print("Time difference (in seconds):", difference_in_seconds)   # Time difference (in seconds): 451800.0