From 317f39bdc706624bcbcaccfd6250f11dd6f46c4e Mon Sep 17 00:00:00 2001 From: Timo Ludwig Date: Thu, 23 Mar 2023 14:54:14 +0100 Subject: [PATCH 1/8] gh-100989: Fix regression in docstrings of collections.deque --- Modules/_collectionsmodule.c | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/Modules/_collectionsmodule.c b/Modules/_collectionsmodule.c index ba4a9760f7b906..9fa65b8e6d8181 100644 --- a/Modules/_collectionsmodule.c +++ b/Modules/_collectionsmodule.c @@ -910,7 +910,7 @@ deque_rotate(dequeobject *deque, PyObject *const *args, Py_ssize_t nargs) } PyDoc_STRVAR(rotate_doc, -"rotate(n)\n\n" +"rotate(n)\n" "Rotate the deque *n* steps to the right (default ``n=1``). " "If *n* is negative, rotates left."); @@ -953,7 +953,7 @@ deque_reverse(dequeobject *deque, PyObject *unused) } PyDoc_STRVAR(reverse_doc, -"reverse()\n\n" +"reverse()\n" "Reverse the elements of the deque *IN PLACE*."); static PyObject * @@ -993,7 +993,7 @@ deque_count(dequeobject *deque, PyObject *v) } PyDoc_STRVAR(count_doc, -"count(x) -> int\n\n" +"count(x) -> int\n" "Count the number of deque elements equal to *x*."); static int @@ -1102,10 +1102,9 @@ deque_index(dequeobject *deque, PyObject *const *args, Py_ssize_t nargs) } PyDoc_STRVAR(index_doc, -"index(x, [start, [stop]]) -> int\n\n" -"Return the position of *x* in the deque " -"(at or after index *start* and before index *stop*). " -"Returns the first match or raises a ValueError if not found."); +"index(x, [start, [stop]]) -> int\n" +"Return first index of *x*. " +"Raises ValueError if *x* is not present."); /* insert(), remove(), and delitem() are implemented in terms of rotate() for simplicity and reasonable performance near the end @@ -1150,11 +1149,11 @@ deque_insert(dequeobject *deque, PyObject *const *args, Py_ssize_t nargs) } PyDoc_STRVAR(insert_doc, -"insert(i, x)\n\n" +"insert(i, x)\n" "Insert *x* into the deque at position *i*."); PyDoc_STRVAR(remove_doc, -"remove(x)\n\n" +"remove(x)\n" "Remove the first occurrence of *x*." "If not found, raises a ValueError."); @@ -1527,7 +1526,7 @@ deque_sizeof(dequeobject *deque, void *unused) } PyDoc_STRVAR(sizeof_doc, -"__sizeof__() -> int\n\n" +"__sizeof__() -> int\n" "Size of the deque in memory, in bytes."); static PyObject * @@ -1563,7 +1562,7 @@ static PySequenceMethods deque_as_sequence = { static PyObject *deque_iter(dequeobject *deque); static PyObject *deque_reviter(dequeobject *deque, PyObject *Py_UNUSED(ignored)); PyDoc_STRVAR(reversed_doc, -"__reversed__()\n\n" +"__reversed__()\n" "Return a reverse iterator over the deque."); static PyMethodDef deque_methods[] = { @@ -1609,7 +1608,7 @@ static PyMethodDef deque_methods[] = { }; PyDoc_STRVAR(deque_doc, -"deque([iterable[, maxlen]]) -> collections.deque\n\n" +"deque([iterable[, maxlen]]) -> collections.deque\n" "A list-like sequence optimized for data accesses near its endpoints."); static PyTypeObject deque_type = { @@ -1989,7 +1988,7 @@ new_defdict(defdictobject *dd, PyObject *arg) dd->default_factory ? dd->default_factory : Py_None, arg, NULL); } -PyDoc_STRVAR(defdict_copy_doc, "copy() -> collections.deque\n\n" +PyDoc_STRVAR(defdict_copy_doc, "copy() -> collections.deque\n" "A shallow copy of the deque."); static PyObject * From e5566e57f13a05bb475a729a6b11cbcd0a6d3031 Mon Sep 17 00:00:00 2001 From: Timo Ludwig Date: Thu, 23 Mar 2023 15:13:48 +0100 Subject: [PATCH 2/8] Add missing space in remove() docstring --- Modules/_collectionsmodule.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Modules/_collectionsmodule.c b/Modules/_collectionsmodule.c index 9fa65b8e6d8181..8cbec0281d3d01 100644 --- a/Modules/_collectionsmodule.c +++ b/Modules/_collectionsmodule.c @@ -1154,7 +1154,7 @@ PyDoc_STRVAR(insert_doc, PyDoc_STRVAR(remove_doc, "remove(x)\n" -"Remove the first occurrence of *x*." +"Remove the first occurrence of *x*. " "If not found, raises a ValueError."); static int From e59aed54f572437190b8ea8ee6b046b68ef0f0da Mon Sep 17 00:00:00 2001 From: Timo Ludwig Date: Thu, 23 Mar 2023 20:01:25 +0100 Subject: [PATCH 3/8] Revert "Add missing space in remove() docstring" This reverts commit e5566e57f13a05bb475a729a6b11cbcd0a6d3031. --- Modules/_collectionsmodule.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Modules/_collectionsmodule.c b/Modules/_collectionsmodule.c index 8cbec0281d3d01..9fa65b8e6d8181 100644 --- a/Modules/_collectionsmodule.c +++ b/Modules/_collectionsmodule.c @@ -1154,7 +1154,7 @@ PyDoc_STRVAR(insert_doc, PyDoc_STRVAR(remove_doc, "remove(x)\n" -"Remove the first occurrence of *x*. " +"Remove the first occurrence of *x*." "If not found, raises a ValueError."); static int From 104a68646508148d6aa76ae1c821b0165f42a3dd Mon Sep 17 00:00:00 2001 From: Timo Ludwig Date: Thu, 23 Mar 2023 20:01:38 +0100 Subject: [PATCH 4/8] Revert "gh-100989: Fix regression in docstrings of collections.deque" This reverts commit 317f39bdc706624bcbcaccfd6250f11dd6f46c4e. --- Modules/_collectionsmodule.c | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/Modules/_collectionsmodule.c b/Modules/_collectionsmodule.c index 9fa65b8e6d8181..ba4a9760f7b906 100644 --- a/Modules/_collectionsmodule.c +++ b/Modules/_collectionsmodule.c @@ -910,7 +910,7 @@ deque_rotate(dequeobject *deque, PyObject *const *args, Py_ssize_t nargs) } PyDoc_STRVAR(rotate_doc, -"rotate(n)\n" +"rotate(n)\n\n" "Rotate the deque *n* steps to the right (default ``n=1``). " "If *n* is negative, rotates left."); @@ -953,7 +953,7 @@ deque_reverse(dequeobject *deque, PyObject *unused) } PyDoc_STRVAR(reverse_doc, -"reverse()\n" +"reverse()\n\n" "Reverse the elements of the deque *IN PLACE*."); static PyObject * @@ -993,7 +993,7 @@ deque_count(dequeobject *deque, PyObject *v) } PyDoc_STRVAR(count_doc, -"count(x) -> int\n" +"count(x) -> int\n\n" "Count the number of deque elements equal to *x*."); static int @@ -1102,9 +1102,10 @@ deque_index(dequeobject *deque, PyObject *const *args, Py_ssize_t nargs) } PyDoc_STRVAR(index_doc, -"index(x, [start, [stop]]) -> int\n" -"Return first index of *x*. " -"Raises ValueError if *x* is not present."); +"index(x, [start, [stop]]) -> int\n\n" +"Return the position of *x* in the deque " +"(at or after index *start* and before index *stop*). " +"Returns the first match or raises a ValueError if not found."); /* insert(), remove(), and delitem() are implemented in terms of rotate() for simplicity and reasonable performance near the end @@ -1149,11 +1150,11 @@ deque_insert(dequeobject *deque, PyObject *const *args, Py_ssize_t nargs) } PyDoc_STRVAR(insert_doc, -"insert(i, x)\n" +"insert(i, x)\n\n" "Insert *x* into the deque at position *i*."); PyDoc_STRVAR(remove_doc, -"remove(x)\n" +"remove(x)\n\n" "Remove the first occurrence of *x*." "If not found, raises a ValueError."); @@ -1526,7 +1527,7 @@ deque_sizeof(dequeobject *deque, void *unused) } PyDoc_STRVAR(sizeof_doc, -"__sizeof__() -> int\n" +"__sizeof__() -> int\n\n" "Size of the deque in memory, in bytes."); static PyObject * @@ -1562,7 +1563,7 @@ static PySequenceMethods deque_as_sequence = { static PyObject *deque_iter(dequeobject *deque); static PyObject *deque_reviter(dequeobject *deque, PyObject *Py_UNUSED(ignored)); PyDoc_STRVAR(reversed_doc, -"__reversed__()\n" +"__reversed__()\n\n" "Return a reverse iterator over the deque."); static PyMethodDef deque_methods[] = { @@ -1608,7 +1609,7 @@ static PyMethodDef deque_methods[] = { }; PyDoc_STRVAR(deque_doc, -"deque([iterable[, maxlen]]) -> collections.deque\n" +"deque([iterable[, maxlen]]) -> collections.deque\n\n" "A list-like sequence optimized for data accesses near its endpoints."); static PyTypeObject deque_type = { @@ -1988,7 +1989,7 @@ new_defdict(defdictobject *dd, PyObject *arg) dd->default_factory ? dd->default_factory : Py_None, arg, NULL); } -PyDoc_STRVAR(defdict_copy_doc, "copy() -> collections.deque\n" +PyDoc_STRVAR(defdict_copy_doc, "copy() -> collections.deque\n\n" "A shallow copy of the deque."); static PyObject * From 2ca708340bc2d061ec6eb729659bb129f0e3403d Mon Sep 17 00:00:00 2001 From: Timo Ludwig Date: Thu, 23 Mar 2023 20:02:06 +0100 Subject: [PATCH 5/8] Revert "gh-100989: Improve the accuracy of collections.deque docstrings (#100990)" This reverts commit c74073657e32b8872f91b3bbe1efa9af20adbea9. --- Modules/_collectionsmodule.c | 37 +++++++++++++----------------------- 1 file changed, 13 insertions(+), 24 deletions(-) diff --git a/Modules/_collectionsmodule.c b/Modules/_collectionsmodule.c index ba4a9760f7b906..68131f3b54d2ea 100644 --- a/Modules/_collectionsmodule.c +++ b/Modules/_collectionsmodule.c @@ -910,9 +910,7 @@ deque_rotate(dequeobject *deque, PyObject *const *args, Py_ssize_t nargs) } PyDoc_STRVAR(rotate_doc, -"rotate(n)\n\n" -"Rotate the deque *n* steps to the right (default ``n=1``). " -"If *n* is negative, rotates left."); +"Rotate the deque n steps to the right (default n=1). If n is negative, rotates left."); static PyObject * deque_reverse(dequeobject *deque, PyObject *unused) @@ -953,8 +951,7 @@ deque_reverse(dequeobject *deque, PyObject *unused) } PyDoc_STRVAR(reverse_doc, -"reverse()\n\n" -"Reverse the elements of the deque *IN PLACE*."); +"D.reverse() -- reverse *IN PLACE*"); static PyObject * deque_count(dequeobject *deque, PyObject *v) @@ -993,8 +990,7 @@ deque_count(dequeobject *deque, PyObject *v) } PyDoc_STRVAR(count_doc, -"count(x) -> int\n\n" -"Count the number of deque elements equal to *x*."); +"D.count(value) -> integer -- return number of occurrences of value"); static int deque_contains(dequeobject *deque, PyObject *v) @@ -1102,10 +1098,8 @@ deque_index(dequeobject *deque, PyObject *const *args, Py_ssize_t nargs) } PyDoc_STRVAR(index_doc, -"index(x, [start, [stop]]) -> int\n\n" -"Return the position of *x* in the deque " -"(at or after index *start* and before index *stop*). " -"Returns the first match or raises a ValueError if not found."); +"D.index(value, [start, [stop]]) -> integer -- return first index of value.\n" +"Raises ValueError if the value is not present."); /* insert(), remove(), and delitem() are implemented in terms of rotate() for simplicity and reasonable performance near the end @@ -1150,13 +1144,10 @@ deque_insert(dequeobject *deque, PyObject *const *args, Py_ssize_t nargs) } PyDoc_STRVAR(insert_doc, -"insert(i, x)\n\n" -"Insert *x* into the deque at position *i*."); +"D.insert(index, object) -- insert object before index"); PyDoc_STRVAR(remove_doc, -"remove(x)\n\n" -"Remove the first occurrence of *x*." -"If not found, raises a ValueError."); +"D.remove(value) -- remove first occurrence of value."); static int valid_index(Py_ssize_t i, Py_ssize_t limit) @@ -1527,8 +1518,7 @@ deque_sizeof(dequeobject *deque, void *unused) } PyDoc_STRVAR(sizeof_doc, -"__sizeof__() -> int\n\n" -"Size of the deque in memory, in bytes."); +"D.__sizeof__() -- size of D in memory, in bytes"); static PyObject * deque_get_maxlen(dequeobject *deque, void *Py_UNUSED(ignored)) @@ -1563,8 +1553,7 @@ static PySequenceMethods deque_as_sequence = { static PyObject *deque_iter(dequeobject *deque); static PyObject *deque_reviter(dequeobject *deque, PyObject *Py_UNUSED(ignored)); PyDoc_STRVAR(reversed_doc, -"__reversed__()\n\n" -"Return a reverse iterator over the deque."); + "D.__reversed__() -- return a reverse iterator over the deque"); static PyMethodDef deque_methods[] = { {"append", (PyCFunction)deque_append, @@ -1609,8 +1598,9 @@ static PyMethodDef deque_methods[] = { }; PyDoc_STRVAR(deque_doc, -"deque([iterable[, maxlen]]) -> collections.deque\n\n" -"A list-like sequence optimized for data accesses near its endpoints."); +"deque([iterable[, maxlen]]) --> deque object\n\ +\n\ +A list-like sequence optimized for data accesses near its endpoints."); static PyTypeObject deque_type = { PyVarObject_HEAD_INIT(NULL, 0) @@ -1989,8 +1979,7 @@ new_defdict(defdictobject *dd, PyObject *arg) dd->default_factory ? dd->default_factory : Py_None, arg, NULL); } -PyDoc_STRVAR(defdict_copy_doc, "copy() -> collections.deque\n\n" -"A shallow copy of the deque."); +PyDoc_STRVAR(defdict_copy_doc, "D.copy() -> a shallow copy of D."); static PyObject * defdict_copy(defdictobject *dd, PyObject *Py_UNUSED(ignored)) From 36d06995f56fc83df8ced24480586e67838b81be Mon Sep 17 00:00:00 2001 From: Timo Ludwig Date: Thu, 23 Mar 2023 20:09:46 +0100 Subject: [PATCH 6/8] Replace `integer` by `int` in return type documentation of collections.deque --- Modules/_collectionsmodule.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Modules/_collectionsmodule.c b/Modules/_collectionsmodule.c index 68131f3b54d2ea..d6cc7fac070596 100644 --- a/Modules/_collectionsmodule.c +++ b/Modules/_collectionsmodule.c @@ -990,7 +990,7 @@ deque_count(dequeobject *deque, PyObject *v) } PyDoc_STRVAR(count_doc, -"D.count(value) -> integer -- return number of occurrences of value"); +"D.count(value) -> int -- return number of occurrences of value"); static int deque_contains(dequeobject *deque, PyObject *v) @@ -1098,7 +1098,7 @@ deque_index(dequeobject *deque, PyObject *const *args, Py_ssize_t nargs) } PyDoc_STRVAR(index_doc, -"D.index(value, [start, [stop]]) -> integer -- return first index of value.\n" +"D.index(value, [start, [stop]]) -> int -- return first index of value.\n" "Raises ValueError if the value is not present."); /* insert(), remove(), and delitem() are implemented in terms of From 269fe64c8cf260ceac491b45e58e5f71b2c9726d Mon Sep 17 00:00:00 2001 From: Timo Ludwig Date: Thu, 23 Mar 2023 20:41:28 +0100 Subject: [PATCH 7/8] Remove superfluous whitespace in docstrings of collections.deque --- Modules/_collectionsmodule.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Modules/_collectionsmodule.c b/Modules/_collectionsmodule.c index d6cc7fac070596..2617873fce6fba 100644 --- a/Modules/_collectionsmodule.c +++ b/Modules/_collectionsmodule.c @@ -910,7 +910,7 @@ deque_rotate(dequeobject *deque, PyObject *const *args, Py_ssize_t nargs) } PyDoc_STRVAR(rotate_doc, -"Rotate the deque n steps to the right (default n=1). If n is negative, rotates left."); +"Rotate the deque n steps to the right (default n=1). If n is negative, rotates left."); static PyObject * deque_reverse(dequeobject *deque, PyObject *unused) From f8ea3d04d63da6d5255fb872e5456503077df37d Mon Sep 17 00:00:00 2001 From: Timo Ludwig Date: Thu, 23 Mar 2023 20:59:57 +0100 Subject: [PATCH 8/8] Revert "Remove superfluous whitespace in docstrings of collections.deque" This reverts commit 269fe64c8cf260ceac491b45e58e5f71b2c9726d. --- Modules/_collectionsmodule.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Modules/_collectionsmodule.c b/Modules/_collectionsmodule.c index 2617873fce6fba..d6cc7fac070596 100644 --- a/Modules/_collectionsmodule.c +++ b/Modules/_collectionsmodule.c @@ -910,7 +910,7 @@ deque_rotate(dequeobject *deque, PyObject *const *args, Py_ssize_t nargs) } PyDoc_STRVAR(rotate_doc, -"Rotate the deque n steps to the right (default n=1). If n is negative, rotates left."); +"Rotate the deque n steps to the right (default n=1). If n is negative, rotates left."); static PyObject * deque_reverse(dequeobject *deque, PyObject *unused)