parsing CSS — cssutils 0.9.8 documentation

### Navigation

- index
- modules |
- next |
- previous |
- cssutils 0.9.8 documentation »

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

    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`

  `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.

### Navigation

- index
- modules |
- next |
- previous |
- cssutils 0.9.8 documentation »