http.parse_date returns timzeone-aware valueparse_date-timezone

2 files changed, 23 insertions, 12 deletions

diff --git a/docs/http.rst b/docs/http.rst
index 0f16cc8f..3db53506 100644
--- a/docs/http.rst
+++ b/docs/http.rst
@@ -9,21 +9,32 @@ that are useful when implementing WSGI middlewares or whenever you are
 operating on a lower level layer.  All this functionality is also exposed
 from request and response objects.
 
-Date Functions
-==============
 
-The following functions simplify working with times in an HTTP context.
-Werkzeug uses offset-naive :class:`~datetime.datetime` objects internally
-that store the time in UTC.  If you're working with timezones in your
-application make sure to replace the tzinfo attribute with a UTC timezone
-information before processing the values.
+Datetime Functions
+==================
 
-.. autofunction:: cookie_date
+These functions simplify working with times in an HTTP context. Werkzeug
+produces timezone-aware :class:`~datetime.datetime` objects in UTC. When
+passing datetime objects to Werkzeug, it assumes any naive datetime is
+in UTC.
 
-.. autofunction:: http_date
+When comparing datetime values from Werkzeug, your own datetime objects
+must also be timezone-aware, or you must make the values from Werkzeug
+naive.
+
+*   ``dt = datetime.now(timezone.utc)`` gets the current time in UTC.
+*   ``dt = datetime(..., tzinfo=timezone.utc)`` creates a time in UTC.
+*   ``dt = dt.replace(tzinfo=timezone.utc)`` makes a naive object aware
+    by assuming it's in UTC.
+*   ``dt = dt.replace(tzinfo=None)`` makes an aware object naive.
 
 .. autofunction:: parse_date
 
+.. autofunction:: http_date
+
+.. autofunction:: cookie_date
+
+
 Header Parsing
 ==============
 
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index abe5c798..be4574f2 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -185,7 +185,7 @@ True
 E-tags and other conditional headers are available in parsed form as well:
 
 >>> request.if_modified_since
-datetime.datetime(2009, 2, 20, 10, 10, 25)
+datetime.datetime(2009, 2, 20, 10, 10, 25, tzinfo=datetime.timezone.utc)
 >>> request.if_none_match
 <ETags '"e51c9-1e5d-46356dc86c640"'>
 >>> request.cache_control
@@ -253,8 +253,8 @@ retrieve them:
 
 >>> response.content_length
 12
->>> from datetime import datetime
->>> response.date = datetime(2009, 2, 20, 17, 42, 51)
+>>> from datetime import datetime, timezone
+>>> response.date = datetime(2009, 2, 20, 17, 42, 51, tzinfo=timezone.utc)
 >>> response.headers['Date']
 'Fri, 20 Feb 2009 17:42:51 GMT'