From 78d9e58f204ec4e90502b42c3e7d48dcd76ccb80 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 25 Jan 2017 00:30:04 +0200 Subject: Issues #29311, #29289: Fixed and improved docstrings for dict and OrderedDict methods. --- Lib/collections/__init__.py | 19 +++++++++---------- Objects/clinic/dictobject.c.h | 12 +++++++----- Objects/clinic/odictobject.c.h | 17 ++++++++--------- Objects/dictobject.c | 18 ++++++++++-------- Objects/odictobject.c | 23 +++++++++++------------ 5 files changed, 45 insertions(+), 44 deletions(-) diff --git a/Lib/collections/__init__.py b/Lib/collections/__init__.py index 85b4c3c..8408255 100644 --- a/Lib/collections/__init__.py +++ b/Lib/collections/__init__.py @@ -157,9 +157,9 @@ class OrderedDict(dict): dict.clear(self) def popitem(self, last=True): - '''od.popitem() -> (k, v), return and remove a (key, value) pair. - Pairs are returned in LIFO order if last is true or FIFO order if false. + '''Remove and return a (key, value) pair from the dictionary. + Pairs are returned in LIFO order if last is true or FIFO order if false. ''' if not self: raise KeyError('dictionary is empty') @@ -180,11 +180,9 @@ class OrderedDict(dict): return key, value def move_to_end(self, key, last=True): - '''Move an existing element to the end (or beginning if last==False). - - Raises KeyError if the element does not exist. - When last=True, acts like a fast version of self[key]=self.pop(key). + '''Move an existing element to the end (or beginning if last is false). + Raise KeyError if the element does not exist. ''' link = self.__map[key] link_prev = link.prev @@ -248,7 +246,10 @@ class OrderedDict(dict): return default def setdefault(self, key, default=None): - 'od.setdefault(k[,d]) -> od.get(k,d), also set od[k]=d if k not in od' + '''Insert key with a value of default if key is not in the dictionary. + + Return the value for key if key is in the dictionary, else default. + ''' if key in self: return self[key] self[key] = default @@ -274,9 +275,7 @@ class OrderedDict(dict): @classmethod def fromkeys(cls, iterable, value=None): - '''OD.fromkeys(S[, v]) -> New ordered dictionary with keys from S. - If not specified, the value defaults to None. - + '''Create a new ordered dictionary with keys from iterable and values set to value. ''' self = cls() for key in iterable: diff --git a/Objects/clinic/dictobject.c.h b/Objects/clinic/dictobject.c.h index deec424..97918e8 100644 --- a/Objects/clinic/dictobject.c.h +++ b/Objects/clinic/dictobject.c.h @@ -6,7 +6,7 @@ PyDoc_STRVAR(dict_fromkeys__doc__, "fromkeys($type, iterable, value=None, /)\n" "--\n" "\n" -"Returns a new dict with keys from iterable and values equal to value."); +"Create a new dictionary with keys from iterable and values set to value."); #define DICT_FROMKEYS_METHODDEF \ {"fromkeys", (PyCFunction)dict_fromkeys, METH_FASTCALL|METH_CLASS, dict_fromkeys__doc__}, @@ -40,7 +40,7 @@ PyDoc_STRVAR(dict___contains____doc__, "__contains__($self, key, /)\n" "--\n" "\n" -"True if D has a key k, else False."); +"True if the dictionary has a specified key, else False."); #define DICT___CONTAINS___METHODDEF \ {"__contains__", (PyCFunction)dict___contains__, METH_O|METH_COEXIST, dict___contains____doc__}, @@ -49,7 +49,7 @@ PyDoc_STRVAR(dict_get__doc__, "get($self, key, default=None, /)\n" "--\n" "\n" -"D.get(key[, default]) -> D[key] if key in D, else default."); +"Return the value for key if key is in the dictionary, else default."); #define DICT_GET_METHODDEF \ {"get", (PyCFunction)dict_get, METH_FASTCALL, dict_get__doc__}, @@ -83,7 +83,9 @@ PyDoc_STRVAR(dict_setdefault__doc__, "setdefault($self, key, default=None, /)\n" "--\n" "\n" -"D.get(key,default), also set D[key]=default if key not in D."); +"Insert key with a value of default if key is not in the dictionary.\n" +"\n" +"Return the value for key if key is in the dictionary, else default."); #define DICT_SETDEFAULT_METHODDEF \ {"setdefault", (PyCFunction)dict_setdefault, METH_FASTCALL, dict_setdefault__doc__}, @@ -113,4 +115,4 @@ dict_setdefault(PyDictObject *self, PyObject **args, Py_ssize_t nargs, PyObject exit: return return_value; } -/*[clinic end generated code: output=6e9d917602373072 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=91aa6a9f3c402b1b input=a9049054013a1b77]*/ diff --git a/Objects/clinic/odictobject.c.h b/Objects/clinic/odictobject.c.h index ee35af6..0e5092c 100644 --- a/Objects/clinic/odictobject.c.h +++ b/Objects/clinic/odictobject.c.h @@ -6,9 +6,7 @@ PyDoc_STRVAR(OrderedDict_fromkeys__doc__, "fromkeys($type, /, iterable, value=None)\n" "--\n" "\n" -"New ordered dictionary with keys from S.\n" -"\n" -"If not specified, the value defaults to None."); +"Create a new ordered dictionary with keys from iterable and values set to value."); #define ORDEREDDICT_FROMKEYS_METHODDEF \ {"fromkeys", (PyCFunction)OrderedDict_fromkeys, METH_FASTCALL|METH_CLASS, OrderedDict_fromkeys__doc__}, @@ -39,7 +37,9 @@ PyDoc_STRVAR(OrderedDict_setdefault__doc__, "setdefault($self, /, key, default=None)\n" "--\n" "\n" -"od.get(k,d), also set od[k]=d if k not in od."); +"Insert key with a value of default if key is not in the dictionary.\n" +"\n" +"Return the value for key if key is in the dictionary, else default."); #define ORDEREDDICT_SETDEFAULT_METHODDEF \ {"setdefault", (PyCFunction)OrderedDict_setdefault, METH_FASTCALL, OrderedDict_setdefault__doc__}, @@ -71,7 +71,7 @@ PyDoc_STRVAR(OrderedDict_popitem__doc__, "popitem($self, /, last=True)\n" "--\n" "\n" -"Return (k, v) and remove a (key, value) pair.\n" +"Remove and return a (key, value) pair from the dictionary.\n" "\n" "Pairs are returned in LIFO order if last is true or FIFO order if false."); @@ -103,10 +103,9 @@ PyDoc_STRVAR(OrderedDict_move_to_end__doc__, "move_to_end($self, /, key, last=True)\n" "--\n" "\n" -"\"Move an existing element to the end (or beginning if last==False).\n" +"Move an existing element to the end (or beginning if last is false).\n" "\n" -" Raises KeyError if the element does not exist.\n" -" When last=True, acts like a fast version of self[key]=self.pop(key)."); +"Raise KeyError if the element does not exist."); #define ORDEREDDICT_MOVE_TO_END_METHODDEF \ {"move_to_end", (PyCFunction)OrderedDict_move_to_end, METH_FASTCALL, OrderedDict_move_to_end__doc__}, @@ -132,4 +131,4 @@ OrderedDict_move_to_end(PyODictObject *self, PyObject **args, Py_ssize_t nargs, exit: return return_value; } -/*[clinic end generated code: output=84ef19e7b5db0086 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=a19a24ac37b42e5e input=a9049054013a1b77]*/ diff --git a/Objects/dictobject.c b/Objects/dictobject.c index 9ff52c3..00fd58c 100644 --- a/Objects/dictobject.c +++ b/Objects/dictobject.c @@ -2311,12 +2311,12 @@ dict.fromkeys value: object=None / -Returns a new dict with keys from iterable and values equal to value. +Create a new dictionary with keys from iterable and values set to value. [clinic start generated code]*/ static PyObject * dict_fromkeys_impl(PyTypeObject *type, PyObject *iterable, PyObject *value) -/*[clinic end generated code: output=8fb98e4b10384999 input=b85a667f9bf4669d]*/ +/*[clinic end generated code: output=8fb98e4b10384999 input=382ba4855d0f74c3]*/ { return _PyDict_FromKeys((PyObject *)type, iterable, value); } @@ -2764,12 +2764,12 @@ dict.__contains__ key: object / -True if D has a key k, else False. +True if the dictionary has the specified key, else False. [clinic start generated code]*/ static PyObject * dict___contains__(PyDictObject *self, PyObject *key) -/*[clinic end generated code: output=a3d03db709ed6e6b input=b852b2a19b51ab24]*/ +/*[clinic end generated code: output=a3d03db709ed6e6b input=f39613886bf975b7]*/ { register PyDictObject *mp = self; Py_hash_t hash; @@ -2797,12 +2797,12 @@ dict.get default: object = None / -D.get(key[, default]) -> D[key] if key in D, else default. +Return the value for key if key is in the dictionary, else default. [clinic start generated code]*/ static PyObject * dict_get_impl(PyDictObject *self, PyObject *key, PyObject *default_value) -/*[clinic end generated code: output=bba707729dee05bf input=e73ab0f028f4b2be]*/ +/*[clinic end generated code: output=bba707729dee05bf input=279ddb5790b6b107]*/ { PyObject *val = NULL; Py_hash_t hash; @@ -2915,13 +2915,15 @@ dict.setdefault default: object = None / -D.get(key,default), also set D[key]=default if key not in D. +Insert key with a value of default if key is not in the dictionary. + +Return the value for key if key is in the dictionary, else default. [clinic start generated code]*/ static PyObject * dict_setdefault_impl(PyDictObject *self, PyObject *key, PyObject *default_value) -/*[clinic end generated code: output=f8c1101ebf69e220 input=b2826255bacd845a]*/ +/*[clinic end generated code: output=f8c1101ebf69e220 input=0f063756e815fd9d]*/ { PyObject *val; diff --git a/Objects/odictobject.c b/Objects/odictobject.c index 8b1e114..c2cef21 100644 --- a/Objects/odictobject.c +++ b/Objects/odictobject.c @@ -926,14 +926,12 @@ OrderedDict.fromkeys iterable as seq: object value: object = None -New ordered dictionary with keys from S. - -If not specified, the value defaults to None. +Create a new ordered dictionary with keys from iterable and values set to value. [clinic start generated code]*/ static PyObject * OrderedDict_fromkeys_impl(PyTypeObject *type, PyObject *seq, PyObject *value) -/*[clinic end generated code: output=c10390d452d78d6d input=33eefc496d5eee7b]*/ +/*[clinic end generated code: output=c10390d452d78d6d input=1a0476c229c597b3]*/ { return _PyDict_FromKeys((PyObject *)type, seq, value); } @@ -1014,13 +1012,15 @@ OrderedDict.setdefault key: object default: object = None -od.get(k,d), also set od[k]=d if k not in od. +Insert key with a value of default if key is not in the dictionary. + +Return the value for key if key is in the dictionary, else default. [clinic start generated code]*/ static PyObject * OrderedDict_setdefault_impl(PyODictObject *self, PyObject *key, PyObject *default_value) -/*[clinic end generated code: output=97537cb7c28464b6 input=d5e940fcea7a5a67]*/ +/*[clinic end generated code: output=97537cb7c28464b6 input=38e098381c1efbc6]*/ { PyObject *result = NULL; @@ -1165,14 +1165,14 @@ OrderedDict.popitem last: bool = True -Return (k, v) and remove a (key, value) pair. +Remove and return a (key, value) pair from the dictionary. Pairs are returned in LIFO order if last is true or FIFO order if false. [clinic start generated code]*/ static PyObject * OrderedDict_popitem_impl(PyODictObject *self, int last) -/*[clinic end generated code: output=98e7d986690d49eb input=4937da2015939126]*/ +/*[clinic end generated code: output=98e7d986690d49eb input=d992ac5ee8305e1a]*/ { PyObject *key, *value, *item = NULL; _ODictNode *node; @@ -1324,15 +1324,14 @@ OrderedDict.move_to_end key: object last: bool = True -"Move an existing element to the end (or beginning if last==False). +Move an existing element to the end (or beginning if last is false). - Raises KeyError if the element does not exist. - When last=True, acts like a fast version of self[key]=self.pop(key). +Raise KeyError if the element does not exist. [clinic start generated code]*/ static PyObject * OrderedDict_move_to_end_impl(PyODictObject *self, PyObject *key, int last) -/*[clinic end generated code: output=fafa4c5cc9b92f20 input=3b8283f7d0e15e43]*/ +/*[clinic end generated code: output=fafa4c5cc9b92f20 input=d6ceff7132a2fcd7]*/ { _ODictNode *node; -- cgit v0.12