Issue #14783: Improve int() docstring and also str(), range(), and slice().
This commit rewrites the docstring for int() to incorporate the documentation
changes made in issue #16036. It also switches the docstrings for int(),
str(), range(), and slice() to use multi-line signatures.
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 1ee8540..2575d7f 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1236,7 +1236,8 @@
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 bc5470a..5cd69b4 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -10,6 +10,9 @@
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 dfedfb7..b9a0d85 100644
--- a/Objects/longobject.c
+++ b/Objects/longobject.c
@@ -4703,13 +4703,20 @@
};
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 935b205..b67b969 100644
--- a/Objects/rangeobject.c
+++ b/Objects/rangeobject.c
@@ -135,7 +135,8 @@
}
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 d7b97c9..0f4b647 100644
--- a/Objects/sliceobject.c
+++ b/Objects/sliceobject.c
@@ -221,7 +221,8 @@
}
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 f59db36..1dd3a85 100644
--- a/Objects/unicodeobject.c
+++ b/Objects/unicodeobject.c
@@ -9986,7 +9986,8 @@
}
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\