interfaces.py 3.61 KB
Newer Older
1
from zope.interface import Interface
Yusei Tahara's avatar
Yusei Tahara committed
2

3 4 5 6
class IPortalTransformsTool(Interface):
    """Marker interface for the portal_transforms tool."""

class IDataStream(Interface):
Yusei Tahara's avatar
Yusei Tahara committed
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42
    """data stream, is the result of a transform"""

    def setData(value):
        """set the main data produced by a transform, i.e. usually a string"""

    def getData():
        """provide access to the transformed data object, i.e. usually a string.
        This data may references subobjects.
        """

    def setSubObjects(objects):
        """set a dict-like object containing subobjects.
        keys should be object's identifier (e.g. usually a filename) and
        values object's content.
        """

    def getSubObjects():
        """return a dict-like object with any optional subobjects associated
        with the data"""

    def getMetadata():
        """return a dict-like object with any optional metadata from
        the transform
        You can modify the returned dictionnary to add/change metadata
        """
        
    def isCacheable():
        """Return a bool which indicates wether the result should be cached
        
        Default is true
        """
        
    def setCachable(value):
        """Set cacheable flag to yes or no
        """

43
class ITransform(Interface):
Yusei Tahara's avatar
Yusei Tahara committed
44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62
    """A transformation plugin -- tranform data somehow
    must be threadsafe and stateless"""

    def name(self):
        """return the name of the transform instance"""

    def convert(data, idata, filename=None, **kwargs):
        """convert the data, store the result in idata and return that

        optional argument filename may give the original file name of received data

        additional arguments given to engine's convert, convertTo or __call__ are
        passed back to the transform
        
        The object on which the translation was invoked is available as context
        (default: None)
        """


63
class IChain(ITransform):
Yusei Tahara's avatar
Yusei Tahara committed
64 65 66 67 68

    def registerTransform(transform, condition=None):
        """Append a transform to the chain"""


69
class IEngine(Interface):
Yusei Tahara's avatar
Yusei Tahara committed
70 71 72 73

    def registerTransform(transform):
        """register a transform

74
        transform must implements ITransform
Yusei Tahara's avatar
Yusei Tahara committed
75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118
        """

    def unregisterTransform(name):
        """ unregister a transform
        name is the name of a registered transform
        """

    def convertTo(mimetype, orig, data=None, object=None, context=None, **kwargs):
        """Convert orig to a given mimetype

        * orig is an encoded string

        * data an optional idatastream object. If None a new datastream will be
        created and returned

        * optional object argument is the object on which is bound the data.
        If present that object will be used by the engine to bound cached data.
        
        * optional context argument is the object on which the transformation
          was called.

        * additional arguments (kwargs) will be passed to the transformations.

        return an object implementing idatastream or None if no path has been
        found.
        """

    def convert(name, orig, data=None, context=None, **kwargs):
        """run a tranform of a given name on data

        * name is the name of a registered transform

        see convertTo docstring for more info
        """

    def __call__(name, orig, data=None, context=None, **kwargs):
        """run a transform by its name, returning the raw data product

        * name is the name of a registered transform.

        return an encoded string.
        see convert docstring for more info on additional arguments.
        """

119 120 121 122 123
# BBB
idatastream = IDataStream
ichain = IChain
iengine = IEngine
itransform = ITransform