Changes between Initial Version and Version 1 of TracDev/PluginDevelopment/ExtensionPoints/trac.attachment.IAttachmentManipulator

Timestamp:

Jul 20, 2012, 8:10:30 PM (12 years ago)

Author:

Peter Suter

Comment:

—

TracDev/PluginDevelopment/ExtensionPoints/trac.attachment.IAttachmentManipulator

@@ +1 @@
+== 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
+ * See trac.ticket.api.ITicketManipulator, 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