#2211: properly document the Morsel behavior changes.

Also deprecate the undocumented set argument instead of removing
it already in 3.5.

Initial patch by Demian Brecht.

Author: bitdancer

Doc/library/http.cookies.rst

@@ -143,38 +143,43 @@ Morsel Objects
 
    The keys are case-insensitive.
 
+   .. versionchanged:: 3.5
+      :meth:`~Morsel.__eq__` now takes :attr:`~Morsel.key` and :attr:`~Morsel.value`
+      into account.
+
 
 .. attribute:: Morsel.value
 
    The value of the cookie.
 
    .. deprecated:: 3.5
-      Setting :attr:`~Morsel.value` directly has been deprecated in favour of
-      using :func:`~Morsel.set`
+      assigning to ``value``; use :meth:`~Morsel.set` instead.
 
 
 .. attribute:: Morsel.coded_value
 
    The encoded value of the cookie --- this is what should be sent.
 
    .. deprecated:: 3.5
-      Setting :attr:`~Morsel.coded_value` directly has been deprecated in
-      favour of using :func:`~Morsel.set`
+      assigning to ``coded_value``; use :meth:`~Morsel.set` instead.
 
 
 .. attribute:: Morsel.key
 
    The name of the cookie.
 
    .. deprecated:: 3.5
-      Setting :attr:`~Morsel.key` directly has been deprecated in
-      favour of using :func:`~Morsel.set`
+      assigning to ``key``; use :meth:`~Morsel.set` instead.
 
 
 .. method:: Morsel.set(key, value, coded_value)
 
    Set the *key*, *value* and *coded_value* attributes.
 
+   .. deprecated:: 3.5
+      The undocumented *LegalChars* parameter is ignored and will be removed in
+      a future version.
+
 
 .. method:: Morsel.isReservedKey(K)
 
@@ -205,6 +210,24 @@ Morsel Objects
    The meaning for *attrs* is the same as in :meth:`output`.
 
 
+.. method:: Morsel.update(values)
+
+   Update the values in the Morsel dictionary with the values in the dictionary
+   *values*.  Raise an error if any of the keys in the *values* dict is not a
+   valid :rfc:`2109` attribute.
+
+   .. versionchanged:: 3.5
+      an error is raised for invalid keys.
+
+
+.. method:: Morsel.copy(value)
+
+   Return a shallow copy of the Morsel object.
+
+   .. versionchanged:: 3.5
+      return a Morsel object instead of a dict.
+
+
 .. _cookie-example:
 
 Example

Doc/whatsnew/3.5.rst

@@ -525,11 +525,12 @@ Deprecated Python modules, functions and methods
   ``True``, but this default is deprecated.  Specify the *decode_data* keyword
   with an appropriate value to avoid the deprecation warning.
 
-* :class:`~http.cookies.Morsel` has previously allowed for setting attributes
-  :attr:`~http.cookies.Morsel.key`, :attr:`~http.cookies.Morsel.value` and
-  :attr:`~http.cookies.Morsel.coded_value`. Use the preferred
-  :func:`~http.cookies.Morsel.set` method in order to avoid the deprecation
-  warning.
+* Directly assigning values to the :attr:`~http.cookies.Morsel.key`,
+  :attr:`~http.cookies.Morsel.value` and
+  :attr:`~http.cookies.Morsel.coded_value` of :class:`~http.cookies.Morsel`
+  objects is deprecated.  Use the :func:`~http.cookies.Morsel.set` method
+  instead.  In addition, the undocumented *LegalChars* parameter of
+  :func:`~http.cookies.Morsel.set` is deprecated, and is now ignored.
 
 * Passing a format string as keyword argument *format_string* to the
   :meth:`~string.Formatter.format` method of the :class:`string.Formatter`
@@ -635,6 +636,16 @@ Changes in the Python API
   string (e.g. ``'x+'`` instead of ``'x*'``).  Patterns that could only match
   an empty string (such as ``'\b'``) now raise an error.
 
+* The :class:`~http.cookies.Morsel` dict-like interface has been made self
+  consistent:  morsel comparison now takes the :attr:`~http.cookies.Morsel.key`
+  and :attr:`~http.cookies.Morsel.value` into account,
+  :meth:`~http.cookies.Morsel.copy` now results in a
+  :class:`~http.cookies.Morsel` instance rather than a *dict*, and
+  :meth:`~http.cookies.Morsel.update` will no raise an exception if any of the
+  keys in the update dictionary are invalid.  In addition, the undocumented
+  *LegalChars* parameter of :func:`~http.cookies.Morsel.set` is deprecated and
+  is now ignored.  (:issue:`2211`)
+
 Changes in the C API
 --------------------
 

Lib/http/cookies.py

@@ -366,7 +366,14 @@ def update(self, values):
     def isReservedKey(self, K):
         return K.lower() in self._reserved
 
-    def set(self, key, val, coded_val):
+    def set(self, key, val, coded_val, LegalChars=_LegalChars):
+        if LegalChars != _LegalChars:
+            import warnings
+            warnings.warn(
+                'LegalChars parameter is deprecated, ignored and will '
+                'be removed in future versions.', DeprecationWarning,
+                stacklevel=2)
+
         if key.lower() in self._reserved:
             raise CookieError('Attempt to set a reserved key %r' % (key,))
         if not _is_legal_key(key):

Lib/test/test_http_cookies.py

@@ -261,6 +261,8 @@ def test_deprecation(self):
             morsel.value = ''
         with self.assertWarnsRegex(DeprecationWarning, r'\bcoded_value\b'):
             morsel.coded_value = ''
+        with self.assertWarnsRegex(DeprecationWarning, r'\bLegalChars\b'):
+            morsel.set('key', 'value', 'coded_value', LegalChars='.*')
 
     def test_eq(self):
         base_case = ('key', 'value', '"value"')