diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -271,14 +271,18 @@ .. _func-dict: -.. function:: dict([arg]) +.. function:: dict(**kwarg) + dict(mapping, **kwarg) + dict(iterable, **kwarg) :noindex: - Create a new data dictionary, optionally with items taken from *arg*. - The dictionary type is described in :ref:`typesmapping`. + Create a new dictionary of type :class:`dict`. This function is the + constructor for the :class:`dict` class. See the :class:`dict` class for + the documentation of this function. See :ref:`typesmapping` for a + discussion of the dictionary type in general. - For other containers see the built in :class:`list`, :class:`set`, and - :class:`tuple` classes, and the :mod:`collections` module. + For other containers see the built-in :class:`list`, :class:`set`, and + :class:`tuple` classes, as well as the :mod:`collections` module. .. function:: dir([object]) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -2952,33 +2952,41 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: 'jack', 4127: 'sjoerd'}``, or by the :class:`dict` constructor. -.. class:: dict([arg]) - - Return a new dictionary initialized from an optional positional argument or - from a set of keyword arguments. If no arguments are given, return a new - empty dictionary. If the positional argument *arg* is a mapping object, - return a dictionary mapping the same keys to the same values as does the - mapping object. Otherwise the positional argument must be a sequence, a - container that supports iteration, or an iterator object. The elements of - the argument must each also be of one of those kinds, and each must in turn - contain exactly two objects. The first is used as a key in the new - dictionary, and the second as the key's value. If a given key is seen more - than once, the last value associated with it is retained in the new +.. class:: dict(**kwarg) + dict(mapping, **kwarg) + dict(iterable, **kwarg) + + Return a new dictionary initialized from an optional positional argument + and a possibly empty set of keyword arguments. + + If no positional argument is given, an empty dictionary is created. + If a positional argument is given and it is a mapping object, a dictionary + is created with the same key-value pairs as the mapping object. Otherwise, + the positional argument must be an :term:`iterator` object. Each item in + the iterable must itself be an iterator with exactly two objects. The + first object of each item is used as a key in the new dictionary, and the + second object as the corresponding value. If a key occurs more than once, + the last value for that key becomes the corresponding value in the new dictionary. - If keyword arguments are given, the keywords themselves with their associated - values are added as items to the dictionary. If a key is specified both in - the positional argument and as a keyword argument, the value associated with - the keyword is retained in the dictionary. For example, these all return a - dictionary equal to ``{"one": 1, "two": 2}``: - - * ``dict(one=1, two=2)`` - * ``dict({'one': 1, 'two': 2})`` - * ``dict(zip(('one', 'two'), (1, 2)))`` - * ``dict([['two', 2], ['one', 1]])`` - - The first example only works for keys that are valid Python identifiers; the - others work with any valid keys. + If keyword arguments are given, the keyword arguments and their values are + added to the dictionary created from the positional argument. If a key + being added is already present, the value from the keyword argument + replaces the value from the positional argument. + + To illustrate, the following examples all return a dictionary equal to + ``{"one": 1, "two": 2}``:: + + >>> a = dict(one=1, two=2) + >>> b = dict({'one': 1, 'two': 2}) + >>> c = dict(zip(('one', 'two'), (1, 2))) + >>> d = dict([['two', 2], ['one', 1]]) + >>> e = {"one": 1, "two": 2} + >>> a == b == c == d == e + True + + Providing keyword arguments as in the first example only works for keys that + are valid Python identifiers. Otherwise, any valid keys can be used. These are the operations that dictionaries support (and therefore, custom