root/livinglogic.python.xist/MIGRATION.rst @ 4524:00f8808b9221

Revision 4524:00f8808b9221, 36.5 KB (checked in by Walter Doerwald <walter@…>, 8 years ago)

Names for UL4 templates.

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