TracDev/ApiChanges/0.12

Summary

1. New Dependencies
   1. Babel (optional)
2. Modifications made to the 0.11 API
   1. Modified Interfaces
      1. IWikiMacroProvider ^{(0.12)​ (0.11)​}
      2. IWikiPageManipulator ^{(0.12)​ (0.11)​}
   2. Other Changes to the 0.11 API
      1. Href with an empty base ^{(0.12)​ (0.11)​}
3. New in the 0.12 API
   1. New Classes
      1. trac.cache.CacheProxy ^(0.12)​
   2. New Interfaces
      1. trac.resource.IResourceManager ^(0.12)​

New Dependencies

Babel (optional)

The internationalization support (i18) for Trac is depending on ​Babel.

It's perfectly fine to go on using Trac without it, but then of course the interface will remain in English.

Modifications made to the 0.11 API

Modified Interfaces

IWikiMacroProvider ^{(0.12)​ (0.11)​}

Added an optional argument args to IWikiMacroProvider.expand_macro() to contain the shebang-line arguments when using wiki processor syntax. For example, with the following content:

{{{
#!MyMacro test=123 other="This is a text"
This is the content.
}}}

The macro MyMacro will have its expand_macro() called with args={'test': '123', 'other': 'This is a text'}.

See also #8204.

IWikiPageManipulator ^{(0.12)​ (0.11)​}

This interface has not actually been changed, but the implementation has been fixed so that it actually does what it promises, that is, validate a wiki page after it's been populated from user input. Previously, page.text would contain the old text, and the new text would typically be retrieved with req.args.get('text') as a workaround.

The page now has the new text in page.text, and the old text in page.old_text.

See also #7731.

Other Changes to the 0.11 API

Href with an empty base ^{(0.12)​ (0.11)​}

The Href class has been changed to ensure that it always generates valid URLs, even with an empty base. In 0.11, the following uses all return an empty string:

# 0.11
>>> href = Href('')             # Also applies to Href('/')
>>> href()
''
>>> href('/')
''

In 0.12, the same expressions return a valid relative URL:

# 0.12
>>> href = Href('')
>>> href()
'/'
>>> href('/')
'/'

This change will break plugins that use the following idiom to concatenate the base URL with a path starting with a slash:

# 0.12
>>> href = Href('')
>>> path = '/path/to/page'
>>> href() + path               # Broken
'//path/to/page'

For this specific use case, a new syntax has been added to avoid doubled slashes:

# 0.12 and 0.11.6
>>> href = Href('')
>>> path = '/path/to/page'
>>> href + path                 # New syntax
'/path/to/page'

The new syntax has been backported to 0.11-stable in 0.11.6 to facilitate compatibility of plugins with both 0.11.6 and 0.12. If compatibility with older releases of the 0.11.x branch is required, the following code can be used:

# 0.12 and 0.11.x
>>> href = Href('')
>>> path = '/path/to/page'
>>> href().rstrip('/') + path   # Compatibility
'/path/to/page'

See also #8159.

New in the 0.12 API

New Classes

trac.cache.CacheProxy ^(0.12)​

There's a new cache subsystem in trac.cache​ so that Component instances can cache any data in a safe way. Whenever the cache entry is invalidated, the cached value will be automatically refreshed at the next retrieval, even if the invalidation occurs in a different process. This makes the config.touch() trick obsolete.

New decorators:

• trac.cache.cached_value ^(0.12)​
• trac.cache.cached ^(0.12)​

See TracDev/Proposals/CacheInvalidation#CacheManager

New Interfaces

trac.resource.IResourceManager ^(0.12)​

FIXME just an example