Tinycss2

1.5.1 · active · verified Sat Mar 28

tinycss2 is a low-level CSS parser and generator written in Python. It can parse CSS strings, return objects representing tokens and blocks, and generate CSS strings from these objects. Based on the CSS Syntax Level 3 specification, it handles the grammar of CSS but does not know specific rules, properties, or values. It is actively maintained with regular releases.

Warnings

deprecated The `tinycss2.parse_declaration_list` function was deprecated in v1.3.0.
Fix: Use `tinycss2.parse_blocks_contents` instead for parsing declaration lists.
breaking Python 3.6 support was dropped in v1.2.0, and Python 3.5 support in v1.1.0. The library currently requires Python 3.10 or newer.
Fix: Ensure your project uses Python 3.10 or a more recent compatible version.
gotcha tinycss2 is a low-level CSS parser. It understands CSS syntax (tokens, blocks, qualified rules, at-rules) but does not interpret the semantics of specific CSS properties, values, or selectors. It does not provide high-level representations of browser-rendered styles.
Fix: Users are expected to build their own higher-level logic on top of tinycss2's parsed output if they need to interpret CSS rules beyond their grammatical structure.
breaking In tinycss2 v0.5, the default behavior for parsing functions changed to preserve CSS comments and top-level whitespace in the output AST. Previously, these were skipped by default.
Fix: If upgrading from very old versions and expecting comments/whitespace to be omitted, pass `skip_comments=True` and `skip_whitespace=True` to parsing functions like `parse_stylesheet` or `parse_declaration_list`.

Install

pip install tinycss2 Install stable version

Imports

parse_stylesheet

import tinycss2
rules = tinycss2.parse_stylesheet('body { color: red; }')

Primary function for parsing full CSS stylesheets.

ast nodes (e.g., QualifiedRule, IdentToken)
```
from tinycss2.ast import QualifiedRule, IdentToken
```
While often not directly imported, AST node classes reside in the `tinycss2.ast` module for inspection and manipulation of parsed output.

Quickstart

Parses a CSS string into an Abstract Syntax Tree (AST) of tokens and blocks, then iterates through the parsed rules and declarations.

import tinycss2

css_input = '#my-id div { width: 50%; height: 100px }'
rules = tinycss2.parse_stylesheet(css_input)

# The parsed output is a list of nodes
for rule in rules:
    if rule.type == 'qualified-rule':
        print(f"Qualified Rule: {rule.prelude[0].value} {rule.prelude[2].value}") # Example: 'my-id', 'div'
        for declaration in tinycss2.parse_declaration_list(rule.content):
            if declaration.type == 'declaration':
                print(f"  Declaration: {declaration.name}: {declaration.value[0].value}{declaration.value[0].unit}")

# To serialize back to CSS (approximate)
serialized_css = ''.join(node.serialize() for node in rules)
print(f"\nSerialized CSS: {serialized_css}")

view raw JSON →