Public API for localtime

[Bradley Ayers <bradley.ayers@…>]

I think there should be a public API for converting timezone aware datetime objects to current timezone versions. This actually existed in django.utils.timezone as localtime, but was made private and removed from the documentation in https://code.djangoproject.com/changeset/17642

The current options for converting a datetime to the current timezone are:

1. Use Python's datetime.astimezone in conjunction with django.utils.timezone helpers:

from django.utils import timezone
local = dt.astimezone(timezone.get_current_timezone())

2. Use the public API for the localtime template filter via the privatish module django.template.defaultfilters:

from django.templatetags.tz import localtime
local = localtime(dt)

While (2) is much cleaner, I'd argue it's dirty to import from defaultfilters.

I propose re-publicising django.utils.timezone.localtime as a public API.

My use-case is generating PDFs that have datetimes in their content.

[Bradley Ayers <bradley.ayers@…>]

Correction:

django.template.defaultfilters import localtime

…should have been:

from django.templatetags.tz import localtime

EDIT(aaugustin): I made this change in the summary.

[Aymeric Augustin]

I made django.utils.timezone.localtime private because it contains some template-specific code.

I agree it would make sense to expose a similar function, without the template-specific bits, for general use.

This function actually has two variants: "default local time" or "current local time". As long as you don't have a timezone switcher for your end users, there's no difference between these. However, we should take this into account while extending the public API.