bpo-29746: Update marshal docs to Python 3. (#547) (#630)

(cherry picked from commit c611a5b)

Author: serhiy-storchaka

Doc/c-api/marshal.rst

@@ -34,7 +34,7 @@ unmarshalling.  Version 2 uses a binary format for floating point numbers.
 
 .. c:function:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
 
-   Return a string object containing the marshalled representation of *value*.
+   Return a bytes object containing the marshalled representation of *value*.
    *version* indicates the file format.
 
 
@@ -88,10 +88,10 @@ written using these routines?
    :exc:`TypeError`) and returns *NULL*.
 
 
-.. c:function:: PyObject* PyMarshal_ReadObjectFromString(const char *string, Py_ssize_t len)
+.. c:function:: PyObject* PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)
 
-   Return a Python object from the data stream in a character buffer
-   containing *len* bytes pointed to by *string*.
+   Return a Python object from the data stream in a byte buffer
+   containing *len* bytes pointed to by *data*.
 
    On error, sets the appropriate exception (:exc:`EOFError` or
    :exc:`TypeError`) and returns *NULL*.

Doc/glossary.rst

@@ -103,6 +103,10 @@ Glossary
    binary file
       A :term:`file object` able to read and write
       :term:`bytes-like objects <bytes-like object>`.
+      Examples of binary files are files opened in binary mode (``'rb'``,
+      ``'wb'`` or ``'rb+'``), :data:`sys.stdin.buffer`,
+      :data:`sys.stdout.buffer`, and instances of :class:`io.BytesIO` and
+      :class:`gzip.GzipFile`.
 
       .. seealso::
          A :term:`text file` reads and writes :class:`str` objects.
@@ -926,6 +930,9 @@ Glossary
       A :term:`file object` able to read and write :class:`str` objects.
       Often, a text file actually accesses a byte-oriented datastream
       and handles the :term:`text encoding` automatically.
+      Examples of text files are files opened in text mode (``'r'`` or ``'w'``),
+      :data:`sys.stdin`, :data:`sys.stdout`, and instances of
+      :class:`io.StringIO`.
 
       .. seealso::
          A :term:`binary file` reads and write :class:`bytes` objects.

Doc/library/marshal.rst

@@ -49,17 +49,15 @@ For format *version* lower than 3, recursive lists, sets and dictionaries cannot
 be written (see below).
 
 There are functions that read/write files as well as functions operating on
-strings.
+bytes-like objects.
 
 The module defines these functions:
 
 
 .. function:: dump(value, file[, version])
 
    Write the value on the open file.  The value must be a supported type.  The
-   file must be an open file object such as ``sys.stdout`` or returned by
-   :func:`open` or :func:`os.popen`.  It must be opened in binary mode (``'wb'``
-   or ``'w+b'``).
+   file must be a writeable :term:`binary file`.
 
    If the value has (or contains an object that has) an unsupported type, a
    :exc:`ValueError` exception is raised --- but garbage data will also be written
@@ -74,8 +72,7 @@ The module defines these functions:
    Read one value from the open file and return it.  If no valid value is read
    (e.g. because the data has a different Python version's incompatible marshal
    format), raise :exc:`EOFError`, :exc:`ValueError` or :exc:`TypeError`.  The
-   file must be an open file object opened in binary mode (``'rb'`` or
-   ``'r+b'``).
+   file must be a readable :term:`binary file`.
 
    .. note::
 
@@ -85,19 +82,19 @@ The module defines these functions:
 
 .. function:: dumps(value[, version])
 
-   Return the string that would be written to a file by ``dump(value, file)``.  The
+   Return the bytes object that would be written to a file by ``dump(value, file)``.  The
    value must be a supported type.  Raise a :exc:`ValueError` exception if value
    has (or contains an object that has) an unsupported type.
 
    The *version* argument indicates the data format that ``dumps`` should use
    (see below).
 
 
-.. function:: loads(string)
+.. function:: loads(bytes)
 
-   Convert the string to a value.  If no valid value is found, raise
-   :exc:`EOFError`, :exc:`ValueError` or :exc:`TypeError`.  Extra characters in the
-   string are ignored.
+   Convert the :term:`bytes-like object` to a value.  If no valid value is found, raise
+   :exc:`EOFError`, :exc:`ValueError` or :exc:`TypeError`.  Extra bytes in the
+   input are ignored.
 
 
 In addition, the following constants are defined:

Python/marshal.c

@@ -549,7 +549,7 @@ w_complex_object(PyObject *v, char flag, WFILE *p)
         w_object(co->co_lnotab, p);
     }
     else if (PyObject_CheckBuffer(v)) {
-        /* Write unknown bytes-like objects as a byte string */
+        /* Write unknown bytes-like objects as a bytes object */
         Py_buffer view;
         if (PyObject_GetBuffer(v, &view, PyBUF_SIMPLE) != 0) {
             w_byte(TYPE_UNKNOWN, p);
@@ -1079,7 +1079,7 @@ r_object(RFILE *p)
             if (PyErr_Occurred())
                 break;
             if (n < 0 || n > SIZE32_MAX) {
-                PyErr_SetString(PyExc_ValueError, "bad marshal data (string size out of range)");
+                PyErr_SetString(PyExc_ValueError, "bad marshal data (bytes object size out of range)");
                 break;
             }
             v = PyBytes_FromStringAndSize((char *)NULL, n);
@@ -1103,7 +1103,7 @@ r_object(RFILE *p)
         if (PyErr_Occurred())
             break;
         if (n < 0 || n > SIZE32_MAX) {
-            PyErr_SetString(PyExc_ValueError, "bad marshal data (unicode size out of range)");
+            PyErr_SetString(PyExc_ValueError, "bad marshal data (string size out of range)");
             break;
         }
         goto _read_ascii;
@@ -1143,7 +1143,7 @@ r_object(RFILE *p)
         if (PyErr_Occurred())
             break;
         if (n < 0 || n > SIZE32_MAX) {
-            PyErr_SetString(PyExc_ValueError, "bad marshal data (unicode size out of range)");
+            PyErr_SetString(PyExc_ValueError, "bad marshal data (string size out of range)");
             break;
         }
         if (n != 0) {
@@ -1594,7 +1594,7 @@ PyMarshal_WriteObjectToString(PyObject *x, int version)
         if (wf.ptr - base > PY_SSIZE_T_MAX) {
             Py_DECREF(wf.str);
             PyErr_SetString(PyExc_OverflowError,
-                            "too much marshal data for a string");
+                            "too much marshal data for a bytes object");
             return NULL;
         }
         if (_PyBytes_Resize(&wf.str, (Py_ssize_t)(wf.ptr - base)) < 0)
@@ -1640,8 +1640,7 @@ PyDoc_STRVAR(dump_doc,
 "dump(value, file[, version])\n\
 \n\
 Write the value on the open file. The value must be a supported type.\n\
-The file must be an open file object such as sys.stdout or returned by\n\
-open() or os.popen(). It must be opened in binary mode ('wb' or 'w+b').\n\
+The file must be a writeable binary file.\n\
 \n\
 If the value has (or contains an object that has) an unsupported type, a\n\
 ValueError exception is raised - but garbage data will also be written\n\
@@ -1697,8 +1696,7 @@ PyDoc_STRVAR(load_doc,
 Read one value from the open file and return it. If no valid value is\n\
 read (e.g. because the data has a different Python version's\n\
 incompatible marshal format), raise EOFError, ValueError or TypeError.\n\
-The file must be an open file object opened in binary mode ('rb' or\n\
-'r+b').\n\
+The file must be a readable binary file.\n\
 \n\
 Note: If an object containing an unsupported type was marshalled with\n\
 dump(), load() will substitute None for the unmarshallable type.");
@@ -1717,7 +1715,7 @@ marshal_dumps(PyObject *self, PyObject *args)
 PyDoc_STRVAR(dumps_doc,
 "dumps(value[, version])\n\
 \n\
-Return the string that would be written to a file by dump(value, file).\n\
+Return the bytes object that would be written to a file by dump(value, file).\n\
 The value must be a supported type. Raise a ValueError exception if\n\
 value has (or contains an object that has) an unsupported type.\n\
 \n\
@@ -1753,8 +1751,8 @@ marshal_loads(PyObject *self, PyObject *args)
 PyDoc_STRVAR(loads_doc,
 "loads(bytes)\n\
 \n\
-Convert the bytes object to a value. If no valid value is found, raise\n\
-EOFError, ValueError or TypeError. Extra characters in the input are\n\
+Convert the bytes-like object to a value. If no valid value is found,\n\
+raise EOFError, ValueError or TypeError. Extra bytes in the input are\n\
 ignored.");
 
 static PyMethodDef marshal_methods[] = {
@@ -1792,8 +1790,8 @@ Functions:\n\
 \n\
 dump() -- write value to a file\n\
 load() -- read value from a file\n\
-dumps() -- write value to a string\n\
-loads() -- read value from a string");
+dumps() -- marshal value as a bytes object\n\
+loads() -- read value from a bytes-like object");