trac.attachment – Attachments for Trac resources

This module contains the Attachment model class and the AttachmentModule component which manages file attachments for any kind of Trac resources. Currently, the wiki pages, tickets and milestones all support file attachments. You can use the same utility methods from the AttachmentModule as they do for easily adding attachments to other kinds of resources.

See also the attach_file_form.html and attachment.html templates which can be used to display the attachments.

Interfaces

class trac.attachment.IAttachmentChangeListener

Bases: trac.core.Interface

Extension point interface for components that require notification when attachments are created, deleted, renamed or reparented.

See also trac.attachment.IAttachmentChangeListener extension point

attachment_added(attachment)

Called when an attachment is added.

attachment_deleted(attachment)

Called when an attachment is deleted.

attachment_moved(attachment, old_parent_realm, old_parent_id, old_filename)

Called when an attachment is moved.

attachment_reparented(attachment, old_parent_realm, old_parent_id)

Called when an attachment is reparented.

Since 1.3.2:deprecated and will be removed in 1.5.1. Use attachment_moved instead.

class trac.attachment.IAttachmentManipulator

Bases: trac.core.Interface

Extension point interface for components that need to manipulate attachments.

Unlike change listeners, a manipulator can reject changes being committed to the database.

See also trac.attachment.IAttachmentManipulator extension point

prepare_attachment(req, attachment, fields)

Not currently called, but should be provided for future compatibility.

validate_attachment(req, attachment)

Validate an attachment after upload but before being stored in Trac environment.

Must return a list of (field, message) tuples, one for each problem detected. field can be any of description, username, filename, content, or None to indicate an overall problem with the attachment. Therefore, a return value of [] means everything is OK.

class trac.attachment.ILegacyAttachmentPolicyDelegate

Bases: trac.core.Interface

Interface that can be used by plugins to seamlessly participate to the legacy way of checking for attachment permissions.

This should no longer be necessary once it becomes easier to setup fine-grained permissions in the default permission store.

See also trac.attachment.ILegacyAttachmentPolicyDelegate extension point

check_attachment_permission(action, username, resource, perm)

Return the usual True/False/None security policy decision appropriate for the requested action on an attachment.

param action:one of ATTACHMENT_VIEW, ATTACHMENT_CREATE, ATTACHMENT_DELETE param username:the user string param resource:the Resource for the attachment. Note that when ATTACHMENT_CREATE is checked, the resource .id will be None. param perm:the permission cache for that username and resource

Classes

class trac.attachment.Attachment(env, parent_realm_or_attachment_resource, parent_id=None, filename=None)

Bases: object

Represents an attachment (new or existing).

delete()

Delete the attachment, both the record in the database and the file itself.

classmethod delete_all(env, parent_realm, parent_id)

Delete all attachments of a given resource.

insert(filename, fileobj, size, t=None)

Create a new Attachment record and save the file content.

move(new_realm=None, new_id=None, new_filename=None)

Move the attachment, changing one or more of its parent realm, parent id and filename.

The new parent resource must exist.

Since:1.3.2

reparent(new_realm, new_id)

Change the attachment’s parent_realm and/or parent_id

Since 1.3.2:deprecated and will be removed in 1.5.1. Use the move method instead.

classmethod reparent_all(env, parent_realm, parent_id, new_realm, new_id)

Reparent all attachments of a given resource to another resource.

classmethod select(env, parent_realm, parent_id)

Iterator yielding all Attachment instances attached to resource identified by parent_realm and parent_id.

Returns:a tuple containing the filename, description, size, time and author.

exception trac.attachment.InvalidAttachment(message, title=None, show_traceback=False)

Bases: trac.core.TracError

Exception raised when attachment validation fails.

Since 1.3.2:deprecated and will be removed in 1.5.1

If message is an Element object, everything up to the first <p> will be displayed in the red box, and everything after will be displayed below the red box. If title is given, it will be displayed as the large header above the error message.

Components

class trac.attachment.AttachmentModule

Bases: trac.core.Component

attachment_data(context)

Return a data dictionary describing the list of viewable attachments in the current context.

change_listeners

List of components that implement IAttachmentChangeListener

get_history(start, stop, realm)

Return an iterable of tuples describing changes to attachments on a particular object realm.

The tuples are in the form (change, realm, id, filename, time, description, author). change can currently only be created.

FIXME: no iterator

get_resource_url(resource, href, **kwargs)

Return an URL to the attachment itself.

A format keyword argument equal to 'raw' will be converted to the raw-attachment prefix.

get_search_results(req, resource_realm, terms)

Return a search result generator suitable for ISearchSource.

Search results are attachments on resources of the given resource_realm.realm whose filename, description or author match the given terms.

get_timeline_events(req, resource_realm, start, stop)

Return an event generator suitable for ITimelineEventProvider.

Events are changes to attachments on resources of the given resource_realm.realm.

manipulators

List of components that implement IAttachmentManipulator

max_size

Maximum allowed file size (in bytes) for attachments.

max_zip_size

Maximum allowed total size (in bytes) for an attachment list to be downloadable as a zip. Set this to -1 to disable download as zip. (‘’since 1.0’‘)

render_unsafe_content

Whether attachments should be rendered in the browser, or only made downloadable.

Pretty much any file may be interpreted as HTML by the browser, which allows a malicious user to attach a file containing cross-site scripting attacks.

For public sites where anonymous users can create attachments it is recommended to leave this option disabled.

viewable_attachments(context)

Return the list of viewable attachments in the given context.

Parameters:context – the RenderingContext corresponding to the parent Resource for the attachments

class trac.attachment.AttachmentAdmin

Bases: trac.core.Component

trac-admin command provider for attachment administration.