Source code for mg.core.element.utils.protocols

# MG_GPL_HEADER_BEGIN
# 
# This file is part of Media Gallery, GNU GPLv2.
# 
# Media Gallery is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; version 2 of the License.
# 
# Media Gallery is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# General Public License for more details.
# 
# You should have received a copy of the GNU General Public License
# along with Media Gallery; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
# 02110-1301, USA.
# 
# MG_GPL_HEADER_END

__author__ = "Media Gallery contributors <mg@lists.ssji.net>"
__copyright__ = "(c) 2010"
__credits__ = ["Dimitri Refauvelet", "Nicolas Pouillon"]

__all__ = ['ElementContainer', 'Importer']

class ElementContainer:
    """
    This is a basic protocol which permits to add and remove elements
    from a container. Stock containers are
    :py:class:`~mg.orga.roll.models.Roll` and
    :py:class:`~mg.orga.tree.models.Directory`.
    """
    
    def append(self, elem):
        """
        Appends an element to the current container

        :param elem: Element to add to this container
        """

    def remove(self, elem):
        """
        Removes an element form the current container

        :param elem: Element to remove from this container
        """

class Importer:
    """
    Each media application that may import files can provide a class
    implementing this protocol as
    ``<app>.management.utils.importer.Importer`` (i.e. a
    ``app/management/utils.importer.py`` file containing::

      from mg.core.element.utils import protocols

      class Importer(protocols.Importer):
          ...

    This class will be instanciated exactly once, and will be used
    through the two following methods for each imported file.

    See :ref:`tuto-new-media` for an example of such code.
    """
    
    def do_import(self, filename, datafile):
        """
        Handle the filename and the given fd as new element. Filename
        may not exist in the filesystem (it may resize in an archive).

        :param filename: New filename, may contain a path component
        :param datatile: Path to temporary file containing the data
        :returns: The new :py:class:`~mg.core.element.models.Element`
                  object
        """
        raise NotImplementedError()

    def can_handle(self, path, type):
        """
        Tells whether this importer can handle this file path and type.

        :param path: Relative path to a file, with full base
                     name. File is not required to exist (it may
                     reside inside an archive)
        :param type: Type of path, may be in ['F', 'D'].
        :returns: True or False
        """
        return False