Index

# package `cssutils`

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

Contents

- package `cssutils`
  - overview
  - CSS codec
  - parsing CSS
  - serializing CSS
    - Serializer
    - Preferences
      - group settings
      - individual settings
  - logging

## 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)