.. 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.
: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*.
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.
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.
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
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::
.. 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.
(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:
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);
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);
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;
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) {
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)
"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\
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.");
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\
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[] = {
\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");
projects / python / commitdiff