= !TracDev/ApiChanges/0.12 =

[[PageOutline(2-4,Summary,inline)]]

== New Dependencies ==
=== Babel (optional) ===

The internationalization support (i18) for Trac is depending on [http://babel.edgewall.org/ 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` ^[source:trunk/trac/wiki/api.py@8372:85#L72 (0.12)] [source:branches/0.11-stable/trac/wiki/api.py@8372:90#L77 (0.11)]^ ==== #IWikiMacroProvider
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` ^[source:trunk/trac/wiki/api.py@8429:64#L52 (0.12)] [source:branches/0.11-stable/trac/wiki/api.py@8429:69#L57 (0.11)]^ ==== #IWikiPageManipulator
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 ^[source:trunk/trac/web/tests/href.py@8551:61-62,76-78#L57 (0.12)] [source:branches/0.11-stable/trac/web/tests/href.py@8551:63-64,79-81#L57 (0.11)]^ ==== #Href
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:
{{{
#!python
# 0.11
>>> href = Href('')             # Also applies to Href('/')
>>> href()
''
>>> href('/')
''
}}}
In 0.12, the same expressions return a valid relative URL:
{{{
#!python
# 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:
{{{
#!python
# 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:
{{{
#!python
# 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:
{{{
#!python
# 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` ^[source:trunk/trac/cache.py@#L87 (0.12)]^ ==== #CacheProxy

There's a new cache subsystem in [source:trunk/trac/cache.py 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` ^[source:trunk/trac/cache.py@#L25 (0.12)]^ 
 - `trac.cache.cached` ^[source:trunk/trac/cache.py@#L65 (0.12)]^ 

See TracDev/Proposals/CacheInvalidation#CacheManager 

=== New Interfaces ===
==== `trac.resource.IResourceManager` ^[source:trunk/trac/resource.py@#L28 (0.12)]^ ==== #IResourceManager

FIXME: just an example