cmlenz@713: ================
cmlenz@233: Upgrading Genshi
cmlenz@233: ================
cmlenz@233: 
cmlenz@606: 
cmlenz@606: .. contents:: Contents
cmlenz@606:    :depth: 2
cmlenz@606: .. sectnum::
cmlenz@606: 
hodgestar@937: ------------------------------------------------------
hodgestar@937: Upgrading from Genshi 0.6.x to the development version
hodgestar@937: ------------------------------------------------------
hodgestar@936: 
hodgestar@937: The Genshi development version now supports both Python 2 and Python 3.
hodgestar@937: 
hodgestar@937: The most noticable API change in the Genshi development version is that the
hodgestar@936: default encoding in numerous places is now None (i.e. unicode) instead
hodgestar@936: of UTF-8. This change was made in order to ease the transition to Python 3
hodgestar@936: where strings are unicode strings by default.
hodgestar@936: 
hodgestar@936: If your application relies on the default UTF-8 encoding a simple way to
hodgestar@937: have it work both with Genshi 0.6.x and the development version is to specify the
hodgestar@936: encoding explicitly in calls to the following classes, methods and functions:
hodgestar@936: 
hodgestar@936: * genshi.HTML
hodgestar@936: * genshi.Stream.render
hodgestar@936: * genshi.input.HTMLParser
hodgestar@936: * genshi.template.MarkupTemplate
hodgestar@936: * genshi.template.TemplateLoader
hodgestar@936: * genshi.template.TextTemplate (and genshi.template.NewTextTemplate)
hodgestar@936: * genshi.template.OldTextTemplate
hodgestar@936: 
hodgestar@936: Whether you explicitly specify UTF-8 or explicitly specify None (unicode) is
hodgestar@936: a matter of personal taste, although working with unicode may make porting
hodgestar@936: your own application to Python 3 easier.
hodgestar@936: 
cmlenz@606: 
cmlenz@713: ------------------------------------
cmlenz@756: Upgrading from Genshi 0.5.x to 0.6.x
cmlenz@756: ------------------------------------
cmlenz@756: 
cmlenz@756: Required Python Version
cmlenz@756: -----------------------
cmlenz@756: 
cmlenz@756: Support for Python 2.3 has been dropped in this release. Python 2.4 is
cmlenz@756: now the minimum version of Python required to run Genshi.
cmlenz@756: 
cmlenz@883: The XPath engine has been completely overhauled for this version. Some
cmlenz@883: patterns that previously matched incorrectly will no longer match, and
cmlenz@883: the other way around. In such cases, the XPath expressions need to be
cmlenz@883: fixed in your application and templates.
cmlenz@883: 
cmlenz@756: 
cmlenz@756: ------------------------------------
cmlenz@592: Upgrading from Genshi 0.4.x to 0.5.x
cmlenz@592: ------------------------------------
cmlenz@592: 
cmlenz@713: Error Handling
cmlenz@713: --------------
cmlenz@592: 
cmlenz@606: The default error handling mode has been changed to "strict". This
cmlenz@606: means that accessing variables not defined in the template data will
cmlenz@606: now generate an immediate exception, as will accessing object
cmlenz@606: attributes or dictionary keys that don't exist. If your templates rely
cmlenz@606: on the old lenient behavior, you can configure Genshi to use that
cmlenz@606: instead. See the documentation for details on how to do that. But be
cmlenz@606: warned that lenient error handling may be removed completely in a
cmlenz@606: future release.
cmlenz@606: 
cmlenz@713: Match Template Processing
cmlenz@713: -------------------------
cmlenz@713: 
cmlenz@694: There has also been a subtle change to how ``py:match`` templates are
cmlenz@694: processed: in previous versions, all match templates would be applied
cmlenz@694: to the content generated by the matching template, and only the
cmlenz@694: matching template itself was applied recursively to the original
cmlenz@694: content. This behavior resulted in problems with many kinds of
cmlenz@694: recursive matching, and hence was changed for 0.5: now, all match
cmlenz@694: templates declared before the matching template are applied to the
cmlenz@694: original content, and match templates declared after the matching
cmlenz@694: template are applied to the generated content. This change should not
cmlenz@694: have any effect on most applications, but you may want to check your
cmlenz@694: use of match templates to make sure.
cmlenz@694: 
cmlenz@713: Text Templates
cmlenz@713: --------------
cmlenz@592: 
cmlenz@713: Genshi 0.5 introduces a new, alternative syntax for text templates,
cmlenz@713: which is more flexible and powerful compared to the old syntax. For
cmlenz@713: backwards compatibility, this new syntax is not used by default,
cmlenz@713: though it will be in a future version. It is recommended that you
cmlenz@713: migrate to using this new syntax. To do so, simply rename any
cmlenz@713: references in your code to ``TextTemplate`` to ``NewTextTemplate``. To
cmlenz@713: explicitly use the old syntax, use ``OldTextTemplate`` instead, so
cmlenz@713: that you can be sure you'll be using the same language when the
cmlenz@713: default in Genshi is changed (at least until the old implementation is
cmlenz@713: completely removed).
cmlenz@713: 
cmlenz@713: ``Markup`` Constructor
cmlenz@713: ----------------------
cmlenz@713: 
cmlenz@745: The ``Markup`` class no longer has a specialized constructor. The old
cmlenz@713: (undocumented) constructor provided a shorthand for doing positional
cmlenz@713: substitutions. If you have code like this:
cmlenz@713: 
cmlenz@713: .. code-block:: python
cmlenz@713: 
cmlenz@713:   Markup('<b>%s</b>', name)
cmlenz@713: 
cmlenz@745: You must replace it by the more explicit:
cmlenz@713: 
cmlenz@713: .. code-block:: python
cmlenz@713: 
cmlenz@713:   Markup('<b>%s</b>') % name
cmlenz@713: 
cmlenz@714: ``Template`` Constructor
cmlenz@714: ------------------------
cmlenz@714: 
cmlenz@714: The constructor of the ``Template`` class and its subclasses has changed
cmlenz@714: slightly: instead of the optional ``basedir`` parameter, it now expects
cmlenz@714: an (also optional) ``filepath`` parameter, which specifies the absolute
cmlenz@714: path to the template. You probably aren't using those constructors
cmlenz@714: directly, anyway, but using the ``TemplateLoader`` API instead.
cmlenz@714: 
cmlenz@713: 
cmlenz@713: ------------------------------------
cmlenz@336: Upgrading from Genshi 0.3.x to 0.4.x
cmlenz@336: ------------------------------------
cmlenz@336: 
cmlenz@452: The modules ``genshi.filters`` and ``genshi.template`` have been
cmlenz@452: refactored into packages containing multiple modules. While code using
cmlenz@452: the regular APIs should continue to work without problems, you should
cmlenz@606: make sure to remove any leftover traces of the files ``filters.py``
cmlenz@606: and ``template.py`` in the ``genshi`` package on the installation
cmlenz@606: path (including the corresponding ``.pyc`` files). This is not
cmlenz@606: necessary when Genshi was installed as a Python egg.
cmlenz@336: 
cmlenz@343: Results of evaluating template expressions are no longer implicitly
cmlenz@343: called if they are callable. If you have been using that feature, you
cmlenz@343: will need to add the parenthesis to actually call the function.
cmlenz@343: 
cmlenz@606: Instances of ``genshi.core.Attrs`` are now immutable. Filters
cmlenz@411: manipulating the attributes in a stream may need to be updated. Also,
cmlenz@606: the ``Attrs`` class no longer automatically wraps all attribute names
cmlenz@606: in ``QName`` objects, so users of the ``Attrs`` class need to do this
cmlenz@606: themselves. See the documentation of the ``Attrs`` class for more
cmlenz@411: information.
cmlenz@411: 
cmlenz@345: 
cmlenz@713: ---------------------
cmlenz@233: Upgrading from Markup
cmlenz@233: ---------------------
cmlenz@233: 
cmlenz@233: Prior to version 0.3, the name of the Genshi project was "Markup". The
cmlenz@233: name change means that you will have to adjust your import statements
cmlenz@233: and the namespace URI of XML templates, among other things:
cmlenz@233: 
cmlenz@606: * The package name was changed from "markup" to "genshi". Please
cmlenz@606:   adjust any import statements referring to the old package name.
cmlenz@606: * The namespace URI for directives in Genshi XML templates has changed
cmlenz@606:   from ``http://markup.edgewall.org/`` to
cmlenz@606:   ``http://genshi.edgewall.org/``. Please update the ``xmlns:py``
cmlenz@606:   declaration in your template files accordingly.
cmlenz@233: 
cmlenz@233: Furthermore, due to the inclusion of a text-based template language,
cmlenz@606: the class::
cmlenz@233: 
cmlenz@606:   markup.template.Template
cmlenz@233: 
cmlenz@606: has been renamed to::
cmlenz@233: 
cmlenz@606:   genshi.template.MarkupTemplate
cmlenz@233: 
cmlenz@233: If you've been using the Template class directly, you'll need to
cmlenz@606: update your code (a simple find/replace should do—the API itself
cmlenz@233: did not change).