Mercurial > genshi > mirror

comparison doc/upgrade.txt @ 720:acf7c5ee36e7 experimental-newctxt

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
newctxt branch: Merged revisions [678:835] via svnmerge from [source:trunk].
author cmlenz
date Fri, 11 Apr 2008 08:42:11 +0000
parents
children
comparison
equal deleted inserted replaced
567:837786a584d5 720:acf7c5ee36e7
1 ================
2 Upgrading Genshi
3 ================
4
5
6 .. contents:: Contents
7 :depth: 2
8 .. sectnum::
9
10
11 ------------------------------------
12 Upgrading from Genshi 0.4.x to 0.5.x
13 ------------------------------------
14
15 Error Handling
16 --------------
17
18 The default error handling mode has been changed to "strict". This
19 means that accessing variables not defined in the template data will
20 now generate an immediate exception, as will accessing object
21 attributes or dictionary keys that don't exist. If your templates rely
22 on the old lenient behavior, you can configure Genshi to use that
23 instead. See the documentation for details on how to do that. But be
24 warned that lenient error handling may be removed completely in a
25 future release.
26
27 Match Template Processing
28 -------------------------
29
30 There has also been a subtle change to how ``py:match`` templates are
31 processed: in previous versions, all match templates would be applied
32 to the content generated by the matching template, and only the
33 matching template itself was applied recursively to the original
34 content. This behavior resulted in problems with many kinds of
35 recursive matching, and hence was changed for 0.5: now, all match
36 templates declared before the matching template are applied to the
37 original content, and match templates declared after the matching
38 template are applied to the generated content. This change should not
39 have any effect on most applications, but you may want to check your
40 use of match templates to make sure.
41
42 Text Templates
43 --------------
44
45 Genshi 0.5 introduces a new, alternative syntax for text templates,
46 which is more flexible and powerful compared to the old syntax. For
47 backwards compatibility, this new syntax is not used by default,
48 though it will be in a future version. It is recommended that you
49 migrate to using this new syntax. To do so, simply rename any
50 references in your code to ``TextTemplate`` to ``NewTextTemplate``. To
51 explicitly use the old syntax, use ``OldTextTemplate`` instead, so
52 that you can be sure you'll be using the same language when the
53 default in Genshi is changed (at least until the old implementation is
54 completely removed).
55
56 ``Markup`` Constructor
57 ----------------------
58
59 The ``Markup`` class now longer has a specialized constructor. The old
60 (undocumented) constructor provided a shorthand for doing positional
61 substitutions. If you have code like this:
62
63 .. code-block:: python
64
65 Markup('<b>%s</b>', name)
66
67 You can simply replace it by the more explicit:
68
69 .. code-block:: python
70
71 Markup('<b>%s</b>') % name
72
73 ``Template`` Constructor
74 ------------------------
75
76 The constructor of the ``Template`` class and its subclasses has changed
77 slightly: instead of the optional ``basedir`` parameter, it now expects
78 an (also optional) ``filepath`` parameter, which specifies the absolute
79 path to the template. You probably aren't using those constructors
80 directly, anyway, but using the ``TemplateLoader`` API instead.
81
82
83 ------------------------------------
84 Upgrading from Genshi 0.3.x to 0.4.x
85 ------------------------------------
86
87 The modules ``genshi.filters`` and ``genshi.template`` have been
88 refactored into packages containing multiple modules. While code using
89 the regular APIs should continue to work without problems, you should
90 make sure to remove any leftover traces of the files ``filters.py``
91 and ``template.py`` in the ``genshi`` package on the installation
92 path (including the corresponding ``.pyc`` files). This is not
93 necessary when Genshi was installed as a Python egg.
94
95 Results of evaluating template expressions are no longer implicitly
96 called if they are callable. If you have been using that feature, you
97 will need to add the parenthesis to actually call the function.
98
99 Instances of ``genshi.core.Attrs`` are now immutable. Filters
100 manipulating the attributes in a stream may need to be updated. Also,
101 the ``Attrs`` class no longer automatically wraps all attribute names
102 in ``QName`` objects, so users of the ``Attrs`` class need to do this
103 themselves. See the documentation of the ``Attrs`` class for more
104 information.
105
106
107 ---------------------
108 Upgrading from Markup
109 ---------------------
110
111 Prior to version 0.3, the name of the Genshi project was "Markup". The
112 name change means that you will have to adjust your import statements
113 and the namespace URI of XML templates, among other things:
114
115 * The package name was changed from "markup" to "genshi". Please
116 adjust any import statements referring to the old package name.
117 * The namespace URI for directives in Genshi XML templates has changed
118 from ``http://markup.edgewall.org/`` to
119 ``http://genshi.edgewall.org/``. Please update the ``xmlns:py``
120 declaration in your template files accordingly.
121
122 Furthermore, due to the inclusion of a text-based template language,
123 the class::
124
125 markup.template.Template
126
127 has been renamed to::
128
129 genshi.template.MarkupTemplate
130
131 If you've been using the Template class directly, you'll need to
132 update your code (a simple find/replace should do—the API itself
133 did not change).
Copyright (C) 2012-2017 Edgewall Software