[Python-checkins] r72600 - in python/branches/release30-maint: Misc/NEWS Python/marshal.c

[r.david.murray]

Author: r.david.murray
Date: Wed May 13 14:53:18 2009
New Revision: 72600

Log:
Merged revisions 72599 via svnmerge from 
svn+ssh://pythondev@svn.python.org/python/branches/py3k

................
  r72599 | r.david.murray | 2009-05-13 08:27:21 -0400 (Wed, 13 May 2009) | 9 lines
  
  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.
  ........
................


Modified:
   python/branches/release30-maint/   (props changed)
   python/branches/release30-maint/Misc/NEWS
   python/branches/release30-maint/Python/marshal.c

Modified: python/branches/release30-maint/Misc/NEWS
==============================================================================
--- python/branches/release30-maint/Misc/NEWS	(original)
+++ python/branches/release30-maint/Misc/NEWS	Wed May 13 14:53:18 2009
@@ -12,6 +12,8 @@
 Core and Builtins
 -----------------
 
+- Issue #5994: the marshal module now has docstrings.
+
 - Issue #5981: Fix two minor inf/nan issues in float.fromhex: (1) inf
   and nan strings with trailing whitespace were incorrectly rejected
   and (2) the interpretation of fromhex('-nan') didn't match that of

Modified: python/branches/release30-maint/Python/marshal.c
==============================================================================
--- python/branches/release30-maint/Python/marshal.c	(original)
+++ python/branches/release30-maint/Python/marshal.c	Wed May 13 14:53:18 2009
@@ -1120,6 +1120,19 @@
 	return res;
 }
 
+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\
+\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\
+to the file. The object will not be properly read back by load()\n\
+\n\
+The version argument indicates the data format that dump should use.");
+
 static PyObject *
 marshal_load(PyObject *self, PyObject *f)
 {
@@ -1154,6 +1167,19 @@
 	return result;
 }
 
+PyDoc_STRVAR(load_doc,
+"load(file)\n\
+\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\
+\n\
+Note: If an object containing an unsupported type was marshalled with\n\
+dump(), load() will substitute None for the unmarshallable type.");
+
+
 static PyObject *
 marshal_dumps(PyObject *self, PyObject *args)
 {
@@ -1164,6 +1190,16 @@
 	return PyMarshal_WriteObjectToString(x, version);
 }
 
+PyDoc_STRVAR(dumps_doc,
+"dumps(value[, version])\n\
+\n\
+Return the string 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\
+The version argument indicates the data format that dumps should use.");
+
+
 static PyObject *
 marshal_loads(PyObject *self, PyObject *args)
 {
@@ -1187,18 +1223,56 @@
 	return result;
 }
 
+PyDoc_STRVAR(loads_doc,
+"loads(string)\n\
+\n\
+Convert the string to a value. If no valid value is found, raise\n\
+EOFError, ValueError or TypeError. Extra characters in the string are\n\
+ignored.");
+
 static PyMethodDef marshal_methods[] = {
-	{"dump",	marshal_dump,	METH_VARARGS},
-	{"load",	marshal_load,	METH_O},
-	{"dumps",	marshal_dumps,	METH_VARARGS},
-	{"loads",	marshal_loads,	METH_VARARGS},
+	{"dump",	marshal_dump,	METH_VARARGS,	dump_doc},
+	{"load",	marshal_load,	METH_O,		load_doc},
+	{"dumps",	marshal_dumps,	METH_VARARGS,	dumps_doc},
+	{"loads",	marshal_loads,	METH_VARARGS,	loads_doc},
 	{NULL,		NULL}		/* sentinel */
 };
 
+
+PyDoc_STRVAR(module_doc,
+"This module contains functions that can read and write Python values in\n\
+a binary format. The format is specific to Python, but independent of\n\
+machine architecture issues.\n\
+\n\
+Not all Python object types are supported; in general, only objects\n\
+whose value is independent from a particular invocation of Python can be\n\
+written and read by this module. The following types are supported:\n\
+None, integers, floating point numbers, strings, bytes, bytearrays,\n\
+tuples, lists, sets, dictionaries, and code objects, where it\n\
+should be understood that tuples, lists and dictionaries are only\n\
+supported as long as the values contained therein are themselves\n\
+supported; and recursive lists and dictionaries should not be written\n\
+(they will cause infinite loops).\n\
+\n\
+Variables:\n\
+\n\
+version -- indicates the format that the module uses. Version 0 is the\n\
+    historical format, version 1 shares interned strings and version 2\n\
+    uses a binary format for floating point numbers.\n\
+\n\
+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");
+
+
+
 static struct PyModuleDef marshalmodule = {
 	PyModuleDef_HEAD_INIT,
 	"marshal",
-	NULL,
+	module_doc,
 	0,
 	marshal_methods,
 	NULL,
@@ -1207,8 +1281,6 @@
 	NULL
 };
 
-
-
 PyMODINIT_FUNC
 PyMarshal_Init(void)
 {