diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 1ee8540b096..2575d7f7879 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1236,7 +1236,8 @@ are always available. They are listed here in alphabetical order. standard type hierarchy in :ref:`types`. -.. 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 bc5470aac90..5cd69b41527 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -10,6 +10,9 @@ What's New in Python 3.2.4 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 dfedfb7bfec..b9a0d8543a6 100644 --- a/Objects/longobject.c +++ b/Objects/longobject.c @@ -4703,13 +4703,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 935b205111a..b67b9694d58 100644 --- a/Objects/rangeobject.c +++ b/Objects/rangeobject.c @@ -135,7 +135,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."); diff --git a/Objects/sliceobject.c b/Objects/sliceobject.c index d7b97c9699a..0f4b6479651 100644 --- a/Objects/sliceobject.c +++ b/Objects/sliceobject.c @@ -221,7 +221,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 f59db36dd3d..1dd3a852f27 100644 --- a/Objects/unicodeobject.c +++ b/Objects/unicodeobject.c @@ -9986,7 +9986,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\