root/livinglogic.python.xist/MIGRATION.rst @ 4533:35aca9b50120

Revision 4533:35aca9b50120, 37.0 KB (checked in by Walter Doerwald <walter@…>, 8 years ago)

Replace ll.xist.xsc.AttrProcInst? with ll.xist.xsc.AttrElement?.

This makes it possible to have a useful output for the new element outside of
attributes.

Make ll.xist.ns.ul4.attr_if an AttrElement? subclass.

Remove ll.xist.ns.ul4.attr_ifnn.

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