Cssutils

- **API CHANGE**: Known but invalid properties raise/log an ERROR instead of a WARNING now. Properties not expected in the current profile log an INFO. As the default profile is ``None`` even basic properties like ``color`` are logged now. You may want to change the default profile by setting e.g. ``cssutils.profiles.defaultprofile = cssutils.profiles.Profiles.CSS_LEVEL_2`` (~ CSS 2.1) to prevent CSS 2.1 properties to be reported. Also other validation related output has been slightly changed.

**The way to change a defaultprofile may change again.**

- **API CHANGE**: ``cssutils.script.csscombine`` has **ONLY** keyword parameters now. Use ``csscombine(path=path[,...])`` for the old behaviour. New parameter ``url`` combines the sheet at URL now.

+ **FEATURE**: Added **experimental** profiles handling. You may add new profiles with new properties and their validation and set a defaultprofile used for validation. The current default profile is ``None`` so all predefined profiles are used. Currently 3 profiles are defined:

``~cssutils.profiles.Profiles.Profiles.CSS_LEVEL_2``
Properties defined by CSS2.1
``~cssutils.profiles.Profiles.Profiles.CSS_COLOR_LEVEL_3``
CSS 3 color properties
``~cssutils.profiles.Profiles.Profiles.CSS_BOX_LEVEL_3``
Currently overflow related properties only

See the docs and source of the cssutils.profiles module for details.

+ **FEATURE**: ``cssutils.util._readUrl()`` allows fetchers to pre-decode CSS content and return `unicode` instances, with or without a specified source encoding (integrated from patch of Issue Bitbucket 19).

+ **FEATURE**: URL fetch method checks if cssutils is run in GoogleAppEngine (GAE) (if ``import google.appengine`` is successful) and uses the GAE fetch methods instead of urllib2 in that case. So in result cssutils should run on GAE just as elsewhere.
+ **FEATURE**: Function ``cssutils.resolveImports(sheet)`` returns a new stylesheet with all rules in given sheet but with all import rules being pulled into the top sheet.
+ FEATURE: CSSCombine script and helper function resolve nested imports now.
+ FEATURE: Script ``csscombine`` has new option ``-u URL, --url=URL URL to parse (path is ignored if URL given)`` now

+ BUGFIX: Other priority values than ``!important`` are parsed now. Nevertheless they log an ERROR or raise a SyntaxErr.
**TODO**: Preference setting. Profile?

- IMPROVEMENT: Added all known properties (by cssutils ;) to CSS2Properties.

+ DOCUMENTATION: Changed documentation generation from Epydoc and home grown HTML generation to Sphinx. Not all is perfectly markup'd yet but not too bad either...

+ **FEATURE**: ``xml.dom.DOMException``\ s raised do now contain infos about the position where the exception occured. 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``.

+ **FEATURE**: page rule accepts named page selector now, e.g. ``page intro`` or ``page main:left``.

+ **FEATURE**: Script ``cssparse`` has new option ``-u URL`` which parses the given URL.

+ **FEATURE**: Started implementation of CSS profiles...
- moved ``cssutils.css.cssproperties.cssvalues`` to ``cssutils.profiles.css2``
- added CSS Color Module Level 3 with properties ``color`` and ``opacity``. Not implemented are SVG color names.
- unknown properties raise a WARNING instead of INFO now
- refactored CSSValue and subclasses therefore there may be some minor changes in serializing or value reporting
+ ``getStringValue()`` returns a string without quotes or for URIs a value without surrounding ``url(...)`` now

+ FEATURE **experimental**: Added class ``CSSColor`` which is used for RGB, RGBA, HSL, HSLA and HEX color values of ``CSSValue`` respective ``CSSPrimitiveValue``.

+ FEATURE (strange): IE only CSS expressions *should* be parsed and serialized now an an ``Expression`` value. I have not tested this deeply and there may be problems but for some common cases this should work, e.g. for hacking maxwidth for IE you may define the following::

width: expression(document.body.clientWidth > 1000 ? "1000px": "100%")

Usage of CSS expressions is strongly discouraged as they do not validate AND may slow down the rendering and browser quite a lot!

+ BUGFIX/IMPROVEMENT: rewrite of CSSValue and related classes
- BUGFIX: Parsing of a CSSValue like ``red /**/`` (value, Space, comment) fixed.
- BUGFIX: Parsing values with ``+`` operator fixed.
- BUGFIX: ``CSSValueList.__str__`` added (missing last underscore rendered it useless)
- IMPROVEMENT: Serializing e.g. ``rgb(0,0,0)`` now defaults to ``rgb(0, 0, 0)``
- IMPROVEMENT: HEX values are minified if possible, e.g. ``Bitbucket 112233`` results in ``Bitbucket 123``
- IMPROVEMENT: Improved handling of zero lengths like ``-0, 0.0, .0mm`` etc all should come out simply as ``0`` now
- IMPROVEMENT: number values are normalized now, e.g. ``010.0px`` results in ``10px`` etc
- IMPROVEMENT: DIMENSIONs are normalized now, e.g. ``1pX`` results in ``1px``
- IMPROVEMENT: for CSSValueList values like e.g. ``margin: 0 1px`` there are no more false WARNINGs emitted
- IMPROVEMENT: Comments should be parsed much better now
- IMPROVEMENT: ``CSSValue.getFloattype(unitType=None)``, parameter is now optional in which case the current dimension is used.
- fixed lots of other minor bugs related to CSSValue

- **BUGFIX**: Fixed tokenizing/parsing of rather strange STRING and URI values like:
- Valid::

"somestring followed by escaped NL\
and continuing here."

and now results in::

"somestring followed by escaped NL and continuing here."

- ``url())`` => not allowed and must be written as ``url(")")``

- **BUGFIX**: Setting ``CSSPageRule.selectorText`` does actually work now.

- BUGFIX: Other priority values than ``!important`` are parsed now. Nevertheless they log an ERROR or raise a SyntaxErr.

- BUGFIX: Fixed Issue Bitbucket 14, added ``CSSStyleDeclaration().borderLeftWidth``. But prefer to use ``CSSStyleDeclaration()['border-left.width']``.

+ **API CLEANUP**:
- moved validating of a property from ``CSSValue`` to ``Property``
- removed ``CSSValue.valid`` as it does not make sense anymore
- removed private init parameter ``CSSValue_propertyName``
- private attribute ``CSSValue._value`` contains ``(value, type)`` now. Do not use as it may change again
- removed ``Property.normalname`` (DEPRECATED from 0.9.5 ), use ``Property.name`` instead
- removed long deprecated ``CSSStyleSheet.replaceUrls``, use ``cssutils.replaceUrls()`` instead
- ``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...

+ IMPROVEMENT:
- minor changes due to deprecation in Py3k. cssutils is NOT Py3k compliant yet though and it will probably take a while until it will be...

+ IMPROVEMENT: Optimized imports and partly removed circular ones which are a bit tricky...

+ **API CHANGE**: If a new medium is trying to be appended to a ``MediaList`` already set to ``all`` an ``xml.dom.InvalidModificationErr`` is raised. The exception to this handling is adding ``handheld`` which is a special case for Opera and kept for now. This special handling may be removed in the future. A ``WARNING`` is logged in any case.

- **BUGFIX**: Fixed reference error in import rule preventing change of the used ``MediaList``.
- **BUGFIX**: Deeply nested ``CSSImportRule``\ s with different encodings should keep the encoding as defined (via HTTP, parendSheet, charset etc) now. Therefor ``cssutils.util._readUrl`` does return ``(encoding, enctype, decodedCssText)`` now where ``enctype`` is a number from 0 to 5 indicating which encoding type was used: 0 for encoding override, 1 for HTTP encoding, 2 for BOM or charset rule, (3 is unused currently), 4 for encoding of the parent sheet and 5 if encoding defaults to UTF-8 as no other information is available. (This may later be done as constants but this function should not be used from programs generally).
- **BUGFIX**: Replaced usage of ``WindowsError`` with ``OSError``. I (naively ;) thought ``WindowsError`` at least be present in environments other than Windows but it just results in a ``NameError``... The part of the API which triggered this Exception is an import rule with an invalid or local (file) URI so should have happened quite rarely anyway.

+ IMPROVEMENT: Standalone scripts ``csscombine`` and ``csscapture`` are available for programmatic use in ``cssutils.script.csscombine`` and ``cssutils.script.CSSCapture`` res.
+ IMPROVEMENT: ``cssutils.script.csscombine`` and ``csscombine`` script do use the cssutils log now instead of just writing messages to ``sys.stderr``
+ IMPROVEMENT: Optimized and refactored tokenizer (CHARSET_SYM).

- **API CHANGE/BUGFIX (major)**:

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

until 0.9.5rc1::

>>> parsing does not raise errors
>>> s = cssutils.parseString('$') empty but CSSStyleSheet object

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

from 0.9.5rc2::

>>> parsing STILL does not raise errors
>>> s = cssutils.parseString('$') empty but CSSStyleSheet object

>>> using DOM methods **does raise now though**
>>> s.cssText = '$' raises:
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. **This setting may also be removed in the future so use with care.**

- **BUGFIX**: Parsing of rules like ``mediaall ...`` does not result in ``media all ...`` anymore (so not a ``CSSMediaRule``) but parses as ``mediaall`` so a ``CSSUnknownRule``. The specification is not too clear here but it seems this is the way to go. To help finding typos like this probably is, for any found CSSUnknownRule (an unknown rule) a WARNING is emitted now (but never an exception raised). These typos will most likely happen like e.g. ``mediaall``, ``importurl()``, ``namespaceprefix"uri"`` or ``pagename:left``.

- **BUGFIX**: Parsing of unicode escapes like ``\\abc`` followed by CR/LF this is now correctly combined as only a single whitespace character.

- **BUGFIX**: Adding a malformed ``stylesheets.MediaQuery`` to a ``stylesheets.MediaList`` does fail now, e.g.::

>>> invalid malformed medialist (missing comma):
>>> sheet = cssutils.parseString('media tv INVALID {a {top: 0;}}')
ERROR MediaQuery: Unexpected syntax. [1:11: INVALID]
ERROR MediaList: Invalid MediaQuery: tv INVALID
>>> the actual rule exists but has default empty content, this may be
changed later as it can be seen as a bug itself
>>> sheet.cssRules[0]
cssutils.css.CSSMediaRule(mediaText=u'all')
>>> sheet.cssText
''

>>> BUT: Unknown media type but as it is valid does parse:
>>> sheet = cssutils.parseString('media tv, UNKNOWN {a {top: 0;}}')
WARNING MediaQuery: Unknown media type "UNKNOWN".
>>> sheet.cssRules[0]
cssutils.css.CSSMediaRule(mediaText=u'tv, UNKNOWN')
>>> sheet.cssText
'media tv, UNKNOWN {\n a {\n top: 0\n }\n }'

- **BUGFIX**: References to ``MediaList`` in ``CSSImportRule`` and ``CSSMediaRule`` are kept now properly.

- BUGFIX: Deleting a ``MediaQuery`` item from a ``MediaList`` does use the libs logging/raising settings instead of always raising

- **IMPROVEMENT**: Parsing performance has been improved (by about 25%, tested with a basic CSS of about 50 lines, so may not be representative but this release definitely is faster ;). The following changes have been done which should not impact any actual stylesheet:

+ A ``BOM`` token is recognized at the start of a stylesheet only (may be swallowed by the CSS codec anyway).
+ A ``BOM`` token is not counted in the line/col reporting anymore so the following token has a line and col of 1 now
+ Tests for tokenizing with css2productions has been removed but this is never used in the library anyway

- **API CHANGE/FEATURE**: ``The cssutils.log`` may be partly used like a standard logging log. The following methods are available: ('setLevel', 'getEffectiveLevel', 'addHandler', 'removeHandler') as well as all "messaging" calls like 'error', 'warning' etc.

Therefor ``cssutils.log.setloglevel`` has been *DEPRECATED* and should be used via ``cssutils.log.setLevel``. The old method is still available though.

``cssutils.log.setlog`` has been renamed to ``cssutils.log.setLog`` but is still available but *DEPRECATED* too.

- **FEATURE**: All three decoders in the codec now have an additional ``force`` argument. If ``force`` is false, the encoding from the input will only by used if is is detected explicitely via BOM or charset rule.

- **FEATURE**: ``cssparse`` script has new option ``-m --minify`` which results in the parsed CSS to be serialized minified

- **FEATURE**: ``CSSCapture`` and ``csscombine`` are now available not only as standalone scripts but also via ``cssutils.script.CSSCapture`` and ``cssutils.script.csscombine`` repectively so you can use them programmatically now.

- **BUGFIX**: A space after rule keyword is added when serializing minified something like ``media all{}``. Until now it was ``mediaall{}`` which is recognized by Safari only but probably is not valid at all. Other rules behave similar now too.

- **BUGFIX**: Properties of rules set via ``css.CSSStyleSheet.add`` or ``.insert`` were not set properly, e.g. ``parentStyleSheet`` or the stylesheet handling of new import rules was buggy.

- BUGFIX: Encountering OSError during resolving import does not throw an error anymore but the resulting CSSImportRule.styleSheet will have a value of ``None``. OSError will probably only happen when using ``parseFile``.

- **IMPROVEMENT/BUGFIX**: A style sheet with ``href == None`` (e.g. parsed with ``parseString()`` or build completely from scratch) uses ``os.getcwd()`` as its base href now to be able to resolve CSSImportRules.

- **IMPROVEMENT/BUGFIX**: Rewrote ``csscombine`` script which should be much more stable now and handles namespaces correctly. Nested imports are still not resolved yet but this may come in the next release.

- IMPROVEMENT/BUGFIX: Added catching of WindowsError to default fetcher (e.g. is a file URL references a file not present).

- **CHANGE/BUGFIX**: Redone ``csscapture`` script. A few minor method changes (parameter ``ua`` of ``capture`` has been replaced by init parameter) and lots of internal improvement has been done.

- CHANGE: ``CSSStyleSheet.add(rule)`` simply appends rules with no specific order in the sheet to the end of it. So e.g. COMMENTs, STYLE_RULEs, etc are appended while rules with a specific place are ordered-in as before (e.g. IMPORT_RULE or NAMESPACE_RULE). Until now rules of a specific type like COMMENTs were ordered together which does not really make sense. The ``csscombine`` script needs this functionality and the resulting combined sheets should be more readable and understandable now.

- CHANGE: Default URL fetcher emits an ERROR instead of a warning if finding a different mine-type than ``text/css``.