class ProfileStorage:
    """An encapsulation of all the files which make up the
    contents of a profile.

    The files are stored in a ZIP file which metadata. In
    order to add/extract files to the profile, they are first
    copied to/from a temporary directory which is then zipped.
    Note, though, that the fact that its a ZIP file and the
    fact that there is a temporary directory are both
    implementation details and not exposed in the API.

    Profile files are stored in /etc/desktop-profiles.

    Each file or directory in the profile has metadata
    associated with it - the "source" of the file/directory
    and a set of arbitrary key value pairs which that source
    may interpret.

    The profile also contains a revision history, allowing
    you to revert to a previous version of a given file
    or a previous version of the profile itself.
    """
    
    def __init__ (self, name):
        """Create a ProfileStorage.

        @name: the name of the profile - translates to
        /etc/desktop-profiles/$(name).zip.
        """

    def copy (self, name):
        """Create a new ProfileStorage object, copying the
        contents of this profile to the new profile.

        @name: the name of the new profile.

        Return value: a #ProfileStorage object.
        """

    def add (self, path, src_dir, source, *metadata):
        """Add a new - or update an existing - file or directory
        to the profile. If @path is a directory, then the contents
        of the directory will be recursively saved in the profile.

        @path: the relative path of the file or directory.
        @src_dir: the directory (which @path is relative to) from
        which the file or directory contents should be copied to
        the profile.
        @source: the name of the #ProfileSource with which the file
        or directory is associated.
        @metadata: a varargs list of arbitrary key/value pairs (specific
        to @source) which should be saved.
        """

    def remove (self, path):
        """Remove a file or directory from the profile.

        @path: the relative path of the file or directory. This is
        the same path used with ProfileStorage::add().
        """

    def extract (self, path, dst_dir, revision = None):
        """Extract a file or directory from the profile.

        @path: the relative path of the file or directory to extract.
        This is the same path used with ProfileStorage::add().
        @dst_dir: the directory to which the file or directory specified
        by @path should be extracted. Any subdirectories of @dst_dir
        specified by @path will be created.
        @revision: an (optional) revision identifier which specifies
        the revision of the file or directory which should be extracted.
        The revision identifier must have been returned from
        ProfileStorage::get_revisions() and may be a profile or file
        revision.
        """

    def list (self, source = None, revision = None):
        """List the current contents of the profile.

        @source: an (optional) identifier of the source whose
        files should be listed. This is identifier as @source
        passed to ProfileStorage::add().
        @revision: specify the profile revision whose contents
        should be listed. Defaults to the current revision. The
        special revision "all" specifies that files and directories
        should be listed if they existed in any revision

        Return value: a list of (@source, @path) tuples.
        """

    def foreach (self, callback, user_data = None, source = None):
        """Iterate over the contents of the profile:

        @callback: an function or method of which takes 
        at least two arguments - @source and @path. If @callback
        is a method, the object which the method is associated
        will be the first parameter. If @user_data is passed,
        then it will be the final parameter to the callback.
        @user_data: an (optional) parameter to pass to @callback.
        @source: an (optional) identifier of the source whose
        files should be listed.
        """

    def save (self):
        """Save the contents of the profile to
        /etc/desktop-profiles/$(name).zip.
        """

    def get_metadata (self, path):
        """Return the metadata associated with a file or directory
        from the profile.

        @path: the relative path of the file or directory to extract.
        This is the same path used with ProfileStorage::add().

        Return value: a dictionary containing the key/value pairs
        passed to ProfileStorage::add().
        """

    def get_revisions (self, path = None):
        """Retrieve the list of profile revisions or the list of
        revisions of a given file or directory.
        
        @path: the relative path of the file or directory to extract.
        This is the same path used with ProfileStorage::add().

        Return value: a list of revision identifiers for the profile
        or file/directory in chronological order.
        """