# 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% }'