Trac API Documentation Release 1.3.3.dev0 The Trac Team September 14, 2017 Contents 1 Content 3 2 Indices and tables 153 Python Module Index 155 i ii Trac API Documentation, Release 1.3.3.dev0 Release 1.3.3.dev0 Date September 14, 2017 This is work in progress. The API is not yet fully covered, but what you’ll find here should be accurate, otherwise it’s a bug and you’re welcome to open a ticket for reporting the problem. Contents 1 Trac API Documentation, Release 1.3.3.dev0 2 Contents CHAPTER 1 Content API Reference trac.about class trac.about.AboutModule Bases: trac.core.Component “About Trac” page provider, showing version information from third-party packages, as well as configuration information. trac.admin.api – Trac Administration panels Primary interface for managing administration panels. Interfaces class trac.admin.api.IAdminPanelProvider Bases: trac.core.Interface Extension point interface for adding panels to the web-based administration interface. See also trac.admin.api.IAdminPanelProvider extension point get_admin_panels(req) Return a list of available admin panels. The items returned by this function must be tuples of the form (category, category_label, page, page_label). render_admin_panel(req, category, page, path_info) Process a request for an admin panel. 3 Trac API Documentation, Release 1.3.3.dev0 This function should return a tuple of the form (template, data), where template is the name of the template to use and data is the data to use when rendering the template. Note: When a plugin wants to use a legacy Genshi template instead of a Jinja2 template, it needs to re- turn instead a triple of the form (template, data, None), similar to what IRequestHandler. process_request does. class trac.admin.api.IAdminCommandProvider Bases: trac.core.Interface Extension point interface for adding commands to the console administration interface trac-admin. See also trac.admin.api.IAdminCommandProvider extension point get_admin_commands() Return a list of available admin commands. The items returned by this function must be tuples of the form (command, args, help, complete, execute), where command contains the space-separated command and sub-command names, args is a string describing the command arguments and help is the help text. The first paragraph of the help text is taken as a short help, shown in the list of commands. complete is called to auto-complete the command arguments, with the current list of arguments as its only argument. It should return a list of relevant values for the last argument in the list. execute is called to execute the command, with the command arguments passed as positional arguments. Exceptions class trac.admin.api.AdminCommandError(msg, show_usage=False, cmd=None) Bases: trac.core.TracError Exception raised when an admin command cannot be executed. Components class trac.admin.api.AdminCommandManager Bases: trac.core.Component trac-admin command manager. complete_command(args, cmd_only=False) Perform auto-completion on the given arguments. execute_command(*args) Execute a command given by a list of arguments. get_command_help(args=[]) Return help information for a set of commands. providers List of components that implement IAdminCommandProvider Classes class trac.admin.api.PathList Bases: list 4 Chapter 1. Content Trac API Documentation, Release 1.3.3.dev0 A list of paths for command argument auto-completion. complete(text) Return the items in the list matching text. class trac.admin.api.PrefixList Bases: list A list of prefixes for command argument auto-completion. Helper Functions trac.admin.api.get_console_locale(env=None, lang=None, categories=(‘LANGUAGE’, ‘LC_ALL’, ‘LC_MESSAGES’, ‘LANG’)) Return negotiated locale for console by locale environments and [trac] default_language. trac.admin.api.get_dir_list(path, dirs_only=False) Return a list of paths to filesystem entries in the same directory as the given path. trac.admin.console trac.admin.console.run(args=None) Main entry point. trac.admin.web_ui class trac.admin.web_ui.AdminModule Bases: trac.core.Component Web administration interface provider and panel manager. panel_providers List of components that implement IAdminPanelProvider 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, re- named or reparented. See also trac.attachment.IAttachmentChangeListener extension point 1.1. API Reference 5 Trac API Documentation, Release 1.3.3.dev0 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, ATTACH- MENT_DELETE param username the user string param resource the Resource for the attachment. Note that when ATTACH- MENT_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 6 Chapter 1. Content Trac API Documentation, Release 1.3.3.dev0 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 1.1. API Reference 7 Trac API Documentation, Release 1.3.3.dev0 get_resource_url(resource, href, **kwargs) Return an URL to the attachment itself. A format keyword argument equal to 'raw' will be converted to