Skip to content

Commit dd226ea

Browse files
committed
Merged revisions 72597 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk ........ r72597 | r.david.murray | 2009-05-12 20:30:29 -0400 (Tue, 12 May 2009) | 2 lines Issue 5994: add docstrings to marshal. ........
1 parent 976faf9 commit dd226ea

2 files changed

Lines changed: 81 additions & 7 deletions

File tree

‎Misc/NEWS‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ What's New in Python 3.1 release candidate 1?
1212
Core and Builtins
1313
-----------------
1414

15+
- Issue #5994: the marshal module now has docstrings.
16+
1517
- Issue #5981: Fix three minor inf/nan issues in float.fromhex:
1618
(1) inf and nan strings with trailing whitespace were incorrectly
1719
rejected; (2) parsing of strings representing infinities and nans

‎Python/marshal.c‎

Lines changed: 79 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1209,6 +1209,19 @@ marshal_dump(PyObject *self, PyObject *args)
12091209
return res;
12101210
}
12111211

1212+
PyDoc_STRVAR(dump_doc,
1213+
"dump(value, file[, version])\n\
1214+
\n\
1215+
Write the value on the open file. The value must be a supported type.\n\
1216+
The file must be an open file object such as sys.stdout or returned by\n\
1217+
open() or os.popen(). It must be opened in binary mode ('wb' or 'w+b').\n\
1218+
\n\
1219+
If the value has (or contains an object that has) an unsupported type, a\n\
1220+
ValueError exception is raised — but garbage data will also be written\n\
1221+
to the file. The object will not be properly read back by load()\n\
1222+
\n\
1223+
The version argument indicates the data format that dump should use.");
1224+
12121225
static PyObject *
12131226
marshal_load(PyObject *self, PyObject *f)
12141227
{
@@ -1243,6 +1256,19 @@ marshal_load(PyObject *self, PyObject *f)
12431256
return result;
12441257
}
12451258

1259+
PyDoc_STRVAR(load_doc,
1260+
"load(file)\n\
1261+
\n\
1262+
Read one value from the open file and return it. If no valid value is\n\
1263+
read (e.g. because the data has a different Python version’s\n\
1264+
incompatible marshal format), raise EOFError, ValueError or TypeError.\n\
1265+
The file must be an open file object opened in binary mode ('rb' or\n\
1266+
'r+b').\n\
1267+
\n\
1268+
Note: If an object containing an unsupported type was marshalled with\n\
1269+
dump(), load() will substitute None for the unmarshallable type.");
1270+
1271+
12461272
static PyObject *
12471273
marshal_dumps(PyObject *self, PyObject *args)
12481274
{
@@ -1253,6 +1279,16 @@ marshal_dumps(PyObject *self, PyObject *args)
12531279
return PyMarshal_WriteObjectToString(x, version);
12541280
}
12551281

1282+
PyDoc_STRVAR(dumps_doc,
1283+
"dumps(value[, version])\n\
1284+
\n\
1285+
Return the string that would be written to a file by dump(value, file).\n\
1286+
The value must be a supported type. Raise a ValueError exception if\n\
1287+
value has (or contains an object that has) an unsupported type.\n\
1288+
\n\
1289+
The version argument indicates the data format that dumps should use.");
1290+
1291+
12561292
static PyObject *
12571293
marshal_loads(PyObject *self, PyObject *args)
12581294
{
@@ -1276,18 +1312,56 @@ marshal_loads(PyObject *self, PyObject *args)
12761312
return result;
12771313
}
12781314

1315+
PyDoc_STRVAR(loads_doc,
1316+
"loads(string)\n\
1317+
\n\
1318+
Convert the string to a value. If no valid value is found, raise\n\
1319+
EOFError, ValueError or TypeError. Extra characters in the string are\n\
1320+
ignored.");
1321+
12791322
static PyMethodDef marshal_methods[] = {
1280-
{"dump", marshal_dump, METH_VARARGS},
1281-
{"load", marshal_load, METH_O},
1282-
{"dumps", marshal_dumps, METH_VARARGS},
1283-
{"loads", marshal_loads, METH_VARARGS},
1323+
{"dump", marshal_dump, METH_VARARGS, dump_doc},
1324+
{"load", marshal_load, METH_O, load_doc},
1325+
{"dumps", marshal_dumps, METH_VARARGS, dumps_doc},
1326+
{"loads", marshal_loads, METH_VARARGS, loads_doc},
12841327
{NULL, NULL} /* sentinel */
12851328
};
12861329

1330+
1331+
PyDoc_STRVAR(module_doc,
1332+
"This module contains functions that can read and write Python values in\n\
1333+
a binary format. The format is specific to Python, but independent of\n\
1334+
machine architecture issues.\n\
1335+
\n\
1336+
Not all Python object types are supported; in general, only objects\n\
1337+
whose value is independent from a particular invocation of Python can be\n\
1338+
written and read by this module. The following types are supported:\n\
1339+
None, integers, floating point numbers, strings, bytes, bytearrays,\n\
1340+
tuples, lists, sets, dictionaries, and code objects, where it\n\
1341+
should be understood that tuples, lists and dictionaries are only\n\
1342+
supported as long as the values contained therein are themselves\n\
1343+
supported; and recursive lists and dictionaries should not be written\n\
1344+
(they will cause infinite loops).\n\
1345+
\n\
1346+
Variables:\n\
1347+
\n\
1348+
version -- indicates the format that the module uses. Version 0 is the\n\
1349+
historical format, version 1 shares interned strings and version 2\n\
1350+
uses a binary format for floating point numbers.\n\
1351+
\n\
1352+
Functions:\n\
1353+
\n\
1354+
dump() -- write value to a file\n\
1355+
load() -- read value from a file\n\
1356+
dumps() -- write value to a string\n\
1357+
loads() -- read value from a string");
1358+
1359+
1360+
12871361
static struct PyModuleDef marshalmodule = {
12881362
PyModuleDef_HEAD_INIT,
12891363
"marshal",
1290-
NULL,
1364+
module_doc,
12911365
0,
12921366
marshal_methods,
12931367
NULL,
@@ -1296,8 +1370,6 @@ static struct PyModuleDef marshalmodule = {
12961370
NULL
12971371
};
12981372

1299-
1300-
13011373
PyMODINIT_FUNC
13021374
PyMarshal_Init(void)
13031375
{

0 commit comments

Comments
 (0)