root/livinglogic.python.xist/MIGRATION.rst @ 5313:5a6c9245dda4

Revision 5313:5a6c9245dda4, 41.8 KB (checked in by Walter Doerwald <walter@…>, 7 years ago)

Builtin UL4 functions and methods are now enhanced generators too.

With this <?render?> can be removed.

Rename <?code?> to <?exe?>.

Add UL4 functions print() and printx().

Line 
1Migrating to version 4.10
2=========================
3
4Changes to UL4
5--------------
6
7*   The UL4 tag ``<?code?>`` has been renamed to ``<?exe?>`` and the tag
8    ``<?render?>`` have been removed.
9
10    To update your code replace:
11
12    *    ``<?code x = 42?>`` with ``<?exe x = 42?>`` and
13
14    *   ``<?render r.render()?>`` with ``<?exe r.render()?>``.
15
16*   The UL4 functions ``vars`` and ``get`` have been removed.
17
18*   The automatic UL4 variable ``stack`` has been removed too.
19
20
21Migrating to version 4.7
22========================
23
24Changes to UL4
25--------------
26
27*   Compiling a UL4 template to a Java ``CompiledTemplate`` is no longer
28    supported (i.e. ``template.javasource(interpreted=False)`` no longer works.
29    Use ``template.javasource()`` instead (which creates Java sourcecode for
30    an ``InterpretedTemplate``).
31
32
33Migrating to version 4.6
34========================
35
36Changes to :mod:`ll.xist`
37-------------------------
38
39*   The :meth:`walk` method has been changed to return a :class:`Cursor` object
40    instead of the path, so you have to replace::
41
42        for path in doc.walk(...):
43            # use path
44
45    with::
46
47        for cursor in doc.walk(...):
48            # use cursor.path
49
50*   Furthermore walk filters have been removed. Determining whether an XIST tree
51    is traversed top down or bottom up can instead by specified via distinct
52    parameters to the :meth:`walk` method. Replace::
53
54        for path in doc.walk((xfind.entercontent, xfind.enterattrs, True)):
55            ...
56
57    with::
58
59        for cursor in doc.walk(entercontent=True, enterattrs=True, startelementnode=False, endelementnode=True):
60            ...
61
62    If you want to enter an element only when a condition is true, you can do
63    that by modifying the approprate cursor attribute inside your loop::
64
65        for cursor in doc.walk(entercontent=True, enterattrs=True):
66            if isinstance(cursor.node, html.script, html.textarea):
67                cursor.entercontent = False
68            ...
69
70*   :func:`ll.xist.parse.itertree` now returns :class:`Cursor` objects too,
71    instead of path lists.
72
73*   Slicing XIST elements now returns a sliced element, instead of a slice from
74    the content :class:`Frag`::
75
76        >>> from ll.xist.ns import html
77        >>> html.ul(html.li(i) for i in range(5))[1:3].string()
78        '<ul><li>1</li><li>2</li></ul>'
79
80    To get a slice from the content simply use::
81
82        >>> html.ul(html.li(i) for i in range(5)).content[1:3].string()
83        '<li>1</li><li>2</li>'
84
85
86Migrating to version 4.4
87========================
88
89Changes to the required Python version
90--------------------------------------
91
92Python 3.3 is required now.
93
94
95Migrating to version 4.2
96========================
97
98Changes to :mod:`ll.ul4c`
99-------------------------
100
101*   The UL4 method ``join`` no longer calls ``str`` on the items in the argument
102    list. Replace ``sep.join(iterable)`` with ``sep.join(str(i) for i in iterable)``
103    when you have an argument list that contains non-strings.
104
105
106Migrating to version 4.1
107========================
108
109Changes to :mod:`ll.make`
110-------------------------
111
112*   The support for Growl notifications in :mod:`ll.make` on the Mac has been
113    replaced by support for Mountain Lions Notification Center.
114
115    The option has been renamed from :option:`--growl` to :option:`--notify`.
116
117    For this to work you need to have terminal-notifier__ installed in its
118    standard location (``/Applications/terminal-notifier.app``).
119
120    __ https://github.com/alloy/terminal-notifier
121
122
123Migrating to version 4.0
124========================
125
126Changes to the required Python version
127--------------------------------------
128
129Python 3.2 is required now.
130
131Changes to UL4
132--------------
133
134*   Date constants in UL4 have changed again. They are now written like this:
135    ``@(2012-04-12)`` or ``@(2012-04-12T12:34:56)``.
136
137*   The function ``json`` has been renamed to ``asjson``.
138
139*   The ``<?render?>`` tag in UL4 now looks like a method call instead of a
140    function call. I.e. ``<?render t(a=17, b=23)?>`` has changed to
141    ``<?render t.render(a=17, b=23)?>``.
142
143Changes to scripts
144------------------
145
146*   The scripts ``oracreate``, ``oradrop``, ``oradelete``, ``oradiff``,
147    ``oramerge``, ``oragrant``, ``orafind`` and ``uhpp`` no longer have an
148    :option:`-e`/:option:`--encoding` option. They always use Pythons output
149    encoding.
150
151*   The options :option:`-i`/:option:`--inputencoding` and
152    :option:`-o`/:option:`--outputencoding` of the script ``db2ul4`` have been
153    replaced with an option :option:`-e`/:option:`--encoding` for the encoding
154    of the template files. For printing the result Pythons output encoding is
155    used.
156
157*   The options :option:`--inputencoding`,/:option:`--inputerrors` and
158    :option:`--outputencoding`/:option:`--outputerrors` of
159    :class:`ll.sisyphus.Job` have been replaced with option
160    :option:`--encoding`/:option:`--errors` for the encoding of the log files.
161
162
163
164Migrating to version 3.25
165=========================
166
167Changes to XIST
168---------------
169
170*   The :meth:`compact` method has been renamed to :meth:`compacted` to avoid
171    collisions with the ``compact`` attribute in HTML elements.
172
173
174Migrating to version 3.24
175=========================
176
177Changes to :mod:`ll.xist.ns.ul4`
178--------------------------------
179
180*   :class:`ll.xist.ns.ul4.attr_if` is now an :class:`ll.xist.xsc.AttrElement`
181    subclass. Change your code from::
182
183        html.div(id=(ul4.attr_if("foo"), "bar"))
184
185    to::
186
187        html.div(id=ul4.attr_if("bar", cond="foo"))
188
189*   :class:`ll.xist.ns.ul4.attr_ifnn` has been removed. Replace it with the
190    equivalent :class:`attr_if` call.
191
192
193Migrating to version 3.23
194=========================
195
196Changes to :mod:`ll.ul4c`
197-------------------------
198
199*   The module global functions :func:`ll.ul4c.compile`, :func:`ll.ul4c.load` and
200    :func:`ll.ul4c.loads` have been removed. Instead of them the :class:`Template`
201    constructor and the class methods :meth:`load` and :meth:`loads` can be used.
202
203
204Migrating to version 3.20
205=========================
206
207Changes to :mod:`ll.orasql`
208---------------------------
209
210*   The :var:`schema` argument used by various methods in :mod:`ll.orasql` has
211    been replaced by a :var:`owner` argument that can be :const:`None` (for the
212    current user), the constant :const:`ALL` for all users (which uses the
213    ``DBA_*`` variant of various meta data views if possible or the ``ALL_*``
214    variants otherwise) and a specific user name.
215
216
217Migrating to version 3.19
218=========================
219
220Changes to :mod:`ll.orasql`
221---------------------------
222
223*   :mod:`ll.orasql` now requires cx_Oracle 5.1 (i.e. ``UNICODE`` mode is no
224    longer used).
225
226*   If the :var:`readlobs` option is false for :mod:`ll.orasql` cursors, the
227    CLOBs/BLOBs returned will be wrapped into something that behaves like a
228    Python file. The original :class:`LOB` object is available as the ``value``
229    attribute of the returned wrapper object::
230
231        db = orasql.connect("user/pwd@db")
232        c = db.cursor()
233        c.execute("select theclob from thetable")
234        row = c.fetchone()
235        print row[0].value.read()
236
237
238Migrating to version 3.18
239=========================
240
241Changes to ``db2ul4``
242---------------------
243
244*   The variables available in UL4 templates used by ``db2ul4`` have changed.
245    Instead of a ``connect`` object, there are now three objects for each
246    supported database (i.e. ``oracle``, ``sqlite`` and ``mysql``). To update
247    your template replace::
248
249        connect["oracle:user/pwd@db"]
250
251    with::
252
253        oracle["user/pwd@db"]
254
255Changes to scripts
256------------------
257
258*   The script ``doc2txt`` now reads from ``stdin`` and writes to ``stdout``
259    instead of requiring file names on the command line.
260
261
262Migrating to version 3.17
263=========================
264
265Changes to :mod:`ll.misc`
266-------------------------
267
268*   :func:`ll.misc.javastring` has been renamed to :func:`ll.misc.javaexpr`.
269
270*   The UL4 method ``format`` is now a function instead.
271
272
273Migrating to version 3.16
274=========================
275
276Changes to :mod:`ll.misc`
277-------------------------
278
279*   :func:`ll.misc.flag` is gone. If the function is still required, here is
280    the source::
281
282        def flag(value):
283            if value in ("1", "true", "yes"):
284                return True
285            elif value in ("0", "false", "no"):
286                return False
287            raise ValueError("unknown flag value")
288
289
290Migrating to version 3.15
291=========================
292
293Changes to :mod:`ll.xist.ns.jsp`
294--------------------------------
295
296*   :func:`ll.xist.ns.jsp.javastring` has been move to :mod:`ll.misc`.
297
298
299Migrating to version 3.14
300=========================
301
302Changes to :mod:`ll.ul4c`
303-------------------------
304
305*   Date constants now need a ``@`` as a prefix. I.e. chance ``2010-11-03T`` to
306    ``@2010-11-03T`` etc.
307
308*   The :var:`function` argument for :meth:`ul4c.Template.pythonsource` is gone.
309    The output will always be a full function.
310
311
312Migrating to version 3.12
313=========================
314
315Changes to :mod:`ll.sisyphus`
316-----------------------------
317
318*   The maximum allowed runtime for jobs is now a hard limit. Previously a
319    running job that exceeded the maximum allowed runtime would only be killed
320    when the next job was started. Now the job will kill itself immediately after
321    ``maxtime`` seconds. This means you *might* have to adjust your ``maxtime``
322    setting.
323
324*   The default location of log files has changed again. Now ``~/ll.sisyphus/``
325    is used as the base directory instead of ``~/ll.sisyphus/log/``.
326
327
328Migrating to version 3.11
329=========================
330
331Changes to :mod:`ll.sisyphus`
332-----------------------------
333
334*   The method :meth:`logLoop` is gone. Replace::
335
336        self.logLoop("done")
337
338    with::
339
340        return "done"
341
342*   The method :meth:`logProgress` is gone. Replace::
343
344        self.logProgress("parsing XML file")
345
346    with::
347
348        self.log("parsing XML file")
349
350    You might also add tags to the logging call via::
351
352        self.log.xml("parsing XML")
353
354    (This adds the tag ``"xml"`` to the log line.)
355
356*   The method :meth:`logError` is gone. Replace::
357
358        self.logError("Can't parse XML file")
359
360    with::
361
362        self.log.error("Can't parse XML file")
363
364    If the object passed to ``self.log`` is an exception, the logging call will
365    add the ``exc`` tag automatically.
366
367*   :class:`sisyphus.Job` no longer has a constructor. Configuration is now done
368    via class attributes. Replace::
369
370        class TransmogrifyStuff(sisyphus.Job):
371            def __init__(self, connectstring):
372                sisyphus.Job.__init__(self, 30, "ACME_TransmogrifyStuff", raiseerrors=True)
373
374    with::
375
376        class TransmogrifyStuff(sisyphus.Job):
377            projectname = "ACME.MyProject"
378            jobname = "TransmogrifyStuff"
379            maxtime = 30
380
381*   The default location of run/log files has changed. Now ``~/ll.sisyphus/log``
382    is used for log files and ``~/ll.sisyphus/run`` is used for run files.
383
384
385Migrating to version 3.10
386=========================
387
388Changes to the required Python version
389--------------------------------------
390
391Python 2.7 is required now.
392
393Changes to :mod:`ll.make`
394-------------------------
395
396*   :mod:`ll.make` uses :mod:`argparse` now.
397
398*   :meth:`ll.make.Project.optionparser` has been renamed to :meth:`argparser`
399    and returns a :class:`argparse.ArgumentParser` object now.
400
401*   :meth:`ll.make.Project.parseoptions` has been renamed to :meth:`parseargs`
402    and returns a :class:`argparse.Namespace` object now.
403
404Changes to :mod:`ll.daemon`
405---------------------------
406
407*   :mod:`ll.daemon` uses :mod:`argparse` now. :meth:`ll.daemon.Daemon.optionparser`
408    has been renamed to :meth:`argparser`.
409
410
411Migrating to version 3.9
412========================
413
414Changes to :mod:`ll.xist.ns.html`
415---------------------------------
416
417*   :class:`ll.xist.ns.html.html` will no longer change the ``lang`` and
418    ``xml:lang`` attributes. This functionality has been moved to the new element
419    :class:`ll.xist.ns.htmlspecials.html`. Furthermore this new element will not
420    change an attribute if this attribute has already been set.
421
422    So if you need the functionality replace any use of
423    :class:`ll.xist.ns.html.html` with :class:`ll.xist.ns.htmlspecials.html`.
424
425*   :class:`ll.xist.ns.html.title` no longer does any manipulation of its content.
426
427    If you needed this functionality, you can copy it from the old ``title``
428    element and put it into your own element class.
429
430
431Migrating to version 3.8
432========================
433
434Changes to parsing
435------------------
436
437*   The parsing infrastructure has been completely rewritten to be more modular
438    and to support iterative parsing (similar to `ElementTree`__). Now parsing
439    XML is done in a pipeline approach.
440
441    __ http://effbot.org/zone/element-iterparse.htm
442
443    Previously parsing a string looked like this::
444
445        >>> from ll.xist import xsc, parsers
446        >>> from ll.xist.ns import html
447        >>> source = "<a href='http://www.python.org/'>Python</a>"
448        >>> doc = parsers.parsestring(source, pool=xsc.Pool(html))
449
450    Now this is done the following way::
451
452        >>> from ll.xist import xsc, parse
453        >>> from ll.xist.ns import html
454        >>> source = "<a href='http://www.python.org/'>Python</a>"
455        >>> doc = parse.tree(
456        ...     parse.String(source)
457        ...     parse.Expat()
458        ...     parse.NS(html)
459        ...     parse.Node(pool=xsc.Pool(html))
460        ... )
461
462    For more info see the module :mod:`ll.xist.parse`.
463
464*   Something that no longer works is parsing XML where elements from different
465    namespaces use the same namespace prefix. You will either have to rewrite
466    your XML or implement a new class for the parsing pipeline that handles
467    namespaces prefixes *and* instantiating XIST classes (i.e. a combination
468    of what :class:`ll.xist.parse.NS` and :class:`ll.xist.parse.Node` do).
469
470*   The module :mod:`ll.xist.parsers` has been renamed to :mod:`parse`.
471
472*   The module :mod:`ll.xist.presenters` has been renamed to :mod:`present`.
473
474*   The classes :class:`ll.xist.converters.Converter` and
475    :class:`ll.xist.publishers.Publisher` have been moved to :mod:`ll.xist.xsc`.
476    The modules :mod:`ll.xist.converters` and :mod:`ll.xist.publishers` no longer
477    exist.
478
479Changes to XISTs walk filters
480-----------------------------
481
482*   The walk methods :meth:`walknode` and :meth:`walkpath` have been renamed to
483    :meth:`walknodes` and :meth:`walkpaths`. The class :class:`WalkFilter` has
484    been moved to :mod:`ll.xist.xfind`.
485
486Changes to :mod:`ll.url`
487------------------------
488
489*   :class:`ll.url.Path` has been simplified: Path segments are strings instead
490    of tuples. If you need the path parameters (i.e. part after ``;`` in a path
491    segment) you have to split the segment yourself.
492
493*   :meth:`ll.url.URL.import_` is gone. As a replacement :func:`misc.module` can
494    be used, i.e. replace::
495
496        >>> from ll import url
497        >>> u = url.File("foo.py")
498        >>> m = u.import_(mode="always")
499
500    with::
501
502        >>> from ll import url, misc
503        >>> u = url.File("foo.py")
504        >>> m = misc.module(u.openread().read(), u.local())
505
506    However, note that :meth:`ll.url.URL.import_` has been reintroduced in 3.8.1
507    based on :func:`misc.import`. This means that the mode argument is no longer
508    supported.
509
510*   ssh URLs now required to standalone :mod:`execnet` package__. The
511    ``ssh_config`` parameter for ssh URLs is gone.
512
513    __ http://codespeak.net/execnet/
514
515Changes to :mod:`ll.make`
516-------------------------
517
518*   The two classes :class:`ll.make.PoolAction` and
519    :class:`ll.make.XISTPoolAction` have been dropped. To update your code,
520    replace::
521
522        make.XISTPoolAction(html)
523
524    with::
525
526        make.ObjectAction(xsc.Pool).call(html)
527
528*   The class :class:`XISTParseAction` has been removed. This action can be
529    replaced by a combination of :class:`ObjectAction`, :class:`CallAction` and
530    :class:`CallAttrAction` using the new parsing infrastructure.
531
532Other changes
533-------------
534
535*   :class:`ll.xist.ns.specials.z` has been moved to the :mod:`ll.xist.ns.doc`
536    module.
537
538
539Migrating to version 3.7
540========================
541
542Changes to the make module
543--------------------------
544
545*   The division operator for actions is no longer implemented, so instead of::
546
547        t1 = make.FileAction(key=url.URL("file:foo.txt"))
548        t2 = t1 /
549             make.DecodeAction("iso-8859-1") /
550             make.EncodeAction("utf-8") /
551             make.FileAction(key=url.URL("bar.txt"))
552
553    you now have to write something like the following::
554
555        t1 = make.FileAction("file:foo.txt")
556        t2 = t1.callattr("decode", "iso-8859-1")
557        t2 = t2.callattr("encode", "utf-8")
558        t2 = make.FileAction("file:bar.txt", t2)
559
560*   Also the following classes have been removed from :mod:`ll.make`:
561    :class:`EncodeAction`, :class:`DecodeAction`, :class:`EvalAction`,
562    :class:`GZipAction`, :class:`GUnzipAction`,
563    :class:`JavascriptMinifyAction`, :class:`XISTBytesAction`,
564    :class:`XISTStringAction`, :class:`JoinAction`, :class:`UnpickleAction`,
565    :class:`PickleAction`, :class:`TOXICAction`, :class:`TOXICPrettifyAction`,
566    :class:`SplatAction`, :class:`UL4CompileAction`, :class:`UL4RenderAction`,
567    :class:`UL4DumpAction`, :class:`UL4LoadAction`, :class:`XISTTextAction` and
568    :class:`XISTConvertAction`. All of these actions can be executed by using
569    :class:`CallAction` or :class:`CallAttrAction`.
570
571
572Migrating to version 3.6
573========================
574
575Changes to the color module
576---------------------------
577
578*   The following :class:`Color` class methods have been dropped: ``fromrgba``,
579    ``fromrgba4``, ``fromrgba8``, ``fromint4``, ``fromint8``.
580
581*   The following :class:`Color` properties have been dropped: ``r4``, ``g4``,
582    ``b4``, ``a4``, ``r8``, ``g8``, ``b8``, ``a8``, ``r``, ``g``, ``b````a``
583    ``int4``, ``int8``, ``rgb4``, ``rgba4``, ``rgb8``, and ``rgba8``. The new
584    methods ``r``, ``g``, ``b`` and ``a`` return the 8 bit component values.
585
586*   The class methods ``fromhsva`` and ``fromhlsa`` have been renamed to
587    ``fromhsv`` and ``fromhls``.
588
589*   The property ``css`` has been dropped. The CSS string is returned by
590    ``__str__`` now.
591
592*   Dividing colors now does a scalar division. Blending colors is now done with
593    the modulo operator.
594
595Removal of XPIT
596---------------
597
598*   The XPIT templating language has been removed. You should replace all your
599    XPIT templates with UL4 templates.
600
601
602Migrating to version 3.5
603========================
604
605Changes to UL4
606--------------
607
608*   The UL4 function ``csvescape`` has been renamed to ``csv``.
609
610Changes to the color module
611---------------------------
612
613*   :class:`ll.color.Color` has been rewritten to create immutable objects
614    with the components being 8 bit values (i.e. 0-255) instead of floating
615    point values between 0 and 1.
616
617
618Migrating to version 3.4
619========================
620
621Changes to the make module
622--------------------------
623
624*   :class:`ll.make.CallMethAction` has been renamed to :class:`CallAttrAction`.
625
626*   :class:`ll.make.XISTPublishAction` has been renamed to :class:`XISTBytesAction`.
627
628Changes to UL4
629--------------
630
631*   The templates available to the ``<?render?>`` tag are no longer passed as a
632    separate argument to the render methods, but can be part of the normal
633    variables.
634
635Changes to XIST
636---------------
637
638*   Building trees with ``with`` blocks has changed slightly. Unchanged code will
639    lead to the following exception::
640
641        File "/usr/local/lib/python2.5/site-packages/ll/xist/xsc.py", line 1285, in __enter__
642            threadlocalnodehandler.handler.enter(self)
643        AttributeError: 'NoneType' object has no attribute 'enter'
644
645    To fix this, change your code from::
646
647        with html.html() as node:
648            with html.head():
649                +html.title("Foo")
650            with html.body():
651                +html.p("The foo page!")
652
653    to::
654
655        with xsc.build():
656            with html.html() as node:
657                with html.head():
658                    +html.title("Foo")
659                with html.body():
660                    +html.p("The foo page!")
661
662    (i.e. wrap the outermost ``with`` block in another ``with xsc.build()``
663    block.)
664
665
666Migrating to version 3.3
667========================
668
669Changes to the make module
670--------------------------
671
672*   :class:`ll.make.ImportAction` has been dropped as now the module object can
673    be used directly (e.g. as the input for an :class:`XISTPoolAction` object).
674
675*   The constructor of most action classes now accept the input action as a
676    parameter again. This means that you might have to change the calls.
677    Usually it's safest to use keyword arguments. I.e. change::
678
679        make.FileAction(url.File("foo.txt"))
680
681    to::
682
683        make.FileAction(key=url.File("foo.txt"))
684
685*   The :var:`targetroot` parameter for :meth:`ll.make.XISTConvertAction.__init__`
686    has been renamed to :var:`root`.
687
688Changes to TOXIC
689----------------
690
691*   TOXIC has been split into a compiler and an XIST namespace module. Instead
692    of calling the function :func:`ll.xist.ns.toxic.xml2ora` you now have to use
693    :func:`ll.toxicc.compile`. (However using TOXIC with :mod:`ll.make` hasn't
694    changed).
695
696Changes to XIST
697---------------
698
699*   The default parser for XIST is expat now. To switch back to sgmlop simply
700    pass an :class:`SGMLOPParser` object to the parsing functions::
701
702        >>> from ll.xist import parsers
703        >>> node = parsers.parsestring("<a>", parser=parsers.SGMLOPParser())
704
705
706Migrating to version 3.2.6
707==========================
708
709Changes to escaping
710-------------------
711
712The functions :mod:`ll.xist.helpers.escapetext` and
713:mod:`ll.xist.helpers.escapeattr` have been merged into :mod:`ll.misc.xmlescape`
714and all the characters ``<``, ``>``, ``&``, ``"`` and ``'`` are escaped now.
715
716
717Migrating to version 3.1
718========================
719
720Changes to URL handling
721-----------------------
722
723URLs containing processing instructions will no longer be transformed in
724any way. If you need the old behaviour you can wrap the initial part of
725the attribute value into a :class:`specials.url` PI.
726
727
728Migrating to version 3.0
729========================
730
731Changes to tree traversal
732-------------------------
733You can no longer apply xfind expression directly to nodes, so instead of::
734
735    for node in root//html.p:
736        print node
737
738you have to write::
739
740    for node in root.walknode(html.p):
741        print node
742
743If you want the search anchored at the root node, you can do the following::
744
745    for node in root.walknode(root/html.p):
746        print node
747
748This will yield :class:`html.p` elements only if they are immediate children of
749the ``root`` node.
750
751Passing a callable to the :meth:`walk` method now creates a
752:class:`ll.xist.xfind.CallableSelector`. If you want the old tree traversal
753logic back, you have to put your code into the :meth:`filterpath` method of a
754:class:`WalkFilter` object.
755
756Many of the XFind operators have been renamed (and all have been rewritten).
757See the :mod:`xfind` documentation for more info.
758
759The death of namespace modules
760------------------------------
761
762It's no longer possible to turn modules into namespaces. Element classes belong
763to a namespace (in the XML sense) simply if their ``xmlns`` attribute have the
764same value. So a module definition like this::
765
766    from ll.xist import xsc
767
768    class foo(xsc.Element):
769        def convert(self, converter):
770            return xsc.Text("foo")
771
772    class xmlns(xsc.Namespace):
773        xmlname = "foo"
774        xmlurl = "http://xmlns.example.org/foo"
775    xmlns.makemod(vars())
776
777has to be changed into this::
778
779    from ll.xist import xsc
780
781    class foo(xsc.Element):
782        xmlns = "http://xmlns.example.org/foo"
783
784        def convert(self, converter):
785            return xsc.Text("foo")
786
787Renamed :mod:`doc` classes
788--------------------------
789
790Many classes in the :mod:`ll.xist.ns.doc` module have been renamed. The
791following names have changed:
792
793*   ``function`` to ``func``;
794*   ``method`` to ``meth``;
795*   ``module`` to ``mod``;
796*   ``property`` to ``prop``;
797*   ``title`` to ``h``;
798*   ``par`` to ``p``;
799*   ``olist`` to ``ol``;
800*   ``ulist`` to ``ul``;
801*   ``dlist`` to ``dl``;
802*   ``item`` to ``li`` or ``dd`` (depending on whether it's inside an
803    :class:`ol`, :class:`ul` or :class:`dl`);
804*   ``term`` to ``dt``;
805*   ``link`` to ``a``.
806
807
808Migrating to version 2.15
809=========================
810
811Changes to plain text conversion
812--------------------------------
813
814The node method :meth:`asText` has been moved to the :mod:`html` namespace,
815so you have to replace::
816
817    print node.asText()
818
819with::
820
821    from ll.xist.ns import html
822    print html.astext(node)
823
824Changes to :class:`htmlspecials.pixel`
825--------------------------------------
826
827If you've been using the ``color`` attribute for :class:`htmlspecials.pixel`,
828you have to add a ``#`` in from of the value, as it is a CSS color value now.
829(And if've you've been using ``color`` and a CSS padding of a different color:
830This will no longer work).
831
832
833Migrating to version 2.14
834=========================
835
836Changes to presenters
837---------------------
838
839Presenters work differently now. Instead of::
840
841    print node.asrepr(presenters.CodePresenter)
842
843simply do the following::
844
845    print presenters.CodePresenter(node)
846
847
848Migrating to version 2.13
849=========================
850
851Changes to :mod:`ll.xist.xsc`
852-----------------------------
853
854:meth:`xsc.Namespace.tokenize` no longer has an :var:`encoding` argument, but
855operates on a unicode string directly. You can either use the result of a
856:meth:`asString` call or decode the result of an :meth:`asBytes` call yourself.
857
858
859Migrating to version 2.11
860=========================
861
862Changes to :mod:`ll.xist.xsc`
863-----------------------------
864
865The function :func:`ToNode` has been renamed to :func:`tonode`.
866
867:class:`ll.xist.Context` no longer subclasses :class:`list`. If you need a stack
868for your context, simply add the list as an attribute of the context object.
869
870Code rearrangements
871-------------------
872
873The iterator stuff from :mod:`ll.xist.xfind` has been moved to the :mod:`ll`
874package/module, i.e. you have to use :func:`ll.first` instead of
875:func:`ll.xist.xfind.first`.
876
877Changes to the :meth:`walk` method
878----------------------------------
879
880The :meth:`walk` method has changed again. There are no inmodes and outmodes any
881longer. Instead input and output are :class:`Cursor` objects. If you're using
882your own :meth:`walk` filters, you have to update them. For different output
883modes you can use the methods :meth:`walknode`, :meth:`walkpath` or
884:meth:`walkindex` instead of using the cursor yielded by :meth:`walk`.
885
886The node methods :meth:`find` and :meth:`findfirst` have been removed. Use
887``xsc.Frag(node.walk(...))`` or ``node.walk(...)[0]`` instead.
888
889Changes to publishing
890---------------------
891
892Publishing has changed: If you've used the method :meth:`repr` before to get a
893string representation of an XML tree, you have to use :meth:`asrepr` instead now
894(:meth:`repr` is a generator which will produce the string in pieces).
895
896Changes to the :mod:`xfind` module
897----------------------------------
898
899The functions :func:`item`, :func:`first`, :func:`last`, :func:`count` and
900:func:`iterone` as well as the class :class:`Iterator` have been moved to the
901:mod:`ll` module.
902
903
904Migrating to version 2.10
905=========================
906
907Changes to publishing
908---------------------
909
910Publishing has been changed from using a stream API to using a iterator API. If
911you've been using :meth:`Publisher.write` or :meth:`Publisher.writetext` (in
912your own :meth:`publish` methods) you must update your code by replacing
913``publisher.write(foo)`` with ``yield publisher.encode(foo)`` and
914``publisher.writetext(foo)`` with ``yield publisher.encodetext(foo)``.
915
916Changes to the test suite
917-------------------------
918
919The test suite now uses py.test__, so if you want to run it you'll need py.test.
920
921__ http://codespeak.net/py/current/doc/test.html
922
923Changes to :mod:`ll.xist.ns.code`
924---------------------------------
925
926The code in a :class:`ll.xist.ns.code.pyexec` object is no longer executed at
927construction time, but at conversion time. So if you relied on this fact (e.g.
928to make a namespace available for parsing of the rest of the XML file) you will
929have to change your code.
930
931Removed namespaces
932------------------
933
934The namespace modules :mod:`ll.xist.ns.css` and :mod:`ll.xist.ns.cssspecials`
935have been removed.
936
937
938Migrating to version 2.9
939========================
940
941Changes to exceptions
942---------------------
943
944All exception classes have been moved from :mod:`ll.xist.errors` to
945:mod:`ll.xist.xsc`.
946
947Changes to XML name handling
948----------------------------
949
950The class attribute :attr:`xmlname` no longer gets replaced with a tuple
951containing both the Python and the XML name. If you want to get the Python name,
952use ``foo.__class__.__name__``.
953
954Changes to the methods :meth:`walk`, :meth:`find` and :meth:`findfirst`
955-----------------------------------------------------------------------
956
957The argument :var:`filtermode` has been renamed to :var:`inmode` and (for
958:meth:`walk`) :var:`walkmode` has been renamed to :var:`outmode`.
959
960
961Migrating to version 2.8
962========================
963
964Changes to display hooks
965------------------------
966
967The way XIST uses :func:`sys.displayhook` has been enhanced. To make use of
968this, you might want to update your Python startup script. For more info see the
969`installation instructions`__.
970
971__ http://www.livinglogic.de/xist/Installation.html
972
973Changes to the :attr:`xmlns` attribute
974--------------------------------------
975
976Each element (or entity, or processing instruction) class had an attribute
977:attr:`xmlns` that references the namespace module. This attribute has been
978renamed to :attr:`__ns__`.
979
980Other minor changes
981-------------------
982
983:class:`ll.xist.ns.specials.x` has been renamed to
984:class:`ll.xist.ns.specials.ignore`.
985
986:class:`ll.xist.xfind.item` no longer handles slices. If you've used that
987functionality, you may now use slices on XFind operators, and materialize the
988result, i.e. replace ``xfind.slice(foo, 1, -1)`` with ``list(foo[1:-1])``, if
989``foo`` is an XFind operator. Otherwise you can use ``list(foo)[1:-1]``.
990
991
992Migrating to version 2.7
993========================
994
995Changes to :mod:`ll.xist.xfind`
996-------------------------------
997
998The functions :func:`xfind.first` and :func:`xfind.last` now use
999:func:`xfind.item`, so they will raise an :exc:`IndexError` when no default
1000value is passed. To get the old behaviour, simply pass :const:`None` as the default.
1001
1002
1003Migrating to version 2.6
1004========================
1005
1006Changes to the publishing API
1007-----------------------------
1008
1009The top level publishing method in the publisher has been renamed from
1010:meth:`dopublication` to :meth:`publish`. If you're using the publishing API
1011directly (instead of the node methods :meth:`asBytes` and :meth:`write`), you'll
1012have to update your code.
1013
1014The method that writes a unicode object to the output stream has been renamed
1015from :meth:`publish` to :meth:`write`. This is only relevant when you've
1016overwritten the :meth:`publish` method in your own node class (e.g. in JSP tag
1017library directives or similar stuff, or for special nodes that publish some text
1018literally).
1019
1020Changes to the presentation API
1021-------------------------------
1022
1023The presentation API has been changed too: The top level presentation method in
1024the presenter has been renamed from :meth:`dopresentation` to :meth:`present`.
1025This is only relevant if you've written your own presenter, or are using the
1026presentation API directly (instead of the node method :meth:`repr`).
1027
1028Parsing HTML
1029------------
1030
1031Parsing HTML is now done via libxml2's HTML parser, instead of using µTidyLib of
1032mxTidy. You can no longer pass arguments to tidy. Only the boolean values of the
1033:var:`tidy` argument will be used. There are no other visible changes to the API
1034but the result of parsing might have changed.
1035
1036Removed APIs and scripts
1037------------------------
1038
1039The script ``xscmake.py`` has been removed.
1040
1041The :meth:`visit` method has been removed.
1042
1043:meth:`ll.xist.xsc.FindOld` has been removed.
1044
1045:class:`ll.xist.ns.xml.header` has been renamed to
1046:class:`ll.xist.ns.xml.declaration`.
1047
1048
1049Migrating to version 2.5
1050========================
1051
1052Changes to content model
1053------------------------
1054
1055The boolean class attribute :attr:`empty` for element classes has been replaced
1056by an object :attr:`model`. :attr:`empty` is still supported, but issues a
1057:class:`PendingDeprecationWarning`. If you don't want to specify a proper
1058content model for your own elements you can replace ``empty = False`` with
1059``model = True`` (which is a shortcut for ``model = sims.Any()``) and
1060``empty = True`` with ``model = False`` (which is a shortcut for
1061``model = sims.Empty()``).
1062
1063
1064Migrating to version 2.4
1065========================
1066
1067Changes to parsing
1068------------------
1069
1070Parsing has changed internally, but the module level parsing functions in
1071:mod:`ll.xist.parsers` are still available (and will create a parser on the
1072fly), but a few arguments have changed:
1073
1074:var:`handler`
1075    This argument is no longer available, if you need a special handler, you
1076    have to subclass :class:`ll.xist.parsers.Parser` and call its parsing
1077    methods.
1078
1079:var:`parser`
1080    This argument has been renamed to :var:`saxparser` and is *not* a SAX2
1081    parser instance any longer, but a callable that will create a SAX2 parser.
1082
1083:var:`sysid`
1084    :var:`sysid` is now available for all parsing functions not just
1085    :func:`parseString`.
1086
1087Changes to converter contexts
1088-----------------------------
1089
1090:meth:`ll.xist.converters.Converter.__getitem__` now doesn't use the key passed
1091in, but ``key.Context`` as the real dictionary key. This has the following
1092consequences:
1093
1094*   If you want a unique context for your own element class, you *must*
1095    implement a new :class:`Context` class (otherwise you'd get
1096    :class:`ll.xist.xsc.Element.Context`)::
1097
1098        class Foo(xsc.Element):
1099            empty = False
1100
1101            class Context(xsc.Element.Context):
1102                def __init_(self):
1103                    xsc.Element.Context.__init__(self)
1104                    ...
1105
1106*   Subclasses that don't overwrite :class:`Context` (as well as instances of
1107    those classes) can be passed to
1108    :meth:`ll.xist.converters.Converter.__getitem__` and the unique base class
1109    context object will be returned.
1110
1111Changed namespaces
1112------------------
1113
1114The character reference classes from :mod:`ll.xist.ns.ihtml` that are duplicates
1115of those in :mod:`ll.xist.ns.chars` have been removed, so you have to use
1116:mod:`ll.xist.ns.chars` for those characters in addition to
1117:mod:`ll.xist.ns.ihtml`
1118
1119
1120Migrating to version 2.3
1121========================
1122
1123Changes in namespace handling
1124-----------------------------
1125
1126Namespace handling has changed. There are no entity or processing instruction
1127prefixes any longer and creating a proper :class:`Prefixes` object has been
1128simplified. For example::
1129
1130    prefixes = xsc.Prefixes()
1131    prefixes.addElementPrefixMapping(None, html)
1132    prefixes.addElementPrefixMapping("svg", svg)
1133
1134can be simplified to::
1135
1136    prefixes = xsc.Prefixes(html, svg=svg)
1137
1138The three arguments :var:`elementmode`, :var:`entitymode` and
1139:var:`procinstmode` for the publishing methods have been combined into
1140:var:`prefixmode`, which is used for elements only.
1141
1142Changed namespaces
1143------------------
1144
1145The character reference classes from :mod:`ll.xist.ns.html` have been moved
1146to a separate namespace :mod:`ll.xist.ns.chars`.
1147
1148The processing instructions :class:`eval_` and :class:`exec_` from the
1149:mod:`ll.xist.ns.code` module have been renamed to :class:`pyeval` and
1150:class:`pyexec`.
1151
1152Changed method names
1153--------------------
1154The method names :meth:`beginPublication`, :meth:`endPublication` and
1155:meth:`doPublication` have been lowercased.
1156
1157
1158Migrating to version 2.2
1159========================
1160
1161Attribute methods
1162-----------------
1163
1164The :class:`Element` methods for accessing attributes have been deprecated. So
1165instead of ``node.hasattr("attr")``, you should use::
1166
1167    "attr" in node.attrs
1168
1169The same holds for checking whether an attribute is allowed. You can use the
1170following code::
1171
1172    "attr" in node.Attrs
1173
1174or::
1175
1176    "attr" in NodeClass.Attrs
1177
1178or::
1179
1180    NodeClass.isallowed("attr")
1181
1182Many :class:`Attrs` methods have gained an additional parameter :var:`xml`,
1183which specifies whether an attribute name should be treated as the XML or the
1184Python name of the attribute. Make sure that you're not mixing up your arguments
1185in the function call. The safest method for this is using keyword arguments,
1186e.g.::
1187
1188    node.attr.get("attr", default=42)
1189
1190JSP directive page element
1191--------------------------
1192
1193A ``contentType`` attribute is no longer generated for the
1194:class:`ll.xist.ns.jsp.directive_page`. You have to explicitly use an attribute
1195``contentType="text/html"`` to get a ``contentType`` attribute in the resulting
1196JSP. The ``charset`` option is generated automatically from the encoding
1197specified in the publisher.
1198
1199:class:`autoimg` changes
1200------------------------
1201
1202:class:`ll.xist.htmlspecials.autoimg` will no longer touch existing ``width`` or
1203`height`` attributes, so e.g. setting the width to twice the image size via
1204``width="2*%(width)s"`` no longer works. You have to implement your own version
1205of :class:`autoimg` if you need this.
1206
1207:meth:`find` changes
1208--------------------
1209
1210:meth:`find` has been completely rewritten to use the new tree traversal
1211filters. For backwards compatibility a filter functor
1212:class:`ll.xist.xsc.FindOld` exists that takes the same arguments as the old
1213:meth:`find` method. I.e. you can replace::
1214
1215    node.find(
1216        type=html.a,
1217        attr={"href": None},
1218        searchchildren=True
1219    )
1220
1221with::
1222
1223    node.find(
1224        xsc.FindOld(
1225            type=html.a,
1226            attr={"href": None},
1227            searchchildren=True
1228        ),
1229        skiproot=True
1230    )
1231
1232But one minor difference remains: when :var:`skiproot` is set to true in the new
1233:meth:`find` method, the attributes of the root element will *not* be traversed.
1234With the old method they would be traversed.
1235
1236:class:`doc` changes
1237--------------------
1238
1239:class:`programlisting` has been renamed to :class:`prog`.
1240
1241Namespace changes
1242-----------------
1243
1244Namespaces can no longer be instantiated. Instead you have to derive a class
1245from :class:`Namespace`. The :var:`xmlprefix` argument from the constructor
1246becomes a class attribute :attr:`xmlname` and the argument :var:`xmlname`
1247becomes :attr:`xmlurl`.
1248
1249Adding element classes to the namespace is now done with the :class:`Namespace`
1250classmethod :meth:`update`. If you want the turn a namespace into a module, you
1251can use the classmethod :meth:`makemod` instead of :meth:`update`, i.e. replace::
1252
1253    xmlns = xsc.Namespace("foo", "http://www.foo.com/", vars())
1254
1255with::
1256
1257    class xmlns(xsc.Namespace):
1258        xmlname = "foo"
1259        xmlurl = "http://www.foo.com/"
1260    xmlns.makemod(vars())
1261
1262
1263Migrating to version 2.1
1264========================
1265
1266The method :meth:`withSep` has been renamed to :meth:`withsep`.
1267
1268The argument :var:`defaultEncoding` for the various parsing functions has been
1269renamed to :var:`encoding`.
1270
1271
1272Migrating to version 2.0
1273========================
1274
1275Attribute handling
1276------------------
1277
1278The biggest change is in the way attributes are defined. In older versions you
1279had to define a class attribute :attr:`attrHandlers` that mapped attribute names
1280to attribute classes. This created problems with "illegal" attribute names (e.g.
1281``class`` and ``http-equiv`` in HTML), so for them an ugly workaround was
1282implemented. With 2.0 this is no longer neccessary. Defining attributes is done
1283via a class :class:`Attrs` nested inside the element class like this::
1284
1285    class foo(xsc.Element):
1286        class Attrs(xsc.Element.Attrs):
1287            class bar(xsc.TextAttr)
1288                "The bar attribute"
1289                default = "spam"
1290                values = ("spam", "eggs")
1291                required = True
1292            class baz(xsc.URLAttr):
1293                "The baz attribute"
1294
1295Default values, set of allowed attributes values and whether the attribute is
1296required can be defined via class attributes as shown above. You should
1297(directly or indirecty) inherit from :class:`xsc.Element.Attrs`, because this
1298class implements handling of global attributes. If you want to inherit some
1299attributes (e.g. from your base class), you can derive from the appropriate
1300:class:`Attrs` class. Removing an attribute you inherited can be done like
1301this::
1302
1303    class bar(foo):
1304        class Attrs(foo.Attrs):
1305            baz = None
1306
1307This removes the attribute ``baz`` inherited from :class:`foo`.
1308
1309For attribute names that are no legal Python identifiers, the same method can be
1310used as for element classes: Define the real XML name via a class attribute.
1311This class attribute has been renamed from :attr:`name` to :attr:`xmlname`.
1312
1313This also means that you always have to use the Python name when using
1314attributes now. The XML name will only be used for parsing and publishing.
1315
1316XIST 2.0 tries to be as backwards compatible as possible: An existing
1317:attr:`attrHandlers` attribute will be converted to an :class:`Attrs` class on
1318the fly (and will generate a :class:`DeprecationWarning` when the class is
1319created). An :class:`Attrs` class will automatically generate an
1320:attr:`attrHandlers` attribute, so it's possible to derive from new element
1321classes in the old way. The only situation where this won't work, is with
1322attributes where the Python and XML name differ, you have to use "new style"
1323attributes there.
1324
1325Namespace support
1326-----------------
1327
1328XIST supports XML namespaces now and for parsing it's possible to configure
1329which namespaces should be available for instantiating classes from. For more
1330info about this refer to the documentation for the class :class:`Prefixes`.
1331
1332Before 2.0 the XML name for a namespace object was pretty useless, now it can be
1333used as the namespace name in ``xmlns`` attributes and it will be used for that
1334when publishing and specifying an ``elementmode`` of ``2`` in the call to the
1335publishing method or the constructor of the publisher.
1336
1337Namespace objects should now be named ``xmlns`` instead of ``namespace`` as
1338before.
1339
1340Global attributes
1341-----------------
1342
1343Global attributes are supported now, e.g. the attributes ``xml:lang`` and
1344``xml:space`` can be specified in an element constructor like this::
1345
1346    from ll.xist import xsc
1347    from ll.xist.ns import html, xml
1348
1349    node = html.html(
1350        content,
1351        {(xml, "lang"): "en", (xml, "space"): "preserve"},
1352        lang="en"
1353    )
1354
1355Instead of the module object (which must contain a namespace object named
1356``xmlns``), you can also pass the namespace object itself (i.e. ``xml.xmlns``)
1357or the namespace name (i.e. ``"http://www.w3.org/XML/1998/namespace"``).
1358
1359Namespace changes
1360-----------------
1361
1362The classes :class:`XML` and :class:`XML10` have been moved from
1363:mod:`ll.xist.xsc` to :mod:`ll.xist.ns.xml`.
1364
1365All the classes in :mod:`ll.xist.ns.specials` that are specific to HTML
1366generation have been moved to the new module :mod:`ll.xist.ns.htmlspecials`.
1367
1368The module :mod:`ll.xist.ns.html` has been updated to the XHTML specification,
1369so there might be some changes. The new feature for specifying attribute
1370restrictions has been used, so e.g. you'll get warnings for missing ``alt``
1371attributes in :class:`img` elements. These warnings are issued via the warning
1372framework. Refer to the documentation for the :mod:`warnings` module to find out
1373how to configure the handling of these warnings.
1374
1375Miscellaneous
1376-------------
1377
1378XIST now requires at least Python 2.2.1 because the integer constants
1379:const:`True` and :const:`False` are used throughout the code wherever
1380appropriate. These constants will become instances of the new class
1381:class:`bool` in Python 2.3. You might want to change your code too, to use
1382these new constant (e.g. when setting the element class attribute
1383:attr:`empty`).
1384
1385Using mixed case method names was a bad idea, because this conflicts with
1386Python's convention of using all lowercase names (without underscores). These
1387method names will be fixed in the next few XIST versions. The first names that
1388where changed were the element methods :meth:`getAttr` and :meth:`hasAttr`,
1389which have been renamed to :meth:`getattr` and :meth:`hasattr` respectively.
1390:meth:`getAttr` and :meth:`hasAttr` are still there and can be called without
1391generating deprecation warnings, but they will start to generate warnings in the
1392upcoming versions.
Note: See TracBrowser for help on using the browser.