Common Use Cases

tinycss2 has been created for WeasyPrint, and many common use cases can thus be found in its repository.

Parsing Stylesheets

Parsing whole stylesheets is done using tinycss2.parse_stylesheet() and tinycss2.parse_stylesheet_bytes().

When CSS comes as Unicode strings, tinycss2.parse_stylesheet() is the function to use. If you know for sure how to decode CSS bytes, or if you want to parse CSS in Unicode strings, you can safely use this function to get rules out of CSS text.

tinycss2.parse_stylesheet('body div { width: 50% }')
# [<QualifiedRule … { … }>]

tinycss2.parse_stylesheet() has two extra parameters: skip_comments if you do not want to generate comment tokens at the top-level of the stylesheet, and skip_whitespace if you want to ignore top-level extra whitespaces.

In many cases, it is hard to know which charset to use. When downloading stylesheets from an online HTML document, you may have a BOM, a @charset rule, a protocol encoding defined by HTTP and an environment encoding.

tinycss2 provides tinycss2.parse_stylesheet_bytes() that knows how to handle these different hints. Use it when your CSS is stored offline or online in a file, it may solve many decoding problems for you.

with open('file.css', 'rb') as fd:
    css = fd.read()
tinycss2.parse_stylesheet_bytes(css)
# [<QualifiedRule … { … }>]

tinycss2.parse_stylesheet_bytes() allows two extra optional arguments: protocol_encoding that may be provided by your network protocol, and environment_encoding used as a fallback encoding if the other ones failed.

Parsing Rules

Parsing a list of declarations is possible from a list of tokens (given by the content attribute of tinycss2.parse_stylesheet() rules) or from a string (given by the style attribute of an HTML element, for example).

The high-level function used to parse declarations is tinycss2.parse_blocks_contents().

rules = tinycss2.parse_stylesheet('body div {width: 50%;height: 50%}')
tinycss2.parse_blocks_contents(rules[0].content)
# [<Declaration width: …>, <Declaration height: …>]

tinycss2.parse_blocks_contents('width: 50%;height: 50%')
# [<Declaration width: …>, <Declaration height: …>]

You can then get the name and value of each declaration:

declarations = tinycss2.parse_blocks_contents('width: 50%;height: 50%')
declarations[0].name, declarations[0].value
# ('width', [<WhitespaceToken>, <PercentageToken 50%>])

This function has the same skip_comments and skip_whitespace parameters as the parse_stylesheet* functions.

Serializing

tinycss2 is also able to generate CSS strings out of abstact Python trees. You can use tinycss2.ast.Node.serialize() to generate a CSS string that would give the same serialization as the original string.

rules = tinycss2.parse_stylesheet('body div { width: 50% }')
rule = rules[0]

print(rule.serialize())
# 'body div { width: 50% }'