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.