Update Interfaces to improve API and support of multiple backends.

 * replace format by mimetype and avoid ambiguity in parameter names
 * remove specific method of ooo handler
 * improve consistency and reuse same parameter names


git-svn-id: https://svn.erp5.org/repos/public/erp5/trunk/utils@44989 20353a03-c40f-0410-a6d1-a30d3c3de9de

cloudooo/interfaces/granulate.py

@@ -30,44 +30,57 @@ from zope.interface import Interface
 
 
 class ITableGranulator(Interface):
-  """Provides methods to granulate a document into tables."""
+  """Provides methods to granulate a document into tables.
+  """
 
-  def getTableItemList(data, source_format):
-    """Returns the list of table IDs in the form of (id, title)."""
+  def getTableItemList(content, source_mimetype):
+    """Returns the list of table IDs in the form of (id, title).
+    """
 
-  def getTable(data, table_id, source_format):
-    """Returns the table into a new 'format' file."""
+  def getTable(content, source_mimetype, table_id ):
+    """Returns the table into a new 'format' file.
+    """
 
-  def getColumnItemList(data, table_id, source_format):
-    """Return the list of columns in the form of (id, title)."""
+  def getColumnItemList(content, source_mimetype, table_id):
+    """Return the list of columns in the form of (id, title).
+    """
 
-  def getLineItemList(data, table_id, source_format):
-    """Returns the lines of a given table as (key, value) pairs."""
+  def getLineItemList(content, source_mimetype, table_id):
+    """Returns the lines of a given table as (key, value) pairs.
+    """
 
 
 class IImageGranulator(Interface):
-  """Provides methods to granulate a document into images."""
+  """Provides methods to granulate a document into images.
+  """
 
-  def getImageItemList(data, source_format):
-    """Return the list of images in the form of (id, title)."""
+  def getImageItemList(content, source_mimetype):
+    """Return the list of images in the form of (id, title).
+    """
 
-  def getImage(data, image_id, source_format,
-               format=None, resolution=None, **kw):
-    """Return the given image."""
+  def getImage(content, filename, source_mimetype,
+               destination_mimetype=None, **kw):
+    """Return the given image.
+    """
 
 
 class ITextGranulator(Interface):
-  """Provides methods to granulate a document into chapters and paragraphs."""
+  """Provides methods to granulate a document into chapters and paragraphs.
+  """
 
-  def getParagraphItemList(data, source_format):
+  def getParagraphItemList(content, source_mimetype):
     """Returns the list of paragraphs in the form of (id, class) where class
-    may have special meaning to define TOC/TOI."""
+    may have special meaning to define TOC/TOI.
+    """
 
-  def getParagraph(data, paragraph_id, source_format):
-    """Returns the paragraph in the form of (text, class)."""
+  def getParagraph(content, source_mimetype, paragraph_id):
+    """Returns the paragraph in the form of (text, class).
+    """
 
-  def getChapterItemList(data, source_format):
-    """Returns the list of chapters in the form of (id, level)."""
+  def getChapterItemList(content, source_mimetype):
+    """Returns the list of chapters in the form of (id, level).
+    """
 
-  def getChapterItem(data, chapter_id, source_format):
-    """Return the chapter in the form of (title, level)."""
+  def getChapterItem(content, source_mimetype, chapter_id):
+    """Return the chapter in the form of (title, level).
+    """

cloudooo/interfaces/handler.py

@@ -28,16 +28,18 @@
 
 from zope.interface import Interface
 
-
 class IHandler(Interface):
-  """Handles connections with the openoffice by socket"""
+  """Handles communications between manager and specific backends
+  """
 
-  def convert(destination_format):
-    """Convert document to ODF"""
+  def convert(destination_mimetype):
+    """Convert to expected format
+    """
 
-  def getMetadata(converted_data):
-    """Returns a dictionary with all metadata of document. If converted_data is
-    True, the document is added in dictionary."""
+  def getMetadata():
+    """Returns a dictionary with all metadata of document.
+    """
 
   def setMetadata(metadata_dict):
-    """Returns a document with the new metadata"""
+    """Returns a document with the new metadata
+    """

cloudooo/interfaces/manager.py

@@ -30,33 +30,83 @@ from zope.interface import Interface
 
 
 class IManager(Interface):
-  """Provides method to manipulate documents and metadatas using OOo"""
+  """Provides public method to communicate with Cloudooo clients
+  """
 
-  def convertFile(file, source_format, destination_format, zip, refresh):
+  def convertFile(content, source_mimetype, destination_mimetype, **kw):
     """Returns the converted file in the given format.
 
-    zip parameter can be specified to return the result of conversion
-    in the form of a zip archive (which may contain multiple parts).
-    This can be useful to convert a single ODF file to HTML
-    and png images.
+    content : binary data to convert
+    source_mimetype : mimetype of given content
+    destination_mimetype : expected output conversion mimetype
+
+    **kw holds specific parameters for the conversion
     """
 
-  def getFileMetadataItemList(file, source_format, base_document):
+  def convertBundle(content, filename, source_mimetype, destination_mimetype,
+                    **kw):
+    """The content must be a zip archive with multiples files.
+    filename is the authority file to convert inside archive.
+    All other files are embedded object usefull to perform the conversion
+    like css, images, videos, audio files, ...
+    It returns the converted data.
+
+    content : zip bundle
+    filename: filename of authority file to extract from the bundle.
+    source_mimetype : mimetype of given authority file
+    destination_mimetype : expected output conversion mimetype
+
+    **kw holds specific parameters for the conversion
+    """
+
+  def getFileMetadataItemList(content, source_mimetype):
     """Returns a list key, value pairs representing the
     metadata values for the document. The structure of this
     list is "unpredictable" and follows the convention of each file.
+
+    content : binary data where to reads metadata
+    source_mimetype : mimetype of given content
+    """
+
+  def convertFileAndGetMetadataItemList(content, source_mimetype,
+                                            destination_mimetype, **kw):
+    """returns a converted version of provided content plus a
+    dictionary of extracted metadata.
+    signature of method is same as convertFile
+
+    result is a json dictionary with 'conversion' and
+    'metadata' entries.
     """
 
-  def updateFileMetadata(file, source_format, metadata_dict):
-    """Updates the file in the given source_format with provided metadata and
-    return the resulting new file."""
+  def updateFileMetadata(content, source_mimetype, metadata_dict):
+    """Updates the content with provided metadata and
+    return the new file.
+
+    content : binary data to convert
+    source_mimetype : mimetype of given content
+    metadata_dict : Metadatas to include in content
+    """
 
-  def getAllowedExtensionList(request_dict):
-    """Returns a list extension which can be generated from given extension or
-    document type."""
+  def getAllowedConversionFormatList(source_mimetype):
+    """Returns a list content_type and their titles which are supported
+    by enabled handlers.
+
+    [('application/vnd.oasis.opendocument.text', 'ODF Text Document'),
+     ('application/pdf', 'PDF - Portable Document Format'),
+     ...
+    ]
+    """
 
-  def granulateFile(file, source_format, zip):
-    """Returns a zip file with parts of an document splited by grains."""
+  def getAllowedConversionFormatInfoList(source_mimetype):
+    """Returns a list content_type and list of parameter which are supported
+    by enabled handlers.
+
+    (see IMimemapper.getAllowedExtensionInfoList)
+    """
+
+  def granulateFile(content, source_mimetype):
+    """Returns a zip file with parts of an document splited by grains.
+    """
 
 
 class IERP5Compatibility(Interface):

cloudooo/interfaces/mimemapper.py

@@ -30,24 +30,24 @@ from zope.interface import Interface
 
 
 class IMimemapper(Interface):
-  """Provide methods to manipulate filters of OOo."""
+  """Provide methods to manipulate conversion abilities of
+  handlers
+  """
 
   def isLoaded():
-    """Returns if the filters were loaded."""
-
-  def getDocumentTypeDict():
-    """Returns document type dict."""
-
-  def getFilterName(extension, document_type):
-    """Returns the name of filter according to parematers passed."""
-
-  def loadFilterList(**kwargs):
-    """Load all filters of openoffice."""
+    """Returns if mimemapper is bootstraped
+    """
 
-  def getFilterList(extension, **kwargs):
-    """Returns a filter list according to extension or other parameters passed.
+  def loadMimemapper():
+    """bootstrap mimemapper of handler
     """
 
-  def getAllowedExtensionList(document_type, **kwargs):
-    """Returns a list with extensions which can be used to export according to
-    document type passed."""
+  def getAllowedExtensionInfoList(mimetype):
+    """Return a detailed list of output mimetypes with a list of
+    accepted parameter to perform the conversion:
+      application/pdf: [('text/plain', ()),
+                        ('image/png', ('frame', 'resolution', 'width', 'height',
+                        'colorspace',)),
+                        ...
+                       ]
+    """