Index

package cssutils

author:$LastChangedBy: cthedot $
date:$LastChangedDate: 2007-08-08 16:14:03 +0200 (Mi, 08 Aug 2007) $
version:$LastChangedRevision: 206 $

overview

Contains tokenizer, parser and helper classes used by subpackages css and stylesheets. Implemented is also the interface DOMImplementationCSS.

codec:A CSS codec registered at standard module codecs
CSSParser:A CSS parser
CSSSerializer:A configurable CSS serializer
log:A configurable cssutils.errorhandler.ErrorHandler() logger
DOMImplementationCSS:Registers cssutils at standard package xml.dom

CSS codec

You may use the provided CSS codec to read or write a CSS stylesheet. Handling is similar to other codecs. The codec handles the text encoding of the file automatically (regarding BOM or @charset rules in the stylesheet).

Example:

import codecs
import cssutils

cssText = codecs.open('sheets/test-unicode.css', encoding='css').read()
sheet = cssutils.parseString(cssText)

parsing CSS

Options to parse a given stylesheet:

  • use the helper functions:
    • cssutils.parse(filename, encoding)
    • cssutils.parseString(cssText, href=None, media=None)
  • or get an instance of cssutils.CSSParser and use the provided parse methods which are the same as the helper functions. The parser is reusable.
  • parsing a stylesheet this way does not raise any exceptions if an error occurs but parses CSS as defined in the specifications. Setting explicit properties (e.g. CSSStyleSheet.cssText with a syntactically incorrect sheet raises the relevant exeptions.

serializing CSS

Serializer

There is only one global serializer used throughout the library. You may configure it or even replace it with your own.

A custom serializer must implement all methods the default one implements. Easiest would be to subclass cssutils.serialize.Serializer.

To set a new serializer, use:

sheet = CSSStyleSheet()
sheet.setSerializer(newser)

You may also set cssutils.ser directly but the above method is the preferred one.

Preferences

Quite a few preferences of the cssutils serializer may be tweaked.

To set a preference use:

sheet = CSSStyleSheet()
sheet.setSerializerPref(pref, value)

You may also set cssutils.ser.prefs.pref directly but the above method is the preferred one.

Preferences are always used globally, so for all stylesheets until preferences are set again.

group settings

Two methods are available to use a predefined set of setting:

useDefaults()
reset all preference options to the default value
useMinified()
sets options to achive a minified stylesheet

individual settings

The following preferences are currently available (name = default value):

defaultAtKeyword = True
Should the literal @keyword from src CSS be used or the default form, e.g. if True: @import else e.g.: @i\mport
defaultPropertyName = True

Should the normalized propertyname be used or the one given in the src file, e.g. if True: color else e.g.: c\olor

Only used if keepAllProperties==False.

importHrefFormat = None
Uses hreftype if None or explicit 'string' or 'uri'
indent = 4 * ' '
Indentation of e.g Properties inside a CSSStyleDeclaration
keepAllProperties = True
If True all properties set in the original CSSStylesheet are kept meaning even properties set twice with the exact same same name are kept!
keepComments = True
If False removes all CSSComments
keepEmptyRules = False
defines if empty rules like e.g. a {} are kept in the resulting serialized sheet
lineNumbers = False
Only used for serializing CSSStyleSheet, not individual rules or properties etc.
lineSeparator = u'\n'
How to end a line. This may be set to e.g. u'' for serializing of CSSStyleDeclarations usable in HTML style attribute.
listItemSpacer = u' '
String which is used in css.SelectorList, css.CSSValue and stylesheets.MediaList after the comma, minifier sets this to the empty string.
omitLastSemicolon = True
If True omits ; after last property of CSSStyleDeclaration
paranthesisSpacer = u' '
String which is used before an opening paranthesis like in a css.CSSMediaRule or css.CSSStyleRule, minifier sets this to the empty string.
propertyNameSpacer = u' '
String which is used after a Property name colon, minifier sets this to the empty string.
validOnly = False (not used anywhere yet)

If True only valid (Properties or Rules) are kept.

A Property is valid if it is a known Property with a valid value. Currently CSS 2.1 values as defined in cssproperties.py would be valid.

wellformedOnly = True (not used everywhere yet)
Only wellformed properties and rules are kept.
DEPRECATED: removeInvalid = True
Omits invalid rules, replaced by validOnly which will be used more cases

logging

A global logger is used throughout the library. You may configure it or even replace it with your own. Customizing the default log should be sufficient for most purposes though.

The default logger is available as cssutils.log. It has the following methods:

  • log.setlog(newlog): To redirect logging output, the default output is sent to stderr

  • log.setloglevel(level): To change the log level. This should be a level defined by the logging module, e.g.:

    import logging
    cssutils.log.setloglevel(logging.FATAL)