Warn about future use_bin_type change (#264)

README.rst

@@ -60,7 +60,7 @@ msgpack provides ``dumps`` and ``loads`` as an alias for compatibility with
 .. code-block:: pycon
 
    >>> import msgpack
-   >>> msgpack.packb([1, 2, 3])
+   >>> msgpack.packb([1, 2, 3], use_bin_type=True)
    '\x93\x01\x02\x03'
    >>> msgpack.unpackb(_)
    [1, 2, 3]
@@ -91,13 +91,13 @@ stream (or from bytes provided through its ``feed`` method).
 
    buf = BytesIO()
    for i in range(100):
-      buf.write(msgpack.packb(range(i)))
+      buf.write(msgpack.packb(range(i), use_bin_type=True))
 
    buf.seek(0)
 
    unpacker = msgpack.Unpacker(buf)
    for unpacked in unpacker:
-       print unpacked
+       print(unpacked)
 
 
 Packing/unpacking of custom data type
@@ -109,7 +109,6 @@ It is also possible to pack/unpack custom data types. Here is an example for
 .. code-block:: python
 
     import datetime
-
     import msgpack
 
     useful_dict = {
@@ -128,7 +127,7 @@ It is also possible to pack/unpack custom data types. Here is an example for
         return obj
 
 
-    packed_dict = msgpack.packb(useful_dict, default=encode_datetime)
+    packed_dict = msgpack.packb(useful_dict, default=encode_datetime, use_bin_type=True)
     this_dict_again = msgpack.unpackb(packed_dict, object_hook=decode_datetime)
 
 ``Unpacker``'s ``object_hook`` callback receives a dict; the
@@ -208,6 +207,10 @@ the packer. If you do so, it will use a non-standard type called **bin** to
 serialize byte arrays, and **raw** becomes to mean **str**. If you want to
 distinguish **bin** and **raw** in the unpacker, specify `encoding='utf-8'`.
 
+**In future version, default value of ``use_bin_type`` will be changed to ``False``.
+To avoid this change will break your code, you must specify it explicitly
+even when you want to use old format.**
+
 Note that Python 2 defaults to byte-arrays over Unicode strings:
 
 .. code-block:: pycon

msgpack/_packer.pyx

@@ -2,6 +2,7 @@
 #cython: embedsignature=True
 
 from cpython cimport *
+from cpython.exc cimport PyErr_WarnEx
 
 from msgpack.exceptions import PackValueError, PackOverflowError
 from msgpack import ExtType
@@ -76,6 +77,8 @@ cdef class Packer(object):
     :param bool use_bin_type:
         Use bin type introduced in msgpack spec 2.0 for bytes.
         It also enables str8 type for unicode.
+        Current default value is false, but it will be changed to true
+        in future version.  You should specify it explicitly.
     :param bool strict_types:
         If set to true, types will be checked to be exact. Derived classes
         from serializeable types will not be serialized and will be
@@ -103,12 +106,17 @@ cdef class Packer(object):
         self.pk.length = 0
 
     def __init__(self, default=None, encoding='utf-8', unicode_errors='strict',
-                 use_single_float=False, bint autoreset=1, bint use_bin_type=0,
+                 use_single_float=False, bint autoreset=1, use_bin_type=None,
                  bint strict_types=0):
+        if use_bin_type is None:
+            PyErr_WarnEx(
+                FutureWarning,
+                "use_bin_type option is not specified. Default value of the option will be changed in future version.",
+                1)
         self.use_float = use_single_float
         self.strict_types = strict_types
         self.autoreset = autoreset
-        self.pk.use_bin_type = use_bin_type
+        self.pk.use_bin_type = <bint>use_bin_type
         if default is not None:
             if not PyCallable_Check(default):
                 raise TypeError("default must be a callable.")