From 143255c8bbefe03ff755d7859f029f0bc7a552aa Mon Sep 17 00:00:00 2001 From: Josh Smeaton Date: Tue, 31 Mar 2015 16:58:37 +1100 Subject: Fixed #22598 -- Allowed make_aware() to work with ambiguous datetime --- docs/ref/utils.txt | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt index b69d11fc36..18312957fc 100644 --- a/docs/ref/utils.txt +++ b/docs/ref/utils.txt @@ -947,20 +947,37 @@ appropriate entities. Returns ``True`` if ``value`` is naive, ``False`` if it is aware. This function assumes that ``value`` is a :class:`~datetime.datetime`. -.. function:: make_aware(value, timezone=None) +.. function:: make_aware(value, timezone=None, is_dst=None) Returns an aware :class:`~datetime.datetime` that represents the same point in time as ``value`` in ``timezone``, ``value`` being a naive :class:`~datetime.datetime`. If ``timezone`` is set to ``None``, it defaults to the :ref:`current time zone `. - This function can raise an exception if ``value`` doesn't exist or is - ambiguous because of DST transitions. + When pytz_ is installed, the exception ``pytz.AmbiguousTimeError`` + will be raised if you try to make ``value`` aware during a DST transition + where the same time occurs twice (when reverting from DST). Setting + ``is_dst`` to ``True`` or ``False`` will avoid the exception by choosing if + the time is pre-transition or post-transition respectively. + + When pytz_ is installed, the exception ``pytz.NonExistentTimeError`` + will be raised if you try to make ``value`` aware during a DST transition + such that the time never occurred (when entering into DST). Setting + ``is_dst`` to ``True`` or ``False`` will avoid the exception by moving the + hour backwards or forwards by 1 respectively. For example, ``is_dst=True`` + would change a non-existent time of 2:30 to 1:30 and ``is_dst=False`` + would change the time to 3:30. + + ``is_dst`` has no effect when ``pytz`` is not installed. .. versionchanged:: 1.8 In older versions of Django, ``timezone`` was a required argument. + .. versionchanged:: 1.9 + + The ``is_dst`` argument was added. + .. function:: make_naive(value, timezone=None) Returns an naive :class:`~datetime.datetime` that represents in -- cgit v1.3