Jinja2-ISO8601

Adds parse_date and format_date filters to Jinja. The iso8601 module handles date parsing, hence the name of this project. The .strftime() method handles date formatting.

Install

First install the Python module:

pip install jinja2-iso8601

Then add the extension into your Jinja environment:

from jinja2 import Environment

jinja_env = Environment(extensions=['jinja2_iso8601.ISO8601Extension'])

Use

You can now use two new filters when writing your Jinja templates: parse_date and format_date. parse_date will turn an ISO-8601 formatted string into a Python datetime object. format_date will call the .strftime() method on whatever you pass to it; this works well with datetime, date, and time objects. You'll need to provide a format string for the format_date filter; check the Python documentation for how to write a format string. You can also check the cheatsheet at strftime.org.

For example, let's say you have a variable called datestr which is a string representing a datetime in valid ISO-8601 format, such as "2022-09-19T14:38:34.213001". You can write your Jinja template like this:

no filter: {{ datestr }}
parsed: {{ datestr|parse_date }}
formatted: {{ datestr|parse_date|format_date("%a, %b %d %Y") }}

and the rendered result will be:

no filter: 2022-09-19T14:38:34.213001
parsed: 2022-09-19 14:38:34.213001
formatted: Mon, Sep 19 2022

Timezones

In Python, date and time objects may include timezone information. Date and time objects that have an associated timezone are "aware", and those that do not have an associated timezone are "naive".

By default, when parsing ISO-8601 strings without any timezone information, the result is a "naive" datetime object. However, in some cases, you may want to assume a default timezone, so that you always get an "aware" datetime object even if no timezone is specified. For example, if you know that the ISO-8601 string is in the UTC timezone, you may want the parse_date filter to return an "aware" datetime with the UTC timezone.

The default_timezone value on the Jinja environment controls which timezone to use when none is specified in the string. By default, this value is None, which makes parse_date return a "naive" datetime. Here's how to make all datetimes parse as UTC:

from datetime import timezone
from jinja2 import Environment

jinja_env = Environment(extensions=['jinja2_iso8601.ISO8601Extension'])
jinja_env.default_timezone = timezone.utc

See Also

These filters can be paired with other Jinja filters that process datetimes, such as jinja2_humanize_extension. You can parse strings into datetime using the parse_date filter from this project, and then "humanize" the datetime using the humanize_naturalday filter from jinja2_humanize_extension. They work together seamlessly!