From 357d62d9f2972bf1bc21e5835c12c849143e06af Mon Sep 17 00:00:00 2001 From: Jacob Kaplan-Moss Date: Thu, 6 Jun 2013 11:03:47 -0500 Subject: [PATCH] Explained that timezone.now() always returns times in UTC. The docs were ambiguous about the time zone for now(), leading people to assume that it would be the current time zone rather that UTC. --- docs/ref/utils.txt | 18 +++++++++++++++--- docs/topics/i18n/timezones.txt | 2 ++ 2 files changed, 17 insertions(+), 3 deletions(-) diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt index bf14af08550..d2ef945a2e6 100644 --- a/docs/ref/utils.txt +++ b/docs/ref/utils.txt @@ -929,9 +929,21 @@ For a complete discussion on the usage of the following see the .. function:: now() - Returns an aware or naive :class:`~datetime.datetime` that represents the - current point in time when :setting:`USE_TZ` is ``True`` or ``False`` - respectively. + Returns a :class:`~datetime.datetime` that represents the + current point in time. Exactly what's returned depends on the value of + :setting:`USE_TZ`: + + * If :setting:`USE_TZ` is ``False``, this will be be a + :ref:`naive ` datetime (i.e. a datetime + without an associated timezone) that represents the current time + in the system's local timezone. + + * If :setting:`USE_TZ` is ``True``, this will be an + :ref:`aware ` datetime representing the + current time in UTC. Note that :func:`now` will always return + times in UTC regardless of the value of :setting:`TIME_ZONE`; + you can use :func:`localtime` to convert to a time in the current + time zone. .. function:: is_aware(value) diff --git a/docs/topics/i18n/timezones.txt b/docs/topics/i18n/timezones.txt index e4a043b08fb..5ed60d0a940 100644 --- a/docs/topics/i18n/timezones.txt +++ b/docs/topics/i18n/timezones.txt @@ -54,6 +54,8 @@ FAQ `. Concepts ======== +.. _naive_vs_aware_datetimes: + Naive and aware datetime objects --------------------------------