class Changes:
    """Manage a user's proposed configuration option changes.

    All changes are either cancelled or applied in a single transaction.

    Arguments used across multiple methods:
        These share the definition used in config.py.
        config_type
        section
        item
        value

    Methods used by ConfigDialog:
        add_item: Add an item to the the changes.
        apply: Apply changes to previous version for keysets and themes.
        delete_section: Remove a section for a config_type.
        save_all: Save all the changes to the config file.
        save_new_config: Apply all the changes for key        
        
    Methods used only for testing:
        
    Methods used internally:
        reset: Clear all changes.  Currently in the dialog, the cancel
            button closes the window and thus clears any changes.  This
            method may be useful in the future as a new dialog button.
        set_user_value: Set a single value for a config_type/section/item.

    TODO:
        - Evaluate extensions usage of this class.
        - One instance of class or one instance for each config_type?
        - Move all IdleConf.userCFg and IdleConf.defaultCfg access to this 
          class to separate that completely from GUI?

    """

    def __init__(self):  # new
        """Create configuration option change manager.

        Attributes:
            items: A 3-level hierarchical dictionary of pending
                changes that mirrors the definition in config.py.
                (XXX - should this be a ConfigParser like the
                 defaultCfg and userfg)
        """
        pass

    def __getitem__(self, config_type):  # new, but emulates changed_items['keys'], for example
        """Pythonic access to first level of object's values.
        """
        pass


    def add_item(self, config_type, section, item, value):  # renamed from add_changed_items
        """Add item/value pair for given config_type and section.
        """
        pass

    def apply(self, config_type, section, new_items):  # new (currently inline code for keys and highlight)
        """Apply changes to current selected config_type.

        One config entry for keysets and themes is the name of the
        keyset/theme and it contains all the settings for that entry.
        This applies the changes to a loaded keyset/theme to create a
        new list of item/value pairs.  The output is used as input
        to save_new_config.
        """
        # existing code sample ('highlight' is exactly the same except for variable names):
        # if prev_key_set_name in self.changed_items['keys']:
        #    key_set_changes = self.changed_items['keys'][prev_key_set_name]
        #    for event in key_set_changes:
        #        new_keys[event] = key_set_changes[event]

        pass

    def delete_section(self, config_type, section):  # new (currently inline)
        """Remove the section from the config_type entry.

        Similar to IdleConf.remove_section, but for current changes.
        """
        # existing code sample:
        # if key_set_name in self.changed_items['keys']:
        #     del(self.changed_items['keys'][key_set_name])
        pass

    def reset(self):  # renamed from reset_changed_items
        """Reset each config_type to an empty dictionary.

        Comment from existing reset_changed_items:
        # When any config item is changed in this dialog, an entry
        # should be made in the relevant section (config type) of this
        # dictionary. The key should be the config file section name and the
        # value a dictionary, whose key:value pairs are item=value pairs for
        # that config file section.

        """
        pass

    def save_all(self):  # renamed from save_all_changed_configs
        """Save configuration changes to the user config file.

        XXX - what to do with save_all_changed_extensions
        """
        pass

    def save_new_config(self, config_type, section, items_):  # renamed from save_new_key_set and save_new_theme
        """Update IdleConf.userCfg values for all sections within a config_type.

        This is used for keysets and themes since those have many items
        that represent what the keyset or theme is.
        """
        pass

    def set_user_value(self, config_type, section, item, value):  # old
        """Update a single IdleConf.userCfg item/value pair.

        Called from save_all for each item within each section for each
        config_type.
        """
        pass