== Extension Point : ''IAttachmentManipulator'' ==

||'''Interface'''||''IAttachmentManipulator''||'''Since'''||0.10||
||'''Module'''||''trac.attachment''||'''Source'''||[source:trunk/trac/attachment.py#/IAttachmentManipulator attachment.py]||

The ''IAttachmentManipulator'' can manipulate and validate attachments before saving.

== Purpose ==

Trac allows users to attach arbitrary files to e.g. tickets or wiki pages. Plugins can hook into the attachment module to tweak the attachment saving process.

The main purpose for this interface is to allow plugins to add new attachment validation rules. Attachments violating these rules are rejected.

== Usage ==

Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].

The `validate_attachment` method is called when a user adds a new attachment or replaces an existing attachment. Returning a list of messages rejects the attachment, returning `[]` accepts it.

Note that currently there is no easy way to validate the attachment's file ''contents''. (See #9281) The `req` parameter contains a file object in `req.args['attachment''].file` that can be read from. (Make sure to `seek` back to `0` or only the remaining file content after the current file position may be stored.)
{{{#!python
if 'attachment' in req.args:
    upload = req.args['attachment']
    try:
        data = upload.file.read(self.sample_size)
        if not is_binary(data):
            content = to_unicode(data)
    finally:
        upload.file.seek(0)
    filename = upload.filename
}}}

The `prepare_attachment` method should always be implemented as an empty dummy method for compatibility reasons:
{{{#!python
    def prepare_attachment(self, req, attachment, fields):
        pass
}}}

== Examples ==

A common use case for attachments is to attach patches to tickets. An open source project might require all such patches to be explicitly licensed under the BSD license.
The following minimal example IAttachmentManipulator implementation could enforce such a policy:
{{{#!python
from trac.core import Component, implements
from trac.attachment import IAttachmentManipulator
from trac.mimeview.api import get_mimetype

class PatchLicenseChecker(Component):
    implements(IAttachmentManipulator)

    def prepare_attachment(self, req, attachment, fields):
        pass

    def validate_attachment(self, req, attachment):
        mimetype = get_mimetype(attachment.filename)
        if mimetype == 'text/x-diff' and \
           not attachment.description.contains('BSD'):
           return [('description', "Patches must be released under BSD license")]
        return []
}}}

== Available Implementations ==

* SpamFilter: Reject attachments that contain spam
* th:AttachFilterPlugin: Reject attachments by MIME type (guessed from file extension)

== Additional Information and References ==

 * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.attachment.IAttachmentManipulator-class.html epydoc]
 * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_attachment.html#trac.attachment.IAttachmentManipulator API Reference]
 * See [../trac.attachment.IAttachmentChangeListener trac.attachment.IAttachmentChangeListener]
 * See [../trac.ticket.api.ITicketManipulator trac.ticket.api.ITicketManipulator], [../trac.wiki.api.IWikiPageManipulator trac.wiki.api.IWikiPageManipulator]
 * Introduced in changeset:3399
 * [TracDev/DatabaseSchema/Attachments Attachments database schema]
 * Related tickets:
  * [query:status!=closed&component=attachment attachment component]
  * #6014 Pre-/Post-processing for compression, virus-check, etc.
  * #9281 Easily accessing attachment data
  * #10125 Discusses unused `prepare_attachment` method
    * comment:15:ticket:10125 and following discuss ideas for fundamental refactoring
  * #10353 Multiple error messages (Fixed in 1.0)
    * comment:7:ticket:10353 and comment:8:ticket:10353 discuss ideas for attachment module refactoring