def update_dictionary(default_dict, overwrite_dict=None, allow_unknown_keys=True):
    """Adds default key-value pairs to items in ``overwrite_dict``.

    Merges the items in ``default_dict`` and ``overwrite_dict``,
    preferring ``overwrite_dict`` if there are conflicts.

    Parameters
    ----------
    default_dict: `dict`
        Dictionary of default values.
    overwrite_dict: `dict` or None, optional, default None
        User-provided dictionary that overrides the defaults.
    allow_unknown_keys: `bool`, optional, default True
        If false, raises an error if ``overwrite_dict`` contains a key that is
        not in ``default_dict``.

    Raises
    ------
    ValueError
        if ``allow_unknown_keys`` is False and ``overwrite_dict``
        has keys that are not in ``default_dict``.

    Returns
    -------
    updated_dict : `dict`
        Updated dictionary.
        Returns ``overwrite_dicts``, with default values added
        based on ``default_dict``.
    """
    if overwrite_dict is None:
        overwrite_dict = {}

    if not allow_unknown_keys:
        extra_keys = overwrite_dict.keys() - default_dict.keys()
        if extra_keys:
            raise ValueError(f"Unexpected key(s) found: {extra_keys}. "
                             f"The valid keys are: {default_dict.keys()}")

    return dict(default_dict, **overwrite_dict)