diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index c2b3b212d2b..e9691948674 100644 --- 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 index 035fa0e7b3b..9c2bd09f9ab 100644 --- 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 index 4cc080f2b5d..06ebeda1e53 100644 --- 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 index c47a4ff0348..68d563694a6 100644 --- 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 index c4a190755c3..15933352634 100644 --- 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 index 8289580af24..6c8fe2d865b 100644 --- a/Objects/unicodeobject.c +++ b/Objects/unicodeobject.c @@ -14074,7 +14074,8 @@ onError: } 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\