Programming

Understanding Python Date and Time, with Examples

    Ini Arthur
    Share

    In this article, we’ll explore how to use date and time in Python. We’ll see real-life examples of working with date and time using the Python datetime and time modules.

    Working with times and dates is inevitable when building real-life projects, and there are many use cases for them. Thankfully, Python has a couple of modules that make it easy to work with dates and times across different timezones.

    The code for this tutorial can be found on GitHub.

    Contents:

    1. The time Module
    2. The datetime Module
    3. Getting the Current Date and Time in Python
    4. Getting the Current Date in Python
    5. The datetime Module Classes
    6. The date Class
    7. The time Class
    8. The datetime Class
    9. The timedelta Class
    10. Python datetime Formatting
    11. Working with timedelta

    The time Module

    The Python time module is for performing time-related operations. We’ll now highlight some of the most commonly used functions in the time module, with examples.

    The time() function

    The time() function returns the current time in seconds since the beginning of a set epoch as a floating point number. The epoch that’s used starts in January 1, 1970, 00:00:00 (UTC):

    import time as time_module

time_in_seconds = time_module.time()
print("Time in sceconds from epoch", time_in_seconds)

    Here’s the output of the code above:

    Time in sceconds from epoch 1680712853.0801558

    The gmtime() function

    The gmtime() function returns a struct_time in UTC from time expressed in seconds since the beginning of the epoch. A struct_time is a type of time value sequence with a named tuple interface returned by gmtime(), localtime(), and strptime():

    import time as time_module

utc_time_in_seconds = time_module.gmtime()
print("Time struct in UTC", utc_time_in_seconds)

    Here’s the output of the code above: 

    Time struct in UTC: time.struct_time(tm_year=2023, tm_mon=3, tm_mday=16, tm_hour=14, tm_min=47, tm_sec=28, tm_wday=3, tm_yday=75, tm_isdst=0)

    The localtime() function

    The localtime() function returns a struct_time in local time from time expressed in seconds since the beginning of the epoch: 

    import time as time_module

local_time = time_module.localtime()
print("Time struct in local time:", local_time)

    Here’s the output of the code above: 

    Time struct in local time: time.struct_time(tm_year=2023, tm_mon=4, tm_mday=20, tm_hour=15, tm_min=46, tm_sec=15, tm_wday=3, tm_yday=75, tm_isdst=0)

    The ctime() function

    The ctime() method converts time in seconds from the beginning of the epoch to a string format. If no arguments are passed to the function, it returns a time string for the current time in seconds: 

    import time as time_module

time_in_secs = 1678671984.939945  

time_string = time_module.ctime(time_in_secs)
print("Time string: ",time_string)

    Here’s the output of the code above:

    Time string: Thu Apr 20 01:46:24 2023

    The strftime() function

    The strftime() method converts a struct_time to a time string as specified by a given format argument:

    import time as time_module

time_tuple = time_module.gmtime()
time_format = "%y/%m/%d %I:%M:%S %p"

time_in_string = time_module.strftime(time_format, time_tuple)

print("Time expressed as formatted string:", time_in_string)

    Here’s the output of the code above:

    Time expressed as formatted string: 23/04/20 04:40:04 PM

    The sleep() function

    The sleep() function delays the execution of a thread for a specified number of seconds:

    import time as time_module 

for i in range(5):
    local_time = time_module.localtime()
    seconds = local_time.tm_sec
    print(seconds)
    time_module.sleep(2)

    Here’s the output of the code above:

    49
51
53
55
57

    In the code above, the number 2 is passed in as an argument of the sleep() function, which causes the loop to delay two seconds before execution. The numbers that are output validate our code.

    The datetime Module

    The datetime module supplies classes for manipulating dates and times.

    These classes are essential for easy manipulation, extraction, and output formatting of time intervals, times and dates. Ordinarily, date and time are not considered data types in Python, but they are date and time objects of the datetime module classes. Datetime classes also have different methods available for handling date and time objects.

    Getting the Current Date and Time in Python

    To get the current date and time, import the datetime class from the datetime module. The datetime class has a method, now(), which returns the current date and time:

    from  datetime  import  datetime

current_date_time = datetime.now()
print(current_date_time)

    Here’s the output of the code above:

    2023-04-20 13:47:02.362424

    Getting the Current Date in Python

    To get the current date, import the date class from the datetime module. The date class has a method, today(), which returns the current date:

    from datetime import date

current_date = date.today()
print(current_date)

    Here’s the output of the code above:

    2023-04-20

    The datetime Module Classes

    The datetime module currently has six classes, each with different methods for manipulating date and time objects. The classes are listed as follows:

    • date
    • time
    • datetime
    • timedelta
    • tzinfo
    • timezone

    The date Class

    A date object represents a date (year, month and day) in an idealized calendar — the current Gregorian calendar indefinitely extended in both directions.

    A date object can be instantiated as follows:

    datetime.date(year, month, day)

    The date object constructor takes three integer arguments and should be within the specified range:

    • MINYEAR <= year <= MAXYEAR
    • 1 <= month <= 12
    • 1 <= day <= number of days in the given month and year

    In the code above, MINYEAR is 1 and MAXYEAR is 9999. The values represent the smallest and biggest year number allowed in a date or datetime object.

    When the arguments are out of range, it throws a ValueError, and non-integer arguments throw a TypeError.

    Example: Create a date object

    To create a date object, import the date class from the datetime module, and pass arguments for year, month and day into the date constructor. The arguments must be integers and within the specified range:

    from datetime import date

mydate = date(2023, 4, 20)
print('The date is: ', mydate)

    Here’s the output of the code above: 

    The date is: 2023-04-20

    Example: Get the current date

    To get the current local date, use the date class today() and ctime() methods:

    from datetime import date

current_date = date.today()
print(current_date.ctime())

    The today() method will return a local date, while the ctime() method renders the date as a string.
    Here’s the output of the code above: 

    Thu Apr 20 00:00:00 2023

    Example: Create the date from ISO format

    A date object can be created from a date string in ISO 8601 format. Use the fromisoformat() method of the date class to do this:

    from datetime import date

iso_date = date.fromisoformat('2023-04-20')
print("Date from ISO format: ", iso_date)

    Note: ISO 8601 is a standardized format for presenting dates and time without creating confusion across different regions or timezones. ISO 8601 takes the format YYYY-MM-DD.

    Here’s the output of the code above: 

    Date from ISO format:  2023-04-20

    Example: Create date object from string

    To create a date object, pass a date string and corresponding format to the strptime() method. Extract the date by using the date() method of the returned datetime object:

    from datetime import datetime

datetime_object = datetime.strptime("20/04/23", "%d/%m/%y")
date_object = datetime_object.date()

print("Date from string:", date_object)

    Here’s the output of the code above:

    Date from string: 2023-04-20

    Example: Get the year, month, day from the date object

    To extract the year, month and day from a date object, use the .year, .month, and .day attributes of the date class:

    from datetime import date

current_date = date.today()

year = current_date.year
print("The year is: ", year)

month = current_date.month
print("The month is: ", month)

day = current_date.day
print("The day is: ", day)

    Here’s the output of the code above: 

    The year is: 2023
The month is: 4
The day is: 20

    The time Class

    A time object represents a (local) time of day, independent of any particular day, and subject to adjustment via a tzinfo object.

    A date object can be instantiated as follows:

    datetime.time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None)

    The time object can be instantiated without any arguments. All arguments are optional with a default value of 0, except tzinfo, which is None. All arguments must be integers within a specified range, while the tzinfo argument should be an instance of the tzinfo subclass:

    • 0 <= hour < 24,
    • 0 <= minute < 60,
    • 0 <= second < 60,
    • 0 <= microsecond < 1000000.

    When arguments that are out of range are passed to the constructor, it raises a ValueError.

    Example: Create a time object

    To create a time object, import the time class from the datetime module. Pass arguments for hours, minutes, seconds, microseconds and tzinfo. Remember that all arguments are optional, so when no argument is passed to the constructor, the time object returns 00:00:00:

    from datetime import time

my_time = time(20, 30, 12)
print("My time is: ", my_time)

    Here’s the output of the code above:

    My time is:  20:30:12

    Example: Create time from ISO format

    A time object can be created from a time string in ISO 8601 format. Use the fromisoformat() method of the time class to do this:

    from datetime import time

iso_time = time.fromisoformat('12:45:12')
print('The time says: ', iso_time)

    Here’s the output of the code above:

    The time says: 12:45:12

    Example: Create time object from string

    To create a time object, pass a date string and corresponding format to the strptime() method. Extract the time by using the time() method of the returned datetime object:

    from datetime import datetime

datetime_object = datetime.strptime("20 Apr, 2023 13:50:30", "%d %b, %Y %H:%M:%S")
time_object = datetime_object.time()

print("Time from string:", time_object)

    Here’s the output of the code above:

    Time from string: 13:50:30

    Example: Get hours, minutes, seconds and microseconds from the time object

    To extract values for hours, minutes, seconds and microseconds, use the hour, minute, second, and microsecond attributes of the time object:

    from datetime import time

new_time = time(7, 20, 50, 569230)

hour = new_time.hour
print('Hours: ',hour)

minute = new_time.minute
print('Minutes: ', minute)

second = new_time.second
print('Seconds: ', second)

microsecond = new_time.microsecond
print('Microseconds: ', microsecond)

    Here’s the output of the code above:

    Hours: 7
Minutes: 20
Seconds: 50
Microseconds: 569230

    The datetime Class

    A datetime object is a single object containing all the information from a date object and a time object.

    A datetime object can be instantiated as follows:

    datetime.datetime(year, month, day, hour, minute=0, second=0, microsecond=0, tzinfo=None)

    The datetime constructor requires the year, month and day arguments. The tzinfo default is None or an instance of the tzinfo subclass. The time arguments are optional, but the arguments must be integers and within range:

    • MINYEAR <= year <= MAXYEAR,
    • 1 <= month <= 12,
    • 1 <= day <= number of days in the given month and year,
    • 0 <= hour < 24,
    • 0 <= minute < 60,
    • 0 <= second < 60,
    • 0 <= microsecond < 1000000.

    A ValueError is raised if arguments are out of range.

    Example: Create a datetime object

    To create a datetime object, import the datetime class from the datetime module and pass the following arguments:

    from datetime import datetime

dt = datetime(2023, 4, 20, 10, 38, 10, 345389)

    Here’s the output of the code above:

    The date time is: 2023-04-20 10:38:10.345389

    Example: Get the current local date and time

    To get the current local date and time, use the now() method of the datetime class:

    from datetime import datetime

print('Current locate date time is: ', datetime.now())

    Here’s the output of the code above:

    Current locate date time is: 2023-04-20 10:50:08.944232

    Example: Create date time from ISO format

    To create a datetime object from a date time string in ISO 8601 format, use the fromisoformat() method of the datetime class:

    from datetime import datetime

iso_dt = datetime.fromisoformat('2023-04-20 11:25:30.983023')
print('Date time from ISO is: ', iso_dt)

    Note: if the date string argument passed into the fromisoformat() method isn’t a valid ISO format string, a ValueError exception is raised. The date output here is quite similar to the result obtain from datetime.now().

    Here’s the output of the code above:

    Date time from ISO is: 2023-04-20 11:25:30.983023

    Example: Get date and time attributes from the datetime object

    A datetime object offers the following attributes: year, month, day, hour, minute, second, microsecond, tzinfo and fold. The attributes can be accessed as follows: 

    from datetime import datetime

new_dt = datetime.now()

year = new_dt.year
print('Year: ', year)

month = new_dt.month
print('Month: ', month)

day = new_dt.day
print('Day: ', day)

hour = new_dt.hour
print('Hours: ', hour)

minute = new_dt.minute
print('Minutes: ', minute)

second = new_dt.second
print('Seconds: ', second)

microsecond = new_dt.microsecond
print('Microseconds: ', microsecond)

tz_info = new_dt.tzinfo
print('Timezone info: ', tz_info)

fold = new_dt.fold
print('Fold: ', fold)

    Here’s the output of the code above:

    Year: 2023
Month: 4
Day: 20
Hours: 12
Minutes: 42
Seconds: 15
Microseconds: 794955
Timezone info: None
Fold: O

    Note: the default attribute value for tzinfo is None, because there’s no object argument passed, and fold will return 0 by default. For more on the fold attribute (which was introduced in Python version 3.6), see the docs.

    The timedelta Class

    A timedelta object represents a duration, the difference between two dates or times.

    A timedelta object can be instantiated as follows:

    datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)

    All arguments are optional, with a default value of 0. Integers or floats, positive or negative numbers are valid arguments for the constructor.

    Arguments are converted as follows:

    • A millisecond is converted to 1000 microseconds.
    • A minute is converted to 60 seconds.
    • An hour is converted to 3600 seconds.
    • A week is converted to 7 days.

    All arguments should fall within the following range as specified in the docs:

    • 0 <= microseconds < 1000000
    • 0 <= seconds < 3600*24 (the number of seconds in one day)
    • -999999999 <= days <= 999999999

    An OverFlowError is raised if arguments are outside the normalized days range.

    Example: Create a timedelta object

    To create a timedelta object, import the timedelta class from the datetime module. Pass the appropriate arguments to the constructor function:

    from datetime import timedelta

td = timedelta(10, 30, 4300, 3000, 12, 5, 3)
print('Time Delta: ', td)

    Here’s the output of the code above:

    Time Delta: 31 days, 5:12:33.004300

    Python datetime Formatting

    Date and time formats differ from region to region and country to country. It’s because of these differences in date and time formats that the ISO 8601 format was introduced, as a way to standardize date and time.
    However, there may be a need to format date and time in a particular way based on a country or region.

    Formatting datetime with the strftime() method

    Datetime formatting can be done with the strftime() method. The strftime() method is an instance method of time, date and datetime classes, which means we have to create a date, time or datetime object to apply the method. The method takes a given format code as an argument, and returns a string representing time, date or datetime from in the desired format.

    The method signature looks like this:

    strftime(format)

    Usually a string format code is passed as an argument to strftime() method to format date. Some of the format codes are as follows:

    • %a: weekday abbreviated name — such as Sun, Mon, etc.
    • %b: month as abbreviated name — such as Jan, Feb, etc.
    • %y: year without century as a zero-padded decimal number — such as 00, 01, 02, etc.

    A more detailed table with format code can be found in the Python docs.

    Example: Format date and time in a datetime object

    Just like in the previous examples, we can pass an argument of the format string of the desired date and time output to the strftime() method: 

    from datetime import datetime

date_time = datetime.now()

formatted_date_time = date_time.strftime("%d %B %Y, %H:%M:%S")
print("Formatted date and time:", formatted_date_time)

formatted_date_time_2 = date_time.strftime("%A, %d %B %Y, %I:%M %p")
print("Formatted date and time in 12-hour clock:", formatted_date_time_2)

    Here’s the output of the code above:

    Formatted date and time: 20 April 2023, 11:11:40
Formatted date and time in 12-hour clock: Thursday, 20 April 2023, 11:11 AM

    Formatting datetime with the strptime() method

    Unlike strftime(), the strptime() is a datetime class method, which means it can be used without creating an object of the class. The method returns a datetime object from a given date string and format.

    The method signature looks like this:

    strptime(date_string, format)

    A string format code is passed as an argument to strptime() method to format date.

    Example: String to datetime object

    To create a datetime object, we’ll pass two arguments to the strptime() method, a date string and a corresponding format. A ValueError is raised when the date string doesn’t match the provided format:

    from datetime import datetime

date_string = "April 20, 23 12:12:20"
dt_format = "%B %d, %y %H:%M:%S"

datetime_from_string = datetime.strptime(date_string, dt_format)
print("Datetime from string:", datetime_from_string)

    Here’s the output of the code above:

    Datetime from string: 2023-04-20 12:12:20

    Working with timedelta

    The timedelta class in Python is used for calculating the difference between dates, calculating time differences between specific dates, and also performing other calculations using specific units of time (such as weeks or hours).

    Example: Calculate a future date

    from datetime import datetime, timedelta

date_now = datetime.now()
print("Today's date:", date_now)

future_date = date_now + timedelta(days=7)
print("Future date is:", future_date)

    Here’s the output of the code above:

    Today's date: 2023-04-20 15:50:43.415319
Future date is: 2023-04-27 15:50:43.415319

    From the example above, we first get a current local date and time and a timedelta object of seven days. Because timedelta supports operations like addition, we add the datetime object and timedelta object to get a future day in seven days. If our current date is 2023-04-20, in seven days the date will be 2023-04-27.

    Example: Calculate the difference between two timedelta objects

    from datetime import timedelta

time_delta1 = timedelta(days=23, hours=0, minutes=20)
time_delta2 = timedelta(days=15, seconds=2, microseconds=123, milliseconds=234566, minutes=5, hours=2)

result = time_delta1 - time_delta2

print("Difference between two timedelta objects:", result)

    Here’s the output of the code above:

    Difference between two timedelta objects: 7 days, 22:11:03.433877

    In the code snippet above, we’ve created two timedelta objects, time_delta1 and time_delta2, and calculated the difference between them.

    Example: Calculate the sum of two timedelta objects

    from datetime import timedelta

time_delta1 = timedelta(days = 2, hours = 1, seconds = 33, weeks=2)
time_delta2 = timedelta(days = 4, hours = 11, minutes = 4, seconds = 54)

result = time_delta1 + time_delta2

print("Sum of two delta objects:", result)

    Here’s the output of the code above:

    Sum of two delta objects: 20 days, 12:05:27

    As seen above, the timedelta objects support addition operation, and the result is output to the console. Timedelta objects support operations like subtraction, multiplication, and division.

    Working with Timezones

    The use of timezones is necessary if we want to create aware date and time objects. An aware time or date object includes information on the timezone. It’s also important for displaying time or date objects in relation to a particular region.

    zoneinfo is a built-in Python module for working with timezones.

    Example: Create a datetime object with timezone information

    from datetime import datetime
from zoneinfo import ZoneInfo

tz = ZoneInfo('Africa/Accra')
date_time_object = datetime.now(tz)

print("Timezone information", date_time_object.tzinfo)
print("Timezone code", date_time_object.tzname())

    Here’s the output for the code above:

    Timezone information: Africa/Accra
Timezone code: GMT

    First, we import the datetime class from the datetime module and ZoneInfo from the zoneinfo module. We create a ZoneInfo object and then a datetime object, but this time we pass the timezone object tz to the now() method.

    When we check the value of the tzinfo attribute, it returns the name of the timezone Africa/Accra, not None.

    Example: Convert a datetime object from one timezone to another

    from datetime import datetime
from zoneinfo import ZoneInfo

accra_timezone = ZoneInfo('Africa/Accra')
accra_datetime = datetime.now(accra_timezone)
print("Current date time in Accra:", accra_datetime)

# switch to New York timezone
new_york_timezone = ZoneInfo('America/New_York')
new_york_datetime = accra_datetime.astimezone(new_york_timezone)
print("Current date time in New York:", new_york_datetime)

    Here’s the output of the code above:

    Current date time in Accra 2023-04-20 10:42:02.476541+00:00
Current date time in New York 2023-04-20 06:42:02.476541-04:00

    To convert between timezones, we use the astimezone() method of the datetime object, passing in a new timezone object. The astimezone() returns a new datetime object with updated timezone information.

    Conclusion

    Keeping track of time is an important aspect of our daily lives, and this also translates into programming. When we build real-world projects, there’s always the need to keep time logs for user activities like login and sign-out, among other use cases. It’s also important to put a time stamp on content generated online and to display time and date according to a user’s region or timezone.

    To better manage times and dates in our programs or applications, Python provides the time and datetime modules. These modules have functions, classes and methods for managing time-related tasks. In this article, we’ve highlighted some commonly used functions and methods, providing examples of how they can be used.

    The code for this tutorial can be found on GitHub.