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

3 files changed, 19 insertions, 15 deletions

diff --git a/Doc/c-api/marshal.rst b/Doc/c-api/marshal.rst
index a6d0f46..c6d1d02 100644
--- a/Doc/c-api/marshal.rst
+++ b/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*.
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index e07ab0d..495934a 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -131,6 +131,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.
@@ -966,6 +970,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.
diff --git a/Doc/library/marshal.rst b/Doc/library/marshal.rst
index 1ffc6ef..d65afc2 100644
--- a/Doc/library/marshal.rst
+++ b/Doc/library/marshal.rst
@@ -49,7 +49,7 @@ 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:
 
@@ -57,9 +57,7 @@ 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,7 +82,7 @@ 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.
 
@@ -93,11 +90,11 @@ The module defines these functions:
    (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: