Genshi: Upgrading Genshi

# Upgrading Genshi

Contents

# 1 Upgrading from Genshi 0.6.x to the development version

The Genshi development version now supports both Python 2 and Python 3.

The most noticable API change in the Genshi development version is that the default encoding in numerous places is now None (i.e. unicode) instead of UTF-8. This change was made in order to ease the transition to Python 3 where strings are unicode strings by default.

If your application relies on the default UTF-8 encoding a simple way to have it work both with Genshi 0.6.x and the development version is to specify the encoding explicitly in calls to the following classes, methods and functions:

- genshi.HTML
- genshi.Stream.render
- genshi.input.HTMLParser
- genshi.template.MarkupTemplate
- genshi.template.TemplateLoader
- genshi.template.TextTemplate (and genshi.template.NewTextTemplate)
- genshi.template.OldTextTemplate

Whether you explicitly specify UTF-8 or explicitly specify None (unicode) is a matter of personal taste, although working with unicode may make porting your own application to Python 3 easier.

# 2 Upgrading from Genshi 0.5.x to 0.6.x

## 2.1 Required Python Version

Support for Python 2.3 has been dropped in this release. Python 2.4 is now the minimum version of Python required to run Genshi.

The XPath engine has been completely overhauled for this version. Some patterns that previously matched incorrectly will no longer match, and the other way around. In such cases, the XPath expressions need to be fixed in your application and templates.

# 3 Upgrading from Genshi 0.4.x to 0.5.x

## 3.1 Error Handling

The default error handling mode has been changed to "strict". This means that accessing variables not defined in the template data will now generate an immediate exception, as will accessing object attributes or dictionary keys that don't exist. If your templates rely on the old lenient behavior, you can configure Genshi to use that instead. See the documentation for details on how to do that. But be warned that lenient error handling may be removed completely in a future release.

## 3.2 Match Template Processing

There has also been a subtle change to how `py:match` templates are processed: in previous versions, all match templates would be applied to the content generated by the matching template, and only the matching template itself was applied recursively to the original content. This behavior resulted in problems with many kinds of recursive matching, and hence was changed for 0.5: now, all match templates declared before the matching template are applied to the original content, and match templates declared after the matching template are applied to the generated content. This change should not have any effect on most applications, but you may want to check your use of match templates to make sure.

## 3.3 Text Templates

Genshi 0.5 introduces a new, alternative syntax for text templates, which is more flexible and powerful compared to the old syntax. For backwards compatibility, this new syntax is not used by default, though it will be in a future version. It is recommended that you migrate to using this new syntax. To do so, simply rename any references in your code to `TextTemplate` to `NewTextTemplate`. To explicitly use the old syntax, use `OldTextTemplate` instead, so that you can be sure you'll be using the same language when the default in Genshi is changed (at least until the old implementation is completely removed).

## 3.4 `Markup` Constructor

The `Markup` class no longer has a specialized constructor. The old (undocumented) constructor provided a shorthand for doing positional substitutions. If you have code like this:

    Markup('<b>%s</b>', name)

You must replace it by the more explicit:

    Markup('<b>%s</b>') % name

## 3.5 `Template` Constructor

The constructor of the `Template` class and its subclasses has changed slightly: instead of the optional `basedir` parameter, it now expects an (also optional) `filepath` parameter, which specifies the absolute path to the template. You probably aren't using those constructors directly, anyway, but using the `TemplateLoader` API instead.

# 4 Upgrading from Genshi 0.3.x to 0.4.x

The modules `genshi.filters` and `genshi.template` have been refactored into packages containing multiple modules. While code using the regular APIs should continue to work without problems, you should make sure to remove any leftover traces of the files `filters.py` and `template.py` in the `genshi` package on the installation path (including the corresponding `.pyc` files). This is not necessary when Genshi was installed as a Python egg.

Results of evaluating template expressions are no longer implicitly called if they are callable. If you have been using that feature, you will need to add the parenthesis to actually call the function.

Instances of `genshi.core.Attrs` are now immutable. Filters manipulating the attributes in a stream may need to be updated. Also, the `Attrs` class no longer automatically wraps all attribute names in `QName` objects, so users of the `Attrs` class need to do this themselves. See the documentation of the `Attrs` class for more information.

# 5 Upgrading from Markup

Prior to version 0.3, the name of the Genshi project was "Markup". The name change means that you will have to adjust your import statements and the namespace URI of XML templates, among other things:

- The package name was changed from "markup" to "genshi". Please adjust any import statements referring to the old package name.
- The namespace URI for directives in Genshi XML templates has changed from `http://markup.edgewall.org/` to `http://genshi.edgewall.org/`. Please update the `xmlns:py` declaration in your template files accordingly.

Furthermore, due to the inclusion of a text-based template language, the class:

    markup.template.Template

has been renamed to:

    genshi.template.MarkupTemplate

If you've been using the Template class directly, you'll need to update your code (a simple find/replace should do—the API itself did not change).