From ad4b0001794e47368b0997183b30b1171eab2790 Mon Sep 17 00:00:00 2001 From: Chris Jerdonek Date: Sun, 7 Oct 2012 20:37:54 -0700 Subject: Issue #14783: Backport changes from 3.2. --- Doc/library/functions.rst | 8 +++++--- Misc/NEWS | 3 +++ Objects/intobject.c | 21 +++++++++++++-------- Objects/longobject.c | 18 ++++++++++++------ Objects/rangeobject.c | 3 ++- Objects/sliceobject.c | 3 ++- Objects/stringobject.c | 2 +- Objects/unicodeobject.c | 7 ++++--- Python/bltinmodule.c | 3 ++- 9 files changed, 44 insertions(+), 24 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 200c714..0314ca5 100644 --- 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 36033ea..a52a71f 100644 --- 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 e518e74..74955ad 100644 --- 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 cd86a1f..9296ad4 100644 --- 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 c602e7d..5203f40 100644 --- 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 d1fe052..767a50a 100644 --- 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 7c4a86b..39fa740 100644 --- 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 d40f2e4..e3c2cb1 100644 --- 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 b4f0e24..d25b14c 100644 --- 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\ -- cgit v0.12