From eb052313d179c562883eddc27159d9b038775c35 Mon Sep 17 00:00:00 2001 From: Timo Ludwig Date: Wed, 22 Mar 2023 12:46:58 +0100 Subject: [PATCH] gh-100989: Improve the accuracy of collections.deque docstrings (GH-100990) (cherry picked from commit c74073657e32b8872f91b3bbe1efa9af20adbea9) Co-authored-by: Timo Ludwig Co-authored-by: C.A.M. Gerlach --- Modules/_collectionsmodule.c | 37 +++++++++++++++++++++++------------- 1 file changed, 24 insertions(+), 13 deletions(-) diff --git a/Modules/_collectionsmodule.c b/Modules/_collectionsmodule.c index eff03c789ede61..84bc2c2d087faf 100644 --- a/Modules/_collectionsmodule.c +++ b/Modules/_collectionsmodule.c @@ -920,7 +920,9 @@ 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(n)\n\n" +"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) @@ -961,7 +963,8 @@ deque_reverse(dequeobject *deque, PyObject *unused) } PyDoc_STRVAR(reverse_doc, -"D.reverse() -- reverse *IN PLACE*"); +"reverse()\n\n" +"Reverse the elements of the deque *IN PLACE*."); static PyObject * deque_count(dequeobject *deque, PyObject *v) @@ -1001,7 +1004,8 @@ deque_count(dequeobject *deque, PyObject *v) } PyDoc_STRVAR(count_doc, -"D.count(value) -> integer -- return number of occurrences of value"); +"count(x) -> int\n\n" +"Count the number of deque elements equal to *x*."); static int deque_contains(dequeobject *deque, PyObject *v) @@ -1110,8 +1114,10 @@ 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" -"Raises ValueError if the value 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 @@ -1156,10 +1162,13 @@ deque_insert(dequeobject *deque, PyObject *const *args, Py_ssize_t nargs) } PyDoc_STRVAR(insert_doc, -"D.insert(index, object) -- insert object before index"); +"insert(i, x)\n\n" +"Insert *x* into the deque at position *i*."); PyDoc_STRVAR(remove_doc, -"D.remove(value) -- remove first occurrence of value."); +"remove(x)\n\n" +"Remove the first occurrence of *x*." +"If not found, raises a ValueError."); static int valid_index(Py_ssize_t i, Py_ssize_t limit) @@ -1537,7 +1546,8 @@ deque_sizeof(dequeobject *deque, void *unused) } PyDoc_STRVAR(sizeof_doc, -"D.__sizeof__() -- size of D in memory, in bytes"); +"__sizeof__() -> int\n\n" +"Size of the deque in memory, in bytes."); static int deque_bool(dequeobject *deque) @@ -1592,7 +1602,8 @@ static PyNumberMethods deque_as_number = { static PyObject *deque_iter(dequeobject *deque); static PyObject *deque_reviter(dequeobject *deque, PyObject *Py_UNUSED(ignored)); PyDoc_STRVAR(reversed_doc, - "D.__reversed__() -- return a reverse iterator over the deque"); +"__reversed__()\n\n" +"Return a reverse iterator over the deque."); static PyMethodDef deque_methods[] = { {"append", (PyCFunction)deque_append, @@ -1637,9 +1648,8 @@ static PyMethodDef deque_methods[] = { }; PyDoc_STRVAR(deque_doc, -"deque([iterable[, maxlen]]) --> deque object\n\ -\n\ -A list-like sequence optimized for data accesses near its endpoints."); +"deque([iterable[, maxlen]]) -> collections.deque\n\n" +"A list-like sequence optimized for data accesses near its endpoints."); static PyTypeObject deque_type = { PyVarObject_HEAD_INIT(NULL, 0) @@ -2022,7 +2032,8 @@ new_defdict(defdictobject *dd, PyObject *arg) dd->default_factory ? dd->default_factory : Py_None, arg, NULL); } -PyDoc_STRVAR(defdict_copy_doc, "D.copy() -> a shallow copy of D."); +PyDoc_STRVAR(defdict_copy_doc, "copy() -> collections.deque\n\n" +"A shallow copy of the deque."); static PyObject * defdict_copy(defdictobject *dd, PyObject *Py_UNUSED(ignored))