Clarify the reasons why pickle is almost always better than marshal

1 files changed, 9 insertions, 1 deletions

diff --git a/Doc/library/marshal.rst b/Doc/library/marshal.rst
index 6927067..8efcbb7 100644
--- a/Doc/library/marshal.rst
+++ b/Doc/library/marshal.rst
@@ -25,7 +25,9 @@ transfer of Python objects through RPC calls, see the modules :mod:`pickle` and
 writing the "pseudo-compiled" code for Python modules of :file:`.pyc` files.
 Therefore, the Python maintainers reserve the right to modify the marshal format
 in backward incompatible ways should the need arise.  If you're serializing and
-de-serializing Python objects, use the :mod:`pickle` module instead.
+de-serializing Python objects, use the :mod:`pickle` module instead -- the
+performance is comparable, version independence is guaranteed, and pickle
+supports a substantially wider range of objects than marshal.
 
 .. warning::
 
@@ -43,6 +45,12 @@ themselves supported; and recursive lists and dictionaries should not be written
 (they will cause infinite loops).
 
 .. warning::
+
+   Some unsupported types such as subclasses of builtins will appear to marshal
+   and unmarshal correctly, but in fact, their type will change and the
+   additional subclass functionality and instance attributes will be lost.
+
+.. warning::
    
    On machines where C's ``long int`` type has more than 32 bits (such as the
    DEC Alpha), it is possible to create plain Python integers that are longer