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)
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.
|
Returns: | CSSStyleSheet.
|
parseFile
-
cssutils.parseFile(filename, encoding=None, href=None, media=None, title=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)
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.
|
Returns: | CSSStyleDeclaration
|
CSSParser
The parser is reusable.
-
class cssutils.CSSParser(log=None, loglevel=None, raiseExceptions=None, fetcher=None, parseComments=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)
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)
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.
|
Returns: | CSSStyleSheet.
|
-
parseUrl(href, encoding=None, media=None, title=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.