Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Issues #29311, #29289: Fixed and improved docstrings for dict and OrderedDict 

methods.
This commit is contained in:
Serhiy Storchaka 2017-01-25 00:30:04 +02:00
parent 0105606f55
commit 78d9e58f20
5 changed files with 45 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
Lib/collections/__init__.py
View File

@ -157,9 +157,9 @@ class OrderedDict(dict):
dict.clear(self) dict.clear(self)
def popitem(self, last=True): def popitem(self, last=True):
'''od.popitem() -> (k, v), return 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.
Pairs are returned in LIFO order if last is true or FIFO order if false.
''' '''
if not self: if not self:
raise KeyError('dictionary is empty') raise KeyError('dictionary is empty')
@ -180,11 +180,9 @@ class OrderedDict(dict):
return key, value return key, value
def move_to_end(self, key, last=True): def move_to_end(self, key, last=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.
''' '''
link = self.__map[key] link = self.__map[key]
link_prev = link.prev link_prev = link.prev
@ -248,7 +246,10 @@ class OrderedDict(dict):
return default return default
def setdefault(self, key, default=None): 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: if key in self:
return self[key] return self[key]
self[key] = default self[key] = default
@ -274,9 +275,7 @@ class OrderedDict(dict):
@classmethod @classmethod
def fromkeys(cls, iterable, value=None): def fromkeys(cls, iterable, value=None):
'''OD.fromkeys(S[, v]) -> New ordered dictionary with keys from S. '''Create a new ordered dictionary with keys from iterable and values set to value.
If not specified, the value defaults to None.
''' '''
self = cls() self = cls()
for key in iterable: for key in iterable:

12
Objects/clinic/dictobject.c.h
View File

@ -6,7 +6,7 @@ PyDoc_STRVAR(dict_fromkeys__doc__,
"fromkeys($type, iterable, value=None, /)\n" "fromkeys($type, iterable, value=None, /)\n"
"--\n" "--\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 \ #define DICT_FROMKEYS_METHODDEF \
{"fromkeys", (PyCFunction)dict_fromkeys, METH_FASTCALL|METH_CLASS, dict_fromkeys__doc__}, {"fromkeys", (PyCFunction)dict_fromkeys, METH_FASTCALL|METH_CLASS, dict_fromkeys__doc__},
@ -40,7 +40,7 @@ PyDoc_STRVAR(dict___contains____doc__,
"__contains__($self, key, /)\n" "__contains__($self, key, /)\n"
"--\n" "--\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 \ #define DICT___CONTAINS___METHODDEF \
{"__contains__", (PyCFunction)dict___contains__, METH_O|METH_COEXIST, dict___contains____doc__}, {"__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" "get($self, key, default=None, /)\n"
"--\n" "--\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 \ #define DICT_GET_METHODDEF \
{"get", (PyCFunction)dict_get, METH_FASTCALL, dict_get__doc__}, {"get", (PyCFunction)dict_get, METH_FASTCALL, dict_get__doc__},
@ -83,7 +83,9 @@ PyDoc_STRVAR(dict_setdefault__doc__,
"setdefault($self, key, default=None, /)\n" "setdefault($self, key, default=None, /)\n"
"--\n" "--\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 \ #define DICT_SETDEFAULT_METHODDEF \
{"setdefault", (PyCFunction)dict_setdefault, METH_FASTCALL, dict_setdefault__doc__}, {"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: exit:
return return_value; return return_value;
} }
/*[clinic end generated code: output=6e9d917602373072 input=a9049054013a1b77]*/ /*[clinic end generated code: output=91aa6a9f3c402b1b input=a9049054013a1b77]*/

17
Objects/clinic/odictobject.c.h
View File

@ -6,9 +6,7 @@ PyDoc_STRVAR(OrderedDict_fromkeys__doc__,
"fromkeys($type, /, iterable, value=None)\n" "fromkeys($type, /, iterable, value=None)\n"
"--\n" "--\n"
"\n" "\n"
"New ordered dictionary with keys from S.\n" "Create a new ordered dictionary with keys from iterable and values set to value.");
"\n"
"If not specified, the value defaults to None.");
#define ORDEREDDICT_FROMKEYS_METHODDEF \ #define ORDEREDDICT_FROMKEYS_METHODDEF \
{"fromkeys", (PyCFunction)OrderedDict_fromkeys, METH_FASTCALL|METH_CLASS, OrderedDict_fromkeys__doc__}, {"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" "setdefault($self, /, key, default=None)\n"
"--\n" "--\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 \ #define ORDEREDDICT_SETDEFAULT_METHODDEF \
{"setdefault", (PyCFunction)OrderedDict_setdefault, METH_FASTCALL, OrderedDict_setdefault__doc__}, {"setdefault", (PyCFunction)OrderedDict_setdefault, METH_FASTCALL, OrderedDict_setdefault__doc__},
@ -71,7 +71,7 @@ PyDoc_STRVAR(OrderedDict_popitem__doc__,
"popitem($self, /, last=True)\n" "popitem($self, /, last=True)\n"
"--\n" "--\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" "\n"
"Pairs are returned in LIFO order if last is true or FIFO order if false."); "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" "move_to_end($self, /, key, last=True)\n"
"--\n" "--\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" "\n"
" Raises KeyError if the element does not exist.\n" "Raise KeyError if the element does not exist.");
" When last=True, acts like a fast version of self[key]=self.pop(key).");
#define ORDEREDDICT_MOVE_TO_END_METHODDEF \ #define ORDEREDDICT_MOVE_TO_END_METHODDEF \
{"move_to_end", (PyCFunction)OrderedDict_move_to_end, METH_FASTCALL, OrderedDict_move_to_end__doc__}, {"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: exit:
return return_value; return return_value;
} }
/*[clinic end generated code: output=84ef19e7b5db0086 input=a9049054013a1b77]*/ /*[clinic end generated code: output=a19a24ac37b42e5e input=a9049054013a1b77]*/

18
Objects/dictobject.c
View File

@ -2311,12 +2311,12 @@ dict.fromkeys
value: object=None 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]*/ [clinic start generated code]*/
static PyObject * static PyObject *
dict_fromkeys_impl(PyTypeObject *type, PyObject *iterable, PyObject *value) 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); return _PyDict_FromKeys((PyObject *)type, iterable, value);
} }
@ -2764,12 +2764,12 @@ dict.__contains__
key: object 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]*/ [clinic start generated code]*/
static PyObject * static PyObject *
dict___contains__(PyDictObject *self, PyObject *key) 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; register PyDictObject *mp = self;
Py_hash_t hash; Py_hash_t hash;
@ -2797,12 +2797,12 @@ dict.get
default: object = None 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]*/ [clinic start generated code]*/
static PyObject * static PyObject *
dict_get_impl(PyDictObject *self, PyObject *key, PyObject *default_value) 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; PyObject *val = NULL;
Py_hash_t hash; Py_hash_t hash;
@ -2915,13 +2915,15 @@ dict.setdefault
default: object = None 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]*/ [clinic start generated code]*/
static PyObject * static PyObject *
dict_setdefault_impl(PyDictObject *self, PyObject *key, dict_setdefault_impl(PyDictObject *self, PyObject *key,
PyObject *default_value) PyObject *default_value)
/*[clinic end generated code: output=f8c1101ebf69e220 input=b2826255bacd845a]*/ /*[clinic end generated code: output=f8c1101ebf69e220 input=0f063756e815fd9d]*/
{ {
PyObject *val; PyObject *val;

23
Objects/odictobject.c
View File

@ -926,14 +926,12 @@ OrderedDict.fromkeys
iterable as seq: object iterable as seq: object
value: object = None value: object = None
New ordered dictionary with keys from S. Create a new ordered dictionary with keys from iterable and values set to value.
If not specified, the value defaults to None.
[clinic start generated code]*/ [clinic start generated code]*/
static PyObject * static PyObject *
OrderedDict_fromkeys_impl(PyTypeObject *type, PyObject *seq, PyObject *value) 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); return _PyDict_FromKeys((PyObject *)type, seq, value);
} }
@ -1014,13 +1012,15 @@ OrderedDict.setdefault
key: object key: object
default: object = None 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]*/ [clinic start generated code]*/
static PyObject * static PyObject *
OrderedDict_setdefault_impl(PyODictObject *self, PyObject *key, OrderedDict_setdefault_impl(PyODictObject *self, PyObject *key,
PyObject *default_value) PyObject *default_value)
/*[clinic end generated code: output=97537cb7c28464b6 input=d5e940fcea7a5a67]*/ /*[clinic end generated code: output=97537cb7c28464b6 input=38e098381c1efbc6]*/
{ {
PyObject *result = NULL; PyObject *result = NULL;
@ -1165,14 +1165,14 @@ OrderedDict.popitem
last: bool = True 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. Pairs are returned in LIFO order if last is true or FIFO order if false.
[clinic start generated code]*/ [clinic start generated code]*/
static PyObject * static PyObject *
OrderedDict_popitem_impl(PyODictObject *self, int last) 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; PyObject *key, *value, *item = NULL;
_ODictNode *node; _ODictNode *node;
@ -1324,15 +1324,14 @@ OrderedDict.move_to_end
key: object key: object
last: bool = True 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. Raise KeyError if the element does not exist.
When last=True, acts like a fast version of self[key]=self.pop(key).
[clinic start generated code]*/ [clinic start generated code]*/
static PyObject * static PyObject *
OrderedDict_move_to_end_impl(PyODictObject *self, PyObject *key, int last) 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; _ODictNode *node;