=================
version migration
=================

0.9.6 incompatible changes
==========================

Exception handling with position information
--------------------------------------------
``xml.dom.DOMException``\ s raised do now contain infos about the position where the exception occured.

**THIS HAS BEEN CHANGED IN 0.9.6a4 again**:

until 0.9.6a3:
     An exception might for example have been raised as::

        raise xml.dom.SyntaxErr('the message', 10, 5)

    (where 10 is the line and 5 the column of the offending text).

    Therefor you may **not** simply use ``str(e)`` to get the exception message but you have to use ``msg, line, col = e.args[0], e.args[1], e.args[2]``. Additionally exceptions raised have attributes ``e.line`` and ``e.col``.

from 0.9.6a4:
    in this version you have to use ``msg, line, col = e.args[0], e.line, e.col``. ``str(e)`` does work again and contains the error message only!


CSSValue / Property has been rewritten
--------------------------------------
- moved validating of a property from ``CSSValue`` to ``Property``
- removed ``CSSValue.valid`` as it does not make sense anymore
- ``CSSPrimitiveValue.getStringValue()`` returns a STRING without quotes or for URIs a value without surrounding ``url(...)`` now

minor API changes
-----------------
+ moved ``cssutils.css.cssproperties.cssvalues`` to ``cssutils.profiles.css2``

+ ``cssutils.utils.Base`` and ``cssutils.utils.Base2`` have been changed and will be removed in favor of new ``cssutils.utils.NewBase``. These are all internal helper classes and should not be used in client code anyway but ye be warned...

+ A few private attributes have been changed. It is best to not use these anyway but if you have:
    - removed private init parameter ``CSSValue._propertyName``
    - private attribute ``CSSValue._value`` contains ``(value, type)`` now. Do not use as it may change again!

+ The API has been cleaned up resulting in *DEPRECATED* attributes and methods being removed:
    - removed ``Property.normalname`` (DEPRECATED from 0.9.5 ), use ``Property.name`` instead
    - removed ``CSSStyleSheet.replaceUrls``, use ``cssutils.replaceUrls()`` instead

----

0.9.5 incompatible changes
==========================
cssutils 0.9.5 introduced some minor incompatible API changes. Reason for most changes is that for most cases the new default behaviour makes more sense.


logging versus raising
----------------------
Upto 0.9.5rc1 any sheet resulting from parsing via any ``parse*`` function or ``CSSParser(raiseExceptions=False)`` (which is also the default) resulted in the library simply logging any later exceptions and not raising them. 0.9.5rc2 fixes this. Until now the global setting of ``cssutils.log.raiseExceptions=True`` (the default) was overwritten with the value of the CSSParser ``raiseExceptions`` setting which is normally ``False`` any time a ``cssutils.parse*`` function or ``CSSParser.parse*`` method was used. So

until 0.9.5rc1::

    >>> # does not raise during parse
    >>> s = cssutils.parseString('$') # empty but CSSStyleSheet object

    >>> # does not raise either but should:
    >>> s.cssText = '$'
    ERROR   CSSStyleRule: No start { of style declaration found: u'$' [1:2: ]
    # [...]

from 0.9.5rc2::

    >>> # still does not raise during parse
    >>> s = cssutils.parseString('$') # empty but CSSStyleSheet object

    >>> # working with the actual DOM does raise now though
    >>> s.cssText = '$'
    # [...] traceback
    xml.dom.SyntaxErr: CSSStyleRule: No start { of style declaration found: u'$' [1:1: $]

To use the old but false behaviour add the following line at the start to your program::

    >>> cssutils.log.raiseExceptions = False # normally True

**This should only be done in specific cases** as normal raising of exceptions in methods or functions with the CSS DOM is the expected behaviour.


parsing
-------
``parse()`` is *DEPRECATED* in favour of ``parseFile()``. Both methods are still available but ``parse`` will be removed for cssutils 1.0.

All ``parse*`` functions (or ``CSSParser.parse*`` methods) do raise errors from 0.9.5final.

iterating over ``CSSStyleDeclaration``
--------------------------------------
Iterating over ``css.CSSStyleDelcaration`` now yields *effective* properties only and not *all* properties set in the declaration. To retrieve *all* properties use ``CSSStyleDeclaration.getProperties(all=True)``.

example
~~~~~~~
iterating over a CSSStyleDeclaration with ``cssText='color: red; c\olor: green'``

OLD:
    yielded two Property objects with the values ``red`` and ``green``.
NEW since 0.9.5:
    yields one Property only (the actual one used) which has the value ``green``.


``Property.name`` attribute
---------------------------
``Property.name`` until now hold the *literal* value (e.g. ``c\olor`` of a properties name. Now it holds the *normalized* name. ``Property.normalname`` is therefor *DEPRECATED*. To access the unnormalized (literal) name use the new readonly property ``Property.literalname``.

example
~~~~~~~

::

        p = Property(ur'c\olor', 'red')

OLD
    ::

        p.name == ur'c\olor'
        p.normalname == ur'color' # now DEPRECATED

NEW since 0.9.5
    ::

        p.name == ur'color'
        p.literalname == ur'c\olor'

``Property.priority`` attribute
-------------------------------
The value of ``Property.priority`` (or ``CSSStyleDeclatation.getPropertyPriority(p)``) is now ``important`` without a leading ``!`` as defined in the CSS specs.

(``Property._normalpriority`` has been removed, the normalized value that was available here is now in ``Property.priority``. The literal priority value is available in ``Property.literalproperty`` now (analog to ``Property.literalname``). All these values probably should not be used by client code anyway but may be helpful when using CSS hacks.)

example
~~~~~~~
::

    p = Property(u'color', 'red', u'!IMPOR\\TANT')

OLD
    ::

        p.priority == u'!IMPOR\\TANT'
        p._normalpriority == u'!important' # now REMOVED!

NEW since 0.9.5
    ::

        p.priority == u'important'
        p.literalpriority == u'IMPOR\\TANT'

``CSSStyleSheet.replaceUrls(replacer)``
---------------------------------------
Since 0.9.5b1 ``replaceUrls`` has been moved from a method of ``CSSStyleSheet`` to a utility function in cssutils directly.

example
~~~~~~~
::

        def replacer(url):
            "returns new URL"

        sheet = cssutils.parseUrl('http://example.com/test.css')


OLD
    ::

        sheet.replaceUrls(replacer)

NEW since 0.9.5b1
    ::

        cssutils.replaceUrls(sheet, replacer)

