Metadata-Version: 1.0
Name: plone.namedfile
Version: 1.0a1
Summary: File types tand fields for images, files and blob files with filenames
Home-page: http://pypi.python.org/pypi/plone.namedfile
Author: Laurence Rowe, Martin Aspeli
Author-email: plone-developers@lists.sourceforge.net
License: GPL
Description: Introduction
        ============
        
        This package contains fields and wrapper objects for storing:
        
        * A file with a filename
        * An image with a filename
        * A file stored in a ZODB blob, with a filename
        * An image stored in a ZODB blob, with a filename
        
        See the usage.txt doctest for more details.
        Changelog
        =========
        
        1.0a1 - 2009-04-17
        ------------------
        
        * Initial release
        
        
        Usage
        =====
        
        This demonstrates how to use the package.
        
        Test setup
        ----------
        
        We must first load the package's ZCML plus some dependencies. In your own
        code, only the last <include /> should be necessary.
        
        >>> configuration = """\
        ... <configure
        ...      xmlns="http://namespaces.zope.org/zope"
        ...      i18n_domain="plone.namedfile.tests">
        ...
        ...     <include package="zope.security" file="meta.zcml" />
        ...     <include package="zope.component" file="meta.zcml" />
        ...     <include package="zope.app.component" file="meta.zcml" />
        ...     <include package="zope.app.publisher" file="meta.zcml" />
        ...
        ...     <permission id="zope2.View" title="View" />
        ...
        ...     <include package="plone.namedfile" />
        ...
        ... </configure>
        ... """
        
        >>> from StringIO import StringIO
        >>> from zope.configuration import xmlconfig
        >>> xmlconfig.xmlconfig(StringIO(configuration))
        
        Schema fields
        -------------
        
        The following schema fields can be used to describe file data.
        
        >>> from zope.interface import Interface
        >>> from plone.namedfile import field
        
        >>> class IFileContainer(Interface):
        ...     simple = field.NamedFile(title=u"Named file")
        ...     image = field.NamedImage(title=u"Named image file")
        ...     blob = field.NamedBlobFile(title=u"Named blob file")
        ...     blobimage = field.NamedBlobImage(title=u"Named blob image file")
        
        These store data with the following types:
        
        >>> from zope.interface import implements
        >>> from plone import namedfile
        
        >>> class FileContainer(object):
        ...     implements(IFileContainer)
        ...     def __init__(self):
        ...         self.simple = namedfile.NamedFile()
        ...         self.image = namedfile.NamedImage()
        ...         self.blob = namedfile.NamedBlobFile()
        ...         self.blobimage = namedfile.NamedBlobImage()
        
        File data and content type
        --------------------------
        
        Let's now show how to get and set file data.
        
        The FileContainer class creates empty objects to start with.
        
        >>> container = FileContainer()
        
        >>> container.simple.data
        ''
        >>> container.simple.contentType
        ''
        >>> container.simple.filename is None
        True
        
        >>> container.image.data
        ''
        >>> container.image.contentType
        ''
        >>> container.image.filename is None
        True
        
        >>> container.blob.data
        ''
        >>> container.blob.contentType
        ''
        >>> container.blob.filename is None
        True
        
        >>> container.blobimage.data
        ''
        >>> container.blobimage.contentType
        ''
        >>> container.blobimage.filename is None
        True
        
        Let's now set some actual data in these files. Notice how the constructor
        will attempt to guess the filename from the file extension.
        
        >>> container.simple = namedfile.NamedFile('dummy test data', filename="test.txt")
        >>> container.simple.data
        'dummy test data'
        >>> container.simple.contentType
        'text/plain'
        >>> container.simple.filename
        'test.txt'
        
        >>> container.blob = namedfile.NamedBlobFile('dummy test data', filename="test.txt")
        >>> container.blob.data
        'dummy test data'
        >>> container.blob.contentType
        'text/plain'
        >>> container.blob.filename
        'test.txt'
        
        Let's also try to read a GIF, courtesy of the zope.app.file tests:
        
        >>> zptlogo = (
        ...     'GIF89a\x10\x00\x10\x00\xd5\x00\x00\xff\xff\xff\xff\xff\xfe\xfc\xfd\xfd'
        ...     '\xfa\xfb\xfc\xf7\xf9\xfa\xf5\xf8\xf9\xf3\xf6\xf8\xf2\xf5\xf7\xf0\xf4\xf6'
        ...     '\xeb\xf1\xf3\xe5\xed\xef\xde\xe8\xeb\xdc\xe6\xea\xd9\xe4\xe8\xd7\xe2\xe6'
        ...     '\xd2\xdf\xe3\xd0\xdd\xe3\xcd\xdc\xe1\xcb\xda\xdf\xc9\xd9\xdf\xc8\xd8\xdd'
        ...     '\xc6\xd7\xdc\xc4\xd6\xdc\xc3\xd4\xda\xc2\xd3\xd9\xc1\xd3\xd9\xc0\xd2\xd9'
        ...     '\xbd\xd1\xd8\xbd\xd0\xd7\xbc\xcf\xd7\xbb\xcf\xd6\xbb\xce\xd5\xb9\xcd\xd4'
        ...     '\xb6\xcc\xd4\xb6\xcb\xd3\xb5\xcb\xd2\xb4\xca\xd1\xb2\xc8\xd0\xb1\xc7\xd0'
        ...     '\xb0\xc7\xcf\xaf\xc6\xce\xae\xc4\xce\xad\xc4\xcd\xab\xc3\xcc\xa9\xc2\xcb'
        ...     '\xa8\xc1\xca\xa6\xc0\xc9\xa4\xbe\xc8\xa2\xbd\xc7\xa0\xbb\xc5\x9e\xba\xc4'
        ...     '\x9b\xbf\xcc\x98\xb6\xc1\x8d\xae\xbaFgs\x00\x00\x00\x00\x00\x00\x00\x00'
        ...     '\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'
        ...     '\x00,\x00\x00\x00\x00\x10\x00\x10\x00\x00\x06z@\x80pH,\x12k\xc8$\xd2f\x04'
        ...     '\xd4\x84\x01\x01\xe1\xf0d\x16\x9f\x80A\x01\x91\xc0ZmL\xb0\xcd\x00V\xd4'
        ...     '\xc4a\x87z\xed\xb0-\x1a\xb3\xb8\x95\xbdf8\x1e\x11\xca,MoC$\x15\x18{'
        ...     '\x006}m\x13\x16\x1a\x1f\x83\x85}6\x17\x1b $\x83\x00\x86\x19\x1d!%)\x8c'
        ...     '\x866#\'+.\x8ca`\x1c`(,/1\x94B5\x19\x1e"&*-024\xacNq\xba\xbb\xb8h\xbeb'
        ...     '\x00A\x00;'
        ...     )
        
        >>> container.image = namedfile.NamedImage(zptlogo, filename="zpt.gif")
        >>> container.image.data == zptlogo
        True
        >>> container.image.contentType
        'image/gif'
        >>> container.image.filename
        'zpt.gif'
        
        >>> container.blobimage = namedfile.NamedBlobImage(zptlogo, filename="zpt.gif")
        >>> container.blobimage.data == zptlogo
        True
        >>> container.blobimage.contentType
        'image/gif'
        >>> container.blobimage.filename
        'zpt.gif'
        
        Note that is possible for force the mimetype:
        
        >>> container.image = namedfile.NamedImage(zptlogo, contentType='image/foo', filename="zpt.gif")
        >>> container.image.data == zptlogo
        True
        >>> container.image.contentType
        'image/foo'
        >>> container.image.filename
        'zpt.gif'
        
        >>> container.blobimage = namedfile.NamedBlobImage(zptlogo, contentType='image/foo', filename="zpt.gif")
        >>> container.blobimage.data == zptlogo
        True
        >>> container.blobimage.contentType
        'image/foo'
        >>> container.blobimage.filename
        'zpt.gif'
        
        Download view
        -------------
        
        This package also comes with a view that can be used to download files. To
        use it, link to ../context-object/@@download/fieldname, where `fieldname` is
        the name of the attribute on the context-object where the named file is
        stored.
        
        We will test this with a dummy request, faking traversal.
        
        >>> from plone.namedfile.browser import Download
        >>> from zope.publisher.browser import TestRequest
        
        >>> request = TestRequest()
        >>> download = Download(container, request).publishTraverse(request, 'simple')
        >>> download()
        'dummy test data'
        >>> request.response.getHeader('Content-Length')
        '15'
        >>> request.response.getHeader('Content-Type')
        'text/plain'
        >>> request.response.getHeader('Content-Disposition')
        'attachment; filename="test.txt"'
        
        >>> request = TestRequest()
        >>> download = Download(container, request).publishTraverse(request, 'blob')
        >>> data = download()
        >>> data #doctest: +ELLIPSIS
        <open file ..., mode 'rb' at ...>
        >>> data.read()
        'dummy test data'
        
        >>> request.response.getHeader('Content-Length')
        '15'
        >>> request.response.getHeader('Content-Type')
        'text/plain'
        >>> request.response.getHeader('Content-Disposition')
        'attachment; filename="test.txt"'
        
        >>> request = TestRequest()
        >>> download = Download(container, request).publishTraverse(request, 'image')
        >>> download() == zptlogo
        True
        
        >>> request.response.getHeader('Content-Length')
        '341'
        >>> request.response.getHeader('Content-Type')
        'image/foo'
        >>> request.response.getHeader('Content-Disposition')
        'attachment; filename="zpt.gif"'
        
        >>> request = TestRequest()
        >>> download = Download(container, request).publishTraverse(request, 'blobimage')
        >>> data = download()
        >>> data #doctest: +ELLIPSIS
        <open file ..., mode 'rb' at ...>
        >>> data.read() == zptlogo
        True
        
        >>> request.response.getHeader('Content-Length')
        '341'
        >>> request.response.getHeader('Content-Type')
        'image/foo'
        >>> request.response.getHeader('Content-Disposition')
        'attachment; filename="zpt.gif"'
Keywords: plone named file image blob
Platform: UNKNOWN
Classifier: Framework :: Plone
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
