Issue #14783: Merge changes from 3.2.

cjerdonek · cjerdonek · commit 042fa653ab91 · 2012-10-07T14:56:27.000-07:00
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
@@ -1203,7 +1203,8 @@ are always available.  They are listed here in alphabetical order.
 
 
 .. _func-str:
-.. function:: str([object[, encoding[, errors]]])
+.. function:: str(object='')
+              str(object[, encoding[, errors]])
 
    Return a string version of an object, using one of the following modes:
 
diff --git a/Misc/NEWS b/Misc/NEWS
@@ -12,6 +12,9 @@ What's New in Python 3.3.1?
 Core and Builtins
 -----------------
 
+- Issue #14783: Improve int() docstring and switch docstrings for str(),
+  range(), and slice() to use multi-line signatures.
+
 - Issue #15379: Fix passing of non-BMP characters as integers for the charmap
   decoder (already working as unicode strings).  Patch by Serhiy Storchaka.
 
diff --git a/Objects/longobject.c b/Objects/longobject.c
@@ -4848,13 +4848,20 @@ static PyGetSetDef long_getset[] = {
 };
 
 PyDoc_STRVAR(long_doc,
-"int(x[, base]) -> integer\n\
+"int(x=0) -> integer\n\
+int(x, base=10) -> integer\n\
 \n\
-Convert a string or number to an integer, if possible.  A floating\n\
-point argument will be truncated towards zero (this does not include a\n\
-string representation of a floating point number!)  When converting a\n\
-string, use the optional base.  It is an error to supply a base when\n\
-converting a non-string.");
+Convert a number or string to an integer, or return 0 if no arguments\n\
+are given.  If x is a number, return x.__int__().  For floating point\n\
+numbers, this truncates towards zero.\n\
+\n\
+If x is not a number or if base is given, then x must be a string,\n\
+bytes, or bytearray instance representing an integer literal in the\n\
+given base.  The literal can be preceded by '+' or '-' and be surrounded\n\
+by whitespace.  The base defaults to 10.  Valid bases are 0 and 2-36.\n\
+Base 0 means to interpret the base from the string as an integer literal.\n\
+>>> int('0b100', base=0)\n\
+4");
 
 static PyNumberMethods long_as_number = {
     (binaryfunc)long_add,       /*nb_add*/
diff --git a/Objects/rangeobject.c b/Objects/rangeobject.c
@@ -136,7 +136,8 @@ range_new(PyTypeObject *type, PyObject *args, PyObject *kw)
 }
 
 PyDoc_STRVAR(range_doc,
-"range([start,] stop[, step]) -> range object\n\
+"range(stop) -> range object\n\
+range(start, stop[, step]) -> range object\n\
 \n\
 Returns a virtual sequence of numbers from start to stop by step.");
 
@@ -969,7 +970,7 @@ rangeiter_reduce(rangeiterobject *r)
 {
     PyObject *start=NULL, *stop=NULL, *step=NULL;
     PyObject *range;
-    
+
     /* create a range object for pickling */
     start = PyLong_FromLong(r->start);
     if (start == NULL)
diff --git a/Objects/sliceobject.c b/Objects/sliceobject.c
@@ -269,7 +269,8 @@ slice_new(PyTypeObject *type, PyObject *args, PyObject *kw)
 }
 
 PyDoc_STRVAR(slice_doc,
-"slice([start,] stop[, step])\n\
+"slice(stop)\n\
+slice(start, stop[, step])\n\
 \n\
 Create a slice object.  This is used for extended slicing (e.g. a[0:10:2]).");
 
diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c
@@ -14074,7 +14074,8 @@ unicode_subtype_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
 }
 
 PyDoc_STRVAR(unicode_doc,
-             "str(object[, encoding[, errors]]) -> str\n\
+"str(object='') -> str\n\
+str(bytes_or_buffer[, encoding[, errors]]) -> str\n\
 \n\
 Create a new string object from the given object. If encoding or\n\
 errors is specified, then the object must expose a data buffer\n\

Original file line number	Diff line number	Diff line change
`@@ -269,7 +269,8 @@ slice_new(PyTypeObject type, PyObject args, PyObject *kw)`
`269`	`269`	`}`
`270`	`270`
`271`	`271`	`PyDoc_STRVAR(slice_doc,`
`272`		`-"slice([start,] stop[, step])\n\`
	`272`	`+"slice(stop)\n\`
	`273`	`+slice(start, stop[, step])\n\`
`273`	`274`	`\n\`
`274`	`275`	`Create a slice object. This is used for extended slicing (e.g. a[0:10:2]).");`
`275`	`276`
Original file line number	Diff line number	Diff line change
`@@ -14074,7 +14074,8 @@ unicode_subtype_new(PyTypeObject type, PyObject args, PyObject *kwds)`
`14074`	`14074`	`}`
`14075`	`14075`
`14076`	`14076`	`PyDoc_STRVAR(unicode_doc,`
`14077`		`- "str(object[, encoding[, errors]]) -> str\n\`
	`14077`	`+"str(object='') -> str\n\`
	`14078`	`+str(bytes_or_buffer[, encoding[, errors]]) -> str\n\`
`14078`	`14079`	`\n\`
`14079`	`14080`	`Create a new string object from the given object. If encoding or\n\`
`14080`	`14081`	`errors is specified, then the object must expose a data buffer\n\`