Edgewall Software
Home
Trac
Trac Hacks
Genshi
Babel
Bitten
Home
Download
Documentation
Mailing Lists
License
FAQ
Search:
Login
Preferences
Help/Guide
About Trac
Wiki
Timeline
Roadmap
Browse Source
View Tickets
New Ticket
Search
Context Navigation
-1
Start Page
Index
History
Editing TracDev/PluginDevelopment/ExtensionPoints/trac.attachment.IAttachmentManipulator
Adjust edit area height:
8
12
16
20
24
28
32
36
40
Edit side-by-side
== 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
Note:
See
WikiFormatting
and
TracWiki
for help on editing wiki content.
Change information
Your email or username:
E-mail address and name can be saved in the
Preferences
Comment about this change (optional):
Note:
See
TracWiki
for help on using the wiki.