← 1.1.1 | 1.1.3 →

Documenting API changes since 1.1.1

The next stable version of Trac will be named 1.2 and will contain the cumulative changes made in the successive 1.1.x releases.

These notes reflect the current status for 1.1.2, in trunk​.

Proposed changes are prefixed with an OPEN mark and the paragraph is written in italics.

Summary

1. Prerequisites
   1. Modified Dependencies
      1. jQuery and jQuery UI (bundled)
      2. Babel (optional)
      3. Genshi (mandatory)
      4. Subversion (optional)
      5. Git (optional)
   2. New Dependencies
2. Detailed List of Developer Visible Changes
3. Other Modifications made to the 1.0 API
   1. Database API Changes
      1. Environment.get_db_cnx has been removed
      2. db parameters removed from function and method signatures
      3. ConnectionBase class
   2. Template and CSS changes
4. New in the 1.1.2 API

Prerequisites

Only Python versions 2.6 and 2.7 are supported.

Modified Dependencies

jQuery and jQuery UI (bundled)

The bundled version of ​jQuery will be 1.9 / 2.0 instead of 1.8.3 in Trac 1.1.1.

See jQuery release notes for the corresponding major updates:

• ​http://blog.jquery.com/2013/01/15/jquery-1-9-final-jquery-2-0-beta-migrate-final-released/

OPEN The bundled version of the full minified ​jQuery UI package will be ​1.10.1. See #11019.

Babel (optional)

The internationalization support (i18) for Trac is depending on ​Babel, version 0.9.6 and later. Support has been added for Babel 1.0 through 1.3 (the most recent at the time of this release).

Genshi (mandatory)

Genshi 0.6.x and 0.7 are supported.

Subversion (optional)

Subversion 1.6 - 1.8 are supported.

Git (optional)

Git 1.5.6 - 2.0 are supported.

New Dependencies

None!

Detailed List of Developer Visible Changes

Component: admin/web (2 matches)

Ticket	Summary
#10994	Add drag and drop and other dynamic behavior to the admin panels containing enum lists
API Changes	The function addSelectAllCheckboxes adds a Select All checkbox to the heading of a table, when executed on jQuery object that wraps a table. The tds containing the checkboxes must have the sel class.
#11519	Allow default_handler to be set from the Basic Settings admin page
API Changes	The IRequestHandler class attribute is_valid_default_handler determines if the class can be used as a default handler, and defaults to True when not present. The function is_valid_default_hanlder should be used to determine whether an IRequestHandler object is a valid default handler.
Component: database backend (1 match)
Ticket	Summary
#11581	Add an abstract base class for connection classes
API Changes	Added an abstract base class ConnectionBase for database connection classes.
Component: general (10 matches)
Ticket	Summary
#11056	Disable submit buttons if required items are not selected
API Changes	To add a datepicker or datetimepicker to an element, add the trac-datepicker and trac-datetimepicker classes respectively, and add jQuery UI and add-ons to the page using Chrome(self.env).add_jquery_ui(req) in process_request. To disable a submit button associated with a set of checkboxes or a file selector, add the trac-disable class to the submit button and add the trac-disable-determinant class to each checkbox or the file element. In both cases there is no need to add any specific JavaScript code to the page.
#11129	Handle CSS as text/css type
API Changes	The rendering method may be specified by the request handler as a fourth parameter in its response. The method is passed to post_process_request when the parameter is in the implementation's signature, and can be modified by the IRequestFilter. When not explicitly specified, the rendering method is still inferred from the content type when rendering the template.
#11406	diff.css is added twice on the diff_view page
API Changes	Plugins using diff_view.html will need to use add_stylesheet to add diff.css before rendering the template.
#11494	Remove deprecated functions and methods from 0.10 and earlier
API Changes	Removed functions and methods that have been deprecated since Trac 0.11 or earlier. trac.mimeview.api:Mimeview.get_max_preview_size trac.mimeview.api:Mimeview.to_utf8 trac.perm:PermissionCache.permissions trac.ticket.ReportModule.execute_report trac.util:pairwise trac.versioncontrol.diff:hdf_diff trac.web.chrome:add_javascript trac.wiki.api:IWikiMacroProvider.render_macro trac.wiki.web_ui:InvalidWikiPage addEvent, addHeadingLinks, enableControl and getAncestorByTagName from trac.js Removed functions and methods that were deprecated and scheduled for removal in Trac 1.0 or earlier: Removed macros.html and macros.rss, which have been deprecated since Trac 0.12. Removed accessor for default_ attributes in TicketModule. The options were moved to TicketSystem in Trac 0.12.
#11565	Reduce code duplication in about and error pages
API Changes	New template environment_info.html renders the System Information, Installed Plugins and Configuration Information. Added get_config_info method to the Environment class. Merged the about.css stylesheet into trac.css.
#11568	All Trac exceptions should inherit from a base class in Trac
API Changes	All exceptions defined in Trac inherit from TracBaseError.
#11587	Implement ISystemInfoProvider in git connector and database connection classes
API Changes	The db, web server and git version info are not directly appended to Environment.systeminfo. The version is instead provided through the ISystemInfoProvider interface. Environment.systeminfo might be made a private attribute in a future release of Trac.
#11600	Remove Python 2.5 compatibility
API Changes	Removed Python 2.5 compatibility: statements from __future__ import with_statement. trac.util.presentation.to_json for the case that json can't be imported. cleandoc definition in trac.util.compat. Utilized Python 2.6 features: PEP 3110 style exception catching, except X as e. Print function (from __future__ import print_function) (PEP 3105). Absolute imports (from __future__ import absolute_import). The function terminate in trac.util will accept either a subprocess.Popen object or integer process id as an input.
#11605	Remove deprecated db parameters
API Changes	The deprecated db parameters have been removed from the signatures of all public methods and functions. Added public method insert_changeset to CachedRepository and deprecated _insert_changeset. The db parameter in the signature of ReportModule.execute_paginated_report is deprecated and may be omitted. The db parameters in the signatures of IEnvironmentSetupParticipant.environment_needs_upgrade and IEnvironmentSetupParticipant.upgrade_environment are deprecated and may be omitted. Environment.get_read_db and the decorators @with_transaction(env) and env.with_transaction() are scheduled for removal in Trac 1.3.1. Environment.get_db_cnx has been removed.
#11609	Add realm attribute to Model classes
API Changes	Added realm attribute to model classes: Attachment, Milestone, Repository, Changeset, Node, Ticket and WikiPage.
Component: notification (1 match)
Ticket	Summary
#11636	Refactoring of trac.notification
API Changes	ListOption and Configuration.getlist support multiple separators, specified in a tuple or list.
Component: rendering (2 matches)
Ticket	Summary
#11126	Some templates could override layout (and theme) stylesheets with own stylesheets
API Changes	trac.web.chrome:add_stylesheet accepts arbitrary link attributes as trailing keyword arguments, and media is no longer a positional argument.
#11169	`render_resource_link` should add the "missing" class if the resource doesn't exist
API Changes	When get_resource_description doesn't return an Element (e.g. when the IResourceManager doesn't implement get_resource_description), render_resource_link adds the missing class and the rel=nofollow attribute if the resource has a ResourceManager and the resource doesn't exist. The realm is always added as a class. Added assertion with error message to check that the first argument to ComponentMeta is a ComponentManager.
Component: report system (2 matches)
Ticket	Summary
#11246	Having keywords in reports be followable
API Changes	parse_arg_list strips the leading ? from the query_string argument.
#11697	ReportModule uses magic number -1 where None should be used
API Changes	Added class attribute REPORT_LIST_ID to the ReportModule class, containing the resource id of the Report List page.
Component: ticket system (2 matches)
Ticket	Summary
#11145	wrap author information for ticket change comments in a span to make them stylable
API Changes	The authorinfo and authorinfo_short methods of the Chrome class in trac.web.chrome return the author wrapped in a span with class trac-author. Added author_email method of the Chrome class which returns the author email from the email_map dictionary if author doesn't already look like an email address. author_email is passed to templates in the Chrome data dictionary after partial evaluation with the email_map as a parameter, resulting in the signature author_email(author). The template author_or_creator.rss was refactored so that email_map doesn't need to be passed as a parameter.
#11499	Eliminate redundant code in milestone and admin milestone templates / modules
API Changes	Added methods to MilestoneModule class: get_default_due save_milestone Added function get_num_tickets_for_milestone (since 1.2; the similar method Milestone.get_num_tickets was added in 1.1.2, but replaced with get_num_tickets_for_milestone in 1.2). New template milestone_edit_form.html for editing a milestone is used on the milestone_edit.html and admin_milestone.html pages. The MilestoneModule is used in trac.ticket.admin.MilestoneAdminPanel to eliminate redundant code.
Component: version control (1 match)
Ticket	Summary
#11610	Move Changeset, Node and Repository classes to model.py
API Changes	Abstract base classes have abc.ABCMeta metaclass and use abstractmethod decorator on abstract methods. Mock has support for abstract base classes defined using abc.ABCMeta. A CachedChangeset instance rather than an instance of the abstract Changeset class is passed to the repository change listeners. Added EmptyChangeset class, an instance of which is returned by get_changes (in trac.versioncontrol.web_ui.util) when a NoSuchChangeset error is raised by the repository.
Component: wiki system (3 matches)
Ticket	Summary
#10834	Option to add line numbers to code blocks
API Changes	The WikiProcessor argument parser supports dashes in the argument value.
#11244	Permissions: setting a Wiki page "read-only" does not restrict adding attachments
API Changes	Added methods get_config, remove_config and set_config to the FunctionalTestEnvironment class.
#11544	Version argument in Resource object is ignored when initializing a WikiPage
API Changes	WikiPage __init__ method uses resource.version when version parameter is None. An invalid version or Resource.version is coerced to None.

Other Modifications made to the 1.0 API

Take the will be removed in version 1.1.1 comments in the code seriously. The earlier the planned API changes in 1.1.x, the better (gives more time to plugin authors to adapt). TODO

Database API Changes

Environment.get_db_cnx has been removed

Following the deprecation made in 0.12, the method Environment.get_db_cnx has been removed.

One should now only use the context managers for retrieving a database Connection in read or write mode.

• a read-only Connection can be used to form queries:

  with env.db_query as db:
      ...
  

  a db instance obtained the above way should only be used for executing SELECT queries
• a writable Connection can be used to modify the database content in a transaction:

  with env.db_transaction as db:
      ...
  

  a db instance obtained the above way can be used to execute INSERT/UPDATE/DELETE queries; they will be committed when the last such automatic transaction in the control flow completes successfully. See DatabaseApi for the full details.

Environment.get_read_db and the decorators @with_transaction(env) and env.with_transaction() have been deprecated since Trac 1.0 and will be removed in Trac 1.3.1.

db parameters removed from function and method signatures

With the introduction of @with_transaction(env) decorators in 0.12 and continuing with the introduction of the database connection context managers in 1.0, the db parameters passed as function and method arguments became deprecated.

The db parameters have been removed from nearly all function and method signatures. The db arguments are still present on methods of IEnvironmentParticipant implementations, but are deprecated and should no longer be used. They will be removed in 1.3.1.

ConnectionBase class

The ConnectionBase class defines an abstract interface that database backends must adhere to when implementing a Connection class.

Template and CSS changes

tt tags are not support in HTML5 and have been replaced with code tags in Trac (#11094). The styling of tt and code tags is the same in Trac , but code tags should be used since the styling for tt tags will be removed in a future version of Trac.

Many more changes to be added, depending on how details we want to get. TracUpgrade#CustomizedTemplates claims that changes to ids and CSS classes will be documented in ApiChanges.

New in the 1.1.2 API

Be sure to have a look at the new ApiDocs (​for latest trunk).

This is a work in progress - coverage is still not yet complete.