Merges two or more dictionaries into a single one.

    Optional keyword arguments allow to control the exact way
    in which the dictionaries will be merged.

    :param overwrite:

        Whether repeated keys should have their values overwritten,
        retaining the last value, as per given order of dictionaries.
        This is the default behavior (equivalent to ``overwrite=True``).
        If ``overwrite=False``, repeated keys are simply ignored.

        Example::

            >> merge({'a': 1}, {'a': 10, 'b': 2}, overwrite=True)
            {'a': 10, 'b': 2}
            >> merge({'a': 1}, {'a': 10, 'b': 2}, overwrite=False)
            {'a': 1, 'b': 2}

    :param deep:

        Whether merging should proceed recursively, and cause
        corresponding subdictionaries to be merged into each other.
        By default, this does not happen (equivalent to ``deep=False``).

        Example::

            >> merge({'a': {'b': 1}}, {'a': {'c': 2}}, deep=False)
            {'a': {'c': 2}}
            >> merge({'a': {'b': 1}}, {'a': {'c': 2}}, deep=True)
            {'a': {'b': 1, 'c': 2}}

    :return: Merged dictionary

    .. note:: For ``dict``\ s ``a`` and ``b``, ``merge(a, b)`` is equivalent
              to ``extend({}, a, b)``.

    .. versionadded:: 0.0.2
       The ``overwrite`` keyword argument.

def merge(*dicts, **kwargs):
    """Merges two or more dictionaries into a single one.

    Optional keyword arguments allow to control the exact way
    in which the dictionaries will be merged.

    :param overwrite:

        Whether repeated keys should have their values overwritten,
        retaining the last value, as per given order of dictionaries.
        This is the default behavior (equivalent to ``overwrite=True``).
        If ``overwrite=False``, repeated keys are simply ignored.

        Example::

            >> merge({'a': 1}, {'a': 10, 'b': 2}, overwrite=True)
            {'a': 10, 'b': 2}
            >> merge({'a': 1}, {'a': 10, 'b': 2}, overwrite=False)
            {'a': 1, 'b': 2}

    :param deep:

        Whether merging should proceed recursively, and cause
        corresponding subdictionaries to be merged into each other.
        By default, this does not happen (equivalent to ``deep=False``).

        Example::

            >> merge({'a': {'b': 1}}, {'a': {'c': 2}}, deep=False)
            {'a': {'c': 2}}
            >> merge({'a': {'b': 1}}, {'a': {'c': 2}}, deep=True)
            {'a': {'b': 1, 'c': 2}}

    :return: Merged dictionary

    .. note:: For ``dict``\ s ``a`` and ``b``, ``merge(a, b)`` is equivalent
              to ``extend({}, a, b)``.

    .. versionadded:: 0.0.2
       The ``overwrite`` keyword argument.
    """
    ensure_argcount(dicts, min_=1)
    dicts = list(imap(ensure_mapping, dicts))

    ensure_keyword_args(kwargs, optional=('deep', 'overwrite'))

    return _nary_dict_update(dicts, copy=True,
                             deep=kwargs.get('deep', False),
                             overwrite=kwargs.get('overwrite', True))