@@ -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+
12121225static PyObject *
12131226marshal_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+
12461272static PyObject *
12471273marshal_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+
12561292static PyObject *
12571293marshal_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+
12791322static 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+
12871361static 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-
13011373PyMODINIT_FUNC
13021374PyMarshal_Init (void )
13031375{
0 commit comments