Issue #14783: Backport changes from 3.2.

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 200c714cbf150d4e9b875667f39724670ee45511..0314ca5b13fa8ef318c3f0d67b70f586b78696c2 100644 (file)
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -733,7 +733,8 @@ available.  They are listed here in alphabetical order.
       affect the values of local and free variables used by the interpreter.
 
 
-.. function:: long([x[, base]])
+.. function:: long(x=0)
+              long(x, base=10)
 
    Convert a string or number to a long integer.  If the argument is a string, it
    must contain a possibly signed number of arbitrary size, possibly embedded in
@@ -1318,7 +1319,7 @@ available.  They are listed here in alphabetical order.
       Function decorator syntax added.
 
 
-.. function:: str([object])
+.. function:: str(object='')
 
    Return a string containing a nicely printable representation of an object.  For
    strings, this returns the string itself.  The difference with ``repr(object)``
@@ -1463,7 +1464,8 @@ available.  They are listed here in alphabetical order.
    .. versionadded:: 2.0
 
 
-.. function:: unicode([object[, encoding [, errors]]])
+.. function:: unicode(object='')
+              unicode(object[, encoding [, errors]])
 
    Return the Unicode string version of *object* using one of the following modes:
 

diff --git a/Misc/NEWS b/Misc/NEWS
index 36033eab00d73c838d8295364d55530ed5e245cb..a52a71f96a7a9ab8addf295f7bbe37290f70f4e6 100644 (file)
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -9,6 +9,9 @@ What's New in Python 2.7.4
 Core and Builtins
 -----------------
 
+- Issue #14783: Improve int() and long() docstrings and switch docstrings for
+  unicode(), slice(), range(), and xrange() to use multi-line signatures.
+
 - Issue #16030: Fix overflow bug in computing the `repr` of an xrange object
   with large start, step or length.
 

diff --git a/Objects/intobject.c b/Objects/intobject.c
index e518e74bbb14e6f6bbe92f6cdcefbf9e71f73648..74955adbeffb26ea3cbd3bbc4aff778e098e1128 100644 (file)
--- a/Objects/intobject.c
+++ b/Objects/intobject.c
@@ -1334,15 +1334,20 @@ static PyGetSetDef int_getset[] = {
 };
 
 PyDoc_STRVAR(int_doc,
-"int(x[, base]) -> integer\n\
+"int(x=0) -> int or long\n\
+int(x, base=10) -> int or long\n\
 \n\
-Convert a string or number to an integer, if possible.  A floating point\n\
-argument will be truncated towards zero (this does not include a string\n\
-representation of a floating point number!)  When converting a string, use\n\
-the optional base.  It is an error to supply a base when converting a\n\
-non-string.  If base is zero, the proper base is guessed based on the\n\
-string content.  If the argument is outside the integer range a\n\
-long object will be returned instead.");
+Convert a number or string to an integer, or return 0 if no arguments\n\
+are given.  If x is floating point, the conversion truncates towards zero.\n\
+If x is outside the integer range, the function returns a long instead.\n\
+\n\
+If x is not a number or if base is given, then x must be a string or\n\
+Unicode object representing an integer literal in the given base.  The\n\
+literal can be preceded by '+' or '-' and be surrounded by whitespace.\n\
+The base defaults to 10.  Valid bases are 0 and 2-36.  Base 0 means to\n\
+interpret the base from the string as an integer literal.\n\
+>>> int('0b100', base=0)\n\
+4");
 
 static PyNumberMethods int_as_number = {
     (binaryfunc)int_add,        /*nb_add*/

diff --git a/Objects/longobject.c b/Objects/longobject.c
index cd86a1f9fe6305097afa66794fe1764783d382a2..9296ad49b1c89901d8c15a2133aafd9aa3051b9c 100644 (file)
--- a/Objects/longobject.c
+++ b/Objects/longobject.c
@@ -4221,13 +4221,19 @@ static PyGetSetDef long_getset[] = {
 };
 
 PyDoc_STRVAR(long_doc,
-"long(x[, base]) -> integer\n\
+"long(x=0) -> long\n\
+long(x, base=10) -> long\n\
 \n\
-Convert a string or number to a long 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 a long integer, or return 0L if no arguments\n\
+are given.  If x is floating point, the conversion truncates towards zero.\n\
+\n\
+If x is not a number or if base is given, then x must be a string or\n\
+Unicode object representing an integer literal in the given base.  The\n\
+literal can be preceded by '+' or '-' and be surrounded by whitespace.\n\
+The base defaults to 10.  Valid bases are 0 and 2-36.  Base 0 means to\n\
+interpret the base from the string as an integer literal.\n\
+>>> int('0b100', base=0)\n\
+4L");
 
 static PyNumberMethods long_as_number = {
     (binaryfunc)long_add,       /*nb_add*/

diff --git a/Objects/rangeobject.c b/Objects/rangeobject.c
index c602e7dcfd1db0411a0bf9c427805206c6cb88c7..5203f409ac59073d796455d1f43a4ced5be49278 100644 (file)
--- a/Objects/rangeobject.c
+++ b/Objects/rangeobject.c
@@ -104,7 +104,8 @@ range_new(PyTypeObject *type, PyObject *args, PyObject *kw)
 }
 
 PyDoc_STRVAR(range_doc,
-"xrange([start,] stop[, step]) -> xrange object\n\
+"xrange(stop) -> xrange object\n\
+xrange(start, stop[, step]) -> xrange object\n\
 \n\
 Like range(), but instead of returning a list, returns an object that\n\
 generates the numbers in the range on demand.  For looping, this is \n\

diff --git a/Objects/sliceobject.c b/Objects/sliceobject.c
index d1fe052814ad68b42939b82790106d74facbcf1f..767a50a8c056bf4f9466140bc523b633abbb5641 100644 (file)
--- a/Objects/sliceobject.c
+++ b/Objects/sliceobject.c
@@ -211,7 +211,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/stringobject.c b/Objects/stringobject.c
index 7c4a86b5e647957669abbe87e73e4195676c6318..39fa7404a7410e8c4a29cd87d763ddfcd582071c 100644 (file)
--- a/Objects/stringobject.c
+++ b/Objects/stringobject.c
@@ -3799,7 +3799,7 @@ PyTypeObject PyBaseString_Type = {
 };
 
 PyDoc_STRVAR(string_doc,
-"str(object) -> string\n\
+"str(object='') -> string\n\
 \n\
 Return a nice string representation of the object.\n\
 If the argument is a string, the return value is the same object.");

diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c
index d40f2e46b22e9e96f1ed9a4b5c4e26451b66bda8..e3c2cb1e2a1bc91e34c4f2d7c2f8502c44b3ded9 100644 (file)
--- a/Objects/unicodeobject.c
+++ b/Objects/unicodeobject.c
@@ -1861,7 +1861,7 @@ char utf8_code_length[256] = {
        illegal prefix.  See RFC 3629 for details */
     1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, /* 00-0F */
     1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
-    1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 
+    1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
     1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
     1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
     1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
@@ -2217,7 +2217,7 @@ PyUnicode_DecodeUTF32Stateful(const char *s,
 #endif
     PyObject *errorHandler = NULL;
     PyObject *exc = NULL;
-    
+
     q = (unsigned char *)s;
     e = q + size;
 
@@ -8759,7 +8759,8 @@ unicode_subtype_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
 }
 
 PyDoc_STRVAR(unicode_doc,
-             "unicode(string [, encoding[, errors]]) -> object\n\
+             "unicode(object='') -> unicode object\n\
+unicode(string[, encoding[, errors]]) -> unicode object\n\
 \n\
 Create a new Unicode object from the given encoded string.\n\
 encoding defaults to the current default string encoding.\n\

diff --git a/Python/bltinmodule.c b/Python/bltinmodule.c
index b4f0e24aaf7bccbf3fc175483e01999928c622d5..d25b14c061703c78e71a1d5c053dc4229483adbc 100644 (file)
--- a/Python/bltinmodule.c
+++ b/Python/bltinmodule.c
@@ -2004,7 +2004,8 @@ builtin_range(PyObject *self, PyObject *args)
 }
 
 PyDoc_STRVAR(range_doc,
-"range([start,] stop[, step]) -> list of integers\n\
+"range(stop) -> list of integers\n\
+range(start, stop[, step]) -> list of integers\n\
 \n\
 Return a list containing an arithmetic progression of integers.\n\
 range(i, j) returns [i, i+1, i+2, ..., j-1]; start (!) defaults to 0.\n\