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”
“2019-07-15T23:05:53.256587-05:00”
1563231953

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

or 

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) 
print(my_new_datetime) 
>> 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)
print(from_unix_datetime)
>> datetime.datetime(1986, 10, 4, 2, 14, 41)

Or backwards:

from_datetime_timestamp = dt.datetime.timestamp(from_unix_datetime)
print(from_datetime_timestamp)
>> 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:

my_new_datetime.replace(tzinfo=dt.timezone.utc)

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)
print(rounded_date)
>>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) 
print(last_week_day) 
>> 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 back-end developer at Prescrypto.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

Avatar
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
Avatar
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
Avatar
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
Avatar
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
Avatar
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
Avatar
Adam Hawkins
— June 13, 2019

Continuous Deployment: What’s the Point?

Continuous Deployment is the pinnacle of high-performance software development. Continuous deployment teams deploy every commit that passes tests to production, and there's nothing faster than that. Even though you'll see the "CD" term thrown around the internet, continuous deployment a...

Read more
  • Development & Deploy
  • DevOps
Avatar
Adam Hawkins
— May 31, 2019

DevOps Telemetry: Open Source vs Cloud vs Third Party

The DevOps principle of feedback calls for business, application, and infrastructure telemetry. While telemetry is important for engineers when debugging production issues or setting base operational conditions, it is also important to product owners and business stakeholders because it...

Read more
  • Analytics
  • DevOps
Avatar
Adam Hawkins
— April 16, 2019

The Convergence of DevOps

IT has changed over the past 10 years with the adoption of cloud computing, continuous delivery, and significantly better telemetry tools. These technologies have spawned an entirely new container ecosystem, demonstrated the importance of strong security practices, and have been a catal...

Read more
  • DevOps
  • Security
Avatar
Adam Hawkins
— March 21, 2019

How DevOps Increases System Security

The perception of DevOps and its role in the IT industry has changed over the last five years due to research, adoption, and experimentation. Accelerate: The Science of Lean Software and DevOps by Gene Kim, Jez Humble, and Nicole Forsgren makes data-backed predictions about how DevOps p...

Read more
  • DevOps
  • Security
Avatar
Adam Hawkins
— February 7, 2019

Measuring DevOps Success: What, Where, and How

The DevOps methodology relates technical and organization practices so it's difficult to simply ascribe a number and say "our organization is a B+ on DevOps!" Things don't work that way. A better approach identifies intended outcomes and measurable characteristics for each outcome. Let'...

Read more
  • DevOps