Understanding Python Datetime Handling

Communicating dates and times with another person is pretty simple… right?

“See you at 6 o’clock on Monday” sounds understandable.

But was it a.m. or p.m.? And was your friend in the same time zone as you when you said that? When we need to use and store dates and times on Python, we have the same issues — and even more — since we can express a date and time in many ways. For example:

“July 15, 2019 07:05 pm”
“2019-15-07 19:05:53 CDT”

All of these strings and even the integer expresses the exact same date and time, but they all look very different one from another, right? In this article, we’ll discuss Python datetimes best practices to reduce the complexity when using, formatting, and storing datetimes on a daily basis. Here are the highlights of what we’ll cover:

To dive deeper into the basic fundamentals of Python, check out Cloud Academy’s new Python for Beginners Learning Path. It’s designed for people new to programming, providing an ideal entry point for people wanting to learn how to program with the Python scripting language. 

Cloud Academy Python for Beginners 

Python datetimes best practices

When we talk about a Python datetime format standard, we mean the ISO 8601 (Date and Time Format). This format is used in most of the databases and it has the following structure:

YYYY-MM-DDThh:mm:ss.sss +00:00


YYYY-MM-DDThh:mm:ss.sss TZ

But when we show it to the user, we might want to change the way it looks. This is because if we use a tool to get it from the user — like a calendar or select inputs — it can also vary on the way the data is sent to the backend.

Creating a Python parser

Luckily, Python has a parser that understands pretty much all of the cases of a string formatting. For example:

Using the following libraries:

from dateutil.parser import parse 
import datetime as dt 
from dateutil.tz import tzutc

The parser will actually recognize parameters like these written as text:

first_date = parse('January 31, 2010') 
print(type(first_date), first_date)

The type of the object looks like this:

>> parse("<class 'datetime.datetime'> 2010-01-31 00:00:00")

And the object created looks like this:

>> datetime.datetime(2010, 1, 31, 0, 0)

The parser can also understand standard notations like “Sat” for Saturday: 

second_date = parse("Sat Oct 11 17:13:46 UTC 2003") 
print(type(second_date), second_date) 
>> <class 'datetime.datetime'> 2003-10-11 17:13:46+00:00 
>> datetime.datetime(2003, 10, 11, 17, 13, 46, tzinfo=tzutc())

We can also directly create a datetime object without the format as following:

my_new_datetime = dt.datetime(2001, 1, 31, 10, 51, 0) 
>> 2001-01-31 10:51:00

Creating a Python datetime with a Unix timestamp

There’s yet another way to create a Python datetime with a unix timestamp.

The unix timestamp is a system for describing a point in time. It is the number of seconds that have elapsed since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds. Every day is treated as if it contains exactly 86400 seconds, so leap seconds are to be subtracted since the epoch. It is used widely in Unix-like and many other operating systems and file formats. (Wikipedia, 2019).

The main characteristic of this format is that we get a datetime stored as an integer. So we can directly convert the Unix timestamp to a Python datetime object with the “fromtimestamp” method as follows:

from_unix_datetime = datetime.datetime.fromtimestamp(528756281)
>> datetime.datetime(1986, 10, 4, 2, 14, 41)

Or backwards:

from_datetime_timestamp = dt.datetime.timestamp(from_unix_datetime)
>> 528756281.0

Setting the Python datetime time zone

Now an optional — but important — parameter to include is the time zone of the datetime. The default time zone is UTC or the one set on your project. However, if the datetime is captured at a local time (let’s say central time for example) and the database that stores this information has UTC time, then it will have a difference of five hours. This can create a conflict if the server that retrieves this datetime is on eastern time (ET). If you didn’t set the time zone on the creation, there’s a way to add it after with a replace as following:


Or we can set it on the creation:

dt.datetime(2001, 1, 31, 10, 51, 0, tzinfo=tzutc())

Another thing to take in consideration is the way you import the datetime library, sometimes on the code we need to call the base datetime library and sometimes we need the datetime.datetime which contains different methods. To avoid this, we can call datetime as dt and datetime.datetime as datetime or to call it directly from dt.datetime.

from datetime import datetime
import datetime as dt

Creating datetime ranges

Following with the common Python mistakes, there’s one mistake that happens silently, but it can affect us if we need an exact range of datetimes and our visual calendar tool doesn’t have time selection but only date selection. When we need a datetime range starting from 00:00:00, we can easily add it to the initial date as follows:

today_datetime = dt.datetime.today() # Create a new datetime with today parameters
rounded_date = today_datetime.replace(hour=0, minute=0, second=0, microsecond=0)
>>2019-07-26 00:00:00

We can also add or subtract time to our datetime with a timedelta. The number of days will initialize a new timedelta with a time of 30 days.

time_delta = dt.timedelta(days=30) 
print(dt.datetime.today() + time_delta) 
>> 2019-08-25 18:46:02.274584

Or compare two datetimes subtracting one from another:

last_week_day = dt.datetime.today() - dt.timedelta(days=7) 
>> 2019-07-19 18:49:43.580625

That was easy right? Now let’s use an even easier tool to get single datetime parameters:

Getting the current date

Get the current day of the month:

my_dt = dt.datetime.today()
my_dt.day  >> 31

Get the current day of the week (in this case, it is Friday):

my_dt.isoweekday() >> 5

Get the current month of the year (in this case, it is February):

my_dt.month  >> 2

Get the year:

my_dt.year  >> 2019

Finally, an issue that we don’t usually take in consideration: What happens when we set a datetime object as a value on a payload and then we send this as the data of a request? 

current_datetime = dt.datetime.today() 
requests.get(url="http://test_endpoint.com", json={ "date": current_datetime}) 
>> TypeError: Object of type datetime is not JSON serializable

Most of the Python requests libraries won’t accept a datetime, date, or time type object. First, we need to convert it to a string or integer. Since the standard is the ISO 8601 format, we will simply do the following:

requests.get(url="http://test_endpoint.com", json={"date": current_datetime.isoformat()})

Next steps

Once you have the foundational knowledge of datetimes in Python, it will get a lot more easy to work with. After you learn the basics, you’ll be ready to jump into Cloud Academy’s Pythonic Programming Learning Path. This learning path will help you master the advanced features of the Python language to ensure your code clean, concise, readable, and maintainable — or “pythonic”. 

Valery Calderón Briz

Written by

Valery Calderón Briz

Valery is currently a Software engineer at Credijusto.com, Telecommunications Engineer with 8+ years of experience developing back-end software. Pythonista, PyLadies CDMX co-organizer, Python Guatemala Community Co-founder. Speaker at PyconLatam 2019 (Puerto Vallarta, Mexico), Pycon 2018 (Cleveland, USA), PyconEs 2017 (Caceres, Spain) and other events.

Related Posts

Luca Casartelli
Luca Casartelli
— May 14, 2020

DevOps Principles: My Journey as a Software Engineer

I spent the last month reading The DevOps Handbook, a great book regarding DevOps principles, and how tech organizations evolved and succeeded in applying them.As a software engineer, you may think that DevOps is a bunch of people that deploy your code on production, and always acco...

Read more
  • DevOps
  • DevOps principles
Michael Dehoyos
Michael Dehoyos
— May 13, 2020

Linux and DevOps: The Most Suitable Distribution

Modern Linux and DevOps have much in common from a philosophy perspective. Both are focused on functionality, scalability, as well as on the constant possibility of growth and improvement. While Windows may still be the most widely used operating system, and by extension the most common...

Read more
  • DevOps
  • Linux
Logan Rakai
— April 7, 2020

How to Effectively Use Azure DevOps

Azure DevOps is a suite of services that collaborate on software development following DevOps principles. The services in Azure DevOps are:Azure Repos for hosting Git repositories for source control of your code Azure Boards for planning and tracking your work using proven agil...

Read more
  • Azure
  • DevOps
Simran Arora
Simran Arora
— October 29, 2019

Docker vs. Virtual Machines: Differences You Should Know

What are the differences between Docker and virtual machines? In this article, we'll compare the differences and provide our insights to help you decide between the two. Before we get started discussing Docker vs. Virtual Machines comparisons, let us first explain the basics.  What is ...

Read more
  • Containers
  • DevOps
  • Docker
  • virtual machines
Adam Hawkins
— October 24, 2019

DevOps: From Continuous Delivery to Continuous Experimentation

Imagine this scenario. Your team built a continuous delivery pipeline. Team members deploy multiple times a day. Telemetry warns the team about production issues before they become outages. Automated tests ensure known regressions don't enter production. Team velocity is consistent and ...

Read more
  • continuous delivery
  • continuous experimentation
  • DevOps
Adam Hawkins
— September 13, 2019

How Google, HP, and Etsy Succeed with DevOps

DevOps is currently well developed, and there are many examples of companies adopting it to improve their existing practices and explore new frontiers. In this article, we'll take a look at case studies and use cases from Google, HP, and Etsy. These companies are having success with Dev...

Read more
  • Continuous Learning
  • DevOps
  • Velocity
Chris Gambino
Chris Gambino
— August 28, 2019

How to Accelerate Development in the Cloud

Understanding how to accelerate development in the cloud can prevent typical challenges that developers face in a traditional enterprise. While there are many benefits to switching to a cloud-first model, the most immediate one is accelerated development and testing. The road blocks tha...

Read more
  • deploy
  • deployment acceleration
  • development
  • DevOps
Adam Hawkins
— August 9, 2019

DevSecOps: How to Secure DevOps Environments

Security has been a friction point when discussing DevOps. This stems from the assumption that DevOps teams move too fast to handle security concerns. This makes sense if Information Security (InfoSec) is separate from the DevOps value stream, or if development velocity exceeds the band...

Read more
  • AWS
  • cloud security
  • DevOps
  • DevSecOps
  • Security
Alisha Reyes
Alisha Reyes
— July 22, 2019

Cloud Academy’s Blog Digest: July 2019

July has been a very exciting month for us at Cloud Academy. On July 10, we officially joined forces with QA, the UK’s largest B2B skills provider (read the announcement). Over the coming weeks, you will see additions from QA’s massive catalog of 500+ certification courses and 1500+ ins...

Read more
  • AWS
  • Azure
  • Cloud Academy
  • Cybersecurity
  • DevOps
  • Kubernetes
Adam Hawkins
— July 17, 2019

How to Become a DevOps Engineer

The DevOps Handbook introduces DevOps as a framework for improving the process for converting a business hypothesis into a technology-enabled service that delivers value to the customer. This process is called the value stream. Accelerate finds that applying DevOps principles of flow, f...

Read more
  • AWS
  • AWS Certifications
  • DevOps
  • DevOps Foundation Certification
  • Engineer
  • Kubernetes
Adam Hawkins
— July 9, 2019

Top 20 Open Source Tools for DevOps Success

Open source tools perform a very specific task, and the source code is openly published for use or modification free of charge. I've written about DevOps multiple times on this blog. I reiterate the point that DevOps is not about specific tools. It's a philosophy for building and improv...

Read more
  • Ansible
  • Chef
  • configuration management
  • DevOps
  • devops tools
  • Docker
  • infrastructure-as-code
  • Kubernetes
  • telemetry
Adam Hawkins
— July 2, 2019

DevOps: Scaling Velocity and Increasing Quality

All software teams strive to build better software and ship it faster. That's a competitive edge required to survive in the Age of Software. DevOps is the best methodology to leverage that competitive advantage, ultimately allowing practitioners to accelerate software delivery and raise...

Read more
  • continuous delivery
  • DevOps
  • software