docs: clarify that proto plus messages are not pickleable (googleapis#260)

software-dov · web-flow · commit 6e691dc27b1e · 2021-10-08T09:44:58.000-07:00
Clarify that proto-plus messages are not pickleable, describe the alternative, and give a multiprocessing example. Note: in the future, we _may_ enable pickling proto-plus messages through custom extensions as described in https://docs.python.org/3/library/pickle.html#pickling-class-instances This is _not_ guaranteed. For the foreseeable future, the preferred method of serializing and deserializing proto-plus messages is Message.serialize and Message.deserialize
diff --git a/docs/messages.rst b/docs/messages.rst
@@ -243,3 +243,32 @@ already allows construction from mapping types.
    song_dict = Song.to_dict(song)
 
    new_song = Song(song_dict)
+
+.. note::
+
+   Protobuf messages **CANNOT** be safely pickled or unpickled. This has serious consequences for programs that use multiprocessing or write messages to files.
+   The preferred mechanism for serializing proto messages is :meth:`~.Message.serialize`.
+
+   Multiprocessing example:
+
+   .. code-block:: python
+
+       import proto
+       from multiprocessing import Pool
+
+       class Composer(proto.Message):
+          name = proto.Field(proto.STRING, number=1)
+          genre = proto.Field(proto.STRING, number=2)
+
+       composers = [Composer(name=n) for n in ["Bach", "Mozart", "Brahms", "Strauss"]]
+
+       with multiprocessing.Pool(2) as p:
+          def add_genre(comp_bytes):
+              composer = Composer.deserialize(comp_bytes)
+              composer.genre = "classical"
+              return Composer.serialize(composer)
+
+       updated_composers = [
+          Composer.deserialize(comp_bytes)
+          for comp_bytes in p.map(add_genre, (Composer.serialize(comp) for comp in composers))
+       ]
diff --git a/noxfile.py b/noxfile.py
@@ -59,7 +59,7 @@ def unitcpp(session):
     return unit(session, proto="cpp")
 
 
-@nox.session(python="3.7")
+@nox.session(python="3.9")
 def docs(session):
     """Build the docs."""
 
