[3.7] bpo-11001: updated cookie docs (GH-13086) (GH-13161)

miss-islington · web-flow · commit 1fe722cf14db · 2019-05-07T10:32:45.000-07:00
Used **spookylukey**'s patch from 2011-01-24 https://bugs.python.org/issue11001 (cherry picked from commit 91cc01f) Co-authored-by: Julia Iliuk <julia.iluyk@gmail.com> https://bugs.python.org/issue11001
diff --git a/Doc/library/http.cookies.rst b/Doc/library/http.cookies.rst
@@ -55,8 +55,9 @@ in Cookie name (as :attr:`~Morsel.key`).
 .. class:: SimpleCookie([input])
 
    This class derives from :class:`BaseCookie` and overrides :meth:`value_decode`
-   and :meth:`value_encode` to be the identity and :func:`str` respectively.
-
+   and :meth:`value_encode`. SimpleCookie supports strings as cookie values.
+   When setting the value, SimpleCookie calls the builtin :func:`str()` to convert
+   the value to a string. Values received from HTTP are kept as strings.
 
 .. seealso::
 
@@ -76,15 +77,16 @@ Cookie Objects
 
 .. method:: BaseCookie.value_decode(val)
 
-   Return a decoded value from a string representation. Return value can be any
-   type. This method does nothing in :class:`BaseCookie` --- it exists so it can be
-   overridden.
+   Return a tuple ``(real_value, coded_value)`` from a string representation.
+   ``real_value`` can be any type. This method does no decoding in
+   :class:`BaseCookie` --- it exists so it can be overridden.
 
 
 .. method:: BaseCookie.value_encode(val)
 
-   Return an encoded value. *val* can be any type, but return value must be a
-   string. This method does nothing in :class:`BaseCookie` --- it exists so it can
+   Return a tuple ``(real_value, coded_value)``. *val* can be any type, but
+   ``coded_value`` will always be converted to a string.
+   This method does no encoding in :class:`BaseCookie` --- it exists so it can
    be overridden.
 
    In general, it should be the case that :meth:`value_encode` and
