trac.ticket.api

class trac.ticket.api.TicketFieldList(*args)

Bases: list

Improved ticket field list, allowing access by name.

append(value)

L.append(object) – append object to end

class trac.ticket.api.ITicketActionController

Bases: trac.core.Interface

Extension point interface for components willing to participate in the ticket workflow.

This is mainly about controlling the changes to the ticket ‘’status’’, though not restricted to it.

get_ticket_actions(ticket)

Return an iterable of (weight, action) tuples corresponding to the actions that are contributed by this component. The list is dependent on the current state of the ticket and the actual request parameter.

action is a key used to identify that particular action. (note that ‘history’ and ‘diff’ are reserved and should not be used by plugins)

The actions will be presented on the page in descending order of the integer weight. The first action in the list is used as the default action.

When in doubt, use a weight of 0.

get_all_status()

Returns an iterable of all the possible values for the ‘’status’’ field this action controller knows about.

This will be used to populate the query options and the like. It is assumed that the terminal status of a ticket is ‘closed’.

render_ticket_action_control(ticket, action)

Return a tuple in the form of (label, control, hint)

label is a short text that will be used when listing the action, control is the markup for the action control and hint should explain what will happen if this action is taken.

This method will only be called if the controller claimed to handle the given action in the call to get_ticket_actions.

Note that the radio button for the action has an id of "action_%s" % action. Any id`s used in `control need to be made unique. The method used in the default ITicketActionController is to use "action_%s_something" % action.

get_ticket_changes(ticket, action)

Return a dictionary of ticket field changes.

This method must not have any side-effects because it will also be called in preview mode (req.args['preview'] will be set, then). See apply_action_side_effects for that. If the latter indeed triggers some side-effects, it is advised to emit a warning (trac.web.chrome.add_warning(req, reason)) when this method is called in preview mode.

This method will only be called if the controller claimed to handle the given action in the call to get_ticket_actions.

apply_action_side_effects(ticket, action)

Perform side effects once all changes have been made to the ticket.

Multiple controllers might be involved, so the apply side-effects offers a chance to trigger a side-effect based on the given action after the new state of the ticket has been saved.

This method will only be called if the controller claimed to handle the given action in the call to get_ticket_actions.

class trac.ticket.api.ITicketChangeListener

Bases: trac.core.Interface

Extension point interface for components that require notification when tickets are created, modified, or deleted.

ticket_created()

Called when a ticket is created.

ticket_changed(comment, author, old_values)

Called when a ticket is modified.

old_values is a dictionary containing the previous values of the fields that have changed.

ticket_deleted()

Called when a ticket is deleted.

ticket_comment_modified(cdate, author, comment, old_comment)

Called when a ticket comment is modified.

ticket_change_deleted(cdate, changes)

Called when a ticket change is deleted.

changes is a dictionary of tuple (oldvalue, newvalue) containing the ticket change of the fields that have changed.

class trac.ticket.api.ITicketManipulator

Bases: trac.core.Interface

Miscellaneous manipulation of ticket workflow features.

prepare_ticket(ticket, fields, actions)

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

validate_ticket(ticket)

Validate ticket properties when creating or modifying.

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

validate_comment(comment)

Validate ticket comment when appending or editing.

Must return a list of messages, one for each problem detected. The return value [] indicates no problems.

Since:1.3.2

class trac.ticket.api.IMilestoneChangeListener

Bases: trac.core.Interface

Extension point interface for components that require notification when milestones are created, modified, or deleted.

milestone_created()

Called when a milestone is created.

milestone_changed(old_values)

Called when a milestone is modified.

old_values is a dictionary containing the previous values of the milestone properties that changed. Currently those properties can be ‘name’, ‘due’, ‘completed’, or ‘description’.

milestone_deleted()

Called when a milestone is deleted.

class trac.ticket.api.TicketSystem

Bases: trac.core.Component

change_listeners

List of components that implement ITicketChangeListener

milestone_change_listeners

List of components that implement IMilestoneChangeListener

ticket_custom_section

In this section, you can define additional fields for tickets. See TracTicketsCustomFields for more details.

action_controllers

Ordered list of workflow controllers to use for ticket actions.

restrict_owner

Make the owner field of tickets use a drop-down menu. Be sure to understand the performance implications before activating this option. See [TracTickets#Assign-toasDrop-DownList Assign-to as Drop-Down List].

Please note that e-mail addresses are ‘’’not’’’ obfuscated in the resulting drop-down menu, so this option should not be used if e-mail addresses must remain protected.

default_version

Default version for newly created tickets.

default_type

Default type for newly created tickets.

default_priority

Default priority for newly created tickets.

default_milestone

Default milestone for newly created tickets.

default_component

Default component for newly created tickets.

default_severity

Default severity for newly created tickets.

default_summary

Default summary (title) for newly created tickets.

default_description

Default description for newly created tickets.

default_keywords

Default keywords for newly created tickets.

default_owner

Default owner for newly created tickets. The component owner is used when set to the value < default >.

default_cc

Default cc: list for newly created tickets.

default_resolution

Default resolution for resolving (closing) tickets.

allowed_empty_fields

Comma-separated list of select fields that can have an empty value. (//since 1.1.2//)

max_comment_size

Maximum allowed comment size in characters.

max_description_size

Maximum allowed description size in characters.

max_summary_size

Maximum allowed summary size in characters. (//since 1.0.2//)

get_available_actions(req, ticket)

Returns a sorted list of available actions

get_all_status()

Returns a sorted list of all the states all of the action controllers know about.

get_ticket_field_labels()

Produce a (name,label) mapping from get_ticket_fields.

get_ticket_fields()

Returns list of fields available for tickets.

Each field is a dict with at least the ‘name’, ‘label’ (localized) and ‘type’ keys. It may in addition contain the ‘custom’ key, the ‘optional’ and the ‘options’ keys. When present ‘custom’ and ‘optional’ are always True.

reset_ticket_fields()

Invalidate ticket field cache.

fields

Return the list of fields available for tickets.

custom_fields

Return the list of custom ticket fields available for tickets.

get_field_synonyms()

Return a mapping from field name synonyms to field names. The synonyms are supposed to be more intuitive for custom queries.

eventually_restrict_owner(field, ticket=None)

Restrict given owner field to be a list of users having the TICKET_MODIFY permission (for the given ticket)

get_allowed_owners(ticket=None)

Returns a list of permitted ticket owners (those possessing the TICKET_MODIFY permission). Returns None if the option [ticket] restrict_owner is False.

If ticket is not None, fine-grained permission checks are used to determine the allowed owners for the specified resource.

Since:1.0.3

resource_exists(resource)

>>> from trac.test import EnvironmentStub
>>> from trac.resource import Resource, resource_exists
>>> env = EnvironmentStub()

>>> resource_exists(env, Resource('ticket', 123456))
False

>>> from trac.ticket.model import Ticket
>>> t = Ticket(env)
>>> int(t.insert())
1
>>> resource_exists(env, t.resource)
True