[Python-checkins] cpython: Issues #29311, #29289: Fixed and improved docstrings for dict and OrderedDict
serhiy.storchaka
python-checkins at python.org
Tue Jan 24 17:30:31 EST 2017
https://hg.python.org/cpython/rev/ffc0840762e4
changeset: 106307:ffc0840762e4
user: Serhiy Storchaka <storchaka at gmail.com>
date: Wed Jan 25 00:30:04 2017 +0200
summary:
Issues #29311, #29289: Fixed and improved docstrings for dict and OrderedDict
methods.
files:
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
--- a/Lib/collections/__init__.py
+++ b/Lib/collections/__init__.py
@@ -157,9 +157,9 @@
dict.clear(self)
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.
-
'''
if not self:
raise KeyError('dictionary is empty')
@@ -180,11 +180,9 @@
return key, value
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_prev = link.prev
@@ -248,7 +246,10 @@
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 @@
@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
--- a/Objects/clinic/dictobject.c.h
+++ b/Objects/clinic/dictobject.c.h
@@ -6,7 +6,7 @@
"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 @@
"__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 @@
"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 @@
"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 @@
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
--- a/Objects/clinic/odictobject.c.h
+++ b/Objects/clinic/odictobject.c.h
@@ -6,9 +6,7 @@
"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 @@
"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 @@
"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 @@
"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 @@
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
--- a/Objects/dictobject.c
+++ b/Objects/dictobject.c
@@ -2311,12 +2311,12 @@
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 @@
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 @@
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 @@
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
--- a/Objects/odictobject.c
+++ b/Objects/odictobject.c
@@ -926,14 +926,12 @@
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 @@
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 @@
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 @@
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;
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list