From: Guido van Rossum <guido@python.org>
Date: Mon, 27 Jan 2003 22:47:53 +0000 (+0000)
Subject: Begin the change from 'binary vs. text mode' to 'protocol 0, 1, 2'.
X-Git-Tag: v2.3c1~2276
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=f29d3d6011e41b40282994375454f2020a429d79;p=python

Begin the change from 'binary vs. text mode' to 'protocol 0, 1, 2'.
The protocol now defaults to 1.  Protocol 2 is still unimplemented.
---

diff --git a/Lib/pickle.py b/Lib/pickle.py
index 79ee8af445..9352283734 100644
--- a/Lib/pickle.py
+++ b/Lib/pickle.py
@@ -36,8 +36,14 @@ import re
 __all__ = ["PickleError", "PicklingError", "UnpicklingError", "Pickler",
            "Unpickler", "dump", "dumps", "load", "loads"]
 
-format_version = "1.3"                     # File format version we write
-compatible_formats = ["1.0", "1.1", "1.2"] # Old format versions we can read
+# These are purely informational; no code usues these
+format_version = "2.0"                  # File format version we write
+compatible_formats = ["1.0",            # Original protocol 0
+                      "1.1",            # Protocol 0 with class supprt added
+                      "1.2",            # Original protocol 1
+                      "1.3",            # Protocol 1 with BINFLOAT added
+                      "2.0",            # Protocol 2
+                      ]                 # Old format versions we can read
 
 mdumps = marshal.dumps
 mloads = marshal.loads
@@ -151,12 +157,18 @@ _quotes = ["'", '"']
 
 class Pickler:
 
-    def __init__(self, file, bin = 0):
+    def __init__(self, file, proto=1):
         """This takes a file-like object for writing a pickle data stream.
 
-        The optional bin parameter if true, tells the pickler to use the more
-        efficient binary pickle format, otherwise the ASCII format is used
-        (this is the default).
+        The optional proto argument tells the pickler to use the given
+        protocol; supported protocols are 0, 1, 2.  The default
+        protocol is 1 (in previous Python versions the default was 0).
+
+        Protocol 1 is more efficient than protocol 0; protocol 2 is
+        more efficient than protocol 1.  Protocol 2 is not the default
+        because it is not supported by older Python versions.
+
+        XXX Protocol 2 is not yet implemented.
 
         The file parameter must have a write() method that accepts a single
         string argument.  It can thus be an open file object, a StringIO
@@ -165,7 +177,8 @@ class Pickler:
         """
         self.write = file.write
         self.memo = {}
-        self.bin = bin
+        self.proto = proto
+        self.bin = proto >= 1
 
     def clear_memo(self):
         """Clears the pickler's "memo".
@@ -1070,12 +1083,12 @@ try:
 except ImportError:
     from StringIO import StringIO
 
-def dump(object, file, bin = 0):
-    Pickler(file, bin).dump(object)
+def dump(object, file, proto=1):
+    Pickler(file, proto).dump(object)
 
-def dumps(object, bin = 0):
+def dumps(object, proto=1):
     file = StringIO()
-    Pickler(file, bin).dump(object)
+    Pickler(file, proto).dump(object)
     return file.getvalue()
 
 def load(file):
diff --git a/Lib/pickletools.py b/Lib/pickletools.py
index 59e0a15202..5c0367be0f 100644
--- a/Lib/pickletools.py
+++ b/Lib/pickletools.py
@@ -1902,7 +1902,7 @@ def dis(pickle, out=None, indentlevel=4):
 _dis_test = """
 >>> import pickle
 >>> x = [1, 2, (3, 4), {'abc': u"def"}]
->>> pik = pickle.dumps(x)
+>>> pik = pickle.dumps(x, 0)
 >>> dis(pik)
     0: ( MARK
     1: l     LIST       (MARK at 0)
@@ -1955,13 +1955,13 @@ Try again with a "binary" pickle.
 Exercise the INST/OBJ/BUILD family.
 
 >>> import random
->>> dis(pickle.dumps(random.random))
+>>> dis(pickle.dumps(random.random, 0))
     0: c GLOBAL     'random random'
    15: p PUT        0
    18: . STOP
 
 >>> x = [pickle.PicklingError()] * 2
->>> dis(pickle.dumps(x))
+>>> dis(pickle.dumps(x, 0))
     0: ( MARK
     1: l     LIST       (MARK at 0)
     2: p PUT        0
@@ -2016,7 +2016,7 @@ True
 True
 >>> T[0][0] is T
 True
->>> dis(pickle.dumps(L))
+>>> dis(pickle.dumps(L, 0))
     0: ( MARK
     1: l     LIST       (MARK at 0)
     2: p PUT        0
@@ -2043,7 +2043,7 @@ doesn't trigger this glitch, because the disassembler realizes that
 POP_MARK gets rid of the MARK.  Doing a better job on the protocol 0
 pickle would require the disassembler to emulate the stack.
 
->>> dis(pickle.dumps(T))
+>>> dis(pickle.dumps(T, 0))
     0: ( MARK
     1: (     MARK
     2: l         LIST       (MARK at 1)