https://github.com/singingwolfboy/jinja2-iso8601
Adds `parse_date` and `format_date` filters to Jinja.
https://github.com/singingwolfboy/jinja2-iso8601
jinja2 jinja2-extension jinja2-filters
Last synced: 2 months ago
JSON representation
Adds `parse_date` and `format_date` filters to Jinja.
- Host: GitHub
- URL: https://github.com/singingwolfboy/jinja2-iso8601
- Owner: singingwolfboy
- License: mit
- Created: 2022-09-19T19:46:02.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2022-09-20T16:51:00.000Z (over 2 years ago)
- Last Synced: 2025-01-20T18:46:57.786Z (4 months ago)
- Topics: jinja2, jinja2-extension, jinja2-filters
- Language: Python
- Homepage:
- Size: 3.91 KB
- Stars: 1
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Jinja2-ISO8601
Adds `parse_date` and `format_date` filters to Jinja.
The [`iso8601`](https://github.com/micktwomey/pyiso8601) module handles date parsing,
hence the name of this project. The
[`.strftime()`](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior)
method handles date formatting.
## Install
First install the Python module:
```bash
pip install jinja2-iso8601
```
Then add the extension into your Jinja environment:
```python
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`](https://docs.python.org/3/library/datetime.html#datetime-objects) 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](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes).
You can also check [the cheatsheet at strftime.org](https://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:
```jinja
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:
```python
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`](https://github.com/metwork-framework/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!