parsing CSS

Options to parse a given stylesheet: Get an instance of cssutils.CSSParser and use the provided parse* methods or for simpler parsing use the parse* convienience functions.

Convienience Functions

Shortcuts for initializing a new cssutils.CSSParser and use its parse* methods. Parsing a stylesheet this way does not raise any exceptions if an error occurs but parses CSS as defined in the specifications. If you need advanced parser handline use cssutils.CSSParser directly.

parseString

cssutils.parseString(cssText, encoding=None, href=None, media=None, title=None, validate=None)

Parse cssText as CSSStyleSheet. Errors may be raised (e.g. UnicodeDecodeError).

Parameters:

  • cssText – CSS string to parse

  • encoding – If None the encoding will be read from BOM or an @charset rule or defaults to UTF-8. If given overrides any found encoding including the ones for imported sheets. It also will be used to decode cssText if given as a (byte) string.

  • href – The href attribute to assign to the parsed style sheet. Used to resolve other urls in the parsed sheet like @import hrefs.

  • media – The media attribute to assign to the parsed style sheet (may be a MediaList, list or a string).

  • title – The title attribute to assign to the parsed style sheet.

  • validate – If given defines if validation is used. Uses CSSParser settings as fallback

Returns:

CSSStyleSheet.

parseFile

cssutils.parseFile(filename, encoding=None, href=None, media=None, title=None, validate=None)

Retrieve content from filename and parse it. Errors may be raised (e.g. IOError).

Parameters:

  • filename – of the CSS file to parse, if no href is given filename is converted to a (file:) URL and set as href of resulting stylesheet. If href is given it is set as sheet.href. Either way sheet.href is used to resolve e.g. stylesheet imports via @import rules.

  • encoding – Value None defaults to encoding detection via BOM or an @charset rule. Other values override detected encoding for the sheet at filename including any imported sheets.

Returns:

CSSStyleSheet.

parseUrl

cssutils.parseUrl(href, encoding=None, media=None, title=None, validate=None)

Retrieve content from URL href and parse it. Errors may be raised (e.g. URLError).

Parameters:

  • href – URL of the CSS file to parse, will also be set as href of resulting stylesheet

  • encoding – Value None defaults to encoding detection via HTTP, BOM or an @charset rule. A value overrides detected encoding for the sheet at href including any imported sheets.

Returns:

CSSStyleSheet.

Working with inline styles

parseStyle

cssutils.parseStyle(cssText, encoding='utf-8')

Parse given cssText which is assumed to be the content of a HTML style attribute.

Parameters:

  • cssText – CSS string to parse

  • encoding – It will be used to decode cssText if given as a (byte) string.

  • validate – If given defines if validation is used. Uses CSSParser settings as fallback

Returns:

CSSStyleDeclaration

CSSParser

The parser is reusable.

class cssutils.CSSParser(log=None, loglevel=None, raiseExceptions=None, fetcher=None, parseComments=True, validate=True)

Parse a CSS StyleSheet from URL, string or file and return a DOM Level 2 CSS StyleSheet object.

Usage:

parser = CSSParser()
# optionally
parser.setFetcher(fetcher)
sheet = parser.parseFile('test1.css', 'ascii')
print sheet.cssText
parseFile(filename, encoding=None, href=None, media=None, title=None, validate=None)

Retrieve content from filename and parse it. Errors may be raised (e.g. IOError).

Parameters:

  • filename – of the CSS file to parse, if no href is given filename is converted to a (file:) URL and set as href of resulting stylesheet. If href is given it is set as sheet.href. Either way sheet.href is used to resolve e.g. stylesheet imports via @import rules.

  • encoding – Value None defaults to encoding detection via BOM or an @charset rule. Other values override detected encoding for the sheet at filename including any imported sheets.

Returns:

CSSStyleSheet.

parseString(cssText, encoding=None, href=None, media=None, title=None, validate=None)

Parse cssText as CSSStyleSheet. Errors may be raised (e.g. UnicodeDecodeError).

Parameters:

  • cssText – CSS string to parse

  • encoding – If None the encoding will be read from BOM or an @charset rule or defaults to UTF-8. If given overrides any found encoding including the ones for imported sheets. It also will be used to decode cssText if given as a (byte) string.

  • href – The href attribute to assign to the parsed style sheet. Used to resolve other urls in the parsed sheet like @import hrefs.

  • media – The media attribute to assign to the parsed style sheet (may be a MediaList, list or a string).

  • title – The title attribute to assign to the parsed style sheet.

  • validate – If given defines if validation is used. Uses CSSParser settings as fallback

Returns:

CSSStyleSheet.

parseStyle(cssText, encoding='utf-8', validate=None)

Parse given cssText which is assumed to be the content of a HTML style attribute.

Parameters:

  • cssText – CSS string to parse

  • encoding – It will be used to decode cssText if given as a (byte) string.

  • validate – If given defines if validation is used. Uses CSSParser settings as fallback

Returns:

CSSStyleDeclaration

parseUrl(href, encoding=None, media=None, title=None, validate=None)

Retrieve content from URL href and parse it. Errors may be raised (e.g. URLError).

Parameters:

  • href – URL of the CSS file to parse, will also be set as href of resulting stylesheet

  • encoding – Value None defaults to encoding detection via HTTP, BOM or an @charset rule. A value overrides detected encoding for the sheet at href including any imported sheets.

Returns:

CSSStyleSheet.

setFetcher(fetcher=None)

Replace the default URL fetch function with a custom one.

Parameters:

fetcher –

A function which gets a single parameter

url

the URL to read

and must return (encoding, content) where encoding is the HTTP charset normally given via the Content-Type header (which may simply omit the charset in which case encoding would be None) and content being the string (or unicode) content.

The Mimetype should be ‘text/css’ but this has to be checked by the fetcher itself (the default fetcher emits a warning if encountering a different mimetype).

Calling setFetcher with fetcher=None resets cssutils to use its default function.

The URL Fetcher

If you want to control how imported stylesheets are read you may define a custom URL fetcher (e.g. would be needed on Google AppEngine as urllib2, which is normally used, is not available. A GAE specific fetcher is included in cssutils from 0.9.5a1 though.)

A custom URL fetcher may be used during parsing via CSSParser.setFetcher(fetcher) (or as an init parameter). The so customized parser is reusable. The fetcher is called when an @import rule is found and the referenced stylesheet is about to be retrieved.

Example:

def fetcher(url):
    return 'ascii', '/*test*/'

parser = cssutils.CSSParser(fetcher=fetcher)
parser.parse...

Example 2 with a fetcher returning a unicode string:

def fetcher(url):
    return None, u'/*test*/'

parser = cssutils.CSSParser(fetcher=fetcher)
parser.parse...

To omit parsing of imported sheets just define a fetcher like lambda url: None (A single None is sufficient but returning None, None would be clearer).

You may also define a fetcher which overrides the internal encoding for imported sheets with a fetcher that returns a (normally HTTP) encoding depending e.g on the URL.